@antelopejs/postgres 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright (c) 2025-present - AntelopeJS Team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @antelopejs/postgres
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+<a href="https://www.npmjs.com/package/@antelopejs/postgres"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/postgres?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/postgres?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
+<a href="https://interfaces.antelopejs.com/docs/database"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
+</div>
+
+The PostgreSQL backend of AntelopeJS: it runs the database interface's queries on PostgreSQL with the [`pg`](https://github.com/brianc/node-postgres) driver, mapping schema definitions onto real relational tables with native column types and indexes. It can also serve tables that already exist in a database it does not own.
+
+## Interfaces
+
+| Interface                                                                            | Documentation                                               |
+| ------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| [`@antelopejs/interface-database`](https://github.com/AntelopeJS/interface-database) | [Database](https://interfaces.antelopejs.com/docs/database) |
+
+Schemas, tables, queries, change feeds and atomic mutations are documented on the database interface pages.
+
+## Install
+
+```bash
+ajs project modules add @antelopejs/postgres
+```
+
+The command writes the module's default configuration: `postgres://postgres@localhost:5432/antelopejs`, with `migrations: "safe"`.
+
+**Requires PostgreSQL 16 or later.** The adapter uses `pg_input_is_valid` so that a text or jsonb
+value which is not a parseable date yields `null` instead of aborting the whole statement. It is
+the only construct used above PostgreSQL 9.5.
+
+## Configuration
+
+```typescript [antelope.config.ts]
+import { defineConfig } from "@antelopejs/interface-core/config";
+
+export default defineConfig({
+  name: "my-project",
+  modules: {
+    postgres: {
+      source: {
+        type: "package",
+        package: "@antelopejs/postgres",
+        version: "^0.2.0",
+      },
+      config: {
+        url: "postgres://postgres@localhost:5432/my-project",
+        migrations: "safe",
+        pool: { max: 10 },
+      },
+    },
+  },
+  envOverrides: {
+    POSTGRES_URL: "modules.postgres.config.url",
+  },
+});
+```
+
+| Key            | Description                                                                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`         | `"owned"` (default) creates and converges the tables; `"external"` serves existing tables without changing them.                                              |
+| `url`          | PostgreSQL connection string.                                                                                                                                 |
+| `migrations`   | `"safe"` (default) only adds columns and indexes; `"destructive"` also alters and drops them. See [Schema convergence](./docs/storage.md#schema-convergence). |
+| `schemaPrefix` | Prefix for generated PostgreSQL schema names, for several applications sharing one database.                                                                  |
+| `pool`         | Optional [`pg.Pool`](https://node-postgres.com/apis/pool) options, merged over the URL.                                                                       |
+
+Cursor, statement-timeout and change-feed tuning are in [docs/configuration.md](./docs/configuration.md).
+
+## Quick start
+
+In the module that stores data, add the database interface:
+
+```bash
+pnpm add @antelopejs/interface-database
+```
+
+Then follow the [database interface guide](https://framework.antelopejs.com/docs/guides/database) to declare a schema and query it. The same code runs on [`@antelopejs/mongodb`](https://github.com/AntelopeJS/mongodb) and [`@antelopejs/rethinkdb`](https://github.com/AntelopeJS/rethinkdb); [Behaviour worth knowing](./docs/behaviour.md) records where the backends differ.
+
+## Storage layout
+
+Unlike the document-store backends, this module treats schema field declarations as real
+DDL: each AntelopeJS schema becomes a PostgreSQL schema, each table a real table, and each
+declared scalar field a natively typed, natively indexable column. Queries compile to a single
+SQL statement — filters become `WHERE` clauses, joins become `JOIN`s, and a `filter` or `orderBy`
+over a declared field reaches its btree index.
+
+- One PostgreSQL schema per AntelopeJS schema id
+- Declared scalar fields become typed columns; objects, arrays and undeclared fields live in `jsonb`
+- Schema instances are isolated by an `_instance` discriminator column
+- Additive schema convergence, with destructive changes refused unless explicitly enabled
+- Change feeds, as a durable log plus a pull-based reader
+
+**Requires PostgreSQL 16 or later.** The adapter uses `pg_input_is_valid` so that a text or jsonb
+value which is not a parseable date yields `null` instead of aborting the whole statement. It is
+the only construct used above PostgreSQL 9.5.
+
+## Documentation
+
+- [Database](https://interfaces.antelopejs.com/docs/database): the `@antelopejs/interface-database` contract this module implements
+- [Configuration](https://framework.antelopejs.com/docs/concepts/configuration): module sources, `config` blocks and config variables in `antelope.config.ts`
+
+This repository documents what is specific to the PostgreSQL backend:
+
+|                                                |                                                                                                                                                    |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Storage and schema](./docs/storage.md)        | What a registered schema becomes in the database, the field-type table, what reaches an index, and how registration converges                      |
+| [Configuration](./docs/configuration.md)       | Every option `construct` accepts                                                                                                                   |
+| [External mode](./docs/external-mode.md)       | Reading tables the module did not create, in a database it does not own                                                                            |
+| [Change feeds](./docs/change-feeds.md)         | `changes()`, its ordering guarantee, its retention contract and its blind spots                                                                    |
+| [Errors and refusals](./docs/errors.md)        | Everything the module refuses, with the message it refuses by                                                                                      |
+| [Behaviour worth knowing](./docs/behaviour.md) | Things that answer rather than throw, where the answer may surprise you — including where this backend differs from the MongoDB and RethinkDB ones |
+
+## Compatibility
+
+| Package                          | Supported range  |
+| -------------------------------- | ---------------- |
+| `@antelopejs/interface-database` | `^0.1.8`         |
+| `@antelopejs/interface-core`     | `>=0.1.1 <1.0.0` |
+
+The module is developed and tested against `@antelopejs/core` `^1.14.0` on Node.js 22 and 24, with the `pg` driver `^8.22.0` and PostgreSQL 18.
+
+## Contributing
+
+**Node 22 or later is required to develop or test this module**, though the published module itself
+runs on any version its `pg` dependency supports. The floor comes from `testcontainers`, a
+devDependency whose bundled `undici` calls `worker_threads.markAsUncloneable`, absent from Node 20.
+
+```bash
+pnpm install
+pnpm lint
+pnpm format:check
+pnpm knip
+pnpm test:unit      # fast loop: this repository's unit specs, no Docker
+pnpm test           # everything, against PostgreSQL: unit specs, conformance and external-mode suites
+```
+
+`pnpm test` provisions PostgreSQL with Testcontainers, so it needs a Docker daemon. Besides this
+repository's own tests, it runs the shared conformance suite of `@antelopejs/interface-database`,
+discovered from `antelopeJs.implements`.
+
+To test against an existing server instead of a container, set `PG_TEST_URL`. It must point to a
+disposable instance: the external suite drops and recreates a fixture database and may create a role.
+
+```bash
+PG_TEST_URL=postgres://postgres:postgres@localhost:5432/antelopejs_test pnpm test
+```
+
+Read the [contribution guidelines](CONTRIBUTING.md) before opening a pull request.
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+import type { PoolConfig } from "pg";
+export type MigrationMode = "safe" | "destructive";
+export type Mode = "owned" | "external";
+export interface Options {
+    mode?: Mode;
+    url?: string;
+    pool?: PoolConfig;
+    schemaPrefix?: string;
+    migrations?: MigrationMode;
+    cursorBatchSize?: number;
+    cursorIdleTimeoutMs?: number;
+    statementTimeoutMs?: number;
+    changeRetentionMs?: number;
+    changeBatchSize?: number;
+    changePollIntervalMs?: number;
+}
+export interface ResolvedOptions {
+    mode: Mode;
+    url: string;
+    pool: PoolConfig;
+    schemaPrefix: string;
+    migrations: MigrationMode;
+    cursorBatchSize: number;
+    cursorIdleTimeoutMs: number;
+    statementTimeoutMs?: number;
+    changeRetentionMs: number;
+    changeBatchSize: number;
+    changePollIntervalMs: number;
+}
+export declare function SetOptions(options?: Options): ResolvedOptions;
+export declare function GetOptions(): ResolvedOptions;
+export declare function IsExternal(): boolean;
+export declare function ClearOptions(): void;

package/dist/config.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SetOptions = SetOptions;
+exports.GetOptions = GetOptions;
+exports.IsExternal = IsExternal;
+exports.ClearOptions = ClearOptions;
+const DEFAULT_URL = "postgres://postgres@localhost:5432/antelopejs";
+const DEFAULT_MODE = "owned";
+const MODES = ["owned", "external"];
+const OWNED_ONLY_OPTIONS = [
+    "schemaPrefix",
+    "migrations",
+    "changeRetentionMs",
+    "changeBatchSize",
+    "changePollIntervalMs",
+];
+const DEFAULT_MIGRATIONS = "safe";
+const DEFAULT_SCHEMA_PREFIX = "";
+const DEFAULT_CURSOR_BATCH_SIZE = 100;
+const DEFAULT_CURSOR_IDLE_TIMEOUT_MS = 60_000;
+const DEFAULT_CHANGE_RETENTION_MS = 300_000;
+const DEFAULT_CHANGE_BATCH_SIZE = 256;
+const DEFAULT_CHANGE_POLL_INTERVAL_MS = 5_000;
+const SMALLEST_POSITIVE_INTEGER = 1;
+const NOT_CONFIGURED = "PostgreSQL adapter is not configured: construct() has not run yet";
+let resolved;
+function PositiveSafeInteger(option, supplied, fallback) {
+    if (supplied === undefined) {
+        return fallback;
+    }
+    if (typeof supplied !== "number" ||
+        !Number.isSafeInteger(supplied) ||
+        supplied < SMALLEST_POSITIVE_INTEGER) {
+        throw new Error(`${option} must be a positive safe integer, received ${String(supplied)}`);
+    }
+    return supplied;
+}
+function ResolveMode(options) {
+    const mode = options?.mode ?? DEFAULT_MODE;
+    if (!MODES.includes(mode)) {
+        throw new Error(`mode must be one of ${MODES.join(", ")}, received ${String(mode)}`);
+    }
+    if (mode === "external") {
+        const refused = OWNED_ONLY_OPTIONS.filter((option) => options?.[option] !== undefined);
+        if (refused.length > 0) {
+            throw new Error(`${refused.join(", ")} cannot be set with mode "external": an external instance owns no schemas, runs no DDL and keeps no change log`);
+        }
+    }
+    return mode;
+}
+function ResolveUrl(mode, options) {
+    if (options?.url !== undefined && options.url.trim() !== "") {
+        return options.url;
+    }
+    if (mode === "external") {
+        throw new Error(`mode "external" needs a non-empty config.url; set it through the project's envOverrides`);
+    }
+    return DEFAULT_URL;
+}
+function SetOptions(options) {
+    const mode = ResolveMode(options);
+    const url = ResolveUrl(mode, options);
+    resolved = {
+        mode,
+        url,
+        pool: options?.pool ?? {},
+        schemaPrefix: options?.schemaPrefix ?? DEFAULT_SCHEMA_PREFIX,
+        migrations: options?.migrations ?? DEFAULT_MIGRATIONS,
+        cursorBatchSize: PositiveSafeInteger("cursorBatchSize", options?.cursorBatchSize, DEFAULT_CURSOR_BATCH_SIZE),
+        cursorIdleTimeoutMs: PositiveSafeInteger("cursorIdleTimeoutMs", options?.cursorIdleTimeoutMs, DEFAULT_CURSOR_IDLE_TIMEOUT_MS),
+        statementTimeoutMs: options?.statementTimeoutMs,
+        changeRetentionMs: PositiveSafeInteger("changeRetentionMs", options?.changeRetentionMs, DEFAULT_CHANGE_RETENTION_MS),
+        changeBatchSize: PositiveSafeInteger("changeBatchSize", options?.changeBatchSize, DEFAULT_CHANGE_BATCH_SIZE),
+        changePollIntervalMs: PositiveSafeInteger("changePollIntervalMs", options?.changePollIntervalMs, DEFAULT_CHANGE_POLL_INTERVAL_MS),
+    };
+    return resolved;
+}
+function GetOptions() {
+    if (!resolved) {
+        throw new Error(NOT_CONFIGURED);
+    }
+    return resolved;
+}
+function IsExternal() {
+    return GetOptions().mode === "external";
+}
+function ClearOptions() {
+    resolved = undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/connection.d.ts

@@ -0,0 +1,14 @@
+import { Pool, type PoolClient, type QueryResult, type QueryResultRow } from "pg";
+import { type Options } from "./config";
+export type BeforeDisconnect = () => unknown;
+export type PoolTeardown = () => Promise<void>;
+export declare function GuardPool(created: Pool): Pool;
+export declare function Connect(options?: Options): Promise<void>;
+export declare function RegisterBeforeDisconnect(callback: BeforeDisconnect): () => void;
+export declare function SettleBeforeDisconnect(endPool: PoolTeardown): Promise<void>;
+export declare function Disconnect(): Promise<void>;
+export declare function GetPool(): Pool;
+export declare function Query<T extends QueryResultRow = QueryResultRow>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+export declare function GuardHeldClient(client: PoolClient): PoolClient;
+export declare function AcquireClient(): Promise<PoolClient>;
+export declare function GetSchemaPrefix(): string;

package/dist/connection.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardPool = GuardPool;
+exports.Connect = Connect;
+exports.RegisterBeforeDisconnect = RegisterBeforeDisconnect;
+exports.SettleBeforeDisconnect = SettleBeforeDisconnect;
+exports.Disconnect = Disconnect;
+exports.GetPool = GetPool;
+exports.Query = Query;
+exports.GuardHeldClient = GuardHeldClient;
+exports.AcquireClient = AcquireClient;
+exports.GetSchemaPrefix = GetSchemaPrefix;
+const pg_1 = require("pg");
+const logger_1 = require("./logger");
+const config_1 = require("./config");
+const NOT_CONNECTED = "PostgreSQL adapter is not connected: construct() has not run yet";
+const SESSION_SETTINGS = "SET TIME ZONE 'UTC'; SET DateStyle = 'ISO, MDY'";
+const CLIENT_ERROR = "error";
+const HELD_CLIENT_FAILED = "the connection under a borrowed PostgreSQL client failed while it was checked out";
+const IDLE_CLIENT_FAILED = "the connection under an idle pooled PostgreSQL client failed";
+const CONNECTED = "connected to PostgreSQL";
+const DISCONNECTED = "disconnected from PostgreSQL";
+const SLOW_ACQUIRE_MS = 10_000;
+const SLOW_ACQUIRE = `no PostgreSQL client has become available in ${SLOW_ACQUIRE_MS} ms: either every pooled connection is checked out — a cursor holds one for as long as it is iterated — or a new connection is not being answered. Raise pool.max, or set pool.connectionTimeoutMillis to fail rather than wait`;
+let pool;
+let isWaiting = false;
+const beforeDisconnect = new Set();
+function PinSession(client) {
+    return client.query(SESSION_SETTINGS);
+}
+async function Invoke(callback) {
+    return callback();
+}
+function ReportIdleClientError(err) {
+    logger_1.Logger.Warn(IDLE_CLIENT_FAILED, err);
+}
+function GuardPool(created) {
+    created.on(CLIENT_ERROR, ReportIdleClientError);
+    return created;
+}
+async function Connect(options) {
+    await Disconnect();
+    const resolved = (0, config_1.SetOptions)(options);
+    const created = GuardPool(new pg_1.Pool({
+        connectionString: resolved.url,
+        statement_timeout: resolved.statementTimeoutMs,
+        ...resolved.pool,
+        onConnect: PinSession,
+    }));
+    try {
+        const client = await created.connect();
+        client.release();
+    }
+    catch (err) {
+        await created.end();
+        (0, config_1.ClearOptions)();
+        throw err;
+    }
+    pool = created;
+    logger_1.Logger.Info(CONNECTED);
+}
+function RegisterBeforeDisconnect(callback) {
+    beforeDisconnect.add(callback);
+    return () => {
+        beforeDisconnect.delete(callback);
+    };
+}
+async function SettleBeforeDisconnect(endPool) {
+    await Promise.allSettled([...beforeDisconnect].map(Invoke));
+    await endPool();
+}
+async function EndPool() {
+    const current = pool;
+    pool = undefined;
+    (0, config_1.ClearOptions)();
+    if (current) {
+        await current.end();
+        logger_1.Logger.Info(DISCONNECTED);
+    }
+}
+async function Disconnect() {
+    await SettleBeforeDisconnect(EndPool);
+}
+function GetPool() {
+    if (!pool) {
+        throw new Error(NOT_CONNECTED);
+    }
+    return pool;
+}
+function Query(sql, params) {
+    return GetPool().query(sql, params);
+}
+function ReportHeldClientError(err) {
+    logger_1.Logger.Warn(HELD_CLIENT_FAILED, err);
+}
+function WarnSlowAcquire() {
+    if (isWaiting) {
+        return;
+    }
+    isWaiting = true;
+    logger_1.Logger.Warn(SLOW_ACQUIRE);
+}
+function GuardHeldClient(client) {
+    const checkin = client.release;
+    client.on(CLIENT_ERROR, ReportHeldClientError);
+    client.release = (...args) => {
+        client.off(CLIENT_ERROR, ReportHeldClientError);
+        client.release = checkin;
+        return checkin.apply(client, args);
+    };
+    return client;
+}
+function AcquireClient() {
+    const current = GetPool();
+    const slow = setTimeout(WarnSlowAcquire, SLOW_ACQUIRE_MS);
+    slow.unref();
+    return current
+        .connect()
+        .then(GuardHeldClient)
+        .finally(() => {
+        clearTimeout(slow);
+        isWaiting = false;
+    });
+}
+function GetSchemaPrefix() {
+    return (0, config_1.GetOptions)().schemaPrefix;
+}
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

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

package/dist/implementations/database/changes.d.ts

@@ -0,0 +1,19 @@
+export type ChangeOperation = "added" | "modified" | "removed";
+export declare const CHANGES_STAGE = "changes";
+export declare const LOG: string;
+export declare const REAPED: string;
+export declare const SEQ_COLUMN: string;
+export declare const TXID_COLUMN: string;
+export declare const CREATED_COLUMN: string;
+export declare const SCHEMA_COLUMN: string;
+export declare const TABLE_COLUMN: string;
+export declare const LOG_INSTANCE_COLUMN: string;
+export declare const OP_COLUMN: string;
+export declare const OLD_ROW_COLUMN: string;
+export declare const NEW_ROW_COLUMN: string;
+export declare const SINGLETON_COLUMN: string;
+export declare const HIGH_WATER_COLUMN: string;
+export declare const EPOCH_COLUMN: string;
+export declare const CHANGE_CHANNEL = "antelopejs_changes";
+export declare const CHANGE_LOG_STATEMENTS: readonly string[];
+export declare function TriggerStatements(schemaId: string, tableId: string): readonly string[];