@atscript/db-postgres 0.1.152 → 0.1.154

package/dist/index.cjs

@@ -192,6 +192,7 @@ const pgDialect = {
 		return zone === void 0 ? void 0 : (0, _atscript_db.bucketTimeZoneUnavailable)(`PostgreSQL does not recognize time zone "${zone}" — update the server's time zone data`);
 	},
 	nullsSortLargest: true,
+	nullsPlacementSyntax: true,
 	createViewPrefix: "CREATE OR REPLACE VIEW",
 	paramPlaceholder(index) {
 		return `$${index}`;
@@ -570,6 +571,12 @@ function parseCount(value) {
 /** The suffix PostgreSQL gives an auto-named constraint of each `pg_constraint.contype`. */
 /** Savepoint guarding one `insertManyIgnore` chunk (see {@link PostgresAdapter.insertManyIgnore}). */
 const IGNORE_SAVEPOINT = "atscript_ignore_chunk";
+/** Retryable concurrency SQLSTATEs (see `PostgresAdapter._mapConstraintError`). */
+const PG_CONTENTION_CODES = {
+	"40P01": "DEADLOCK",
+	"55P03": "LOCK_TIMEOUT",
+	"40001": "SERIALIZATION_FAILURE"
+};
 const PG_CONSTRAINT_LABELS = {
 	p: "pkey",
 	u: "key",
@@ -788,6 +795,10 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	supportsAggregateExpressions() {
 		return true;
 	}
+	/** `$nulls` / `@db.sort.nulls` NULL placement — `NULLS FIRST` / `NULLS LAST`. */
+	supportsNullsPlacement() {
+		return true;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return _atscript_db.ALL_VIEW_CAPABILITIES;
@@ -865,6 +876,9 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	* PostgreSQL uses SQLSTATE codes:
 	* - 23505 = unique_violation
 	* - 23503 = foreign_key_violation
+	* - 40P01 = deadlock_detected → `DEADLOCK`
+	* - 55P03 = lock_not_available (`lock_timeout`, `NOWAIT`) → `LOCK_TIMEOUT`
+	* - 40001 = serialization_failure → `SERIALIZATION_FAILURE`
 	*/
 	async _wrapConstraintError(fn) {
 		try {
@@ -873,7 +887,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 			return this._mapConstraintError(error);
 		}
 	}
-	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock timeout, else as is. */
 	_mapConstraintError(error) {
 		if (error && typeof error === "object" && "code" in error) {
 			const err = error;
@@ -882,6 +896,11 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 				message: err.detail ?? err.message
 			}]);
 			if (err.code === "23503") throw new _atscript_db.DbError("FK_VIOLATION", this._mapFkError(err.detail ?? err.message, err.constraint));
+			const contention = PG_CONTENTION_CODES[err.code];
+			if (contention) throw new _atscript_db.DbError(contention, [{
+				path: "",
+				message: err.message
+			}]);
 		}
 		throw error;
 	}
@@ -959,9 +978,21 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	* with the same `ON CONFLICT DO NOTHING`, so the result is always exact. A
 	* one-row chunk (or a table without keys) maps exactly by construction, so
 	* it needs no savepoint — and a single such chunk no transaction either.
+	* `ON CONFLICT DO NOTHING` takes no lock on a stored conflicting row, so a
+	* caller's transaction is left without any. `opts.lockConflicts` (since
+	* 0.1.153) locks them: one `SELECT … FOR UPDATE` of the stored rows matching
+	* the batch's keys, in primary-key order, BEFORE the insert, and one more
+	* for the skipped rows a concurrent writer committed in between.
 	*/
