@agentuity/postgres 0.1.41

package/src/transaction.ts

@@ -0,0 +1,312 @@
+import type { SQL, SQLQuery } from 'bun';
+import { TransactionError } from './errors';
+
+/**
+ * Represents a PostgreSQL transaction with support for savepoints.
+ *
+ * Transactions are created via `PostgresClient.begin()` and support
+ * tagged template literal syntax for queries.
+ */
+export class Transaction {
+	private _sql: SQL;
+	private _connection: SQLQuery;
+	private _committed = false;
+	private _rolledBack = false;
+	private _savepointCounter = 0;
+
+	constructor(sql: SQL, connection: SQLQuery) {
+		this._sql = sql;
+		this._connection = connection;
+	}
+
+	/**
+	 * Whether the transaction has been committed.
+	 */
+	get committed(): boolean {
+		return this._committed;
+	}
+
+	/**
+	 * Whether the transaction has been rolled back.
+	 */
+	get rolledBack(): boolean {
+		return this._rolledBack;
+	}
+
+	/**
+	 * Whether the transaction is still active (not committed or rolled back).
+	 */
+	get active(): boolean {
+		return !this._committed && !this._rolledBack;
+	}
+
+	/**
+	 * Execute a query within this transaction using tagged template literal syntax.
+	 *
+	 * @example
+	 * ```typescript
+	 * const tx = await client.begin();
+	 * const result = await tx`SELECT * FROM users WHERE id = ${userId}`;
+	 * await tx.commit();
+	 * ```
+	 */
+	query(strings: TemplateStringsArray, ...values: unknown[]): SQLQuery {
+		this._ensureActive('query');
+		return this._sql(strings, ...values);
+	}
+
+	/**
+	 * Create a savepoint within this transaction.
+	 *
+	 * @param name - Optional name for the savepoint. If not provided, a unique name is generated.
+	 *               If provided, must be a valid SQL identifier (alphanumeric and underscores only,
+	 *               starting with a letter or underscore).
+	 * @returns A Savepoint object that can be used to rollback to this point.
+	 * @throws {TransactionError} If the provided name is not a valid SQL identifier.
+	 *
+	 * @example
+	 * ```typescript
+	 * const tx = await client.begin();
+	 * await tx`INSERT INTO users (name) VALUES ('Alice')`;
+	 *
+	 * const sp = await tx.savepoint();
+	 * await tx`INSERT INTO users (name) VALUES ('Bob')`;
+	 *
+	 * // Oops, rollback Bob but keep Alice
+	 * await sp.rollback();
+	 *
+	 * await tx.commit(); // Only Alice is committed
+	 * ```
+	 */
+	async savepoint(name?: string): Promise<Savepoint> {
+		this._ensureActive('savepoint');
+
+		const savepointName = name ?? `sp_${++this._savepointCounter}`;
+
+		// Validate savepoint name to prevent SQL injection
+		// Must be a valid SQL identifier: starts with letter or underscore, contains only alphanumeric and underscores
+		const validIdentifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+		if (!validIdentifierPattern.test(savepointName)) {
+			throw new TransactionError({
+				message: `Invalid savepoint name "${savepointName}": must be a valid SQL identifier (alphanumeric and underscores only, starting with a letter or underscore)`,
+				phase: 'savepoint',
+			});
+		}
+
+		try {
+			await this._sql`SAVEPOINT ${this._sql.unsafe(savepointName)}`;
+			return new Savepoint(this._sql, savepointName);
+		} catch (error) {
+			throw new TransactionError({
+				message: `Failed to create savepoint: ${error instanceof Error ? error.message : String(error)}`,
+				phase: 'savepoint',
+				cause: error,
+			});
+		}
+	}
+
+	/**
+	 * Commit the transaction.
+	 *
+	 * @throws {TransactionError} If the transaction is not active or commit fails.
+	 */
+	async commit(): Promise<void> {
+		this._ensureActive('commit');
+
+		try {
+			await this._sql`COMMIT`;
+			this._committed = true;
+		} catch (error) {
+			throw new TransactionError({
+				message: `Failed to commit transaction: ${error instanceof Error ? error.message : String(error)}`,
+				phase: 'commit',
+				cause: error,
+			});
+		}
+	}
+
+	/**
+	 * Rollback the transaction.
+	 *
+	 * @throws {TransactionError} If the transaction is not active or rollback fails.
+	 */
+	async rollback(): Promise<void> {
+		this._ensureActive('rollback');
+
+		try {
+			await this._sql`ROLLBACK`;
+			this._rolledBack = true;
+		} catch (error) {
+			throw new TransactionError({
+				message: `Failed to rollback transaction: ${error instanceof Error ? error.message : String(error)}`,
+				phase: 'rollback',
+				cause: error,
+			});
+		}
+	}
+
+	/**
+	 * Ensures the transaction is still active.
+	 */
+	private _ensureActive(operation: string): void {
+		if (this._committed) {
+			throw new TransactionError({
+				message: `Cannot ${operation}: transaction has been committed`,
+				phase: operation as 'begin' | 'commit' | 'rollback' | 'savepoint',
+			});
+		}
+		if (this._rolledBack) {
+			throw new TransactionError({
+				message: `Cannot ${operation}: transaction has been rolled back`,
+				phase: operation as 'begin' | 'commit' | 'rollback' | 'savepoint',
+			});
+		}
+	}
+}
+
+/**
+ * Represents a savepoint within a transaction.
+ */
+export class Savepoint {
+	private _sql: SQL;
+	private _name: string;
+	private _released = false;
+	private _rolledBack = false;
+
+	constructor(sql: SQL, name: string) {
+		this._sql = sql;
+		this._name = name;
+	}
+
+	/**
+	 * The name of this savepoint.
+	 */
+	get name(): string {
+		return this._name;
+	}
+
+	/**
+	 * Whether the savepoint has been released.
+	 */
+	get released(): boolean {
+		return this._released;
+	}
+
+	/**
+	 * Whether the savepoint has been rolled back to.
+	 */
+	get rolledBack(): boolean {
+		return this._rolledBack;
+	}
+
+	/**
+	 * Rollback to this savepoint.
+	 * All changes made after this savepoint was created will be undone.
+	 *
+	 * @throws {TransactionError} If the savepoint has been released or already rolled back.
+	 */
+	async rollback(): Promise<void> {
+		if (this._released) {
+			throw new TransactionError({
+				message: `Cannot rollback: savepoint "${this._name}" has been released`,
+				phase: 'savepoint',
+			});
+		}
+
+		if (this._rolledBack) {
+			throw new TransactionError({
+				message: `Cannot rollback: savepoint "${this._name}" has already been rolled back`,
+				phase: 'savepoint',
+			});
+		}
+
+		try {
+			await this._sql`ROLLBACK TO SAVEPOINT ${this._sql.unsafe(this._name)}`;
+			this._rolledBack = true;
+		} catch (error) {
+			throw new TransactionError({
+				message: `Failed to rollback to savepoint: ${error instanceof Error ? error.message : String(error)}`,
+				phase: 'savepoint',
+				cause: error,
+			});
+		}
+	}
+
+	/**
+	 * Release this savepoint.
+	 * The savepoint is destroyed but changes are kept.
+	 */
+	async release(): Promise<void> {
+		if (this._released) {
+			return; // Already released, no-op
+		}
+
+		try {
+			await this._sql`RELEASE SAVEPOINT ${this._sql.unsafe(this._name)}`;
+			this._released = true;
+		} catch (error) {
+			throw new TransactionError({
+				message: `Failed to release savepoint: ${error instanceof Error ? error.message : String(error)}`,
+				phase: 'savepoint',
+				cause: error,
+			});
+		}
+	}
+}
+
+/**
+ * Represents a reserved (exclusive) connection from the pool.
+ *
+ * Reserved connections are created via `PostgresClient.reserve()` and support
+ * tagged template literal syntax for queries.
+ */
+export class ReservedConnection {
+	private _sql: SQL;
+	private _released = false;
+
+	constructor(sql: SQL) {
+		this._sql = sql;
+	}
+
+	/**
+	 * Whether the connection has been released back to the pool.
+	 */
+	get released(): boolean {
+		return this._released;
+	}
+
+	/**
+	 * Execute a query on this reserved connection using tagged template literal syntax.
+	 *
+	 * @example
+	 * ```typescript
+	 * const conn = await client.reserve();
+	 * try {
+	 *   await conn`SET LOCAL timezone = 'UTC'`;
+	 *   const result = await conn`SELECT NOW()`;
+	 * } finally {
+	 *   conn.release();
+	 * }
+	 * ```
+	 */
+	query(strings: TemplateStringsArray, ...values: unknown[]): SQLQuery {
+		if (this._released) {
+			throw new TransactionError({
+				message: 'Cannot query: connection has been released',
+			});
+		}
+		return this._sql(strings, ...values);
+	}
+
+	/**
+	 * Release the connection back to the pool.
+	 */
+	release(): void {
+		if (this._released) {
+			return; // Already released, no-op
+		}
+		this._released = true;
+		// The underlying SQL connection will be returned to the pool
+		// when it goes out of scope or is explicitly closed
+	}
+}

