singulio-postgres 1.1.0

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @singulio/postgres - Type Definitions
+ * PostgreSQL 18.x types for Bun native client
+ */
+/** Connection configuration */
+export interface PostgresConfig {
+    /** Connection string (postgres://user:pass@host:port/db) */
+    connectionString?: string;
+    /** Host (default: localhost) */
+    host?: string;
+    /** Port (default: 5432) */
+    port?: number;
+    /** Database name */
+    database?: string;
+    /** Username */
+    user?: string;
+    /** Password */
+    password?: string;
+    /** SSL mode */
+    ssl?: boolean | 'require' | 'prefer' | 'disable';
+    /** Application name for pg_stat_activity */
+    applicationName?: string;
+}
+/** Pool configuration */
+export interface PoolConfig extends PostgresConfig {
+    /** Minimum connections (default: 2) */
+    min?: number;
+    /** Maximum connections (default: 20) */
+    max?: number;
+    /** Idle timeout in ms (default: 30000) */
+    idleTimeout?: number;
+    /** Connection timeout in ms (default: 10000) */
+    connectionTimeout?: number;
+    /** Max lifetime per connection in ms (default: 3600000 = 1 hour) */
+    maxLifetime?: number;
+}
+/** RLS context for multi-tenant isolation */
+export interface RLSContext {
+    /** Tenant reference ID */
+    tenantId: string;
+    /** User ID (optional) */
+    userId?: string;
+    /** Is admin user (bypasses some RLS) */
+    isAdmin?: boolean;
+    /** Additional session GUCs */
+    extraGUCs?: Record<string, string>;
+}
+/** Query result row */
+export type QueryRow = Record<string, unknown>;
+/** Query result */
+export interface QueryResult<T = QueryRow> {
+    /** Result rows */
+    rows: T[];
+    /** Number of affected rows */
+    rowCount: number;
+    /** Field metadata */
+    fields?: FieldInfo[];
+}
+/** Field metadata */
+export interface FieldInfo {
+    name: string;
+    dataTypeID: number;
+    tableID?: number;
+    columnID?: number;
+}
+/** Transaction isolation levels */
+export type IsolationLevel = 'READ UNCOMMITTED' | 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE';
+/** Transaction options */
+export interface TransactionOptions {
+    /** Isolation level (default: READ COMMITTED) */
+    isolationLevel?: IsolationLevel;
+    /** Read-only transaction */
+    readOnly?: boolean;
+    /** Deferrable (only with SERIALIZABLE + readOnly) */
+    deferrable?: boolean;
+    /** RLS context to apply */
+    rlsContext?: RLSContext;
+}
+/** Health check result */
+export interface HealthCheckResult {
+    healthy: boolean;
+    latencyMs: number;
+    poolStats?: PoolStats;
+    error?: string;
+}
+/** Pool statistics */
+export interface PoolStats {
+    /** Total connections in pool */
+    total: number;
+    /** Idle connections */
+    idle: number;
+    /** Active connections */
+    active: number;
+    /** Pending connection requests */
+    pending: number;
+}
+/** Vector distance operators for pgvector */
+export type VectorDistanceOperator = '<->' | '<=>' | '<#>' | '<+>';
+/** Vector index types */
+export type VectorIndexType = 'hnsw' | 'ivfflat';
+/** Vector search options */
+export interface VectorSearchOptions {
+    /** Distance operator (default: <->) */
+    operator?: VectorDistanceOperator;
+    /** Maximum results (default: 10) */
+    limit?: number;
+    /** Minimum similarity threshold (optional) */
+    threshold?: number;
+    /** Additional WHERE clause */
+    filter?: string;
+    /** Filter parameters */
+    filterParams?: unknown[];
+}
+/** Logger interface (matches @singulio/logger) */
+export interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * @singulio/postgres - Type Definitions
+ * PostgreSQL 18.x types for Bun native client
+ */
+export {};

