@softure-ai/db 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,15 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`db@x.y.z`).
 
+## 0.1.7
+
+- `createProcessDatabase(url, { schema, max })` returns `{ db, open, close, withDatabase, isOpen }`: a module-level,
+  synchronous `db` over the process-wide handle for the URL. A query before `open()` throws `Database is not open`;
+  `withDatabase(main)` opens, runs and closes for a script. `url` may be a function, read on `open()` (#313).
+- `findDriverError(error)` (`{ code, constraint, message }` of the Postgres error under drizzle's wrapper) and
+  `isConstraintViolation(error, { code, constraint })`, so apps and modules stop copying them (#313).
+- `closeSharedDatabase(url)` closes and forgets one shared handle.
+
 ## 0.1.6
 
 - One database handle per process: `getConfiguredDatabase` opens the config's `database.handle` or URL once, and modules, health route and commands share it.

package/README.md

@@ -7,7 +7,9 @@ The database layer every SOFTURE module stands on. Standard:
 
 A pg/PGlite client chosen by URL, a migrator that runs each module's SQL in the module's own
 Postgres schema (with a ledger, checksums, a lock, a dry run and adoption of existing tables),
-`createTestDatabase` for unit tests, and the `softure migrate` command.
+`createTestDatabase` for unit tests, the `softure migrate` command, a module-level process database
+(`createProcessDatabase`) and helpers that read the Postgres error behind a failed query
+(`findDriverError`, `isConstraintViolation`).
 
 ## 2. Installation
 
@@ -140,6 +142,49 @@ export async function getDb() {
 the modules use can call it too. A migration run on a PGlite handle the app shares keeps the app's
 session settings (`TimeZone`, `search_path`); only what the run changed is put back.
 
+### A module-level `db`
+
+An app whose code imports one `db` everywhere, instead of awaiting a handle in each function,
+creates it once with `createProcessDatabase`. `db` stands in for the shared handle's drizzle instance
+(the one `getSharedDatabase(url)` gives the modules, so there is still one pool); every entry point
+opens it first, and a query before that throws `Database is not open`:
+
+```ts
+// db/index.ts
+import { createProcessDatabase } from "@softure-ai/db";
+import * as schema from "./schema";
+
+// A function: read on open(), so a script may load its environment after importing this file.
+export const { db, open, close, withDatabase } = createProcessDatabase(() => process.env.DATABASE_URL ?? "", { schema });
+
+// instrumentation.ts (the server): open once at startup
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") await (await import("./db")).open();
+}
+
+// scripts/import.ts: opens, runs, closes (also when main throws)
+await withDatabase(async (db) => { /* … */ });
+```
+
+`open()` is idempotent; `close()` closes the shared handle for that URL, which the modules use too,
+so only a script's end calls it. With `schema`, `db.query.<table>` is typed and works.
+
+### Driver errors
+
+`findDriverError(error)` returns `{ code, constraint, message }` of the Postgres error behind a failed
+query (node-postgres and PGlite alike; drizzle wraps it as the `cause`), or `undefined`.
+`isConstraintViolation(error, { code, constraint })` answers whether it is that SQLSTATE on that
+constraint (any constraint when `constraint` is left out):
+
+```ts
+try {
+  await db.insert(articles).values(article);
+} catch (error) {
+  if (!isConstraintViolation(error, { code: "23505", constraint: "articles_slug_key" })) throw error;
+  return err("slug_taken");
+}
+```
+
 ## 4. Mounting
 
 Nothing to mount. Migrations run as a deploy step:

package/dist/driver-errors.d.ts

@@ -0,0 +1,21 @@
+export interface DriverError {
+    /** The SQLSTATE, e.g. `23505` (unique violation) or `23P01` (exclusion violation). */
+    readonly code: string;
+    /** The violated constraint's name, when the error is about one. */
+    readonly constraint: string | undefined;
+    readonly message: string;
+}
+export interface ConstraintViolation {
+    /** The SQLSTATE to match, e.g. `23505`. */
+    readonly code: string;
+    /** The constraint's name; when left out, any constraint (or none) matches. */
+    readonly constraint?: string;
+}
+/** The driver error behind `error` (itself or one of its causes), or undefined when there is none. */
+export declare function findDriverError(error: unknown): DriverError | undefined;
+/**
+ * Whether `error` is the driver's `violation.code`, on `violation.constraint` when given:
+ * `isConstraintViolation(error, { code: "23505", constraint: "articles_slug_key" })` for a taken slug.
+ */
+export declare function isConstraintViolation(error: unknown, violation: ConstraintViolation): boolean;
+//# sourceMappingURL=driver-errors.d.ts.map

package/dist/driver-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-errors.d.ts","sourceRoot":"","sources":["../src/driver-errors.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAMvE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAI7F"}

package/dist/driver-errors.js

@@ -0,0 +1,25 @@
+// The Postgres error behind a failed query. node-postgres and PGlite both put the SQLSTATE in `code` and the
+// violated constraint's name in `constraint`; drizzle wraps that error as the `cause` of its own query error.
+// App and module code that turns a known violation into a result (a taken slug, a conflicting row) reads it here.
+/** How many `cause` links are followed: drizzle adds one, an app's own wrapper may add another. */
+const MAX_CAUSE_DEPTH = 5;
+/** The driver error behind `error` (itself or one of its causes), or undefined when there is none. */
+export function findDriverError(error) {
+    for (let current = error, depth = 0; current instanceof Error && depth < MAX_CAUSE_DEPTH; current = current.cause, depth += 1) {
+        const { code, constraint } = current;
+        if (typeof code === "string")
+            return { code, constraint: typeof constraint === "string" ? constraint : undefined, message: current.message };
+    }
+    return undefined;
+}
+/**
+ * Whether `error` is the driver's `violation.code`, on `violation.constraint` when given:
+ * `isConstraintViolation(error, { code: "23505", constraint: "articles_slug_key" })` for a taken slug.
+ */
+export function isConstraintViolation(error, violation) {
+    const driverError = findDriverError(error);
+    if (driverError?.code !== violation.code)
+        return false;
+    return violation.constraint === undefined || driverError.constraint === violation.constraint;
+}
+//# sourceMappingURL=driver-errors.js.map

package/dist/driver-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-errors.js","sourceRoot":"","sources":["../src/driver-errors.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAC7G,8GAA8G;AAC9G,kHAAkH;AAElH,mGAAmG;AACnG,MAAM,eAAe,GAAG,CAAC,CAAC;AAiB1B,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,KAAK,IAAI,OAAO,GAAY,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,OAAO,YAAY,KAAK,IAAI,KAAK,GAAG,eAAe,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACvI,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,OAAmD,CAAC;QACjF,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/I,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,SAA8B;IAClF,MAAM,WAAW,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,WAAW,EAAE,IAAI,KAAK,SAAS,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACvD,OAAO,SAAS,CAAC,UAAU,KAAK,SAAS,IAAI,WAAW,CAAC,UAAU,KAAK,SAAS,CAAC,UAAU,CAAC;AAC/F,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { createDatabase, createPgliteHandle, createPostgresHandle, isDatabaseHandle, type CreateDatabaseOptions, type Database, type DatabaseHandle, type DatabaseSchema, type PgliteClientDatabase, type PostgresDatabase, type Queryable, } from "./client.js";
-export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { createProcessDatabase, type ProcessDatabase, type ProcessDatabaseOptions } from "./process.js";
+export { findDriverError, isConstraintViolation, type ConstraintViolation, type DriverError } from "./driver-errors.js";
 export { closeConfiguredDatabases, getConfiguredDatabase, openCommandDatabase, type CommandDatabase } from "./configured.js";
 export { computeChecksum, readMigrationFiles, type MigrationFile } from "./migrations/files.js";
 export { describeProblem, type MigrationErrorCode, type MigrationFailure, type MigrationProblem, type MigrationResult, } from "./migrations/problems.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACxH,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,7 +1,9 @@
 // Public API of @softure-ai/db: the database client and the module migrator
 // (docs/02-module-standard.md §4). Test databases: `@softure-ai/db/testing`; CLI: `@softure-ai/db/cli`.
 export { createDatabase, createPgliteHandle, createPostgresHandle, isDatabaseHandle, } from "./client.js";
-export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { createProcessDatabase } from "./process.js";
+export { findDriverError, isConstraintViolation } from "./driver-errors.js";
 export { closeConfiguredDatabases, getConfiguredDatabase, openCommandDatabase } from "./configured.js";
 export { computeChecksum, readMigrationFiles } from "./migrations/files.js";
 export { describeProblem, } from "./migrations/problems.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wGAAwG;AACxG,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,GAQjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAwB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAsB,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,GAKhB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,GAQjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAA0C,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,GAGxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAyC,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wGAAwG;AACxG,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,GAQjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,qBAAqB,EAAqD,MAAM,cAAc,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAA8C,MAAM,oBAAoB,CAAC;AACxH,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAwB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAsB,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,GAKhB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,GAQjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAA0C,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,GAGxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAyC,MAAM,wBAAwB,CAAC"}

package/dist/process.d.ts

@@ -0,0 +1,23 @@
+import type { Database, DatabaseHandle, DatabaseSchema, CreateDatabaseOptions } from "./client.js";
+export interface ProcessDatabaseOptions<TSchema extends DatabaseSchema> extends CreateDatabaseOptions {
+    /** The app's drizzle schema: `db` is built with it, so `db.query.<table>` is typed and works. */
+    readonly schema?: TSchema;
+}
+export interface ProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema> {
+    /** The open database. Usable from module scope; a query before `open()` resolves throws "Database is not open". */
+    readonly db: Database<TSchema>;
+    /** Opens the process-wide handle for the URL (`getSharedDatabase`), once; later calls return the same handle. */
+    readonly open: () => Promise<DatabaseHandle>;
+    /** Closes the handle and forgets it, so `db` refuses queries again. Does nothing when not open. */
+    readonly close: () => Promise<void>;
+    /** For a script: opens, runs `main` with `db`, and closes whether `main` resolves or throws. */
+    readonly withDatabase: <T>(main: (db: Database<TSchema>) => Promise<T>) => Promise<T>;
+    readonly isOpen: () => boolean;
+}
+/**
+ * A module-level database for the process. `url` may be a function, read on `open()`, so a script can load its
+ * environment after importing the module that creates it. The handle is the one `getSharedDatabase(url)` gives the
+ * modules, so the app and the modules share one pool (db README §3, "One handle per process").
+ */
+export declare function createProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema>(url: string | (() => string), options?: ProcessDatabaseOptions<TSchema>): ProcessDatabase<TSchema>;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAKnG,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,cAAc,CAAE,SAAQ,qBAAqB;IACnG,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,cAAc,GAAG,cAAc;IAC9E,mHAAmH;IACnH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC/B,iHAAiH;IACjH,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7C,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACtF,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS,cAAc,GAAG,cAAc,EACnF,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EAC5B,OAAO,GAAE,sBAAsB,CAAC,OAAO,CAAM,GAC5C,eAAe,CAAC,OAAO,CAAC,CA0C1B"}

package/dist/process.js

@@ -0,0 +1,82 @@
+import { closeSharedDatabase, getSharedDatabase } from "./shared.js";
+const NOT_OPEN_MESSAGE = "Database is not open: call open() or withDatabase() at the process entry before querying";
+/**
+ * A module-level database for the process. `url` may be a function, read on `open()`, so a script can load its
+ * environment after importing the module that creates it. The handle is the one `getSharedDatabase(url)` gives the
+ * modules, so the app and the modules share one pool (db README §3, "One handle per process").
+ */
+export function createProcessDatabase(url, options = {}) {
+    const { schema, ...databaseOptions } = options;
+    let opening;
+    let opened;
+    const open = () => {
+        opening ??= openHandle().catch((error) => {
+            opening = undefined;
+            throw error;
+        });
+        return opening;
+    };
+    async function openHandle() {
+        const resolvedUrl = typeof url === "function" ? url() : url;
+        const handle = await getSharedDatabase(resolvedUrl, databaseOptions);
+        opened = { url: resolvedUrl, db: await buildDatabase(handle, schema) };
+        return handle;
+    }
+    const close = async () => {
+        if (opening === undefined)
+            return;
+        const pending = opening;
+        opening = undefined;
+        await pending.catch(() => undefined);
+        const current = opened;
+        opened = undefined;
+        if (current !== undefined)
+            await closeSharedDatabase(current.url);
+    };
+    const withDatabase = async (main) => {
+        await open();
+        try {
+            return await main(db);
+        }
+        finally {
+            await close();
+        }
+    };
+    const db = createDatabaseProxy(() => opened?.db);
+    return { db, open, close, withDatabase, isOpen: () => opened !== undefined };
+}
+/** The handle's drizzle instance, or a new one over the same pool or client when the app passes its schema. */
+async function buildDatabase(handle, schema) {
+    // The handle's own instance is typed with the default schema; without the app's schema the two types agree.
+    if (schema === undefined)
+        return handle.db;
+    if (handle.kind === "postgres") {
+        const { drizzle } = await import("drizzle-orm/node-postgres");
+        return drizzle({ client: handle.pool, schema });
+    }
+    const { drizzle } = await import("drizzle-orm/pglite");
+    return drizzle({ client: handle.client, schema });
+}
+/** A stand-in that forwards every property to the open database, or throws when none is open. */
+function createDatabaseProxy(getDatabase) {
+    return new Proxy({}, {
+        get(_target, property) {
+            const database = getDatabase();
+            if (database === undefined) {
+                // `await db` and `Promise.resolve(db)` look for `then`: a closed database is just not a thenable.
+                if (property === "then")
+                    return undefined;
+                throw new Error(NOT_OPEN_MESSAGE);
+            }
+            const value = Reflect.get(database, property, database);
+            return typeof value === "function" ? value.bind(database) : value;
+        },
+        has(_target, property) {
+            const database = getDatabase();
+            if (database === undefined)
+                throw new Error(NOT_OPEN_MESSAGE);
+            return Reflect.has(database, property);
+        },
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/process.js.map

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

package/dist/shared.d.ts

@@ -4,6 +4,8 @@ import { type CreateDatabaseOptions, type DatabaseHandle } from "./client.js";
  * A failed open is not kept, so the next call tries again.
  */
 export declare function getSharedDatabase(url: string, options?: CreateDatabaseOptions): Promise<DatabaseHandle>;
+/** Closes and forgets the shared handle for `url`, if one is open. For a script's end. */
+export declare function closeSharedDatabase(url: string): Promise<void>;
 /** Closes and forgets every shared handle. For tests and graceful shutdown. */
 export declare function closeSharedDatabases(): Promise<void>;
 //# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ9F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,+EAA+E;AAC/E,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1D"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ9F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,0FAA0F;AAC1F,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpE;AAED,+EAA+E;AAC/E,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1D"}

package/dist/shared.js

@@ -19,6 +19,15 @@ export function getSharedDatabase(url, options = {}) {
     }
     return handle;
 }
+/** Closes and forgets the shared handle for `url`, if one is open. For a script's end. */
+export async function closeSharedDatabase(url) {
+    const handle = host[HANDLES_KEY]?.get(url);
+    if (handle === undefined)
+        return;
+    host[HANDLES_KEY]?.delete(url);
+    const opened = await handle.catch(() => undefined);
+    await opened?.close();
+}
 /** Closes and forgets every shared handle. For tests and graceful shutdown. */
 export async function closeSharedDatabases() {
     const handles = host[HANDLES_KEY];

package/dist/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,oGAAoG;AACpG,8FAA8F;AAC9F,sFAAsF;AACtF,OAAO,EAAE,cAAc,EAAmD,MAAM,aAAa,CAAC;AAE9F,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAIhE,MAAM,IAAI,GAAG,UAAmC,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,UAAiC,EAAE;IAChF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,GAAG,EAAmC,CAAC,CAAC;IACnF,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAChH,CAAC"}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,oGAAoG;AACpG,8FAA8F;AAC9F,sFAAsF;AACtF,OAAO,EAAE,cAAc,EAAmD,MAAM,aAAa,CAAC;AAE9F,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAIhE,MAAM,IAAI,GAAG,UAAmC,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,UAAiC,EAAE;IAChF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,GAAG,EAAmC,CAAC,CAAC;IACnF,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAW;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IACjC,IAAI,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC;AACxB,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAChH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/db",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "SOFTURE AI database layer: pg/PGlite client, per-module migrator with plan and adopt, PGlite test databases.",
   "license": "MIT",
   "type": "module",

package/src/driver-errors.ts

@@ -0,0 +1,40 @@
+// The Postgres error behind a failed query. node-postgres and PGlite both put the SQLSTATE in `code` and the
+// violated constraint's name in `constraint`; drizzle wraps that error as the `cause` of its own query error.
+// App and module code that turns a known violation into a result (a taken slug, a conflicting row) reads it here.
+
+/** How many `cause` links are followed: drizzle adds one, an app's own wrapper may add another. */
+const MAX_CAUSE_DEPTH = 5;
+
+export interface DriverError {
+  /** The SQLSTATE, e.g. `23505` (unique violation) or `23P01` (exclusion violation). */
+  readonly code: string;
+  /** The violated constraint's name, when the error is about one. */
+  readonly constraint: string | undefined;
+  readonly message: string;
+}
+
+export interface ConstraintViolation {
+  /** The SQLSTATE to match, e.g. `23505`. */
+  readonly code: string;
+  /** The constraint's name; when left out, any constraint (or none) matches. */
+  readonly constraint?: string;
+}
+
+/** The driver error behind `error` (itself or one of its causes), or undefined when there is none. */
+export function findDriverError(error: unknown): DriverError | undefined {
+  for (let current: unknown = error, depth = 0; current instanceof Error && depth < MAX_CAUSE_DEPTH; current = current.cause, depth += 1) {
+    const { code, constraint } = current as { code?: unknown; constraint?: unknown };
+    if (typeof code === "string") return { code, constraint: typeof constraint === "string" ? constraint : undefined, message: current.message };
+  }
+  return undefined;
+}
+
+/**
+ * Whether `error` is the driver's `violation.code`, on `violation.constraint` when given:
+ * `isConstraintViolation(error, { code: "23505", constraint: "articles_slug_key" })` for a taken slug.
+ */
+export function isConstraintViolation(error: unknown, violation: ConstraintViolation): boolean {
+  const driverError = findDriverError(error);
+  if (driverError?.code !== violation.code) return false;
+  return violation.constraint === undefined || driverError.constraint === violation.constraint;
+}

package/src/index.ts

@@ -13,7 +13,9 @@ export {
   type PostgresDatabase,
   type Queryable,
 } from "./client.js";
-export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { createProcessDatabase, type ProcessDatabase, type ProcessDatabaseOptions } from "./process.js";
+export { findDriverError, isConstraintViolation, type ConstraintViolation, type DriverError } from "./driver-errors.js";
 export { closeConfiguredDatabases, getConfiguredDatabase, openCommandDatabase, type CommandDatabase } from "./configured.js";
 export { computeChecksum, readMigrationFiles, type MigrationFile } from "./migrations/files.js";
 export {

package/src/process.ts

@@ -0,0 +1,110 @@
+// A process-wide database for an app whose code imports one module-level `db` (drizzle queries everywhere)
+// instead of awaiting a handle in every function. `db` is a synchronous stand-in for the shared handle's
+// drizzle instance: each entry point (the server's startup, a script's main) opens it first, and a query
+// before that throws instead of silently opening a second pool.
+import type { Database, DatabaseHandle, DatabaseSchema, CreateDatabaseOptions } from "./client.js";
+import { closeSharedDatabase, getSharedDatabase } from "./shared.js";
+
+const NOT_OPEN_MESSAGE = "Database is not open: call open() or withDatabase() at the process entry before querying";
+
+export interface ProcessDatabaseOptions<TSchema extends DatabaseSchema> extends CreateDatabaseOptions {
+  /** The app's drizzle schema: `db` is built with it, so `db.query.<table>` is typed and works. */
+  readonly schema?: TSchema;
+}
+
+export interface ProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema> {
+  /** The open database. Usable from module scope; a query before `open()` resolves throws "Database is not open". */
+  readonly db: Database<TSchema>;
+  /** Opens the process-wide handle for the URL (`getSharedDatabase`), once; later calls return the same handle. */
+  readonly open: () => Promise<DatabaseHandle>;
+  /** Closes the handle and forgets it, so `db` refuses queries again. Does nothing when not open. */
+  readonly close: () => Promise<void>;
+  /** For a script: opens, runs `main` with `db`, and closes whether `main` resolves or throws. */
+  readonly withDatabase: <T>(main: (db: Database<TSchema>) => Promise<T>) => Promise<T>;
+  readonly isOpen: () => boolean;
+}
+
+/**
+ * A module-level database for the process. `url` may be a function, read on `open()`, so a script can load its
+ * environment after importing the module that creates it. The handle is the one `getSharedDatabase(url)` gives the
+ * modules, so the app and the modules share one pool (db README §3, "One handle per process").
+ */
+export function createProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema>(
+  url: string | (() => string),
+  options: ProcessDatabaseOptions<TSchema> = {},
+): ProcessDatabase<TSchema> {
+  const { schema, ...databaseOptions } = options;
+  let opening: Promise<DatabaseHandle> | undefined;
+  let opened: { readonly url: string; readonly db: Database<TSchema> } | undefined;
+
+  const open = (): Promise<DatabaseHandle> => {
+    opening ??= openHandle().catch((error: unknown) => {
+      opening = undefined;
+      throw error;
+    });
+    return opening;
+  };
+
+  async function openHandle(): Promise<DatabaseHandle> {
+    const resolvedUrl = typeof url === "function" ? url() : url;
+    const handle = await getSharedDatabase(resolvedUrl, databaseOptions);
+    opened = { url: resolvedUrl, db: await buildDatabase(handle, schema) };
+    return handle;
+  }
+
+  const close = async (): Promise<void> => {
+    if (opening === undefined) return;
+    const pending = opening;
+    opening = undefined;
+    await pending.catch(() => undefined);
+    const current = opened;
+    opened = undefined;
+    if (current !== undefined) await closeSharedDatabase(current.url);
+  };
+
+  const withDatabase = async <T>(main: (db: Database<TSchema>) => Promise<T>): Promise<T> => {
+    await open();
+    try {
+      return await main(db);
+    } finally {
+      await close();
+    }
+  };
+
+  const db = createDatabaseProxy(() => opened?.db);
+
+  return { db, open, close, withDatabase, isOpen: () => opened !== undefined };
+}
+
+/** The handle's drizzle instance, or a new one over the same pool or client when the app passes its schema. */
+async function buildDatabase<TSchema extends DatabaseSchema>(handle: DatabaseHandle, schema: TSchema | undefined): Promise<Database<TSchema>> {
+  // The handle's own instance is typed with the default schema; without the app's schema the two types agree.
+  if (schema === undefined) return handle.db as unknown as Database<TSchema>;
+  if (handle.kind === "postgres") {
+    const { drizzle } = await import("drizzle-orm/node-postgres");
+    return drizzle({ client: handle.pool, schema });
+  }
+  const { drizzle } = await import("drizzle-orm/pglite");
+  return drizzle({ client: handle.client, schema });
+}
+
+/** A stand-in that forwards every property to the open database, or throws when none is open. */
+function createDatabaseProxy<TSchema extends DatabaseSchema>(getDatabase: () => Database<TSchema> | undefined): Database<TSchema> {
+  return new Proxy({} as Database<TSchema>, {
+    get(_target, property) {
+      const database = getDatabase();
+      if (database === undefined) {
+        // `await db` and `Promise.resolve(db)` look for `then`: a closed database is just not a thenable.
+        if (property === "then") return undefined;
+        throw new Error(NOT_OPEN_MESSAGE);
+      }
+      const value: unknown = Reflect.get(database, property, database);
+      return typeof value === "function" ? (value as (...args: unknown[]) => unknown).bind(database) : value;
+    },
+    has(_target, property) {
+      const database = getDatabase();
+      if (database === undefined) throw new Error(NOT_OPEN_MESSAGE);
+      return Reflect.has(database, property);
+    },
+  });
+}

package/src/shared.ts

@@ -25,6 +25,15 @@ export function getSharedDatabase(url: string, options: CreateDatabaseOptions =
   return handle;
 }
 
+/** Closes and forgets the shared handle for `url`, if one is open. For a script's end. */
+export async function closeSharedDatabase(url: string): Promise<void> {
+  const handle = host[HANDLES_KEY]?.get(url);
+  if (handle === undefined) return;
+  host[HANDLES_KEY]?.delete(url);
+  const opened = await handle.catch(() => undefined);
+  await opened?.close();
+}
+
 /** Closes and forgets every shared handle. For tests and graceful shutdown. */
 export async function closeSharedDatabases(): Promise<void> {
   const handles = host[HANDLES_KEY];