-	async insertManyIgnore(data) {
+	async insertManyIgnore(data, opts) {
 		if (data.length === 0) return [];
+		if (opts?.lockConflicts && this._table.uniqueKeySets.length > 0) return this.withTransaction(async () => {
+			const locked = await this._lockKeyedRows(data);
+			const slots = await this.insertManyIgnore(data);
+			const raced = data.filter((_, i) => slots[i] === null && !locked.has(i));
+			if (raced.length > 0) await this._lockKeyedRows(raced);
+			return slots;
+		});
 		const plan = this._ignorePlan();
 		const { columns, batches } = (0, _atscript_db_sql_tools.chunkInsertRows)(data);
 		const needsSavepoint = (batch) => batch.length > 1 && plan.returning.length > 0;
@@ -998,6 +1029,52 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		return batches.length === 1 && !needsSavepoint(batches[0]) ? run() : this.withTransaction(run);
 	}
 	/**
+	* `SELECT <key columns> … FOR UPDATE` of the stored rows sharing a primary /
+	* unique key tuple with one of `rows`, ordered by the primary key (so
+	* concurrent lockers queue instead of deadlocking); PostgreSQL locks only
+	* the rows returned. Returns the indices of `rows` a locked row matched.
+	*/
+	async _lockKeyedRows(rows) {
+		const keySets = this._table.uniqueKeySets.filter((f) => f.length > 0);
+		const rowTuples = rows.map((row) => keySets.map((fields) => (0, _atscript_db.uniqueKeyTuple)(row, fields)));
+		const order = (this._pk().cols.length > 0 ? this._pk().cols : keySets[0]).map((c) => qi(c)).join(", ");
+		const selectCols = [...new Set(keySets.flat())].map((c) => qi(c)).join(", ");
+		const lockedTuples = keySets.map(() => /* @__PURE__ */ new Set());
+		const width = keySets.reduce((n, f) => n + f.length, 0);
+		const sliceSize = Math.max(1, Math.floor(3e4 / width));
+		for (let offset = 0; offset < rows.length; offset += sliceSize) {
+			const end = Math.min(rows.length, offset + sliceSize);
+			const clauses = [];
+			const params = [];
+			const ph = (value) => {
+				params.push(pgDialect.toValue(value));
+				return `$${params.length}`;
+			};
+			keySets.forEach((fields, k) => {
+				const tuples = [];
+				for (let i = offset; i < end; i++) {
+					if (rowTuples[i][k] === void 0) continue;
+					const row = rows[i];
+					tuples.push(`(${fields.map((f) => ph(row[f])).join(", ")})`);
+				}
+				if (tuples.length > 0) clauses.push(`(${fields.map((f) => qi(f)).join(", ")}) IN (${tuples.join(", ")})`);
+			});
+			if (clauses.length === 0) continue;
+			const sql = `SELECT ${selectCols} FROM ${quoteTableName(this.resolveTableName())} WHERE ${clauses.join(" OR ")} ORDER BY ${order} FOR UPDATE`;
+			this._log(sql, params);
+			const found = await this._wrapConstraintError(() => this._exec().all(sql, params));
+			for (const doc of found) keySets.forEach((fields, k) => {
+				const tuple = (0, _atscript_db.uniqueKeyTuple)(doc, fields);
+				if (tuple !== void 0) lockedTuples[k].add(tuple);
+			});
+		}
+		const locked = /* @__PURE__ */ new Set();
+		rowTuples.forEach((tuples, i) => {
+			if (tuples.some((t, k) => t !== void 0 && lockedTuples[k].has(t))) locked.add(i);
+		});
+		return locked;
+	}
+	/**
 	* The key columns of a conflict-ignoring insert (built once per table):
 	* every primary / unique key set, their RETURNING list, and the key columns
 	* whose physical type is not text (see {@link mapIgnoredBatch}). Keyed on the
@@ -2284,6 +2361,10 @@ function createCustomTypes(pgTypes) {
 		return pgTypes.getTypeParser(oid, format);
 	} };
 }
+/** The warning logged for a pool client whose connection broke (`57P01`, `ECONNRESET`, …). */
+function lostConnectionMessage(err, where) {
+	return `[atscript/db-postgres] ${where} pool connection lost (${err.code ?? err.name}): ${err.message}`;
+}
 /**
 * {@link TPgDriver} implementation backed by `pg` (node-postgres).
 *
@@ -2310,6 +2391,12 @@ function createCustomTypes(pgTypes) {
 * const driver = new PgDriver(pool)
 * ```
 *
+* A broken pool connection (a terminated backend, failover, network reset) is
+* logged through `options.logger` instead of crashing the process (since
+* 0.1.154): idle clients of a pool the driver creates, and clients checked out
+* for a transaction. A pre-created `pg.Pool` is the caller's — attach your own
+* `pool.on('error', …)` listener, or an idle client's error crashes the process.
+*
 * Requires `pg` to be installed:
 * ```bash
 * pnpm add pg
@@ -2318,7 +2405,9 @@ function createCustomTypes(pgTypes) {
 var PgDriver = class {
 	pool;
 	poolInit;
-	constructor(poolOrConfig) {
+	logger;
+	constructor(poolOrConfig, options = {}) {
+		this.logger = options.logger ?? console;
 		if (typeof poolOrConfig === "object" && typeof poolOrConfig.query === "function") this.pool = poolOrConfig;
 		else this.poolInit = import("pg").then((pg) => {
 			const Pool = pg.default?.Pool ?? pg.Pool;
@@ -2332,6 +2421,7 @@ var PgDriver = class {
 				...poolOrConfig,
 				types: customTypes
 			});
+			this.pool.on("error", (err) => this.logger.warn(lostConnectionMessage(err, "idle")));
 			return this.pool;
 		});
 	}
@@ -2356,6 +2446,13 @@ var PgDriver = class {
 	}
 	async getConnection() {
 		const client = await (await this.getPool()).connect();
+		let lost;
+		const onError = (err) => {
+			if (lost) return;
+			lost = err;
+			this.logger.warn(lostConnectionMessage(err, "checked-out"));
+		};
+		client.on("error", onError);
 		return {
 			async run(sql, params) {
 				const result = await client.query(sql, sanitizeParams(params));
@@ -2374,7 +2471,8 @@ var PgDriver = class {
 				await client.query(sql);
 			},
 			release() {
-				client.release();
+				client.removeListener("error", onError);
+				client.release(lost);
 			}
 		};
 	}

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair, TViewCapability } from "@atscript/db";
 import { TMetadataMap } from "@atscript/typescript/utils";
 import { TFilterVisitorOptions, TSqlFragment } from "@atscript/db-sql-tools";
 
@@ -176,6 +176,8 @@ declare class PostgresAdapter extends BaseDbAdapter {
   aggregateFns(): ReadonlySet<AggregateFn>;
   /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
   supportsAggregateExpressions(): boolean;
+  /** `$nulls` / `@db.sort.nulls` NULL placement — `NULLS FIRST` / `NULLS LAST`. */
+  supportsNullsPlacement(): boolean;
   /** Computed view columns and first-row joins. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
@@ -196,9 +198,12 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * PostgreSQL uses SQLSTATE codes:
    * - 23505 = unique_violation
    * - 23503 = foreign_key_violation
+   * - 40P01 = deadlock_detected → `DEADLOCK`
+   * - 55P03 = lock_not_available (`lock_timeout`, `NOWAIT`) → `LOCK_TIMEOUT`
+   * - 40001 = serialization_failure → `SERIALIZATION_FAILURE`
    */
   private _wrapConstraintError;
-  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock timeout, else as is. */
   private _mapConstraintError;
   private _extractFieldFromConstraint;
   private _mapFkError;
@@ -216,8 +221,20 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * with the same `ON CONFLICT DO NOTHING`, so the result is always exact. A
    * one-row chunk (or a table without keys) maps exactly by construction, so
    * it needs no savepoint — and a single such chunk no transaction either.
+   * `ON CONFLICT DO NOTHING` takes no lock on a stored conflicting row, so a
+   * caller's transaction is left without any. `opts.lockConflicts` (since
+   * 0.1.153) locks them: one `SELECT … FOR UPDATE` of the stored rows matching
+   * the batch's keys, in primary-key order, BEFORE the insert, and one more
+   * for the skipped rows a concurrent writer committed in between.
    */