package/dist/vector.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @singulio/postgres - pgvector Extension Support
+ * Vector operations for AI/ML embeddings
+ */
+import type { VectorDistanceOperator, VectorIndexType, VectorSearchOptions, QueryResult, Logger } from './types.js';
+/** Vector type (array of numbers) */
+export type Vector = number[] | Float32Array | Float64Array;
+/**
+ * Format a vector for PostgreSQL insertion
+ * Converts array to '[1,2,3]' format expected by pgvector
+ */
+export declare function formatVector(vector: Vector): string;
+/**
+ * Parse a vector from PostgreSQL result
+ * Converts '[1,2,3]' string back to number array
+ */
+export declare function parseVector(value: string | number[] | null): number[] | null;
+/**
+ * Calculate vector dimension
+ */
+export declare function vectorDimension(vector: Vector): number;
+/**
+ * Normalize a vector to unit length (for cosine similarity)
+ */
+export declare function normalizeVector(vector: Vector): number[];
+/**
+ * Get the distance operator SQL string
+ */
+export declare function getDistanceOperator(op: VectorDistanceOperator): string;
+/**
+ * Get human-readable name for distance operator
+ */
+export declare function getDistanceOperatorName(op: VectorDistanceOperator): string;
+/**
+ * Ensure pgvector extension is installed
+ */
+export declare function ensureVectorExtension(): Promise<void>;
+/**
+ * Create a vector column on a table
+ */
+export declare function createVectorColumn(table: string, column: string, dimensions: number): Promise<void>;
+/**
+ * Create a vector index for similarity search
+ */
+export declare function createVectorIndex(table: string, column: string, indexType?: VectorIndexType, operator?: VectorDistanceOperator, options?: {
+    /** HNSW: max connections per layer (default: 16) */
+    m?: number;
+    /** HNSW: size of dynamic candidate list (default: 64) */
+    efConstruction?: number;
+    /** IVFFlat: number of lists (default: 100) */
+    lists?: number;
+}): Promise<void>;
+/**
+ * Search for similar vectors
+ */
+export declare function vectorSearch<T = Record<string, unknown>>(table: string, column: string, queryVector: Vector, options?: VectorSearchOptions, logger?: Logger): Promise<QueryResult<T & {
+    distance: number;
+}>>;
+/**
+ * Insert a row with vector data
+ */
+export declare function insertWithVector(table: string, data: Record<string, unknown>, vectorColumn: string, vector: Vector): Promise<QueryResult>;
+/**
+ * Update vector data for a row
+ */
+export declare function updateVector(table: string, idColumn: string, idValue: unknown, vectorColumn: string, vector: Vector): Promise<QueryResult>;
+/**
+ * Batch insert rows with vectors
+ */
+export declare function batchInsertWithVectors(table: string, columns: string[], vectorColumn: string, rows: Array<{
+    data: unknown[];
+    vector: Vector;
+}>): Promise<QueryResult>;
+//# sourceMappingURL=vector.d.ts.map

package/dist/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../src/vector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,MAAM,EACP,MAAM,YAAY,CAAC;AAEpB,qCAAqC;AACrC,MAAM,MAAM,MAAM,GAAG,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,MAAM,EAAE,GAAG,IAAI,CAc5E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAKxD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,sBAAsB,GAAG,MAAM,CAEtE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,sBAAsB,GAAG,MAAM,CAa1E;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3D;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,eAAwB,EACnC,QAAQ,GAAE,sBAA8B,EACxC,OAAO,CAAC,EAAE;IACR,oDAAoD;IACpD,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,EACjC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAyChD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CAetB;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC/C,OAAO,CAAC,WAAW,CAAC,CAkCtB"}

package/dist/vector.js

