@ingram-tech/nk-db 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# @ingram-tech/nk-db
+
+The Ingram **Postgres data layer**: one TLS-aware `pg` pool, raw-SQL helpers,
+Drizzle wiring, and a **PGlite** (no-Docker) dev/test harness. It consolidates
+the `src/lib/db/` layer that integrain, orbitr.ee, peppost, and thornhill each
+hand-rolled when they moved off Supabase. Design + rationale:
+[`docs/db-package.md`](https://github.com/ingram-technologies/nextkit/blob/main/docs/db-package.md).
+
+`pg` and `drizzle-orm` are **peer dependencies** (one copy in the app).
+`@electric-sql/pglite` + `@electric-sql/pglite-socket` are **optional** peers —
+add them as `devDependencies` only if you use `nk dev` / the test harness.
+
+## Install
+
+```bash
+bun add @ingram-tech/nk-db pg drizzle-orm
+bun add -d @electric-sql/pglite @electric-sql/pglite-socket   # for PGlite dev/test
+```
+
+Env contract (validated by `keys.ts`; resolves in precedence order):
+
+```dotenv
+DATABASE_URL=…            # direct Postgres (session pooler / :5432), NOT PostgREST
+# fallbacks, for running on Supabase Postgres before the data moves:
+# POSTGRES_URL_NON_POOLING / POSTGRES_URL
+DATABASE_CA_CERT=…        # optional PEM CA → verify-full
+DATABASE_SSL=true         # optional
+DATABASE_POOL_MAX=5       # optional; keep small on serverless
+```
+
+## The one barrel (`src/lib/db.ts`)
+
+Create the pool once and share it across Drizzle, the raw helpers, and Better
+Auth — exactly one pool per process.
+
+```ts
+import { createDb, createPool, createQueries } from "@ingram-tech/nk-db";
+import * as schema from "./schema";
+
+export const pool = createPool(); // TLS-aware; local socket → max:1
+export const db = createDb(pool, schema); // Drizzle — the default query path
+export const { query, one, maybeOne, execute, withTx } = createQueries(pool);
+export { schema };
+```
+
+Then `import { db, query } from "@/lib/db"` everywhere. Better Auth reuses the
+same pool: `betterAuth({ database: pool, … })`.
+
+- **Drizzle** is the default: schema-first, `drizzle-kit` generates migrations
+  into `drizzle/`.
+- **Raw helpers** (`createQueries(pool)`) are the escape hatch — Postgres
+  functions (`select fn($1,…)`), `pgmq` draining, `pg_trgm`. Signatures match the
+  hand-rolled originals, so adopting is a find-and-replace of the import.
+- **`configureTimestampsAsStrings()`** — opt-in, for legacy row types that expect
+  `timestamptz` as ISO strings (on the golden path, prefer Drizzle's
+  `timestamp(..., { mode: "string" })` per column).
+
+## PGlite dev & test (`@ingram-tech/nk-db/pglite`)
+
+`nk dev` runs the `nk-pglite-dev` bin automatically when this package is
+installed: it boots Postgres-in-WASM persisted to `.pglite/`, applies the
+`drizzle/` migrations, sets `DATABASE_URL`, then runs `next dev`. `--fresh` wipes
+and rebuilds. No Docker, no daemon.
+
+Tests use an in-memory instance:
+
+```ts
+import { createTestDb } from "@ingram-tech/nk-db/pglite";
+
+// Vitest: fileParallelism:false (the socket is single-connection).
+const { pool, db, reset, close } = await createTestDb({ migrationsFolder: "drizzle" });
+// beforeEach(reset); afterAll(close);
+```
+
+## Gotchas it bakes in
+
+- **Local pool is capped at `max:1`** — the PGlite socket is single-connection;
+  a larger pool breaks dev with "Connection terminated unexpectedly".
+- **`pg.Pool` destroys a connection on a query *error*.** Don't catch unique
+  violations as control flow — use `INSERT … ON CONFLICT DO NOTHING RETURNING …`.
+- **`jsonb` params:** `JSON.stringify()` the value and cast `$n::jsonb` (Drizzle's
+  `jsonb()` columns handle this).

package/dist/drizzle.d.ts

@@ -0,0 +1,14 @@
+import { type NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { Pool } from "pg";
+/**
+ * Build the Drizzle instance on the shared pool. This is the default query path
+ * for app tables — schema-first, with `drizzle-kit` generating the migrations
+ * (kills the hand-written-SQL drift). It rides the same `pg.Pool` that backs the
+ * raw helpers and Better Auth, so there's still exactly one pool per process.
+ *
+ *   import * as schema from "./schema";
+ *   export const pool = createPool();
+ *   export const db = createDb(pool, schema);
+ */
+export declare const createDb: <TSchema extends Record<string, unknown>>(pool: Pool, schema: TSchema) => NodePgDatabase<TSchema>;
+//# sourceMappingURL=drizzle.d.ts.map

package/dist/drizzle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../src/drizzle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,MAAM,IAAI,EACV,QAAQ,OAAO,KACb,cAAc,CAAC,OAAO,CAA8B,CAAC"}

package/dist/drizzle.js

@@ -0,0 +1,13 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+/**
+ * Build the Drizzle instance on the shared pool. This is the default query path
+ * for app tables — schema-first, with `drizzle-kit` generating the migrations
+ * (kills the hand-written-SQL drift). It rides the same `pg.Pool` that backs the
+ * raw helpers and Better Auth, so there's still exactly one pool per process.
+ *
+ *   import * as schema from "./schema";
+ *   export const pool = createPool();
+ *   export const db = createDb(pool, schema);
+ */
+export const createDb = (pool, schema) => drizzle(pool, { schema });
+//# sourceMappingURL=drizzle.js.map

package/dist/drizzle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.js","sourceRoot":"","sources":["../src/drizzle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAuB,MAAM,2BAA2B,CAAC;AAGzE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACvB,IAAU,EACV,MAAe,EACW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createDb } from "./drizzle";
+export { type DbEnv, dbEnv, getDatabaseUrl, isConfigured } from "./keys";
+export { type CreatePoolConfig, createPool } from "./pool";
+export { createQueries, type PoolQueries, type Queries } from "./queries";
+export { configureTimestampsAsStrings } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// The Ingram Postgres data layer. The PGlite dev/test harness lives behind the
+// "@ingram-tech/nk-db/pglite" subpath so its WASM/dev-only deps never reach a
+// production bundle.
+export { createDb } from "./drizzle";
+export { dbEnv, getDatabaseUrl, isConfigured } from "./keys";
+export { createPool } from "./pool";
+export { createQueries } from "./queries";
+export { configureTimestampsAsStrings } from "./types";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8EAA8E;AAC9E,qBAAqB;AAErB,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAc,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAyB,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAkC,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Environment contract for @ingram-tech/nk-db.
+ *
+ * Following the "each package owns its own env validation" pattern (see
+ * @ingram-tech/nk-auth). Env vars are external input, so we parse them with Zod
+ * (per docs/code-style.md) rather than reading `process.env` ad hoc.
+ *
+ * The connection string resolves in a fixed precedence so an app can deploy the
+ * direct-`pg` code **while still pointed at Supabase Postgres**, before any data
+ * has moved (see docs/db-package.md and the Supabase->Postgres playbook):
+ *
+ *   1. DATABASE_URL                 — our DO cluster (or the local PGlite socket)
+ *   2. POSTGRES_URL_NON_POOLING     — Supabase integration's direct URL
+ *   3. POSTGRES_URL                 — Supabase integration's pooled URL
+ *
+ * Optional TLS / pool controls:
+ *   DATABASE_SSL        — "true" to require TLS (managed hosts)
+ *   DATABASE_CA_CERT    — PEM CA; when set, verify the server cert + hostname
+ *   DATABASE_POOL_MAX   — pool size cap; keep small on serverless (e.g. 5)
+ */
+export interface DbEnv {
+    /** The resolved connection string (precedence applied). */
+    connectionString: string;
+    /** PEM CA cert; when set, the pool verifies the server cert + hostname. */
+    caCert?: string;
+    /** Whether TLS was explicitly requested via DATABASE_SSL. */
+    ssl: boolean;
+    /** Pool size cap, if configured. */
+    poolMax?: number;
+}
+/**
+ * Resolve the connection string from the environment by precedence, without
+ * validating the rest of the contract. Returns `undefined` if none is set —
+ * useful for "is a database configured?" checks (e.g. degrade in local dev).
+ */
+export declare const getDatabaseUrl: (env?: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * Read and validate the nk-db env vars at once. Throws a single error listing
+ * everything missing/invalid so a misconfigured site fails fast at startup
+ * rather than at first query.
+ */
+export declare const dbEnv: () => DbEnv;
+/** Whether a database connection string is present (degrade gracefully if not). */
+export declare const isConfigured: () => boolean;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAaH,MAAM,WAAW,KAAK;IACrB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAC1B,MAAK,MAAM,CAAC,UAAwB,KAClC,MAAM,GAAG,SACyD,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAO,KAqBxB,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,YAAY,QAAO,OAAyC,CAAC"}

package/dist/keys.js

@@ -0,0 +1,63 @@
+/**
+ * Environment contract for @ingram-tech/nk-db.
+ *
+ * Following the "each package owns its own env validation" pattern (see
+ * @ingram-tech/nk-auth). Env vars are external input, so we parse them with Zod
+ * (per docs/code-style.md) rather than reading `process.env` ad hoc.
+ *
+ * The connection string resolves in a fixed precedence so an app can deploy the
+ * direct-`pg` code **while still pointed at Supabase Postgres**, before any data
+ * has moved (see docs/db-package.md and the Supabase->Postgres playbook):
+ *
+ *   1. DATABASE_URL                 — our DO cluster (or the local PGlite socket)
+ *   2. POSTGRES_URL_NON_POOLING     — Supabase integration's direct URL
+ *   3. POSTGRES_URL                 — Supabase integration's pooled URL
+ *
+ * Optional TLS / pool controls:
+ *   DATABASE_SSL        — "true" to require TLS (managed hosts)
+ *   DATABASE_CA_CERT    — PEM CA; when set, verify the server cert + hostname
+ *   DATABASE_POOL_MAX   — pool size cap; keep small on serverless (e.g. 5)
+ */
+import { z } from "zod";
+const schema = z.object({
+    DATABASE_URL: z.string().min(1).optional(),
+    POSTGRES_URL_NON_POOLING: z.string().min(1).optional(),
+    POSTGRES_URL: z.string().min(1).optional(),
+    DATABASE_SSL: z.enum(["true", "false"]).optional(),
+    DATABASE_CA_CERT: z.string().min(1).optional(),
+    DATABASE_POOL_MAX: z.coerce.number().int().positive().optional(),
+});
+/**
+ * Resolve the connection string from the environment by precedence, without
+ * validating the rest of the contract. Returns `undefined` if none is set —
+ * useful for "is a database configured?" checks (e.g. degrade in local dev).
+ */
+export const getDatabaseUrl = (env = process.env) => env.DATABASE_URL ?? env.POSTGRES_URL_NON_POOLING ?? env.POSTGRES_URL;
+/**
+ * Read and validate the nk-db env vars at once. Throws a single error listing
+ * everything missing/invalid so a misconfigured site fails fast at startup
+ * rather than at first query.
+ */
+export const dbEnv = () => {
+    const result = schema.safeParse(process.env);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join(", ");
+        throw new Error(`@ingram-tech/nk-db: invalid environment — ${issues}`);
+    }
+    const connectionString = getDatabaseUrl();
+    if (!connectionString) {
+        throw new Error("@ingram-tech/nk-db: no database connection string — set DATABASE_URL " +
+            "(or POSTGRES_URL_NON_POOLING / POSTGRES_URL).");
+    }
+    return {
+        connectionString,
+        caCert: result.data.DATABASE_CA_CERT,
+        ssl: result.data.DATABASE_SSL === "true",
+        poolMax: result.data.DATABASE_POOL_MAX,
+    };
+};
+/** Whether a database connection string is present (degrade gracefully if not). */
+export const isConfigured = () => getDatabaseUrl() !== undefined;
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IACvB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1C,wBAAwB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACtD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1C,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC9C,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAChE,CAAC,CAAC;AAaH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC7B,MAAyB,OAAO,CAAC,GAAG,EACf,EAAE,CACvB,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,wBAAwB,IAAI,GAAG,CAAC,YAAY,CAAC;AAEtE;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,GAAU,EAAE;IAChC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAChC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;aAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,6CAA6C,MAAM,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,gBAAgB,GAAG,cAAc,EAAE,CAAC;IAC1C,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACd,uEAAuE;YACtE,+CAA+C,CAChD,CAAC;IACH,CAAC;IACD,OAAO;QACN,gBAAgB;QAChB,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,gBAAgB;QACpC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,KAAK,MAAM;QACxC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,iBAAiB;KACtC,CAAC;AACH,CAAC,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAG,GAAY,EAAE,CAAC,cAAc,EAAE,KAAK,SAAS,CAAC"}

package/dist/pglite/dev.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=dev.d.ts.map

package/dist/pglite/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/pglite/dev.ts"],"names":[],"mappings":""}

package/dist/pglite/dev.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// The `nk-pglite-dev` bin: what `nk dev` shells out to when this package is
+// installed. Boots PGlite (persisted to .pglite/), applies the `drizzle/`
+// migrations, then runs `next dev` against it. `--fresh` wipes and rebuilds.
+//
+// Run directly by Node, so the relative import carries a `.js` extension.
+import { startPgliteDev } from "./index.js";
+const fresh = process.argv.includes("--fresh");
+const nextArgs = process.argv.slice(2).filter((arg) => arg !== "--fresh");
+startPgliteDev({ fresh, nextArgs }).catch((error) => {
+    console.error("nk(pglite): failed to start —", error);
+    process.exit(1);
+});
+//# sourceMappingURL=dev.js.map

package/dist/pglite/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/pglite/dev.ts"],"names":[],"mappings":";AACA,4EAA4E;AAC5E,0EAA0E;AAC1E,6EAA6E;AAC7E,EAAE;AACF,0EAA0E;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC;AAE1E,cAAc,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC5D,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;IACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC,CAAC,CAAC"}

package/dist/pglite/index.d.ts

@@ -0,0 +1,55 @@
+import { PGlite } from "@electric-sql/pglite";
+import { PGLiteSocketServer } from "@electric-sql/pglite-socket";
+import type { Pool } from "pg";
+export interface PgliteServerOptions {
+    /** Persisted data dir; omit for an in-memory database (tests). */
+    dataDir?: string;
+    /** Host to bind the TCP socket on. Default `127.0.0.1`. */
+    host?: string;
+    /** Port for the TCP socket. Default `PGLITE_PORT` env or `5432`. */
+    port?: number;
+    /** Wipe `dataDir` before booting (rebuild after adding a migration). */
+    fresh?: boolean;
+    /** Drizzle migrations folder for the default applier. Default `drizzle`. */
+    migrationsFolder?: string;
+    /** Override how migrations are applied (e.g. raw-SQL apps). */
+    migrate?: (db: PGlite) => Promise<void>;
+}
+export interface PgliteServer {
+    db: PGlite;
+    server: PGLiteSocketServer;
+    /** Connection string the app's `pg.Pool` should use. */
+    databaseUrl: string;
+    stop: () => Promise<void>;
+}
+/**
+ * Boot PGlite, apply migrations (on a fresh/in-memory db), and expose it over a
+ * TCP socket so a normal `pg.Pool` connects via `DATABASE_URL` with no app code
+ * changes. Reused by both `startPgliteDev` (persisted) and `createTestDb`
+ * (in-memory). The socket server is single-connection — keep the consuming pool
+ * at `max: 1` (createPool does this for local hosts).
+ */
+export declare const createPgliteServer: (options?: PgliteServerOptions) => Promise<PgliteServer>;
+/**
+ * `nk dev`'s PGlite mode: boot a persisted local Postgres, then `next dev` with
+ * `DATABASE_URL` pointed at it. Invoked by the `nk-pglite-dev` bin.
+ */
+export declare const startPgliteDev: (options?: PgliteServerOptions & {
+    nextArgs?: string[];
+}) => Promise<void>;
+export interface TestDb {
+    /** A `pg.Pool` (max:1) bound to the in-memory database over the socket. */
+    pool: Pool;
+    databaseUrl: string;
+    /** TRUNCATE every public table — call in Vitest `beforeEach`. */
+    reset: () => Promise<void>;
+    /** Close the pool and the database — call in `afterAll`. */
+    close: () => Promise<void>;
+}
+/**
+ * An in-memory PGlite for integration tests. Real Postgres semantics, instant,
+ * no cleanup. Run with Vitest `fileParallelism: false` (the socket is
+ * single-connection) and close in `afterAll` (modules are isolated per file).
+ */
+export declare const createTestDb: (options?: PgliteServerOptions) => Promise<TestDb>;
+//# sourceMappingURL=index.d.ts.map

package/dist/pglite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pglite/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B,MAAM,WAAW,mBAAmB;IACnC,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,kBAAkB,CAAC;IAC3B,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAUD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC9B,UAAS,mBAAwB,KAC/B,OAAO,CAAC,YAAY,CAuBtB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAC1B,UAAS,mBAAmB,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,KACzD,OAAO,CAAC,IAAI,CA0Bd,CAAC;AAEF,MAAM,WAAW,MAAM;IACtB,2EAA2E;IAC3E,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACxB,UAAS,mBAAwB,KAC/B,OAAO,CAAC,MAAM,CAiBhB,CAAC"}

package/dist/pglite/index.js

@@ -0,0 +1,94 @@
+// PGlite dev/test harness — Postgres-in-WASM, no Docker. Ported from the proven
+// peppost `scripts/pglite-dev.ts` (which its own comment said should "move into
+// @ingram-tech/nk-cli so the whole fleet inherits it"). PGlite 0.5.x is
+// PostgreSQL 18.3, so plpgsql / gen_random_uuid() / RLS all work and dev matches
+// a pg18 prod target.
+//
+// This module is the only place the PGlite deps are imported; it loads solely
+// via the "@ingram-tech/nk-db/pglite" subpath (dev/test), never from the main
+// entry, so production bundles stay clean.
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { PGlite } from "@electric-sql/pglite";
+import { PGLiteSocketServer } from "@electric-sql/pglite-socket";
+const defaultMigrate = (migrationsFolder) => async (db) => {
+    const { drizzle } = await import("drizzle-orm/pglite");
+    const { migrate } = await import("drizzle-orm/pglite/migrator");
+    await migrate(drizzle(db), { migrationsFolder });
+};
+/**
+ * Boot PGlite, apply migrations (on a fresh/in-memory db), and expose it over a
+ * TCP socket so a normal `pg.Pool` connects via `DATABASE_URL` with no app code
+ * changes. Reused by both `startPgliteDev` (persisted) and `createTestDb`
+ * (in-memory). The socket server is single-connection — keep the consuming pool
+ * at `max: 1` (createPool does this for local hosts).
+ */
+export const createPgliteServer = async (options = {}) => {
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? Number(process.env.PGLITE_PORT ?? 5432);
+    const migrationsFolder = options.migrationsFolder ?? "drizzle";
+    const { dataDir } = options;
+    if (options.fresh && dataDir && existsSync(dataDir)) {
+        await rm(dataDir, { recursive: true, force: true });
+    }
+    const needsMigrations = !dataDir || !existsSync(dataDir);
+    const db = dataDir ? await PGlite.create({ dataDir }) : await PGlite.create();
+    if (needsMigrations) {
+        await (options.migrate ?? defaultMigrate(migrationsFolder))(db);
+    }
+    const server = new PGLiteSocketServer({ db, host, port });
+    await server.start();
+    const databaseUrl = `postgresql://postgres:postgres@${host}:${port}/postgres`;
+    const stop = async () => {
+        await server.stop().catch(() => { });
+        await db.close().catch(() => { });
+    };
+    return { db, server, databaseUrl, stop };
+};
+/**
+ * `nk dev`'s PGlite mode: boot a persisted local Postgres, then `next dev` with
+ * `DATABASE_URL` pointed at it. Invoked by the `nk-pglite-dev` bin.
+ */
+export const startPgliteDev = async (options = {}) => {
+    const { spawn } = await import("node:child_process");
+    const { databaseUrl, stop } = await createPgliteServer({
+        dataDir: options.dataDir ?? ".pglite",
+        ...options,
+    });
+    console.log(`nk(pglite): Postgres 18 (WASM) ready on ${databaseUrl} — no Docker, no Supabase CLI`);
+    const child = spawn("bunx", ["next", "dev", "--turbopack", ...(options.nextArgs ?? [])], { stdio: "inherit", env: { ...process.env, DATABASE_URL: databaseUrl } });
+    let closing = false;
+    const close = async (code) => {
+        if (closing)
+            return;
+        closing = true;
+        await stop();
+        process.exit(code);
+    };
+    process.on("SIGINT", () => child.kill("SIGINT"));
+    process.on("SIGTERM", () => child.kill("SIGTERM"));
+    child.on("exit", (code) => void close(code ?? 0));
+};
+/**
+ * An in-memory PGlite for integration tests. Real Postgres semantics, instant,
+ * no cleanup. Run with Vitest `fileParallelism: false` (the socket is
+ * single-connection) and close in `afterAll` (modules are isolated per file).
+ */
+export const createTestDb = async (options = {}) => {
+    const { Pool } = await import("pg");
+    const { databaseUrl, stop } = await createPgliteServer(options);
+    const pool = new Pool({ connectionString: databaseUrl, max: 1 });
+    const reset = async () => {
+        const result = await pool.query("select tablename from pg_tables where schemaname = 'public'");
+        if (result.rows.length === 0)
+            return;
+        const list = result.rows.map((row) => `"${row.tablename}"`).join(", ");
+        await pool.query(`truncate table ${list} restart identity cascade`);
+    };
+    const close = async () => {
+        await pool.end();
+        await stop();
+    };
+    return { pool, databaseUrl, reset, close };
+};
+//# sourceMappingURL=index.js.map

package/dist/pglite/index.js.map

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

package/dist/pool.d.ts

@@ -0,0 +1,33 @@
+import { Pool } from "pg";
+export interface CreatePoolConfig {
+    /** Override the resolved connection string (defaults to the env contract). */
+    connectionString?: string;
+    /** PEM CA cert; when set, the server cert + hostname are verified. */
+    caCert?: string;
+    /** Pool size cap. Defaults to env DATABASE_POOL_MAX, or 1 for a local socket. */
+    max?: number;
+}
+/**
+ * The one shared `pg.Pool`. Reuse this for everything — app queries (via
+ * `createQueries` / Drizzle) AND Better Auth's adapter — so there's exactly one
+ * pool per process (the playbook's rule).
+ *
+ * TLS handling matches the fleet standard (lifted from nk-auth's
+ * `createAuthPool`):
+ *
+ *   - `caCert` set  -> verify the server cert + hostname (`sslmode=verify-full`).
+ *   - local host    -> no TLS, and cap at `max: 1` (the PGlite socket server is
+ *                      single-connection/multiplexed; a larger pool breaks dev).
+ *   - otherwise     -> TLS **without** chain verification. Managed certs (DO,
+ *                      Supabase) aren't in Node's trust store, so full
+ *                      verification fails with "self-signed certificate in
+ *                      certificate chain"; the link is still encrypted. `sslmode`
+ *                      is stripped from the URL because `pg` ignores the `ssl`
+ *                      object when the URL carries SSL settings.
+ *
+ * On Vercel Fluid / serverless, hold the pool on `globalThis` so warm
+ * invocations reuse it instead of opening a connection per request (see the
+ * app-side `src/lib/db.ts` pattern in docs/db-package.md).
+ */
+export declare const createPool: (config?: CreatePoolConfig) => Pool;
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAmB,MAAM,IAAI,CAAC;AAG3C,MAAM,WAAW,gBAAgB;IAChC,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,UAAU,GAAI,SAAQ,gBAAqB,KAAG,IA6B1D,CAAC"}

package/dist/pool.js

@@ -0,0 +1,54 @@
+import { Pool } from "pg";
+import { dbEnv } from "./keys";
+const isLocal = (connectionString) => connectionString.includes("127.0.0.1") || connectionString.includes("localhost");
+/**
+ * The one shared `pg.Pool`. Reuse this for everything — app queries (via
+ * `createQueries` / Drizzle) AND Better Auth's adapter — so there's exactly one
+ * pool per process (the playbook's rule).
+ *
+ * TLS handling matches the fleet standard (lifted from nk-auth's
+ * `createAuthPool`):
+ *
+ *   - `caCert` set  -> verify the server cert + hostname (`sslmode=verify-full`).
+ *   - local host    -> no TLS, and cap at `max: 1` (the PGlite socket server is
+ *                      single-connection/multiplexed; a larger pool breaks dev).
+ *   - otherwise     -> TLS **without** chain verification. Managed certs (DO,
+ *                      Supabase) aren't in Node's trust store, so full
+ *                      verification fails with "self-signed certificate in
+ *                      certificate chain"; the link is still encrypted. `sslmode`
+ *                      is stripped from the URL because `pg` ignores the `ssl`
+ *                      object when the URL carries SSL settings.
+ *
+ * On Vercel Fluid / serverless, hold the pool on `globalThis` so warm
+ * invocations reuse it instead of opening a connection per request (see the
+ * app-side `src/lib/db.ts` pattern in docs/db-package.md).
+ */
+export const createPool = (config = {}) => {
+    const env = config.connectionString ? undefined : dbEnv();
+    const connectionString = config.connectionString ?? env?.connectionString;
+    if (!connectionString) {
+        throw new Error("@ingram-tech/nk-db: createPool needs a connection string.");
+    }
+    const caCert = config.caCert ?? env?.caCert;
+    const local = isLocal(connectionString);
+    const max = config.max ?? env?.poolMax ?? (local ? 1 : undefined);
+    const base = max === undefined ? {} : { max };
+    if (caCert) {
+        return new Pool({
+            ...base,
+            connectionString,
+            ssl: { ca: caCert, rejectUnauthorized: true },
+        });
+    }
+    if (local) {
+        return new Pool({ ...base, connectionString });
+    }
+    const url = new URL(connectionString);
+    url.searchParams.delete("sslmode");
+    return new Pool({
+        ...base,
+        connectionString: url.toString(),
+        ssl: { rejectUnauthorized: false },
+    });
+};
+//# sourceMappingURL=pool.js.map

package/dist/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAmB,MAAM,IAAI,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAW/B,MAAM,OAAO,GAAG,CAAC,gBAAwB,EAAW,EAAE,CACrD,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,SAA2B,EAAE,EAAQ,EAAE;IACjE,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IAC1D,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,IAAI,GAAG,EAAE,gBAAgB,CAAC;IAC1E,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,MAAM,CAAC;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,GAAG,EAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAElE,MAAM,IAAI,GAAe,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;IAE1D,IAAI,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,IAAI,CAAC;YACf,GAAG,IAAI;YACP,gBAAgB;YAChB,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE;SAC7C,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACtC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACnC,OAAO,IAAI,IAAI,CAAC;QACf,GAAG,IAAI;QACP,gBAAgB,EAAE,GAAG,CAAC,QAAQ,EAAE;QAChC,GAAG,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE;KAClC,CAAC,CAAC;AACJ,CAAC,CAAC"}

package/dist/queries.d.ts

@@ -0,0 +1,29 @@
+import type { Pool, QueryResultRow } from "pg";
+export interface Queries {
+    /** Run a query and return all rows. */
+    query: <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => Promise<T[]>;
+    /** Run a query expected to return at most one row; `null` when none. */
+    maybeOne: <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => Promise<T | null>;
+    /** Run a query that must return exactly one row; throws otherwise. */
+    one: <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => Promise<T>;
+    /** Run a write and return the affected row count. */
+    execute: (text: string, params?: unknown[]) => Promise<number>;
+}
+export interface PoolQueries extends Queries {
+    /**
+     * Run `fn` inside a single transaction on a dedicated client (`begin` /
+     * `commit`, `rollback` on throw). The `tx` passed to `fn` is a `Queries`
+     * bound to that client — use it, not the pool-level helpers, for the
+     * statements that must be atomic.
+     */
+    withTx: <T>(fn: (tx: Queries) => Promise<T>) => Promise<T>;
+}
+/**
+ * Bind the raw-SQL helpers (`query` / `one` / `maybeOne` / `execute` / `withTx`)
+ * to a pool. Signatures match what peppost/orbitr.ee hand-rolled, so adopting
+ * this is a find-and-replace of the import. Drizzle (via `createDb`) is the
+ * default query path; these are the escape hatch for SQL the ORM is awkward at
+ * (Postgres-function `select fn($1,…)` calls, `pgmq` draining, `pg_trgm`).
+ */
+export declare const createQueries: (pool: Pool) => PoolQueries;
+//# sourceMappingURL=queries.d.ts.map

package/dist/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAc,cAAc,EAAE,MAAM,IAAI,CAAC;AAK3D,MAAM,WAAW,OAAO;IACvB,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAChD,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,KACd,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAClB,wEAAwE;IACxE,QAAQ,EAAE,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACnD,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,KACd,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,sEAAsE;IACtE,GAAG,EAAE,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,KACd,OAAO,CAAC,CAAC,CAAC,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/D;AAoCD,MAAM,WAAW,WAAY,SAAQ,OAAO;IAC3C;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC3D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,KAAG,WAiB1C,CAAC"}

package/dist/queries.js

@@ -0,0 +1,53 @@
+const bind = (executor) => {
+    const query = async (text, params = []) => {
+        const result = await executor.query(text, params);
+        return result.rows;
+    };
+    const maybeOne = async (text, params = []) => {
+        const rows = await query(text, params);
+        return rows[0] ?? null;
+    };
+    const one = async (text, params = []) => {
+        const rows = await query(text, params);
+        const row = rows[0];
+        if (!row)
+            throw new Error("Expected exactly one row, got none");
+        if (rows.length > 1) {
+            throw new Error(`Expected exactly one row, got ${rows.length}`);
+        }
+        return row;
+    };
+    const execute = async (text, params = []) => {
+        const result = await executor.query(text, params);
+        return result.rowCount ?? 0;
+    };
+    return { query, maybeOne, one, execute };
+};
+/**
+ * Bind the raw-SQL helpers (`query` / `one` / `maybeOne` / `execute` / `withTx`)
+ * to a pool. Signatures match what peppost/orbitr.ee hand-rolled, so adopting
+ * this is a find-and-replace of the import. Drizzle (via `createDb`) is the
+ * default query path; these are the escape hatch for SQL the ORM is awkward at
+ * (Postgres-function `select fn($1,…)` calls, `pgmq` draining, `pg_trgm`).
+ */
+export const createQueries = (pool) => {
+    const base = bind(pool);
+    const withTx = async (fn) => {
+        const client = await pool.connect();
+        try {
+            await client.query("begin");
+            const result = await fn(bind(client));
+            await client.query("commit");
+            return result;
+        }
+        catch (error) {
+            await client.query("rollback");
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    };
+    return { ...base, withTx };
+};
+//# sourceMappingURL=queries.js.map

package/dist/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"AAyBA,MAAM,IAAI,GAAG,CAAC,QAAkB,EAAW,EAAE;IAC5C,MAAM,KAAK,GAAG,KAAK,EAClB,IAAY,EACZ,SAAoB,EAAE,EACP,EAAE;QACjB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAI,IAAI,EAAE,MAAM,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC,IAAI,CAAC;IACpB,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,KAAK,EACrB,IAAY,EACZ,SAAoB,EAAE,EACF,EAAE;QACtB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAI,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACxB,CAAC,CAAC;IACF,MAAM,GAAG,GAAG,KAAK,EAChB,IAAY,EACZ,SAAoB,EAAE,EACT,EAAE;QACf,MAAM,IAAI,GAAG,MAAM,KAAK,CAAI,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAChE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,GAAG,CAAC;IACZ,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,EAAE,IAAY,EAAE,SAAoB,EAAE,EAAmB,EAAE;QAC/E,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAClD,OAAO,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC,CAAC;AAYF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAU,EAAe,EAAE;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,MAAM,MAAM,GAAG,KAAK,EAAK,EAA+B,EAAc,EAAE;QACvE,MAAM,MAAM,GAAe,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QAChD,IAAI,CAAC;YACJ,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACtC,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,MAAM,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/B,MAAM,KAAK,CAAC;QACb,CAAC;gBAAS,CAAC;YACV,MAAM,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;IACF,CAAC,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Opt-in: keep `timestamptz` / `timestamp` columns as the raw ISO **strings**
+ * Postgres sends, instead of letting `pg` parse them into JS `Date`s.
+ *
+ * Why this exists: supabase-js / PostgREST returned timestamps as strings, and
+ * Supabase-generated row types declare them `string`. After moving to direct
+ * `pg`, the same columns come back as `Date`, which silently breaks any code
+ * doing string ops on them (and mismatches the generated types). Call this once
+ * at startup if your row types expect strings.
+ *
+ * Note: with Drizzle you usually express this per-column instead
+ * (`timestamp(..., { mode: "string" })`), so reach for that first on the golden
+ * path; this global switch is for the raw-helper / legacy-types case.
+ */
+export declare const configureTimestampsAsStrings: () => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B,QAAO,IAI/C,CAAC"}

package/dist/types.js

@@ -0,0 +1,24 @@
+import pg from "pg";
+/** Postgres type OIDs we care about. */
+const TIMESTAMPTZ_OID = 1184;
+const TIMESTAMP_OID = 1114;
+/**
+ * Opt-in: keep `timestamptz` / `timestamp` columns as the raw ISO **strings**
+ * Postgres sends, instead of letting `pg` parse them into JS `Date`s.
+ *
+ * Why this exists: supabase-js / PostgREST returned timestamps as strings, and
+ * Supabase-generated row types declare them `string`. After moving to direct
+ * `pg`, the same columns come back as `Date`, which silently breaks any code
+ * doing string ops on them (and mismatches the generated types). Call this once
+ * at startup if your row types expect strings.
+ *
+ * Note: with Drizzle you usually express this per-column instead
+ * (`timestamp(..., { mode: "string" })`), so reach for that first on the golden
+ * path; this global switch is for the raw-helper / legacy-types case.
+ */
+export const configureTimestampsAsStrings = () => {
+    const keep = (value) => value;
+    pg.types.setTypeParser(TIMESTAMPTZ_OID, keep);
+    pg.types.setTypeParser(TIMESTAMP_OID, keep);
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,wCAAwC;AACxC,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAS,EAAE;IACtD,MAAM,IAAI,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC;IAC9C,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IAC9C,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@ingram-tech/nk-db",
+	"version": "0.1.0",
+	"description": "The Ingram Postgres data layer: one TLS-aware pg pool, raw-SQL helpers, Drizzle wiring, and a PGlite (no-Docker) dev/test harness for Next.js sites.",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ingram-technologies/nextkit.git",
+		"directory": "packages/nk-db"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist"
+	],
+	"bin": {
+		"nk-pglite-dev": "./dist/pglite/dev.js"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./pglite": {
+			"types": "./dist/pglite/index.d.ts",
+			"import": "./dist/pglite/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"type-check": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"zod": "^4.0.0"
+	},
+	"peerDependencies": {
+		"@electric-sql/pglite": ">=0.5.0",
+		"@electric-sql/pglite-socket": ">=0.0.10",
+		"drizzle-orm": ">=0.44.0",
+		"pg": "^8.13.0"
+	},
+	"peerDependenciesMeta": {
+		"@electric-sql/pglite": {
+			"optional": true
+		},
+		"@electric-sql/pglite-socket": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@electric-sql/pglite": "^0.5.0",
+		"@electric-sql/pglite-socket": "^0.0.10",
+		"@ingram-tech/typescript-config": "workspace:*",
+		"@types/node": "^20.0.0",
+		"@types/pg": "^8.11.0",
+		"drizzle-orm": "^0.45.0",
+		"pg": "^8.13.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.6"
+	}
+}