ts-prorm-orm 1.1.0 → 1.2.1

package/dist/dialects/yugabytedb/index.d.ts

@@ -0,0 +1,276 @@
+/**
+ * YugabyteDB dialect implementation for the TypeScript ORM
+ *
+ * YugabyteDB's YSQL API reuses the PostgreSQL query layer (it is literally
+ * forked from the PostgreSQL source), so it speaks the PostgreSQL wire
+ * protocol and is largely SQL-compatible with PostgreSQL. This dialect
+ * therefore `extends PostgresDialect` and reuses the same `pg` driver
+ * (`library === 'pg'`). Notable differences from the Postgres dialect that
+ * this class layers on top:
+ *
+ * - Default port is 5433 (not Postgres's 5432). YugabyteDB's YSQL server
+ *   listens on 5433 by default; 5432 is used by other services in some
+ *   deployments.
+ * - `SPLIT INTO n TABLETS` / `SPLIT AT VALUES (...)`: because YugabyteDB
+ *   shards ("tablets") tables across nodes, `CREATE TABLE`/`CREATE INDEX`
+ *   accepts pre-splitting clauses to control the initial tablet layout.
+ *   `SPLIT INTO n TABLETS` presplits a hash-sharded table/index into `n`
+ *   tablets; `SPLIT AT VALUES ((a), (b), ...)` presplits a range-sharded
+ *   table/index at the given range boundaries. See
+ *   https://docs.yugabyte.com/preview/api/ysql/the-sql-language/statements/ddl_create_table/#split-into
+ * - Colocated tables: small tables can be co-located onto a single tablet
+ *   with `WITH (colocated = true)` (older syntax) / `WITH (colocation = true)`
+ *   to avoid the overhead of a tablet-per-table. See
+ *   https://docs.yugabyte.com/preview/architecture/docdb-sharding/colocated-tables/
+ * - Primary-key column ordering: unlike Postgres, a YugabyteDB primary key
+ *   column carries a sharding/sort directive — `HASH` (hash-sharded, the
+ *   default for the first PK column) or `ASC`/`DESC` (range-sharded). This is
+ *   emitted as `PRIMARY KEY (id HASH, created_at DESC)`. See
+ *   https://docs.yugabyte.com/preview/architecture/docdb-sharding/sharding/
+ * - `CREATE TABLEGROUP`: YugabyteDB groups tables that should share tablets
+ *   into a tablegroup; `createTableGroup()` is a small helper that emits the
+ *   DDL and `buildCreateTableGroupSQL()` builds it synchronously.
+ *
+ * Behavioral notes shared with PostgreSQL (inherited, called out here so
+ * callers know the caveats):
+ * - Because YSQL is the PostgreSQL wire protocol, connection handling,
+ *   parameter binding, transactions, and most query building are inherited
+ *   unchanged from {@link PostgresDialect}.
+ * - `CREATE INDEX ... CONCURRENTLY` behaves differently: in YugabyteDB online
+ *   index backfill is the default mechanism and `CONCURRENTLY` has its own
+ *   semantics/restrictions (and cannot run inside a transaction block), so it
+ *   should not be assumed to behave identically to vanilla PostgreSQL.
+ * - Some PostgreSQL system-catalog (`pg_catalog`) internals differ: YugabyteDB
+ *   emulates the catalogs for compatibility but a handful of columns/values
+ *   reflect its distributed storage rather than a single-node heap.
+ */
+import { PostgresDialect, PostgresDialectOptions, PostgresTransaction } from '../postgres/index';
+import { ColumnDefinition, TableOptions, IndexOptions } from '../dialect';
+import { QueryOptions, QueryResult, TransactionOptions } from '../../types';
+/**
+ * Sharding/sort directive for a single YugabyteDB primary-key column.
+ *
+ * - `HASH`  — hash-shard on this column (the storage is distributed by a hash
+ *   of the column; only meaningful on leading PK columns).
+ * - `ASC` / `DESC` — range-shard, storing rows in ascending/descending order
+ *   of this column.
+ */
+export type YugabytePrimaryKeyOrder = 'HASH' | 'ASC' | 'DESC';
+/** A single primary-key column together with its sharding/sort directive. */
+export interface YugabytePrimaryKeyColumn {
+    /** Column name */
+    name: string;
+    /** Sharding/sort order for this PK column (`HASH` / `ASC` / `DESC`). */
+    order?: YugabytePrimaryKeyOrder;
+}
+/**
+ * YugabyteDB-specific `CREATE TABLE` options. These extend the shared
+ * {@link TableOptions} with YugabyteDB's distributed-storage knobs. Passed
+ * alongside the common options to {@link YugabyteDBDialect.buildCreateTableSQL}
+ * / {@link YugabyteDBDialect.createTable}.
+ */
+export interface YugabyteTableOptions extends TableOptions {
+    /**
+     * Table-level primary key with per-column sharding/sort directives, emitted
+     * as `PRIMARY KEY (col HASH, col2 ASC, ...)`. Use this (instead of the
+     * column-level `primaryKey: true`) when the PK needs an explicit `HASH` /
+     * `ASC` / `DESC` layout.
+     */
+    primaryKey?: YugabytePrimaryKeyColumn[];
+    /**
+     * Presplit a hash-sharded table into this many tablets:
+     * `SPLIT INTO n TABLETS`.
+     */
+    splitIntoTablets?: number;
+    /**
+     * Presplit a range-sharded table at the given boundaries:
+     * `SPLIT AT VALUES ((a), (b), ...)`. Each inner array is one split point's
+     * column value(s).
+     */
+    splitAtValues?: Array<Array<string | number>>;
+    /**
+     * Co-locate this table onto the database's colocation tablet:
+     * `WITH (colocated = true)`.
+     */
+    colocated?: boolean;
+    /** Alias for {@link YugabyteTableOptions.colocated} using the newer keyword `colocation`. */
+    colocation?: boolean;
+    /** Place the table in a tablegroup: `TABLEGROUP name`. */
+    tablegroup?: string;
+}
+/** Options for {@link YugabyteDBDialect.createTableGroup}. */
+export interface YugabyteCreateTableGroupOptions {
+    /** Emit `IF NOT EXISTS`. */
+    ifNotExists?: boolean;
+    /** Owner role for the tablegroup (`OWNER role`). */
+    owner?: string;
+}
+/**
+ * YugabyteDB connection options — identical to {@link PostgresDialectOptions}
+ * (same `pg` driver), just defaulting to port 5433.
+ */
+export interface YugabyteDBDialectOptions extends PostgresDialectOptions {
+}
+/**
+ * Options for {@link YugabyteDBDialect.runTransaction}: the standard
+ * {@link TransactionOptions} plus a `maxRetries` cap on how many times the
+ * transaction body is re-run after a retryable (serialization/conflict) error.
+ */
+export interface YugabyteRunTransactionOptions extends TransactionOptions {
+    /**
+     * Maximum number of times the transaction body is retried after a retryable
+     * error (SQLSTATE 40001 serialization failure, 40P01 deadlock, or a
+     * YugabyteDB "Restart read required"/conflict abort) before the error is
+     * rethrown. Defaults to 5.
+     */
+    maxRetries?: number;
+}
+/**
+ * YugabyteDB dialect. Postgres-wire-compatible: reuses the `pg` driver and the
+ * PostgreSQL query-building layer, layering on YugabyteDB's distributed-table
+ * DDL (tablet splitting, colocation, hash/range primary keys, tablegroups).
+ */
+export declare class YugabyteDBDialect extends PostgresDialect {
+    readonly name: YugabyteDBDialect["name"];
+    constructor(config: YugabyteDBDialectOptions);
+    /** Default cap on transaction/statement retries after a retryable error. */
+    private static readonly DEFAULT_MAX_RETRIES;
+    /**
+     * Determine whether an error signals that the client should retry the
+     * transaction (or statement) that produced it. Detects the SQLSTATE codes
+     * (`40001`, `40P01`) as well as YugabyteDB's textual conflict/read-restart
+     * signals, which some driver/wrapper paths surface without a `.code`.
+     */
+    isRetryableError(error: unknown): boolean;
+    /** Sleep with capped exponential backoff + jitter for retry attempt `n` (1-based). */
+    private backoffDelay;
+    /**
+     * Execute a single SQL statement, automatically retrying it on a retryable
+     * serialization/conflict error. Statements run through {@link query} are
+     * auto-committed by the server, so retrying the whole statement is safe and
+     * correct. Statements executed inside an explicit transaction go through the
+     * transaction's own client (not this method), so they are unaffected — use
+     * {@link runTransaction} to retry a multi-statement unit of work atomically.
+     */
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Run a function inside a YugabyteDB transaction, retrying the *entire
+     * transaction body* on a retryable serialization/conflict error (SQLSTATE
+     * `40001`/`40P01`, or a "Restart read required"/conflict abort). This
+     * implements YugabyteDB's documented client-side retry contract: on a
+     * retryable failure the transaction is rolled back and re-run from the
+     * beginning on a fresh connection.
+     *
+     * @param fn - Callback that receives the transaction and performs the work to
+     *   (re)try. It may be invoked more than once, so it must be idempotent apart
+     *   from its database effects (which are rolled back between attempts).
+     * @param options - Transaction options plus an optional `maxRetries` (default
+     *   5) capping how many times `fn` is retried before the error is rethrown.
+     */
+    runTransaction<T>(fn: (tx: PostgresTransaction) => Promise<T>, options?: YugabyteRunTransactionOptions): Promise<T>;
+    /**
+     * Quote a `SPLIT AT VALUES` / `PRIMARY KEY` scalar for inlining into DDL:
+     * numbers pass through, everything else is single-quoted and escaped.
+     */
+    private quoteSplitValue;
+    /**
+     * Build the trailing YugabyteDB-specific clauses for a `CREATE TABLE`
+     * statement (colocation, tablegroup, tablet splitting), in the order
+     * YugabyteDB expects them. Returns an empty string when none apply.
+     */
+    private buildYugabyteTableClauses;
+    /**
+     * Format a column `DEFAULT` value for inlining into DDL. Mirrors the base
+     * PostgreSQL dialect's behavior (which lives in a private helper we cannot
+     * call from here): numbers/booleans pass through; strings that look like a
+     * SQL function call (`gen_random_uuid()`), a `CURRENT_*` keyword, or `NULL`
+     * are emitted raw rather than quoted; `DataType` instances that expose
+     * `toDefaultValue()` (e.g. `DataTypes.NOW`) delegate to it; everything else
+     * is single-quoted and escaped.
+     */
+    private formatDefaultValue;
+    /**
+     * Emit a column-level `REFERENCES` (foreign key) clause, if the column
+     * carries one. Handles composite reference targets.
+     */
+    private buildColumnReferencesSql;
+    /**
+     * Build a single column definition for a `CREATE TABLE` statement. Kept
+     * self-contained (rather than reusing the base class's private helper) so
+     * this dialect can synchronously assemble DDL. Column-level `primaryKey` is
+     * intentionally NOT emitted here — YugabyteDB primary keys are emitted as a
+     * table-level `PRIMARY KEY (...)` (see {@link buildPrimaryKeyClause}) so the
+     * per-column `HASH`/`ASC`/`DESC` directive can be attached.
+     */
+    private buildColumnDefinitionSql;
+    /**
+     * Build a table-level constraint clause (`PRIMARY KEY`/`UNIQUE`/
+     * `FOREIGN KEY`/`CHECK`) for inlining into a `CREATE TABLE` statement.
+     * Mirrors the base PostgreSQL dialect's private helper (which we cannot call
+     * from here). Returns null for an unrecognized/empty constraint.
+     */
+    private buildYbConstraintSql;
+    /**
+     * Build the table-level `PRIMARY KEY (col HASH, col2 ASC, ...)` clause from
+     * either the explicit {@link YugabyteTableOptions.primaryKey} directive list
+     * or, failing that, any columns flagged with column-level `primaryKey: true`
+     * (which get no explicit sharding directive). Returns null when there is no
+     * primary key to emit.
+     */
+    private buildPrimaryKeyClause;
+    /**
+     * Synchronously build a YugabyteDB `CREATE TABLE` statement, including the
+     * distributed-table clauses (hash/range primary key, colocation,
+     * tablegroup, tablet splitting). Used by {@link createTable} and directly
+     * testable without a live connection.
+     */
+    buildCreateTableSQL(tableName: string, columns: Record<string, ColumnDefinition>, options?: YugabyteTableOptions): string;
+    /**
+     * Create a new table. Overrides {@link PostgresDialect.createTable} so the
+     * YugabyteDB-specific clauses (tablet splitting, colocation, hash/range
+     * primary keys, tablegroup) are emitted. Falls back to the inherited
+     * Postgres implementation when no YugabyteDB-specific option is present, so
+     * indexes/comments/uniqueKeys handling is preserved for the common case.
+     */
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: YugabyteTableOptions): Promise<void>;
+    /**
+     * Emit the follow-up statements PostgresDialect runs after `CREATE TABLE`
+     * (unique keys, table comment, sequence start value, secondary indexes).
+     * Kept here because the base dialect performs them inline in its own
+     * `createTable`, which the YugabyteDB custom-DDL path bypasses.
+     */
+    private applyPostCreateTableSteps;
+    /**
+     * Add an index to a table.
+     *
+     * Overrides {@link PostgresDialect.addIndex} only to account for
+     * YugabyteDB's `CREATE INDEX ... CONCURRENTLY` divergence: in YugabyteDB
+     * index backfill is already online by default, and `CONCURRENTLY` carries
+     * different semantics/restrictions (notably it cannot run inside a
+     * transaction block). Like the CockroachDB dialect, a requested
+     * `concurrently` flag is ignored (with a warning) rather than emitted, so
+     * the generated SQL stays safe to run in the common (transactional) case.
+     * All other index-building behavior is inherited unchanged.
+     */
+    addIndex(tableName: string, indexName: string, fields?: string[], options?: IndexOptions): Promise<void>;
+    /**
+     * Build a `CREATE TABLEGROUP` statement synchronously.
+     */
+    buildCreateTableGroupSQL(name: string, options?: YugabyteCreateTableGroupOptions): string;
+    /**
+     * Create a tablegroup (`CREATE TABLEGROUP name`). Tables created with the
+     * `tablegroup` option share the tablegroup's tablets.
+     */
+    createTableGroup(name: string, options?: YugabyteCreateTableGroupOptions): Promise<void>;
+    /**
+     * Drop a tablegroup (`DROP TABLEGROUP [IF EXISTS] name`).
+     */
+    dropTableGroup(name: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Create a new YugabyteDB dialect instance.
+ */
+export declare function createYugabyteDBDialect(options?: YugabyteDBDialectOptions): YugabyteDBDialect;
+export default YugabyteDBDialect;

package/dist/dialects/yugabytedb/index.js

@@ -63,6 +63,108 @@ class YugabyteDBDialect extends index_1.PostgresDialect {
         // pg driver, so `library` ('pg') is inherited unchanged.
         this.name = 'yugabytedb';
     }
+    /**
+     * Determine whether an error signals that the client should retry the
+     * transaction (or statement) that produced it. Detects the SQLSTATE codes
+     * (`40001`, `40P01`) as well as YugabyteDB's textual conflict/read-restart
+     * signals, which some driver/wrapper paths surface without a `.code`.
+     */
+    isRetryableError(error) {
+        if (!error) {
+            return false;
+        }
+        const err = error;
+        if (err.code === '40001' || err.code === '40P01') {
+            return true;
+        }
+        if (err.cause && err.cause !== error && this.isRetryableError(err.cause)) {
+            return true;
+        }
+        const message = typeof err.message === 'string' ? err.message : String(error);
+        const normalized = message.toLowerCase();
+        return (message.includes('40001') ||
+            message.includes('40P01') ||
+            normalized.includes('serialization_failure') ||
+            normalized.includes('could not serialize') ||
+            normalized.includes('restart read required') ||
+            normalized.includes('read restart') ||
+            normalized.includes('restart transaction') ||
+            normalized.includes('conflicts with higher priority transaction') ||
+            normalized.includes('conflicts with committed transaction') ||
+            normalized.includes('transaction aborted') ||
+            normalized.includes('all transparent retries exhausted') ||
+            normalized.includes('operation expired'));
+    }
+    /** Sleep with capped exponential backoff + jitter for retry attempt `n` (1-based). */
+    async backoffDelay(attempt) {
+        const base = 50;
+        const max = 2000;
+        const delay = Math.min(max, base * 2 ** (attempt - 1));
+        const jittered = delay / 2 + Math.random() * (delay / 2);
+        await new Promise((resolve) => setTimeout(resolve, jittered));
+    }
+    /**
+     * Execute a single SQL statement, automatically retrying it on a retryable
+     * serialization/conflict error. Statements run through {@link query} are
+     * auto-committed by the server, so retrying the whole statement is safe and
+     * correct. Statements executed inside an explicit transaction go through the
+     * transaction's own client (not this method), so they are unaffected — use
+     * {@link runTransaction} to retry a multi-statement unit of work atomically.
+     */
+    async query(sql, options) {
+        const maxRetries = YugabyteDBDialect.DEFAULT_MAX_RETRIES;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await super.query(sql, options);
+            }
+            catch (error) {
+                if (attempt < maxRetries && this.isRetryableError(error)) {
+                    await this.backoffDelay(attempt + 1);
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    /**
+     * Run a function inside a YugabyteDB transaction, retrying the *entire
+     * transaction body* on a retryable serialization/conflict error (SQLSTATE
+     * `40001`/`40P01`, or a "Restart read required"/conflict abort). This
+     * implements YugabyteDB's documented client-side retry contract: on a
+     * retryable failure the transaction is rolled back and re-run from the
+     * beginning on a fresh connection.
+     *
+     * @param fn - Callback that receives the transaction and performs the work to
+     *   (re)try. It may be invoked more than once, so it must be idempotent apart
+     *   from its database effects (which are rolled back between attempts).
+     * @param options - Transaction options plus an optional `maxRetries` (default
+     *   5) capping how many times `fn` is retried before the error is rethrown.
+     */
+    async runTransaction(fn, options) {
+        const maxRetries = options?.maxRetries ?? YugabyteDBDialect.DEFAULT_MAX_RETRIES;
+        for (let attempt = 0;; attempt++) {
+            const transaction = (await this.startTransaction(options));
+            try {
+                const result = await fn(transaction);
+                await this.commitTransaction(transaction);
+                return result;
+            }
+            catch (error) {
+                try {
+                    await this.rollbackTransaction(transaction);
+                }
+                catch {
+                    // The connection/transaction may already be unusable after the abort;
+                    // ignore the rollback failure and act on the original error.
+                }
+                if (attempt < maxRetries && this.isRetryableError(error)) {
+                    await this.backoffDelay(attempt + 1);
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
     /**
      * Quote a `SPLIT AT VALUES` / `PRIMARY KEY` scalar for inlining into DDL:
      * numbers pass through, everything else is single-quoted and escaped.
@@ -415,6 +517,25 @@ class YugabyteDBDialect extends index_1.PostgresDialect {
     }
 }
 exports.YugabyteDBDialect = YugabyteDBDialect;
+// ---------------------------------------------------------------------------
+// Distributed transaction retry.
+//
+// YugabyteDB is a distributed, strongly-consistent SQL database. Like
+// CockroachDB (and unlike single-node Postgres), concurrent transactions can
+// abort mid-flight with a serialization/conflict error that the client is
+// expected to retry — SQLSTATE 40001 ("could not serialize"), 40P01
+// (deadlock), or a YugabyteDB-specific "Restart read required"/"conflicts
+// with ... transaction" abort. The inherited Postgres dialect performs no
+// such retry (its query() only retries connection-level errors, and only when
+// an explicit `retry` option is passed), so YugabyteDB layers automatic retry
+// on top: single statements retry in `query()`, and multi-statement units of
+// work retry as a whole via `runTransaction()`.
+//
+// @see https://docs.yugabyte.com/preview/architecture/transactions/read-restart-error/
+// @see https://docs.yugabyte.com/preview/develop/learn/transactions/transactions-retries-ysql/
+// ---------------------------------------------------------------------------
+/** Default cap on transaction/statement retries after a retryable error. */
+YugabyteDBDialect.DEFAULT_MAX_RETRIES = 5;
 /**
  * Create a new YugabyteDB dialect instance.
  */