@makaio/storage-pg 1.0.0-dev-1781260968078

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Makaio GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @makaio/storage-pg
+
+Postgres storage engine for the Makaio framework.
+
+## Install & Usage
+
+```bash
+npm install @makaio/storage-pg
+export MAKAIO_DATABASE_URL=postgres://user:password@host:5432/makaio
+```
+
+The node-postgres driver (`pg`) is a regular dependency — installing this
+package is everything a Postgres host needs for the driver. The committed
+Postgres migration chain ships inside the npm tarball (`drizzle-postgres/`)
+and is applied automatically at boot. The engine attaches through the storage
+engine registry: Node and Bun runtime hosts auto-resolve it for recognized
+`postgres://` / `postgresql://` URLs, the `database.engines` boot option
+registers it explicitly, and direct callers use
+`registerStorageEngine(storageEngine)` — see "How It Attaches" below.
+
+## What This Is
+
+Packages everything Postgres-specific behind the storage engine seam of
+`@makaio/storage-drizzle` (one `StorageEngine` per dialect, attached through
+the global engine registry):
+
+- **Engine definition** — `postgresStorageEngine` claims `postgres://` /
+  `postgresql://` URLs (case-insensitively, mirroring the core URL hint table)
+  and creates clients over the node-postgres driver.
+- **Error classifiers** — `isPostgresDuplicateObjectError` (SQLSTATE
+  `42P07`/`42710`) and `isPostgresUniqueViolationError` (`23505`, with optional
+  constraint-name scoping); both walk wrapped error cause chains.
+- **Migration behavior** — the `__makaio_migrations` ledger (identity primary
+  key plus `UNIQUE` hash), `BEGIN ISOLATION LEVEL READ COMMITTED` transaction
+  pinning, the `pg_advisory_xact_lock` cross-process protocol keyed by
+  `migrationAdvisoryLockKey`, `__makaio_migrations_<hash>` extension ledgers,
+  and the committed Postgres migration chain itself: it ships in this
+  package's `drizzle-postgres/` directory and is resolved through the engine's
+  `resolveSourceChainDir`. The directory name is deliberately distinct from
+  the default `drizzle` directory so embedded-host chain discovery never picks
+  up the Postgres chain.
+- **Full-text search** — `postgresFtsSearchStrategy`: tsvector matching via
+  `websearch_to_tsquery`, `ts_rank` ordering, and `ts_headline` excerpts over
+  the stored generated `messages.content_tsv` column. Boot-time provisioning is
+  a no-op — the column and its GIN index ship through the central Postgres
+  migration chain.
+
+## How It Attaches
+
+The engine is never imported statically by framework core — attachment always
+goes through the engine registry (a lint rule enforces the dependency
+direction, because a static import would let bundlers silently inline the
+Postgres engine into the core distribution):
+
+- **Explicit registration** — `registerStorageEngine(storageEngine)` before any
+  database client is created, or via the runtime boot option
+  `database.engines: [storageEngine]` (registration precedes database
+  initialization by construction).
+- **Host auto-resolve** — Node and Bun runtime hosts recognize Postgres
+  database URLs through the core hint table, import this package, and register
+  its well-known `storageEngine` export before any client is created.
+- **Test harnesses** — register explicitly (the storage conformance harness
+  calls its idempotent `ensurePostgresEngineRegistered()` in every
+  client-creating entry point).
+
+## Key Exports
+
+- `postgresStorageEngine` — the engine definition
+- `storageEngine` — well-known auto-resolve alias (same object as
+  `postgresStorageEngine`)
+- `isPostgresDuplicateObjectError(error)` / `isPostgresUniqueViolationError(error, constraint?)`
+  — error classifiers (also wired as `postgresStorageEngine.errors`)
+- `migrationAdvisoryLockKey(tableName)` — signed 64-bit advisory lock key
+  (first 8 bytes, big-endian, of `SHA-256("makaio:migrations:<tableName>")`)
+- `buildPostgresLedgerDdl(tableName)` — idempotent ledger `CREATE TABLE` DDL
+- `POSTGRES_MIGRATION_BEGIN` — the pinned `BEGIN ISOLATION LEVEL READ COMMITTED`
+  statement text
+- `postgresFtsSearchStrategy` — the tsvector FTS strategy (also wired as
+  `postgresStorageEngine.fts`)
+
+The Postgres column bundle (`epochMs`, `bool`, `jsonCol`, `autoPk`, `float8`)
+is NOT part of this package: column bundles are schema-declaration vocabulary
+owned by `@makaio/framework/storage/drizzle/columns/postgres`, so hand-written
+Postgres twin schema files in framework core never import this engine package.
+
+The migration statement texts, ledger names, and the advisory-lock key
+derivation are **cross-version contracts**: runners built from different
+framework versions must agree on them byte-for-byte, otherwise concurrent runs
+stop serializing against each other or stop recognizing each other's ledgers.
+All of them are byte-pinned by this package's tests and exercised live by the
+storage conformance suite.
+
+---
+
+*Part of Makaio Framework*