-  insertManyIgnore(data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
+  insertManyIgnore(data: Array<Record<string, unknown>>, opts?: TDbInsertIgnoreOptions): Promise<TDbInsertIgnoreSlot[]>;
+  /**
+   * `SELECT <key columns> … FOR UPDATE` of the stored rows sharing a primary /
+   * unique key tuple with one of `rows`, ordered by the primary key (so
+   * concurrent lockers queue instead of deadlocking); PostgreSQL locks only
+   * the rows returned. Returns the indices of `rows` a locked row matched.
+   */
+  private _lockKeyedRows;
   /**
    * The key columns of a conflict-ignoring insert (built once per table):
    * every primary / unique key set, their RETURNING list, and the key columns
@@ -425,6 +442,14 @@ declare class PostgresAdapter extends BaseDbAdapter {
 }
 //#endregion
 //#region src/pg-driver.d.ts
+/** Options of {@link PgDriver}. */
+interface TPgDriverOptions {
+  /**
+   * Receives a warning when a pool connection breaks — a terminated backend,
+   * failover or network reset (default `console`). See {@link PgDriver}.
+   */
+  logger?: Pick<TGenericLogger, "warn">;
+}
 /**
  * {@link TPgDriver} implementation backed by `pg` (node-postgres).
  *
@@ -451,6 +476,12 @@ declare class PostgresAdapter extends BaseDbAdapter {
  * const driver = new PgDriver(pool)
  * ```
  *
+ * A broken pool connection (a terminated backend, failover, network reset) is
+ * logged through `options.logger` instead of crashing the process (since
+ * 0.1.154): idle clients of a pool the driver creates, and clients checked out
+ * for a transaction. A pre-created `pg.Pool` is the caller's — attach your own
+ * `pool.on('error', …)` listener, or an idle client's error crashes the process.
+ *
  * Requires `pg` to be installed:
  * ```bash
  * pnpm add pg
@@ -459,7 +490,8 @@ declare class PostgresAdapter extends BaseDbAdapter {
 declare class PgDriver implements TPgDriver {
   private pool;
   private poolInit;
-  constructor(poolOrConfig: string | import("pg").Pool | import("pg").PoolConfig);
+  private readonly logger;
+  constructor(poolOrConfig: string | import("pg").Pool | import("pg").PoolConfig, options?: TPgDriverOptions);
   private getPool;
   run(sql: string, params?: unknown[]): Promise<TPgRunResult>;
   all<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
@@ -500,4 +532,4 @@ declare function buildWhere(filter: FilterExpr, opts?: TFilterVisitorOptions): T
  */
 declare function createAdapter(uri: string, options?: Record<string, unknown>): DbSpace;
 //#endregion
-export { PgDriver, PostgresAdapter, type TPgConnection, type TPgDriver, type TPgRunResult, type TSqlFragment, buildWhere, createAdapter };
+export { PgDriver, PostgresAdapter, type TPgConnection, type TPgDriver, type TPgDriverOptions, type TPgRunResult, type TSqlFragment, buildWhere, createAdapter };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair, TViewCapability } from "@atscript/db";
 import { TFilterVisitorOptions, TSqlFragment } from "@atscript/db-sql-tools";
 import { TMetadataMap } from "@atscript/typescript/utils";
 