@@ -0,0 +1,223 @@
+/**
+ * @singulio/postgres - pgvector Extension Support
+ * Vector operations for AI/ML embeddings
+ */
+import { sql } from 'bun';
+/**
+ * Format a vector for PostgreSQL insertion
+ * Converts array to '[1,2,3]' format expected by pgvector
+ */
+export function formatVector(vector) {
+    const arr = Array.isArray(vector) ? vector : Array.from(vector);
+    return `[${arr.join(',')}]`;
+}
+/**
+ * Parse a vector from PostgreSQL result
+ * Converts '[1,2,3]' string back to number array
+ */
+export function parseVector(value) {
+    if (value === null)
+        return null;
+    // Already an array (some drivers return it parsed)
+    if (Array.isArray(value))
+        return value;
+    // Parse string format '[1,2,3]'
+    if (typeof value === 'string') {
+        const trimmed = value.replace(/^\[|\]$/g, '');
+        if (!trimmed)
+            return [];
+        return trimmed.split(',').map(Number);
+    }
+    return null;
+}
+/**
+ * Calculate vector dimension
+ */
+export function vectorDimension(vector) {
+    return Array.isArray(vector) ? vector.length : vector.length;
+}
+/**
+ * Normalize a vector to unit length (for cosine similarity)
+ */
+export function normalizeVector(vector) {
+    const arr = Array.isArray(vector) ? vector : Array.from(vector);
+    const magnitude = Math.sqrt(arr.reduce((sum, val) => sum + val * val, 0));
+    if (magnitude === 0)
+        return arr;
+    return arr.map(val => val / magnitude);
+}
+/**
+ * Get the distance operator SQL string
+ */
+export function getDistanceOperator(op) {
+    return op;
+}
+/**
+ * Get human-readable name for distance operator
+ */
+export function getDistanceOperatorName(op) {
+    switch (op) {
+        case '<->':
+            return 'L2 (Euclidean)';
+        case '<=>':
+            return 'Cosine';
+        case '<#>':
+            return 'Inner Product';
+        case '<+>':
+            return 'L1 (Manhattan)';
+        default:
+            return 'Unknown';
+    }
+}
+/**
+ * Ensure pgvector extension is installed
+ */
+export async function ensureVectorExtension() {
+    await sql `CREATE EXTENSION IF NOT EXISTS vector`;
+}
+/**
+ * Create a vector column on a table
+ */
+export async function createVectorColumn(table, column, dimensions) {
+    await sql.unsafe(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${column} vector(${dimensions})`);
+}
+/**
+ * Create a vector index for similarity search
+ */
+export async function createVectorIndex(table, column, indexType = 'hnsw', operator = '<->', options) {
+    const indexName = `idx_${table}_${column}_${indexType}`;
+    // Determine operator class
+    let opClass;
+    switch (operator) {
+        case '<=>':
+            opClass = 'vector_cosine_ops';
+            break;
+        case '<#>':
+            opClass = 'vector_ip_ops';
+            break;
+        case '<+>':
+            opClass = 'vector_l1_ops';
+            break;
+        default:
+            opClass = 'vector_l2_ops';
+    }
+    if (indexType === 'hnsw') {
+        const m = options?.m ?? 16;
+        const efConstruction = options?.efConstruction ?? 64;
+        await sql.unsafe(`
+      CREATE INDEX IF NOT EXISTS ${indexName}
+      ON ${table} USING hnsw (${column} ${opClass})
+      WITH (m = ${m}, ef_construction = ${efConstruction})
+    `);
+    }
+    else {
+        const lists = options?.lists ?? 100;
+        await sql.unsafe(`
+      CREATE INDEX IF NOT EXISTS ${indexName}
+      ON ${table} USING ivfflat (${column} ${opClass})
+      WITH (lists = ${lists})
+    `);
+    }
+}
+/**
+ * Search for similar vectors
+ */
+export async function vectorSearch(table, column, queryVector, options = {}, logger) {
+    const { operator = '<->', limit = 10, threshold, filter, filterParams = [] } = options;
+    const vectorStr = formatVector(queryVector);
+    const params = [vectorStr, ...filterParams, limit];
+    let whereClause = '';
+    if (filter) {
+        whereClause = `WHERE ${filter}`;
+    }
+    if (threshold !== undefined) {
+        const thresholdClause = `${column} ${operator} $1 < ${threshold}`;
+        whereClause = whereClause
+            ? `${whereClause} AND ${thresholdClause}`
+            : `WHERE ${thresholdClause}`;
+    }
+    const start = performance.now();
+    const result = await sql.unsafe(`
+    SELECT *, ${column} ${operator} $1 AS distance
+    FROM ${table}
+    ${whereClause}
+    ORDER BY ${column} ${operator} $1
+    LIMIT $${params.length}
+  `, params);
+    logger?.debug('Vector search completed', {
+        table,
+        column,
+        operator: getDistanceOperatorName(operator),
+        results: result.length,
+        latencyMs: (performance.now() - start).toFixed(2),
+    });
+    return {
+        rows: result,
+        rowCount: result.length,
+    };
+}
+/**
+ * Insert a row with vector data
+ */
+export async function insertWithVector(table, data, vectorColumn, vector) {
+    const columns = Object.keys(data);
+    const values = Object.values(data);
+    columns.push(vectorColumn);
+    values.push(formatVector(vector));
+    const placeholders = values.map((_, i) => `$${i + 1}`).join(', ');
+    const result = await sql.unsafe(`
+    INSERT INTO ${table} (${columns.join(', ')})
+    VALUES (${placeholders})
+    RETURNING *
+  `, values);
+    return {
+        rows: result,
+        rowCount: result.length,
+    };
+}
+/**
+ * Update vector data for a row
+ */
+export async function updateVector(table, idColumn, idValue, vectorColumn, vector) {
+    const result = await sql.unsafe(`
+    UPDATE ${table}
+    SET ${vectorColumn} = $1
+    WHERE ${idColumn} = $2
+    RETURNING *
+  `, [formatVector(vector), idValue]);
+    return {
+        rows: result,
+        rowCount: result.length,
+    };
+}
+/**
+ * Batch insert rows with vectors
+ */
+export async function batchInsertWithVectors(table, columns, vectorColumn, rows) {
+    if (rows.length === 0) {
+        return { rows: [], rowCount: 0 };
+    }
+    const allColumns = [...columns, vectorColumn];
+    const valueSets = [];
+    const params = [];
+    let paramIndex = 1;
+    for (const row of rows) {
+        const placeholders = [];
+        for (const value of row.data) {
+            placeholders.push(`$${paramIndex++}`);
+            params.push(value);
+        }
+        placeholders.push(`$${paramIndex++}`);
+        params.push(formatVector(row.vector));
+        valueSets.push(`(${placeholders.join(', ')})`);
+    }
+    const result = await sql.unsafe(`
+    INSERT INTO ${table} (${allColumns.join(', ')})
+    VALUES ${valueSets.join(', ')}
+    RETURNING *
+  `, params);
+    return {
+        rows: result,
+        rowCount: result.length,
+    };
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "singulio-postgres",
+  "version": "1.1.0",
+  "description": "PostgreSQL client wrapper with RLS, pooling, transactions, and pgvector support",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./pool": {
+      "types": "./dist/pool.d.ts",
+      "import": "./dist/pool.js"
+    },
+    "./rls": {
+      "types": "./dist/rls.d.ts",
+      "import": "./dist/rls.js"
+    },
+    "./vector": {
+      "types": "./dist/vector.d.ts",
+      "import": "./dist/vector.js"
+    },
+    "./transaction": {
+      "types": "./dist/transaction.d.ts",
+      "import": "./dist/transaction.js"
+    },
+    "./health": {
+      "types": "./dist/health.d.ts",
+      "import": "./dist/health.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "rls",
+    "pgvector",
+    "multi-tenant",
+    "database"
+  ],
+  "author": "Singulio",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/singuliodev/postgres.git"
+  },
+  "bugs": {
+    "url": "https://github.com/singuliodev/postgres/issues"
+  },
+  "homepage": "https://github.com/singuliodev/postgres#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "ia32",
+    "arm64",
+    "arm"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,153 @@
+/**
+ * @singulio/postgres - PostgreSQL Client
+ * Thin wrapper around bun:postgres native client
+ */
+
+import { sql } from 'bun';
+import type { PostgresConfig, QueryResult, QueryRow, Logger } from './types.js';
+
+/**
+ * PostgreSQL client wrapping Bun's native postgres driver
+ */
+export class PostgresClient {
+  private connectionString: string;
+  private logger?: Logger;
+  private connected = false;
+
+  constructor(config: PostgresConfig | string, logger?: Logger) {
+    this.connectionString =
+      typeof config === 'string' ? config : this.buildConnectionString(config);
+    this.logger = logger;
+  }
+
+  private buildConnectionString(config: PostgresConfig): string {
+    if (config.connectionString) return config.connectionString;
+
+    const {
+      host = 'localhost',
+      port = 5432,
+      database = 'postgres',
+      user = 'postgres',
+      password = '',
+      ssl,
+      applicationName,
+    } = config;
+
+    let connStr = `postgres://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}/${database}`;
+
+    const params: string[] = [];
+    if (ssl === true || ssl === 'require') {
+      params.push('sslmode=require');
+    } else if (ssl === 'prefer') {
+      params.push('sslmode=prefer');
+    }
+    if (applicationName) {
+      params.push(`application_name=${encodeURIComponent(applicationName)}`);
+    }
+
+    if (params.length > 0) {
+      connStr += '?' + params.join('&');
+    }
+
+    return connStr;
+  }
+
+  /**
+   * Execute a SQL query with parameters
+   */
+  async query<T = QueryRow>(queryText: string, params?: unknown[]): Promise<QueryResult<T>> {
+    const start = performance.now();
+
+    try {
+      // Use Bun's sql tagged template for parameterized queries
+      const result = await sql.unsafe(queryText, params ?? []);
+
+      const latency = performance.now() - start;
+      this.logger?.debug('Query executed', {
+        query: queryText.substring(0, 100),
+        params: params?.length ?? 0,
+        rows: result.length,
+        latencyMs: latency.toFixed(2),
+      });
+
+      return {
+        rows: result as T[],
+        rowCount: result.length,
+      };
+    } catch (error) {
+      const latency = performance.now() - start;
+      this.logger?.error('Query failed', {
+        query: queryText.substring(0, 100),
+        error: error instanceof Error ? error.message : String(error),
+        latencyMs: latency.toFixed(2),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Execute a query and return the first row or null
+   */
+  async queryOne<T = QueryRow>(queryText: string, params?: unknown[]): Promise<T | null> {
+    const result = await this.query<T>(queryText, params);
+    return result.rows[0] ?? null;
+  }
+
+  /**
+   * Execute a query and return all rows
+   */
+  async queryAll<T = QueryRow>(queryText: string, params?: unknown[]): Promise<T[]> {
+    const result = await this.query<T>(queryText, params);
+    return result.rows;
+  }
+
+  /**
+   * Execute a command (INSERT/UPDATE/DELETE) and return affected row count
+   */
+  async execute(queryText: string, params?: unknown[]): Promise<number> {
+    const result = await this.query(queryText, params);
+    return result.rowCount;
+  }
+
+  /**
+   * Check if connected and working
+   */
+  async ping(): Promise<boolean> {
+    try {
+      const result = await sql`SELECT 1 as ok`;
+      return result.length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get server version
+   */
+  async version(): Promise<string> {
+    const result = await sql`SELECT version()`;
+    return result[0]?.version ?? 'unknown';
+  }
+
+  /**
+   * Close all connections (for bun:postgres this is mostly a no-op as it manages connections)
+   */
+  async close(): Promise<void> {
+    this.connected = false;
+    this.logger?.info('PostgresClient closed');
+  }
+
+  /**
+   * Get connection string (for debugging, sensitive parts masked)
+   */
+  get maskedConnectionString(): string {
+    return this.connectionString.replace(/:([^@]+)@/, ':***@');
+  }
+}
+
+/**
+ * Create a new PostgresClient instance
+ */
+export function createClient(config: PostgresConfig | string, logger?: Logger): PostgresClient {
+  return new PostgresClient(config, logger);
+}