package/src/types.ts

@@ -0,0 +1,250 @@
+/**
+ * TLS configuration options for PostgreSQL connections.
+ */
+export interface TLSConfig {
+	/**
+	 * Whether to require TLS for the connection.
+	 * - `true`: Require TLS (fail if not available)
+	 * - `false`: Disable TLS
+	 * - `'prefer'`: Use TLS if available, fall back to unencrypted
+	 */
+	require?: boolean | 'prefer';
+
+	/**
+	 * Whether to reject unauthorized certificates.
+	 * Set to `false` to allow self-signed certificates.
+	 */
+	rejectUnauthorized?: boolean;
+
+	/**
+	 * CA certificate(s) for verifying the server certificate.
+	 */
+	ca?: string | Buffer | (string | Buffer)[];
+
+	/**
+	 * Client certificate for mutual TLS authentication.
+	 */
+	cert?: string | Buffer;
+
+	/**
+	 * Client private key for mutual TLS authentication.
+	 */
+	key?: string | Buffer;
+}
+
+/**
+ * Configuration for automatic reconnection behavior.
+ */
+export interface ReconnectConfig {
+	/**
+	 * Maximum number of reconnection attempts before giving up.
+	 * @default 10
+	 */
+	maxAttempts?: number;
+
+	/**
+	 * Initial delay in milliseconds before the first reconnection attempt.
+	 * @default 100
+	 */
+	initialDelayMs?: number;
+
+	/**
+	 * Maximum delay in milliseconds between reconnection attempts.
+	 * @default 30000
+	 */
+	maxDelayMs?: number;
+
+	/**
+	 * Multiplier for exponential backoff.
+	 * @default 2
+	 */
+	multiplier?: number;
+
+	/**
+	 * Maximum random jitter in milliseconds to add to the delay.
+	 * Helps prevent thundering herd problems.
+	 * @default 1000
+	 */
+	jitterMs?: number;
+
+	/**
+	 * Whether to automatically reconnect on connection loss.
+	 * @default true
+	 */
+	enabled?: boolean;
+}
+
+/**
+ * Statistics about the connection state and reconnection history.
+ */
+export interface ConnectionStats {
+	/**
+	 * Whether the client is currently connected.
+	 */
+	connected: boolean;
+
+	/**
+	 * Whether a reconnection attempt is in progress.
+	 */
+	reconnecting: boolean;
+
+	/**
+	 * Total number of successful connections (including reconnections).
+	 */
+	totalConnections: number;
+
+	/**
+	 * Total number of reconnection attempts.
+	 */
+	reconnectAttempts: number;
+
+	/**
+	 * Total number of failed reconnection attempts.
+	 */
+	failedReconnects: number;
+
+	/**
+	 * Timestamp of the last successful connection.
+	 */
+	lastConnectedAt: Date | null;
+
+	/**
+	 * Timestamp of the last disconnection.
+	 */
+	lastDisconnectedAt: Date | null;
+
+	/**
+	 * Timestamp of the last reconnection attempt.
+	 */
+	lastReconnectAttemptAt: Date | null;
+}
+
+/**
+ * PostgreSQL connection configuration options.
+ * Extends Bun.SQL options with reconnection configuration.
+ */
+export interface PostgresConfig {
+	/**
+	 * PostgreSQL connection URL.
+	 * If not provided, uses `process.env.DATABASE_URL`.
+	 */
+	url?: string;
+
+	/**
+	 * Database hostname.
+	 */
+	hostname?: string;
+
+	/**
+	 * Database port.
+	 * @default 5432
+	 */
+	port?: number;
+
+	/**
+	 * Database username.
+	 */
+	username?: string;
+
+	/**
+	 * Database password.
+	 */
+	password?: string;
+
+	/**
+	 * Database name.
+	 */
+	database?: string;
+
+	/**
+	 * TLS configuration.
+	 */
+	tls?: TLSConfig | boolean;
+
+	/**
+	 * Maximum number of connections in the pool.
+	 * @default 10
+	 */
+	max?: number;
+
+	/**
+	 * Connection timeout in milliseconds.
+	 * @default 30000
+	 */
+	connectionTimeout?: number;
+
+	/**
+	 * Idle timeout in milliseconds.
+	 * @default 0 (no timeout)
+	 */
+	idleTimeout?: number;
+
+	/**
+	 * Reconnection configuration.
+	 */
+	reconnect?: ReconnectConfig;
+
+	/**
+	 * Whether to establish a connection immediately on client creation.
+	 * If true, the client will execute a test query (SELECT 1) to verify
+	 * the connection is working. If false (default), the connection is
+	 * established lazily on first query.
+	 *
+	 * Note: Even with preconnect=false, the underlying Bun.SQL client is
+	 * created immediately, but the actual TCP connection is deferred.
+	 *
+	 * @default false
+	 */
+	preconnect?: boolean;
+
+	/**
+	 * Callback invoked when the connection is closed.
+	 */
+	onclose?: (error?: Error) => void;
+
+	/**
+	 * Callback invoked when reconnection starts.
+	 */
+	onreconnect?: (attempt: number) => void;
+
+	/**
+	 * Callback invoked when reconnection succeeds.
+	 */
+	onreconnected?: () => void;
+
+	/**
+	 * Callback invoked when reconnection fails permanently.
+	 */
+	onreconnectfailed?: (error: Error) => void;
+}
+
+/**
+ * Options for creating a transaction.
+ */
+export interface TransactionOptions {
+	/**
+	 * Transaction isolation level.
+	 */
+	isolationLevel?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable';
+
+	/**
+	 * Whether the transaction is read-only.
+	 */
+	readOnly?: boolean;
+
+	/**
+	 * Whether the transaction is deferrable.
+	 * Only applicable for serializable read-only transactions.
+	 */
+	deferrable?: boolean;
+}
+
+/**
+ * Options for reserving a connection.
+ */
+export interface ReserveOptions {
+	/**
+	 * Timeout in milliseconds for acquiring a connection from the pool.
+	 */
+	timeout?: number;
+}