@@ -176,6 +176,8 @@ declare class PostgresAdapter extends BaseDbAdapter {
   aggregateFns(): ReadonlySet<AggregateFn>;
   /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
   supportsAggregateExpressions(): boolean;
+  /** `$nulls` / `@db.sort.nulls` NULL placement — `NULLS FIRST` / `NULLS LAST`. */
+  supportsNullsPlacement(): boolean;
   /** Computed view columns and first-row joins. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
@@ -196,9 +198,12 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * PostgreSQL uses SQLSTATE codes:
    * - 23505 = unique_violation
    * - 23503 = foreign_key_violation
+   * - 40P01 = deadlock_detected → `DEADLOCK`
+   * - 55P03 = lock_not_available (`lock_timeout`, `NOWAIT`) → `LOCK_TIMEOUT`
+   * - 40001 = serialization_failure → `SERIALIZATION_FAILURE`
    */
   private _wrapConstraintError;
-  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock timeout, else as is. */
   private _mapConstraintError;
   private _extractFieldFromConstraint;
   private _mapFkError;
@@ -216,8 +221,20 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * with the same `ON CONFLICT DO NOTHING`, so the result is always exact. A
    * one-row chunk (or a table without keys) maps exactly by construction, so
    * it needs no savepoint — and a single such chunk no transaction either.
+   * `ON CONFLICT DO NOTHING` takes no lock on a stored conflicting row, so a
+   * caller's transaction is left without any. `opts.lockConflicts` (since
+   * 0.1.153) locks them: one `SELECT … FOR UPDATE` of the stored rows matching
+   * the batch's keys, in primary-key order, BEFORE the insert, and one more
+   * for the skipped rows a concurrent writer committed in between.
    */
