@probitas/client-sql-mysql

MySQL client for Probitas scenario testing framework.

This package provides a MySQL client designed for integration testing, with transaction support and prepared statement capabilities.

Features

• Query Execution: Parameterized queries with type-safe results
• Transactions: Full transaction support with isolation levels
• Prepared Statements: Automatic parameter escaping and type conversion
• Connection Pooling: Configurable pool with idle timeout
• Resource Management: Implements AsyncDisposable for proper cleanup

Installation

deno add jsr:@probitas/client-sql-mysql

Quick Start

import { createMySqlClient } from "@probitas/client-sql-mysql";

const client = await createMySqlClient({
  url: {
    host: "localhost",
    port: 3306,
    username: "root",
    password: "secret",
    database: "mydb",
  },
});

// Query with parameters (uses ? placeholders)
const result = await client.query<{ id: number; name: string }>(
  "SELECT id, name FROM users WHERE active = ?",
  [true]
);
console.log(result.rows);

// Get first row
const user = await client.queryOne<{ id: number; name: string }>(
  "SELECT * FROM users WHERE id = ?",
  [1]
);

await client.close();

Transactions

import { createMySqlClient } from "@probitas/client-sql-mysql";
import type { SqlTransaction } from "@probitas/client-sql";

const client = await createMySqlClient({ url: "mysql://localhost:3306/testdb" });
await client.transaction(async (tx: SqlTransaction) => {
  await tx.query("INSERT INTO accounts (id, balance) VALUES (?, ?)", [1, 100]);
  await tx.query("INSERT INTO accounts (id, balance) VALUES (?, ?)", [2, 200]);
  // Automatically committed if no error, rolled back on exception
}, { isolationLevel: "serializable" });
await client.close();

Using with using Statement

import { createMySqlClient } from "@probitas/client-sql-mysql";

await using client = await createMySqlClient({
  url: { host: "localhost", username: "root", database: "testdb" },
});

const result = await client.query("SELECT 1 as n");
// Client automatically closed when block exits

Related Packages

Links

• GitHub Repository
• Probitas Framework
• MySQL

deno add jsr:@probitas/client-sql-mysql

class AccessDeniedError extends MySqlError

new AccessDeniedError(message: string, options?: MySqlErrorOptions)

class ConnectionRefusedError extends MySqlError

new ConnectionRefusedError(message: string, options?: MySqlErrorOptions)

class ConstraintError extends SqlError

new ConstraintError(
  message: string,
  constraint: string,
  options?: SqlErrorOptions,
)

class DeadlockError extends SqlError

new DeadlockError(message: string, options?: SqlErrorOptions)

class MySqlError extends SqlError

new MySqlError(message: string, options?: MySqlErrorOptions)

class MySqlTransactionImpl implements MySqlTransaction

new MySqlTransactionImpl(connection: AnyPoolConnection)

static begin(): unknown

query(): unknown

queryOne(): unknown

commit(): unknown

rollback(): unknown

savepoint(): unknown

rollbackToSavepoint(): unknown

releaseSavepoint(): unknown

class QuerySyntaxError extends SqlError

new QuerySyntaxError(message: string, options?: SqlErrorOptions)

class SqlConnectionError extends SqlError

new SqlConnectionError(message: string, options?: SqlErrorOptions)

class SqlError extends ClientError

new SqlError(message: string, kind: SqlErrorKind, options?: SqlErrorOptions)

interface MySqlClient extends AsyncDisposable

query<T = Record<string, any>>(
  sql: string,
  params?: unknown[],
  options?: SqlQueryOptions,
): Promise<SqlQueryResult<T>>

queryOne<T = Record<string, any>>(
  sql: string,
  params?: unknown[],
  options?: SqlQueryOptions,
): Promise<T | undefined>

transaction<T>(
  fn: (tx: SqlTransaction) => unknown,
  options?: SqlTransactionOptions,
): Promise<T>

close(): Promise<void>

interface MySqlClientConfig extends CommonOptions

interface MySqlConnectionConfig extends CommonConnectionConfig

interface MySqlErrorOptions extends SqlErrorOptions

interface MySqlPoolConfig

interface MySqlTlsConfig

interface MySqlTransaction extends SqlTransaction

savepoint(name: string): Promise<void>

rollbackToSavepoint(name: string): Promise<void>

releaseSavepoint(name: string): Promise<void>

interface SqlErrorOptions extends ErrorOptions

interface SqlQueryOptions extends CommonOptions

interface SqlQueryResultError<T = any> extends SqlQueryResultBase<T>

interface SqlQueryResultFailure<T = any> extends SqlQueryResultBase<T>

interface SqlQueryResultSuccess<T = any> extends SqlQueryResultBase<T>

interface SqlQueryResultSuccessParams<T = any>

interface SqlTransaction

query<T = Record<string, any>>(
  sql: string,
  params?: unknown[],
  options?: SqlQueryOptions,
): Promise<SqlQueryResult<T>>

queryOne<T = Record<string, any>>(
  sql: string,
  params?: unknown[],
  options?: SqlQueryOptions,
): Promise<T | undefined>

commit(): Promise<void>

rollback(): Promise<void>

interface SqlTransactionOptions

function convertMySqlError(error: unknown): SqlError

async function createMySqlClient(
  config: MySqlClientConfig,
): Promise<MySqlClient>

import { createMySqlClient } from "@probitas/client-sql-mysql";

const client = await createMySqlClient({
  url: "mysql://user:password@localhost:3306/testdb",
});

const result = await client.query<{ id: number; name: string }>(
  "SELECT * FROM users WHERE id = ?",
  [1],
);
if (result.ok) {
  console.log(result.rows[0]);  // { id: 1, name: "Alice" }
}

await client.close();

import { createMySqlClient } from "@probitas/client-sql-mysql";

const client = await createMySqlClient({
  url: {
    host: "localhost",
    port: 3306,
    username: "root",
    password: "password",
    database: "testdb",
  },
  pool: { connectionLimit: 20 },
});
await client.close();

import { createMySqlClient } from "@probitas/client-sql-mysql";
import type { SqlTransaction } from "@probitas/client-sql";

const client = await createMySqlClient({ url: "mysql://localhost:3306/testdb" });
const user = await client.transaction(async (tx: SqlTransaction) => {
  await tx.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
  return await tx.queryOne("SELECT LAST_INSERT_ID() as id");
});
await client.close();

import { createMySqlClient } from "@probitas/client-sql-mysql";

await using client = await createMySqlClient({
  url: "mysql://localhost:3306/testdb",
});

const result = await client.query("SELECT 1");
// Client automatically closed when scope exits

function isConnectionError(error: unknown): boolean

type MySqlErrorKind = "access_denied" | "connection_refused"

type SqlErrorKind = "query" | "constraint" | "deadlock" | "connection" | "unknown"

type SqlFailureError = SqlConnectionError | AbortError | TimeoutError

type SqlIsolationLevel = "read_uncommitted" | "read_committed" | "repeatable_read" | "serializable"

type SqlOperationError = QuerySyntaxError | ConstraintError | DeadlockError | SqlError

type SqlQueryResult<T = any> = SqlQueryResultSuccess<T> | SqlQueryResultError<T> | SqlQueryResultFailure<T>