@nextlyhq/adapter-postgres 0.0.1

package/dist/index.cjs

@@ -0,0 +1,679 @@
+'use strict';
+
+var adapterDrizzle = require('@nextlyhq/adapter-drizzle');
+var types = require('@nextlyhq/adapter-drizzle/types');
+var versionCheck = require('@nextlyhq/adapter-drizzle/version-check');
+var nodePostgres = require('drizzle-orm/node-postgres');
+var pg = require('pg');
+
+// src/index.ts
+
+// src/provider.ts
+function detectPostgresProvider(url, explicitProvider) {
+  if (explicitProvider) {
+    const normalized = explicitProvider.toLowerCase();
+    if (normalized === "neon" || normalized === "supabase" || normalized === "standard") {
+      return normalized;
+    }
+  }
+  if (url.includes(".neon.tech") || url.includes("neon.")) {
+    return "neon";
+  }
+  if (url.includes(".supabase.") || url.includes("supabase.")) {
+    return "supabase";
+  }
+  return "standard";
+}
+function getProviderDefaults(provider) {
+  switch (provider) {
+    case "neon":
+      return {
+        ssl: true,
+        poolMax: 5,
+        poolMin: 0,
+        idleTimeoutMs: 1e4,
+        connectionTimeoutMs: 2e4,
+        statementTimeoutMs: 3e4,
+        retryAttempts: 5
+      };
+    case "supabase":
+      return {
+        ssl: true,
+        poolMax: 5,
+        poolMin: 0,
+        idleTimeoutMs: 3e4,
+        connectionTimeoutMs: 15e3,
+        statementTimeoutMs: 15e3,
+        retryAttempts: 3
+      };
+    case "standard":
+    default:
+      return {
+        ssl: false,
+        poolMax: 10,
+        poolMin: 0,
+        idleTimeoutMs: 3e4,
+        connectionTimeoutMs: 15e3,
+        statementTimeoutMs: 15e3,
+        retryAttempts: 3
+      };
+  }
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+var DEFAULT_POOL_CONFIG = {
+  min: 0,
+  max: 5,
+  idleTimeoutMs: 3e4,
+  connectionTimeoutMs: 15e3
+};
+var PG_ERROR_CODES = {
+  // Class 08 - Connection Exception
+  "08000": "connection",
+  "08003": "connection",
+  "08006": "connection",
+  "08001": "connection",
+  "08004": "connection",
+  "08007": "connection",
+  "08P01": "connection",
+  // Class 23 - Integrity Constraint Violation
+  "23000": "constraint",
+  "23001": "constraint",
+  "23502": "not_null_violation",
+  "23503": "foreign_key_violation",
+  "23505": "unique_violation",
+  "23514": "check_violation",
+  "23P01": "constraint",
+  // Class 40 - Transaction Rollback
+  "40000": "query",
+  "40001": "serialization_failure",
+  "40002": "constraint",
+  "40003": "query",
+  "40P01": "deadlock",
+  // Class 57 - Operator Intervention
+  "57014": "timeout",
+  "57P01": "connection",
+  "57P02": "connection",
+  "57P03": "connection"
+};
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var PostgresAdapter = class extends adapterDrizzle.DrizzleAdapter {
+  /**
+   * The database dialect - always 'postgresql' for this adapter.
+   */
+  dialect = "postgresql";
+  /**
+   * Adapter configuration.
+   */
+  config;
+  /**
+   * Connection pool instance.
+   */
+  pool = null;
+  /**
+   * Connection state flag.
+   */
+  connected = false;
+  /**
+   * Auto-detected provider (Neon, Supabase, or standard).
+   * Set during connect() from DATABASE_URL pattern or DB_PROVIDER env var.
+   */
+  detectedProvider = "standard";
+  /**
+   * Provider-specific connection defaults. Applied as fallbacks when
+   * user config doesn't specify a value.
+   */
+  providerDefaults = getProviderDefaults("standard");
+  /**
+   * Creates a new PostgreSQL adapter instance.
+   *
+   * @param config - Adapter configuration
+   */
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  /**
+   * Establishes a connection to the PostgreSQL database.
+   *
+   * @remarks
+   * This method initializes the connection pool and verifies connectivity
+   * by executing a simple query. It is idempotent - calling it multiple
+   * times will not create multiple pools.
+   *
+   * @throws {DatabaseError} If connection fails
+   */
+  async connect() {
+    if (this.connected && this.pool) {
+      return;
+    }
+    const url = this.config.url || "";
+    this.detectedProvider = detectPostgresProvider(
+      url,
+      process.env.DB_PROVIDER
+    );
+    this.providerDefaults = getProviderDefaults(this.detectedProvider);
+    if (this.config.logger?.info) {
+      const source = process.env.DB_PROVIDER ? "(explicit)" : "(auto-detected)";
+      this.config.logger.info(
+        `PostgreSQL provider: ${this.detectedProvider} ${source}`,
+        {}
+      );
+    }
+    const retryableNodeCodes = /* @__PURE__ */ new Set([
+      "ETIMEDOUT",
+      "ECONNREFUSED",
+      "ECONNRESET",
+      "ENOTFOUND",
+      "EAI_AGAIN"
+    ]);
+    const maxAttempts = this.providerDefaults.retryAttempts;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const poolConfig = this.buildPoolConfig();
+        this.pool = new pg.Pool(poolConfig);
+        this.pool.on("error", (err) => {
+          if (this.config.logger?.error) {
+            this.config.logger.error(err, {
+              context: "pool_error",
+              message: "Unexpected error on idle client"
+            });
+          }
+        });
+        const client = await this.pool.connect();
+        try {
+          await client.query("SELECT 1");
+          await versionCheck.checkDialectVersion(client, "postgresql", {
+            // Why: route any future variant warnings through the adapter's
+            // logger. PG has no recognized variants today, but this keeps
+            // the integration symmetric with MySQL.
+            onWarning: (msg) => this.config.logger?.warn?.(msg)
+          });
+          this.connected = true;
+          if (this.config.logger?.info) {
+            this.config.logger.info("PostgreSQL connection established", {
+              host: this.config.host ?? "from URL",
+              database: this.config.database ?? "from URL"
+            });
+          }
+          return;
+        } finally {
+          client.release();
+        }
+      } catch (error) {
+        if (this.pool) {
+          await this.pool.end().catch(() => {
+          });
+          this.pool = null;
+        }
+        const nodeError = error;
+        const isRetryable = nodeError.code != null && retryableNodeCodes.has(nodeError.code);
+        if (isRetryable && attempt < maxAttempts) {
+          const waitMs = 1e3 * attempt;
+          const msg = `PostgreSQL connection attempt ${attempt}/${maxAttempts} failed with ${nodeError.code}, retrying in ${waitMs}ms...`;
+          if (this.config.logger?.warn) {
+            this.config.logger.warn(msg);
+          } else {
+            console.warn(`[PostgresAdapter] ${msg}`);
+          }
+          await delay(waitMs);
+          continue;
+        }
+        throw this.classifyError(error);
+      }
+    }
+  }
+  /**
+   * Closes the database connection and releases all pool resources.
+   *
+   * @remarks
+   * This method is idempotent - calling it multiple times is safe.
+   * It waits for all checked-out clients to be returned before shutting down.
+   */
+  async disconnect() {
+    if (!this.pool) {
+      return;
+    }
+    try {
+      await this.pool.end();
+      if (this.config.logger?.info) {
+        this.config.logger.info("PostgreSQL connection closed");
+      }
+    } finally {
+      this.pool = null;
+      this.connected = false;
+    }
+  }
+  /**
+   * Checks if the adapter is currently connected.
+   *
+   * @returns True if connected and pool is available
+   */
+  isConnected() {
+    return this.connected && this.pool !== null;
+  }
+  /**
+   * Executes a raw SQL query.
+   *
+   * @param sql - SQL statement with $1, $2, ... placeholders
+   * @param params - Query parameters
+   * @returns Array of result rows
+   *
+   * @throws {DatabaseError} If query execution fails
+   */
+  async executeQuery(sql, params = []) {
+    const pool = this.ensurePool();
+    const startTime = Date.now();
+    const retryableNodeCodes = /* @__PURE__ */ new Set([
+      "ETIMEDOUT",
+      "ECONNRESET",
+      "ECONNREFUSED"
+    ]);
+    const maxQueryAttempts = 3;
+    for (let attempt = 1; attempt <= maxQueryAttempts; attempt++) {
+      try {
+        const result = await pool.query(sql, params);
+        if (this.config.logger?.query) {
+          const durationMs = Date.now() - startTime;
+          this.config.logger.query(sql, params, durationMs);
+        }
+        return result.rows;
+      } catch (error) {
+        const nodeError = error;
+        const isRetryable = nodeError.code != null && retryableNodeCodes.has(nodeError.code);
+        if (isRetryable && attempt < maxQueryAttempts) {
+          const waitMs = 500 * attempt;
+          console.warn(
+            `[PostgresAdapter] Query attempt ${attempt}/${maxQueryAttempts} failed with ${nodeError.code}, retrying in ${waitMs}ms...`
+          );
+          await delay(waitMs);
+          continue;
+        }
+        throw this.classifyError(error, sql);
+      }
+    }
+    throw this.classifyError(new Error("executeQuery: exhausted retries"));
+  }
+  /**
+   * Executes a callback within a database transaction.
+   *
+   * @remarks
+   * PostgreSQL supports full ACID transactions with savepoints.
+   * If the callback throws, the transaction is rolled back.
+   *
+   * Supports automatic retry for serialization failures (40001) and
+   * deadlocks (40P01) when `retryCount` is specified in options.
+   *
+   * @param callback - Function to execute within the transaction
+   * @param options - Transaction options (isolation level, timeout, retry)
+   * @returns The result of the callback
+   *
+   * @throws {DatabaseError} If transaction fails after all retries
+   */
+  async transaction(callback, options) {
+    const pool = this.ensurePool();
+    const maxAttempts = (options?.retryCount ?? 0) + 1;
+    const retryDelayMs = options?.retryDelayMs ?? 100;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const client = await pool.connect();
+      const startTime = Date.now();
+      try {
+        await this.beginTransaction(client, options);
+        const ctx = this.createTransactionContext(client);
+        const result = await callback(ctx);
+        await client.query("COMMIT");
+        if (this.config.logger?.debug) {
+          const durationMs = Date.now() - startTime;
+          this.config.logger.debug("Transaction committed", {
+            attempt,
+            durationMs
+          });
+        }
+        return result;
+      } catch (error) {
+        await client.query("ROLLBACK").catch(() => {
+        });
+        lastError = error;
+        const pgError = error;
+        const isRetryable = pgError.code === "40001" || // serialization_failure
+        pgError.code === "40P01";
+        if (isRetryable && attempt < maxAttempts) {
+          if (this.config.logger?.warn) {
+            this.config.logger.warn(
+              `Transaction failed with ${pgError.code}, retrying (${attempt}/${maxAttempts})`,
+              { code: pgError.code, attempt }
+            );
+          }
+          await delay(retryDelayMs * attempt);
+          continue;
+        }
+        throw this.classifyError(error);
+      } finally {
+        client.release();
+      }
+    }
+    throw this.classifyError(lastError);
+  }
+  /**
+   * Returns the database capabilities for PostgreSQL.
+   *
+   * @remarks
+   * PostgreSQL has the most comprehensive feature set of all supported
+   * databases, including JSONB, arrays, full-text search, and more.
+   */
+  getCapabilities() {
+    return {
+      dialect: "postgresql",
+      supportsJsonb: true,
+      supportsJson: true,
+      supportsArrays: true,
+      supportsGeneratedColumns: true,
+      supportsFts: true,
+      supportsIlike: true,
+      supportsReturning: true,
+      supportsSavepoints: true,
+      supportsOnConflict: true,
+      maxParamsPerQuery: 65535,
+      // PostgreSQL limit
+      maxIdentifierLength: 63
+      // PostgreSQL default
+    };
+  }
+  /**
+   * Returns connection pool statistics.
+   *
+   * @returns Pool stats or null if not connected
+   */
+  getPoolStats() {
+    if (!this.pool) {
+      return null;
+    }
+    return {
+      total: this.pool.totalCount,
+      idle: this.pool.idleCount,
+      waiting: this.pool.waitingCount,
+      active: this.pool.totalCount - this.pool.idleCount
+    };
+  }
+  /**
+   * Override insertMany for bulk insert optimization.
+   *
+   * @remarks
+   * Uses a single multi-row INSERT statement for better performance
+   * when inserting multiple records.
+   */
+  async insertMany(table, data, options) {
+    if (data.length === 0) {
+      return [];
+    }
+    if (data.length === 1) {
+      const result = await this.insert(table, data[0], options);
+      return [result];
+    }
+    const columns = Object.keys(data[0]);
+    const params = [];
+    const valuesClauses = [];
+    for (let i = 0; i < data.length; i++) {
+      const record = data[i];
+      const placeholders = [];
+      for (const col of columns) {
+        params.push(record[col]);
+        placeholders.push(`$${params.length}`);
+      }
+      valuesClauses.push(`(${placeholders.join(", ")})`);
+    }
+    const columnList = columns.map((col) => this.escapeIdentifier(col)).join(", ");
+    let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columnList}) VALUES ${valuesClauses.join(", ")}`;
+    if (options?.returning) {
+      const returning = options.returning === "*" ? "*" : options.returning.map((col) => this.escapeIdentifier(col)).join(", ");
+      sql += ` RETURNING ${returning}`;
+    }
+    try {
+      return await this.executeQuery(sql, params);
+    } catch (error) {
+      throw this.handleQueryError(error, "insertMany", table);
+    }
+  }
+  // ============================================================
+  // Protected Helper Methods
+  // ============================================================
+  /**
+   * Ensures pool is connected and returns it.
+   *
+   * @throws {DatabaseError} If not connected
+   */
+  ensurePool() {
+    if (!this.pool) {
+      throw types.createDatabaseError({
+        kind: "connection",
+        message: "PostgresAdapter is not connected. Call connect() first."
+      });
+    }
+    return this.pool;
+  }
+  /**
+   * Return the typed Drizzle instance for PostgreSQL.
+   * Guarded for server-only usage and requires an active connection.
+   *
+   * @param schema - Optional schema for relational queries (db.query.*)
+   * @returns Drizzle ORM instance wrapping the pg pool connection
+   * @throws {Error} If called in browser or not connected
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  getDrizzle(schema) {
+    if (typeof window !== "undefined") {
+      throw new Error("getDrizzle() is server-only");
+    }
+    const pool = this.ensurePool();
+    return schema ? nodePostgres.drizzle(pool, { schema }) : nodePostgres.drizzle(pool);
+  }
+  /**
+   * Builds pg Pool configuration from adapter config.
+   */
+  buildPoolConfig() {
+    const config = {};
+    if (this.config.url) {
+      config.connectionString = this.config.url;
+    } else {
+      if (this.config.host) config.host = this.config.host;
+      if (this.config.port) config.port = this.config.port;
+      if (this.config.database) config.database = this.config.database;
+      if (this.config.user) config.user = this.config.user;
+      if (this.config.password) config.password = this.config.password;
+    }
+    config.min = this.config.pool?.min ?? this.providerDefaults.poolMin ?? DEFAULT_POOL_CONFIG.min;
+    config.max = this.config.pool?.max ?? this.providerDefaults.poolMax ?? DEFAULT_POOL_CONFIG.max;
+    config.idleTimeoutMillis = this.config.pool?.idleTimeoutMs ?? this.providerDefaults.idleTimeoutMs ?? DEFAULT_POOL_CONFIG.idleTimeoutMs;
+    config.connectionTimeoutMillis = this.config.pool?.connectionTimeoutMs ?? this.providerDefaults.connectionTimeoutMs ?? DEFAULT_POOL_CONFIG.connectionTimeoutMs;
+    config.keepAlive = true;
+    config.keepAliveInitialDelayMillis = 1e4;
+    if (this.config.ssl) {
+      if (typeof this.config.ssl === "boolean") {
+        config.ssl = this.config.ssl;
+      } else {
+        if (this.config.ssl.rejectUnauthorized === false) {
+          console.warn(
+            "[nextly/adapter-postgres] ssl.rejectUnauthorized is set to false \u2014 TLS certificates will not be validated. This is unsafe on untrusted networks. Provide a trusted `ca` cert instead, or remove the rejectUnauthorized override."
+          );
+        }
+        config.ssl = {
+          rejectUnauthorized: this.config.ssl.rejectUnauthorized,
+          ca: this.config.ssl.ca,
+          cert: this.config.ssl.cert,
+          key: this.config.ssl.key
+        };
+      }
+    } else if (this.providerDefaults.ssl) {
+      config.ssl = { rejectUnauthorized: true };
+    }
+    if (this.config.applicationName) {
+      config.application_name = this.config.applicationName;
+    }
+    if (this.config.statementTimeout) {
+      config.statement_timeout = this.config.statementTimeout;
+    }
+    if (this.config.queryTimeout) {
+      config.query_timeout = this.config.queryTimeout;
+    }
+    return config;
+  }
+  /**
+   * Begins a transaction with the specified options.
+   */
+  async beginTransaction(client, options) {
+    let beginSql = "BEGIN";
+    if (options?.isolationLevel) {
+      const isolationMap = {
+        "read uncommitted": "READ UNCOMMITTED",
+        "read committed": "READ COMMITTED",
+        "repeatable read": "REPEATABLE READ",
+        serializable: "SERIALIZABLE"
+      };
+      const level = isolationMap[options.isolationLevel];
+      if (level) {
+        beginSql += ` ISOLATION LEVEL ${level}`;
+      }
+    }
+    if (options?.readOnly) {
+      beginSql += " READ ONLY";
+    }
+    await client.query(beginSql);
+    if (options?.timeoutMs) {
+      await client.query(`SET LOCAL statement_timeout = ${options.timeoutMs}`);
+    }
+  }
+  /**
+   * Creates a TransactionContext for the given client.
+   */
+  createTransactionContext(client) {
+    return {
+      execute: async (sql, params = []) => {
+        const result = await client.query(sql, params);
+        return result.rows;
+      },
+      insert: async (table, data, options) => {
+        const columns = Object.keys(data);
+        const values = Object.values(data);
+        const placeholders = values.map((_, i) => `$${i + 1}`).join(", ");
+        let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES (${placeholders})`;
+        if (options?.returning) {
+          const returning = options.returning === "*" ? "*" : options.returning.map((col) => this.escapeIdentifier(col)).join(", ");
+          sql += ` RETURNING ${returning}`;
+        } else {
+          sql += " RETURNING *";
+        }
+        const result = await client.query(sql, values);
+        return result.rows[0];
+      },
+      insertMany: async (table, data, options) => {
+        if (data.length === 0) return [];
+        const columns = Object.keys(data[0]);
+        const params = [];
+        const valuesClauses = [];
+        for (const record of data) {
+          const placeholders = [];
+          for (const col of columns) {
+            params.push(record[col]);
+            placeholders.push(`$${params.length}`);
+          }
+          valuesClauses.push(`(${placeholders.join(", ")})`);
+        }
+        let sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES ${valuesClauses.join(", ")}`;
+        if (options?.returning) {
+          const returning = options.returning === "*" ? "*" : options.returning.map((col) => this.escapeIdentifier(col)).join(", ");
+          sql += ` RETURNING ${returning}`;
+        } else {
+          sql += " RETURNING *";
+        }
+        const result = await client.query(sql, params);
+        return result.rows;
+      },
+      // TransactionContext CRUD methods delegate to the adapter's CRUD
+      // which uses Drizzle query API via the TableResolver.
+      // The Drizzle transaction is handled at a higher level.
+      select: async (table, options) => {
+        return this.select(table, options);
+      },
+      selectOne: async (table, options) => {
+        return this.selectOne(table, options);
+      },
+      update: async (table, data, where, options) => {
+        return this.update(table, data, where, options);
+      },
+      delete: async (table, where, _options) => {
+        return this.delete(table, where);
+      },
+      upsert: async (table, data, options) => {
+        return this.upsert(table, data, options);
+      },
+      savepoint: async (name) => {
+        await client.query(`SAVEPOINT ${this.escapeIdentifier(name)}`);
+      },
+      rollbackToSavepoint: async (name) => {
+        await client.query(
+          `ROLLBACK TO SAVEPOINT ${this.escapeIdentifier(name)}`
+        );
+      },
+      releaseSavepoint: async (name) => {
+        await client.query(`RELEASE SAVEPOINT ${this.escapeIdentifier(name)}`);
+      }
+    };
+  }
+  /**
+   * Classifies a PostgreSQL error into a DatabaseError.
+   *
+   * @param error - Original error from pg
+   * @param sql - SQL statement that caused the error (optional)
+   * @returns DatabaseError with proper classification
+   */
+  classifyError(error, sql) {
+    if (types.isDatabaseError(error)) return error;
+    const pgError = error;
+    const kind = pgError.code && PG_ERROR_CODES[pgError.code] || "unknown";
+    let message = pgError.message ?? String(error);
+    if (sql && kind === "query") {
+      message = `Query failed: ${message}`;
+    }
+    return types.createDatabaseError({
+      kind,
+      message,
+      code: pgError.code,
+      constraint: pgError.constraint,
+      table: pgError.table,
+      column: pgError.column,
+      detail: pgError.detail,
+      hint: pgError.hint,
+      cause: error instanceof Error ? error : void 0
+    });
+  }
+  /**
+   * Override handleQueryError to use PostgreSQL-specific classification.
+   */
+  handleQueryError(error, operation, table) {
+    const dbError = this.classifyError(error);
+    if (!dbError.message.includes(operation)) {
+      dbError.message = `${operation} operation failed on table '${table}': ${dbError.message}`;
+    }
+    if (!dbError.table) {
+      dbError.table = table;
+    }
+    return dbError;
+  }
+};
+function createPostgresAdapter(config) {
+  return new PostgresAdapter(config);
+}
+function isPostgresAdapter(value) {
+  return value instanceof PostgresAdapter;
+}
+
+exports.PostgresAdapter = PostgresAdapter;
+exports.VERSION = VERSION;
+exports.createPostgresAdapter = createPostgresAdapter;
+exports.isPostgresAdapter = isPostgresAdapter;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map