-  insertManyIgnore(data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
+  insertManyIgnore(data: Array<Record<string, unknown>>, opts?: TDbInsertIgnoreOptions): Promise<TDbInsertIgnoreSlot[]>;
+  /**
+   * `SELECT <key columns> … FOR UPDATE` of the stored rows sharing a primary /
+   * unique key tuple with one of `rows`, ordered by the primary key (so
+   * concurrent lockers queue instead of deadlocking); PostgreSQL locks only
+   * the rows returned. Returns the indices of `rows` a locked row matched.
+   */
+  private _lockKeyedRows;
   /**
    * The key columns of a conflict-ignoring insert (built once per table):
    * every primary / unique key set, their RETURNING list, and the key columns
@@ -425,6 +442,14 @@ declare class PostgresAdapter extends BaseDbAdapter {
 }
 //#endregion
 //#region src/pg-driver.d.ts
+/** Options of {@link PgDriver}. */
+interface TPgDriverOptions {
+  /**
+   * Receives a warning when a pool connection breaks — a terminated backend,
+   * failover or network reset (default `console`). See {@link PgDriver}.
+   */
+  logger?: Pick<TGenericLogger, "warn">;
+}
 /**
  * {@link TPgDriver} implementation backed by `pg` (node-postgres).
  *
@@ -451,6 +476,12 @@ declare class PostgresAdapter extends BaseDbAdapter {
  * const driver = new PgDriver(pool)
  * ```
  *
+ * A broken pool connection (a terminated backend, failover, network reset) is
+ * logged through `options.logger` instead of crashing the process (since
+ * 0.1.154): idle clients of a pool the driver creates, and clients checked out
+ * for a transaction. A pre-created `pg.Pool` is the caller's — attach your own
+ * `pool.on('error', …)` listener, or an idle client's error crashes the process.
+ *
  * Requires `pg` to be installed:
  * ```bash
  * pnpm add pg
@@ -459,7 +490,8 @@ declare class PostgresAdapter extends BaseDbAdapter {
 declare class PgDriver implements TPgDriver {
   private pool;
   private poolInit;
-  constructor(poolOrConfig: string | import("pg").Pool | import("pg").PoolConfig);
+  private readonly logger;
+  constructor(poolOrConfig: string | import("pg").Pool | import("pg").PoolConfig, options?: TPgDriverOptions);
   private getPool;
   run(sql: string, params?: unknown[]): Promise<TPgRunResult>;
   all<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
@@ -500,4 +532,4 @@ declare function buildWhere(filter: FilterExpr, opts?: TFilterVisitorOptions): T
  */
 declare function createAdapter(uri: string, options?: Record<string, unknown>): DbSpace;
 //#endregion
-export { PgDriver, PostgresAdapter, type TPgConnection, type TPgDriver, type TPgRunResult, type TSqlFragment, buildWhere, createAdapter };
+export { PgDriver, PostgresAdapter, type TPgConnection, type TPgDriver, type TPgDriverOptions, type TPgRunResult, type TSqlFragment, buildWhere, createAdapter };

package/dist/index.mjs

@@ -191,6 +191,7 @@ const pgDialect = {
 		return zone === void 0 ? void 0 : bucketTimeZoneUnavailable(`PostgreSQL does not recognize time zone "${zone}" — update the server's time zone data`);
 	},
 	nullsSortLargest: true,
+	nullsPlacementSyntax: true,
 	createViewPrefix: "CREATE OR REPLACE VIEW",
 	paramPlaceholder(index) {
 		return `$${index}`;
@@ -569,6 +570,12 @@ function parseCount(value) {
 /** The suffix PostgreSQL gives an auto-named constraint of each `pg_constraint.contype`. */
 /** Savepoint guarding one `insertManyIgnore` chunk (see {@link PostgresAdapter.insertManyIgnore}). */
 const IGNORE_SAVEPOINT = "atscript_ignore_chunk";
+/** Retryable concurrency SQLSTATEs (see `PostgresAdapter._mapConstraintError`). */
+const PG_CONTENTION_CODES = {
+	"40P01": "DEADLOCK",
+	"55P03": "LOCK_TIMEOUT",
+	"40001": "SERIALIZATION_FAILURE"
+};
 const PG_CONSTRAINT_LABELS = {
 	p: "pkey",
 	u: "key",
@@ -787,6 +794,10 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	supportsAggregateExpressions() {
 		return true;
 	}
+	/** `$nulls` / `@db.sort.nulls` NULL placement — `NULLS FIRST` / `NULLS LAST`. */
+	supportsNullsPlacement() {
+		return true;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return ALL_VIEW_CAPABILITIES;
@@ -864,6 +875,9 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	* PostgreSQL uses SQLSTATE codes:
 	* - 23505 = unique_violation
 	* - 23503 = foreign_key_violation
+	* - 40P01 = deadlock_detected → `DEADLOCK`
+	* - 55P03 = lock_not_available (`lock_timeout`, `NOWAIT`) → `LOCK_TIMEOUT`
+	* - 40001 = serialization_failure → `SERIALIZATION_FAILURE`
 	*/
 	async _wrapConstraintError(fn) {
 		try {
@@ -872,7 +886,7 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			return this._mapConstraintError(error);
 		}
 	}
-	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock timeout, else as is. */
 	_mapConstraintError(error) {
 		if (error && typeof error === "object" && "code" in error) {
 			const err = error;
@@ -881,6 +895,11 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 				message: err.detail ?? err.message
 			}]);
 			if (err.code === "23503") throw new DbError("FK_VIOLATION", this._mapFkError(err.detail ?? err.message, err.constraint));
+			const contention = PG_CONTENTION_CODES[err.code];
+			if (contention) throw new DbError(contention, [{
+				path: "",
+				message: err.message
+			}]);
 		}
 		throw error;
 	}
@@ -958,9 +977,21 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	* with the same `ON CONFLICT DO NOTHING`, so the result is always exact. A
 	* one-row chunk (or a table without keys) maps exactly by construction, so
 	* it needs no savepoint — and a single such chunk no transaction either.
+	* `ON CONFLICT DO NOTHING` takes no lock on a stored conflicting row, so a
+	* caller's transaction is left without any. `opts.lockConflicts` (since
+	* 0.1.153) locks them: one `SELECT … FOR UPDATE` of the stored rows matching
+	* the batch's keys, in primary-key order, BEFORE the insert, and one more
+	* for the skipped rows a concurrent writer committed in between.
 	*/
-	async insertManyIgnore(data) {
+	async insertManyIgnore(data, opts) {
 		if (data.length === 0) return [];
+		if (opts?.lockConflicts && this._table.uniqueKeySets.length > 0) return this.withTransaction(async () => {
+			const locked = await this._lockKeyedRows(data);
+			const slots = await this.insertManyIgnore(data);
+			const raced = data.filter((_, i) => slots[i] === null && !locked.has(i));
+			if (raced.length > 0) await this._lockKeyedRows(raced);
+			return slots;
+		});
 		const plan = this._ignorePlan();
 		const { columns, batches } = chunkInsertRows(data);
 		const needsSavepoint = (batch) => batch.length > 1 && plan.returning.length > 0;
@@ -997,6 +1028,52 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		return batches.length === 1 && !needsSavepoint(batches[0]) ? run() : this.withTransaction(run);
 	}
 	/**
+	* `SELECT <key columns> … FOR UPDATE` of the stored rows sharing a primary /
+	* unique key tuple with one of `rows`, ordered by the primary key (so
+	* concurrent lockers queue instead of deadlocking); PostgreSQL locks only
+	* the rows returned. Returns the indices of `rows` a locked row matched.
+	*/
+	async _lockKeyedRows(rows) {
+		const keySets = this._table.uniqueKeySets.filter((f) => f.length > 0);
+		const rowTuples = rows.map((row) => keySets.map((fields) => uniqueKeyTuple(row, fields)));
+		const order = (this._pk().cols.length > 0 ? this._pk().cols : keySets[0]).map((c) => qi(c)).join(", ");
+		const selectCols = [...new Set(keySets.flat())].map((c) => qi(c)).join(", ");
+		const lockedTuples = keySets.map(() => /* @__PURE__ */ new Set());
+		const width = keySets.reduce((n, f) => n + f.length, 0);
+		const sliceSize = Math.max(1, Math.floor(3e4 / width));
+		for (let offset = 0; offset < rows.length; offset += sliceSize) {
+			const end = Math.min(rows.length, offset + sliceSize);
+			const clauses = [];
+			const params = [];
+			const ph = (value) => {
+				params.push(pgDialect.toValue(value));
+				return `$${params.length}`;
+			};
+			keySets.forEach((fields, k) => {
+				const tuples = [];
+				for (let i = offset; i < end; i++) {
+					if (rowTuples[i][k] === void 0) continue;
+					const row = rows[i];
+					tuples.push(`(${fields.map((f) => ph(row[f])).join(", ")})`);
+				}
+				if (tuples.length > 0) clauses.push(`(${fields.map((f) => qi(f)).join(", ")}) IN (${tuples.join(", ")})`);
+			});
+			if (clauses.length === 0) continue;
+			const sql = `SELECT ${selectCols} FROM ${quoteTableName(this.resolveTableName())} WHERE ${clauses.join(" OR ")} ORDER BY ${order} FOR UPDATE`;
+			this._log(sql, params);
+			const found = await this._wrapConstraintError(() => this._exec().all(sql, params));
+			for (const doc of found) keySets.forEach((fields, k) => {
+				const tuple = uniqueKeyTuple(doc, fields);
+				if (tuple !== void 0) lockedTuples[k].add(tuple);
+			});
+		}
+		const locked = /* @__PURE__ */ new Set();
+		rowTuples.forEach((tuples, i) => {
+			if (tuples.some((t, k) => t !== void 0 && lockedTuples[k].has(t))) locked.add(i);
+		});
+		return locked;
+	}
+	/**
 	* The key columns of a conflict-ignoring insert (built once per table):
 	* every primary / unique key set, their RETURNING list, and the key columns
 	* whose physical type is not text (see {@link mapIgnoredBatch}). Keyed on the
@@ -2283,6 +2360,10 @@ function createCustomTypes(pgTypes) {
 		return pgTypes.getTypeParser(oid, format);
 	} };
 }
+/** The warning logged for a pool client whose connection broke (`57P01`, `ECONNRESET`, …). */
+function lostConnectionMessage(err, where) {
+	return `[atscript/db-postgres] ${where} pool connection lost (${err.code ?? err.name}): ${err.message}`;
+}
 /**
 * {@link TPgDriver} implementation backed by `pg` (node-postgres).
 *
@@ -2309,6 +2390,12 @@ function createCustomTypes(pgTypes) {
 * const driver = new PgDriver(pool)
 * ```
 *
+* A broken pool connection (a terminated backend, failover, network reset) is
+* logged through `options.logger` instead of crashing the process (since
+* 0.1.154): idle clients of a pool the driver creates, and clients checked out
+* for a transaction. A pre-created `pg.Pool` is the caller's — attach your own
+* `pool.on('error', …)` listener, or an idle client's error crashes the process.
+*
 * Requires `pg` to be installed:
 * ```bash
 * pnpm add pg
@@ -2317,7 +2404,9 @@ function createCustomTypes(pgTypes) {
 var PgDriver = class {
 	pool;
 	poolInit;
-	constructor(poolOrConfig) {
+	logger;
+	constructor(poolOrConfig, options = {}) {
+		this.logger = options.logger ?? console;
 		if (typeof poolOrConfig === "object" && typeof poolOrConfig.query === "function") this.pool = poolOrConfig;
 		else this.poolInit = import("pg").then((pg) => {
 			const Pool = pg.default?.Pool ?? pg.Pool;
@@ -2331,6 +2420,7 @@ var PgDriver = class {
 				...poolOrConfig,
 				types: customTypes
 			});
+			this.pool.on("error", (err) => this.logger.warn(lostConnectionMessage(err, "idle")));
 			return this.pool;
 		});
 	}
@@ -2355,6 +2445,13 @@ var PgDriver = class {
 	}
 	async getConnection() {
 		const client = await (await this.getPool()).connect();
+		let lost;
+		const onError = (err) => {
+			if (lost) return;
+			lost = err;
+			this.logger.warn(lostConnectionMessage(err, "checked-out"));
+		};
+		client.on("error", onError);
 		return {
 			async run(sql, params) {
 				const result = await client.query(sql, sanitizeParams(params));
@@ -2373,7 +2470,8 @@ var PgDriver = class {
 				await client.query(sql);
 			},
 			release() {
-				client.release();
+				client.removeListener("error", onError);
+				client.release(lost);
 			}
 		};
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-postgres",
-  "version": "0.1.152",
+  "version": "0.1.154",
   "description": "PostgreSQL adapter for @atscript/db with pg (node-postgres) driver support.",
   "keywords": [
     "atscript",
@@ -43,20 +43,20 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
     "@types/pg": "^8.11.0",
-    "@uniqu/core": "^0.1.14",
+    "@uniqu/core": "^0.1.15",
     "pg": "^8.13.0",
-    "unplugin-atscript": "^0.1.102"
+    "unplugin-atscript": "^0.1.103"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "@uniqu/core": "^0.1.14",
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "@uniqu/core": "^0.1.15",
     "pg": ">=8.0.0",
-    "@atscript/db": "^0.1.152",
-    "@atscript/db-sql-tools": "^0.1.152"
+    "@atscript/db": "^0.1.154",
+    "@atscript/db-sql-tools": "^0.1.154"
   },
   "peerDependenciesMeta": {
     "pg": {