package/dist/client.d.ts

@@ -0,0 +1,52 @@
+import type { DatabaseClient, PostgresClientOptions } from '@makaio/framework/storage/drizzle/client';
+import { type PostgresPoolLike } from './raw-sql.js';
+/** Structural surface of the `pg` module used by {@link createNodePgClient}. */
+interface PgModule {
+    default: {
+        Pool: new (config: {
+            connectionString: string;
+            max: number;
+        }) => PostgresPoolLike;
+    };
+}
+/** Structural surface of the `drizzle-orm/node-postgres` module used by {@link createNodePgClient}. */
+interface NodePgDrizzleModule {
+    drizzle: (pool: PostgresPoolLike) => object;
+}
+/**
+ * Lazy loaders for the Postgres driver modules.
+ *
+ * Internal seam: the production defaults are the literal dynamic imports below;
+ * tests inject a loader that throws to exercise the missing-driver error-wrap
+ * path without mocking the module system.
+ */
+export interface NodePgDriverLoaders {
+    /** Loads the `pg` module. */
+    readonly loadPg: () => Promise<PgModule>;
+    /** Loads the `drizzle-orm/node-postgres` module. */
+    readonly loadDrizzlePg: () => Promise<NodePgDrizzleModule>;
+}
+/**
+ * Creates a database client backed by the node-postgres (`pg`) driver.
+ *
+ * Delegation target of the Postgres engine's `createClient`: the engine
+ * package owns both the dialect-specific behavior registered through the
+ * engine seam and this driver glue.
+ *
+ * Both `'pg'` and `'drizzle-orm/node-postgres'` load through direct dynamic
+ * `import()` calls, so the drivers load on the first Postgres client rather
+ * than at module load (laziness is preserved). Resolution happens from this
+ * module, which declares both as regular dependencies, so it stays
+ * strict-install-safe (pnpm, Yarn PnP) where the drivers are only resolvable
+ * from this package. Bundle-time resolvability is acceptable here precisely
+ * because they are declared dependencies of this package — the build leaves
+ * them external (see `build.ts`); bundler-opacity is only required for
+ * specifiers the resolving package does not declare.
+ * @param url - Postgres connection URL (`postgres://` or `postgresql://`).
+ * @param options - Optional pool tuning options.
+ * @param loaders - Internal driver-loader seam; defaults to the literal
+ *   dynamic imports. Tests inject a throwing loader to exercise the error path.
+ * @returns Database client with drizzle ORM instance and async close method.
+ */
+export declare function createNodePgClient(url: string, options: PostgresClientOptions | undefined, loaders?: NodePgDriverLoaders): Promise<DatabaseClient>;
+export {};

package/dist/engine.d.ts

@@ -0,0 +1,21 @@
+import type { StorageEngine } from '@makaio/framework/storage/drizzle';
+/**
+ * The Postgres storage engine.
+ *
+ * Claims `postgres://` and `postgresql://` URLs (case-insensitively,
+ * mirroring the engine hint table in `@makaio/storage-drizzle`) and creates
+ * clients over the node-postgres driver glue owned by this package (`pg` is
+ * a regular dependency, loaded lazily when a client is created). Register it
+ * explicitly via `registerStorageEngine` or host boot options; Node runtime hosts
+ * additionally auto-register it for recognized database URLs through this
+ * package's well-known `storageEngine` export.
+ *
+ * Migration behavior preserves the cross-version Postgres contracts
+ * byte-for-byte (`__makaio_migrations` ledger name and DDL,
+ * `BEGIN ISOLATION LEVEL READ COMMITTED`, the advisory-lock key derivation,
+ * `__makaio_migrations_<hash>` extension ledgers). The chain directory name
+ * `drizzle-postgres` is deliberately distinct from the default `drizzle`
+ * directory so embedded-host chain discovery never picks up the Postgres
+ * chain.
+ */
+export declare const postgresStorageEngine: StorageEngine;

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Returns `true` when the error (or any link in its cause chain) reports
+ * that a schema object already exists on Postgres.
+ *
+ * Matches the SQLSTATE codes `42P07`/`42710`. Used by the migration
+ * applicator to decide whether a failed first CREATE can be adopted into the
+ * ledger.
+ * @param error - Error thrown by a DDL statement.
+ * @returns Whether the failure is a duplicate-schema-object conflict.
+ */
+export declare function isPostgresDuplicateObjectError(error: unknown): boolean;
+/**
+ * Returns `true` when the error (or any link in its cause chain) reports a
+ * Postgres unique-constraint violation.
+ *
+ * Matches SQLSTATE `23505` (unique_violation); when `constraint` is given,
+ * the driver error's `constraint` property must match it too, so callers can
+ * react to one specific index without swallowing unrelated violations.
+ *
+ * Used by write paths that resolve write-write races through a bounded retry
+ * (for example MAX-based counter assignment under `READ COMMITTED`, where two
+ * concurrent statements can compute the same next value).
+ * @param error - Error thrown by a DML statement.
+ * @param constraint - Optional constraint/index name to scope the match.
+ * @returns Whether the failure is a unique-constraint violation.
+ */
+export declare function isPostgresUniqueViolationError(error: unknown, constraint?: string): boolean;

package/dist/fts-strategy.d.ts

@@ -0,0 +1,6 @@
+import { type FtsSearchStrategy } from '@makaio/framework/storage/drizzle';
+/**
+ * The Postgres FTS strategy: tsvector matching via `websearch_to_tsquery`,
+ * `ts_rank` ordering, and `ts_headline` excerpts.
+ */
+export declare const postgresFtsSearchStrategy: FtsSearchStrategy;

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * \@makaio/storage-pg
+ *
+ * Postgres storage engine for the Makaio framework: driver glue, error
+ * classification, and migration behavior packaged behind the storage engine
+ * seam of `@makaio/storage-drizzle`.
+ *
+ * Hosts register the engine explicitly (boot `database.engines` option or
+ * `registerStorageEngine`); Node runtime hosts additionally auto-resolve this
+ * package for recognized `postgres://` / `postgresql://` URLs through the
+ * well-known {@link storageEngine} export.
+ * @packageDocumentation
+ */
+export { postgresStorageEngine } from './engine.js';
+export { isPostgresDuplicateObjectError, isPostgresUniqueViolationError } from './errors.js';
+export { postgresFtsSearchStrategy } from './fts-strategy.js';
+export { buildPostgresLedgerDdl, migrationAdvisoryLockKey, POSTGRES_MIGRATION_BEGIN } from './migrations.js';
+/**
+ * Well-known engine export consumed by host URL auto-resolve: runtime hosts
+ * that recognize a Postgres database URL import this package and register
+ * `storageEngine` with the engine registry. Same object as
+ * {@link postgresStorageEngine}.
+ */
+export declare const storageEngine: import("@makaio/framework/storage/drizzle").StorageEngine;