@thomasfosterau/effect-drizzle-ext-pg 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,109 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { makeDatabaseServices } from "@thomasfosterau/effect-drizzle-ext/database";
+import * as PgDrizzle from "drizzle-orm/effect-postgres";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+// src/index.ts
+/**
+* @copyright Thomas Foster
+*
+* The `@effect/sql-pg` binding of the driver-agnostic service factory: one
+* call to {@link makePgDatabase} gives an application the `Database` and
+* `CurrentTransaction` services, the `transact` write boundary and the
+* `readHandle` resolver, all typed over its own `relations` graph, plus the
+* `Effect` and `Layer` that build the Drizzle client itself.
+*
+* `drizzle-orm/effect-postgres` already ships the Effect-native Drizzle
+* driver; nothing here re-implements it. What this module adds is the two
+* pieces every consuming application was spelling out by hand:
+*
+* - the `Layer.effect(Database, PgDrizzle.make({ relations }).pipe(provide(
+*   DefaultServices)))` stanza, which appeared four times per application
+*   (request path, event path, test harness, proxied test harness), and
+* - the choice of `PgClient` construction, which is a real decision rather
+*   than a detail — see {@link pgClientFromUrl} and {@link pgClientFromPool}.
+*
+* Deployment topology stays with the consuming application: resolving a
+* connection string from a platform binding, degrading a failed binding to a
+* chainable proxy client, and any proxy wrapper around the concrete client
+* are all things only the application knows about.
+*
+* @module index
+*/
+/**
+* Builds one application's {@link PgDatabase} from its relations graph and a
+* service key.
+*
+* Call it once, at module scope, and export what it returns; the keys are
+* derived from `key`, so calling it twice with the same key produces services
+* that share a runtime slot.
+*
+* @example
+* ```ts
+* import { makePgDatabase } from "@thomasfosterau/effect-drizzle-ext-pg";
+*
+* const relations = {}; // the application's drizzle relations graph
+* const database = makePgDatabase({ relations, key: "Database" });
+* export const { Database, CurrentTransaction, transact, readHandle } = database;
+* export type Database = typeof database.Database.Identifier; // "Database"
+*
+* console.log(Database.key); // "Database"
+* ```
+*/
+const makePgDatabase = (options) => {
+	const services = makeDatabaseServices()({ key: options.key });
+	const make = PgDrizzle.make({ relations: options.relations }).pipe(Effect.provide(PgDrizzle.DefaultServices));
+	return {
+		...services,
+		make,
+		layer: Layer.effect(services.Database, make)
+	};
+};
+/**
+* A `PgClient` layer over a connection URL that **pings the database
+* (`SELECT 1`) at layer BUILD**, failing the build with a `SqlError` if the
+* ping does not answer within `connectTimeout`.
+*
+* That is the right trade for a long-lived process — a misconfigured URL
+* fails once, loudly, at startup rather than on the first query — and the
+* wrong one for a runtime that is built per request, where it opens a
+* connection even for requests that never touch the database. Use
+* {@link pgClientFromPool} there.
+*
+* `@effect/sql-pg` 4.0.0-rc.115 replaced the `pg` driver with its own wire
+* protocol, and its `PgClient.layer` no longer pings on its own: the pool
+* opens connections on first use. The ping is therefore this function's, run
+* once over the freshly built client.
+*
+* The output includes `SqlClient` as well as `PgClient` because that is what
+* `PgClient.layerFrom` provides; a consumer that only needs `PgClient` can
+* ignore the extra service.
+*/
+const pgClientFromUrl = (config) => PgClient.layerFrom(Effect.tap(PgClient.make(config), (client) => client`SELECT 1`));
+/**
+* A `PgClient` layer over a connection URL that **does not connect at layer
+* build** — the lazy counterpart to {@link pgClientFromUrl}.
+*
+* The pool is `@effect/sql-pg`'s own: it opens connections on first use (up
+* to `maxConnections`) and is shut down, every session released, when the
+* layer's scope closes. A runtime built per request therefore disposes of its
+* pool with that request, and a connection failure surfaces on the first
+* query as a `SqlError` instead of at build. Platforms that pin I/O to the
+* event that created it require exactly this — a pool must never outlive
+* that event (website #455).
+*
+* Until `@effect/sql-pg` 4.0.0-rc.115 this wrapped a bare `pg.Pool` via
+* `PgClient.fromPool`, because `PgClient.layer` pinged at build; rc.115
+* dropped both the `pg` driver and `fromPool`, and its pool is lazy by
+* construction. The name is kept for the contract, not the mechanism.
+*/
+const pgClientFromPool = (options) => PgClient.layer({
+	url: options.connectionString,
+	maxConnections: options.maxConnections,
+	connectTimeout: options.connectTimeout,
+	types: options.types,
+	prepare: options.prepare
+});
+export { makePgDatabase, pgClientFromPool, pgClientFromUrl };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiIA,MAAa,kBAA4E,YAGvD;CAChC,MAAM,WAAW,qBAA4E,CAAC,CAAC,EAC7F,KAAK,QAAQ,IACf,CAAC;CAED,MAAM,OAIF,UAAU,KAAgB,EAAE,WAAW,QAAQ,UAAU,CAAC,CAAC,CAAC,KAC9D,OAAO,QAAQ,UAAU,eAAe,CAC1C;CAEA,OAAO;EAAE,GAAG;EAAU;EAAM,OAAO,MAAM,OAAO,SAAS,UAAU,IAAI;CAAE;AAC3E;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,mBAAmB,WAiB9B,SAAS,UAAU,OAAO,IAAI,SAAS,KAAK,MAAM,IAAI,WAAW,MAAM,UAAU,CAAC;;;;;;;;;;;;;;;;;;AAoBpF,MAAa,oBAAoB,YAiB/B,SAAS,MAAM;CACb,KAAK,QAAQ;CACb,gBAAgB,QAAQ;CACxB,gBAAgB,QAAQ;CACxB,OAAO,QAAQ;CACf,SAAS,QAAQ;AACnB,CAAC"}

package/dist/migrations-Dp67FrXh.d.ts

@@ -0,0 +1,68 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { SqlClient } from "effect/sql/SqlClient";
+import { PlatformError } from "effect/PlatformError";
+/** drizzle-kit's statement separator inside a `migration.sql`. */
+declare const STATEMENT_BREAKPOINT = "--> statement-breakpoint";
+/** One migration as the runner applies it: its directory name and its statements, in order. */
+interface Migration {
+  readonly name: string;
+  readonly statements: ReadonlyArray<string>;
+}
+declare const MigrationError_base: Schema.Class<MigrationError, Schema.TaggedStruct<"MigrationError", {
+  readonly migration: Schema.String;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A migration failed to apply. `migration` names the directory — a bare
+ * driver error says only which statement broke, not which file it came from
+ * — and `cause` is the driver's `SqlError`. The migration's transaction has
+ * been rolled back; the ones before it stay applied.
+ */
+declare class MigrationError extends MigrationError_base {
+  get message(): string;
+}
+/**
+ * Split one `migration.sql` into its statements on
+ * {@link STATEMENT_BREAKPOINT}, dropping the empty chunks a trailing marker
+ * or blank file leaves behind.
+ */
+declare const splitStatements: (sql: string) => ReadonlyArray<string>;
+/**
+ * Every migration under `dir`, in apply order (directory-name order). Only
+ * directories count; one with no `migration.sql` is skipped.
+ */
+declare const readMigrations: (dir: string) => Effect.Effect<ReadonlyArray<Migration>, PlatformError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Apply `migrations` in order on the ambient `SqlClient`, each inside its own
+ * transaction, returning how many ran. Stops at the first failure with a
+ * {@link MigrationError} naming the migration.
+ */
+declare const applyMigrationList: (migrations: ReadonlyArray<Migration>) => Effect.Effect<number, MigrationError, SqlClient>;
+/**
+ * Apply every migration under `dir` to the (brand-new) database behind the
+ * ambient `SqlClient` — {@link readMigrations} then {@link applyMigrationList}
+ * — returning how many ran.
+ *
+ * @example
+ * ```ts
+ * import * as NodeServices from "@effect/platform-node/NodeServices";
+ * import * as PgClient from "@effect/sql-pg/PgClient";
+ * import { applyMigrations } from "@thomasfosterau/effect-drizzle-ext-pg/migrations";
+ * import * as Effect from "effect/Effect";
+ * import * as Redacted from "effect/Redacted";
+ *
+ * const url = Redacted.make("postgres://postgres@localhost:5432/app_test");
+ *
+ * // Building the Effect connects to nothing; running it applies the chain.
+ * export const applied = applyMigrations("packages/database/migrations").pipe(
+ *   Effect.provide(PgClient.layer({ url, maxConnections: 1 })),
+ *   Effect.provide(NodeServices.layer),
+ * );
+ * ```
+ */
+declare const applyMigrations: (dir: string) => Effect.Effect<number, MigrationError | PlatformError, SqlClient | FileSystem.FileSystem | Path.Path>;
+export { applyMigrations as a, applyMigrationList as i, MigrationError as n, readMigrations as o, STATEMENT_BREAKPOINT as r, splitStatements as s, Migration as t };
+//# sourceMappingURL=migrations-Dp67FrXh.d.ts.map

package/dist/migrations-Dp67FrXh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations-Dp67FrXh.d.ts","names":[],"sources":["../src/migrations.ts"],"mappings":";;;;;;;cAqDa;;UAGI;WACN;WACA,YAAY;;;;;;;;;;;;cASV,uBAAuB;MAIrB;;;;;;;cAUF,kBAAe,gBAAkB;;;;;cAUjC,iBAAc,gBAExB,OAAO,OAAO,cAAc,YAAY,eAAe,WAAW,aAAa,KAAK;;;;;;cA0B1E,qBAAkB,YACjB,cAAc,eACzB,OAAO,eAAe,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;cA6C5B,kBAAe,gBAEzB,OAAO,eAER,iBAAiB,eACjB,YAAY,WAAW,aAAa,KAAK"}

package/dist/migrations.d.ts

@@ -0,0 +1,2 @@
+import { a as applyMigrations, i as applyMigrationList, n as MigrationError, o as readMigrations, r as STATEMENT_BREAKPOINT, s as splitStatements, t as Migration } from "./migrations-Dp67FrXh.js";
+export { Migration, MigrationError, STATEMENT_BREAKPOINT, applyMigrationList, applyMigrations, readMigrations, splitStatements };

package/dist/migrations.js

@@ -0,0 +1,136 @@
+import * as Effect from "effect/Effect";
+import * as Arr from "effect/Array";
+import * as FileSystem from "effect/FileSystem";
+import * as Order from "effect/Order";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { SqlClient } from "effect/sql/SqlClient";
+import * as Str from "effect/String";
+// src/migrations.ts
+/**
+* @copyright Thomas Foster
+*
+* **The ordered migration runner for a brand-new database.** Reads a
+* drizzle-kit `migrations/` directory and applies every migration in it, in
+* directory-name order, one transaction per migration, with no ledger.
+*
+* It is what an integration suite's provisioning runs against the database it
+* has just created ({@link ../testing.ts}'s `provisionTestDatabase` calls it by
+* default), and it mirrors the apply order and per-migration transaction
+* shape of alchemy's deploy-time `migrationsDir` runner, minus its ledger:
+* the database is **always** brand new, so every migration applies
+* unconditionally and no bookkeeping table is needed. A database that already
+* holds some of the migrations is not this runner's input — use the
+* deployment's own migrator there.
+*
+* ## The layout it reads
+*
+* drizzle-kit writes one directory per migration, `<digits>_<slug>/`,
+* holding `migration.sql` (and `snapshot.json`, which this runner ignores).
+* The all-digit, fixed-width prefixes make name order chronological. A
+* directory with no `migration.sql` is skipped rather than failing the run —
+* drizzle-kit writes the snapshot before the SQL, and a sanctioned
+* hand-written bootstrap directory may carry only SQL.
+*
+* ## Statements, not files
+*
+* `@effect/sql-pg` speaks the extended query protocol, which rejects more
+* than one statement per query ("cannot insert multiple commands into a
+* prepared statement"). drizzle-kit separates the statements of a migration
+* with a `--> statement-breakpoint` line, and drizzle's own migrator splits
+* on exactly that marker, so this runner does the same: each migration's
+* statements run in order inside that migration's one transaction. A
+* hand-written migration must keep the marker between statements.
+*
+* Idiomatic Effect: the directory is read through the `FileSystem` / `Path`
+* services (a Node consumer provides `@effect/platform-node`'s
+* `NodeServices.layer`), and the statements run on the ambient `SqlClient`.
+*
+* @module migrations
+*/
+/** drizzle-kit's statement separator inside a `migration.sql`. */
+const STATEMENT_BREAKPOINT = "--> statement-breakpoint";
+/**
+* A migration failed to apply. `migration` names the directory — a bare
+* driver error says only which statement broke, not which file it came from
+* — and `cause` is the driver's `SqlError`. The migration's transaction has
+* been rolled back; the ones before it stay applied.
+*/
+var MigrationError = class extends Schema.TaggedError()("MigrationError", {
+	migration: Schema.String,
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `migration '${this.migration}' failed`;
+	}
+};
+/**
+* Split one `migration.sql` into its statements on
+* {@link STATEMENT_BREAKPOINT}, dropping the empty chunks a trailing marker
+* or blank file leaves behind.
+*/
+const splitStatements = (sql) => sql.split(STATEMENT_BREAKPOINT).map((statement) => statement.trim()).filter(Str.isNonEmpty);
+/**
+* Every migration under `dir`, in apply order (directory-name order). Only
+* directories count; one with no `migration.sql` is skipped.
+*/
+const readMigrations = (dir) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const names = Arr.sort(yield* fs.readDirectory(dir), Order.String);
+	return (yield* Effect.forEach(names, (name) => Effect.gen(function* () {
+		if ((yield* fs.stat(path.join(dir, name))).type !== "Directory") return [];
+		const file = path.join(dir, name, "migration.sql");
+		if (!(yield* fs.exists(file))) return [];
+		const sql = yield* fs.readFileString(file);
+		return [{
+			name,
+			statements: splitStatements(sql)
+		}];
+	}), { concurrency: 1 })).flat();
+});
+/**
+* Apply `migrations` in order on the ambient `SqlClient`, each inside its own
+* transaction, returning how many ran. Stops at the first failure with a
+* {@link MigrationError} naming the migration.
+*/
+const applyMigrationList = (migrations) => Effect.gen(function* () {
+	const sql = yield* SqlClient;
+	yield* Effect.forEach(migrations, (migration) => sql.withTransaction(Effect.forEach(migration.statements, (statement) => sql.unsafe(statement), {
+		concurrency: 1,
+		discard: true
+	})).pipe(Effect.mapError((cause) => new MigrationError({
+		migration: migration.name,
+		cause
+	}))), {
+		concurrency: 1,
+		discard: true
+	});
+	return migrations.length;
+});
+/**
+* Apply every migration under `dir` to the (brand-new) database behind the
+* ambient `SqlClient` — {@link readMigrations} then {@link applyMigrationList}
+* — returning how many ran.
+*
+* @example
+* ```ts
+* import * as NodeServices from "@effect/platform-node/NodeServices";
+* import * as PgClient from "@effect/sql-pg/PgClient";
+* import { applyMigrations } from "@thomasfosterau/effect-drizzle-ext-pg/migrations";
+* import * as Effect from "effect/Effect";
+* import * as Redacted from "effect/Redacted";
+*
+* const url = Redacted.make("postgres://postgres@localhost:5432/app_test");
+*
+* // Building the Effect connects to nothing; running it applies the chain.
+* export const applied = applyMigrations("packages/database/migrations").pipe(
+*   Effect.provide(PgClient.layer({ url, maxConnections: 1 })),
+*   Effect.provide(NodeServices.layer),
+* );
+* ```
+*/
+const applyMigrations = (dir) => Effect.flatMap(readMigrations(dir), applyMigrationList);
+export { MigrationError, STATEMENT_BREAKPOINT, applyMigrationList, applyMigrations, readMigrations, splitStatements };
+
+//# sourceMappingURL=migrations.js.map

package/dist/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","names":[],"sources":["../src/migrations.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,MAAa,uBAAuB;;;;;;;AAcpC,IAAa,iBAAb,cAAoC,OAAO,YAA4B,CAAC,CAAC,kBAAkB;CACzF,WAAW,OAAO;CAClB,OAAO,OAAO,OAAO;AACvB,CAAC,CAAC,CAAC;CACD,IAAa,UAAkB;EAC7B,OAAO,cAAc,KAAK,UAAU;CACtC;AACF;;;;;;AAOA,MAAa,mBAAmB,QAC9B,IACG,MAAM,oBAAoB,CAAC,CAC3B,KAAK,cAAc,UAAU,KAAK,CAAC,CAAC,CACpC,OAAO,IAAI,UAAU;;;;;AAM1B,MAAa,kBACX,QAEA,OAAO,IAAI,aAAa;CACtB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,OAAO,OAAO,KAAK;CACzB,MAAM,QAAQ,IAAI,KAAK,OAAO,GAAG,cAAc,GAAG,GAAG,MAAM,MAAM;CAcjE,QAAO,OAba,OAAO,QACzB,QACC,SACC,OAAO,IAAI,aAAa;EAEtB,KAAI,OADgB,GAAG,KAAK,KAAK,KAAK,KAAK,IAAI,CAAC,EAAA,CACvC,SAAS,aAAa,OAAO,CAAC;EACvC,MAAM,OAAO,KAAK,KAAK,KAAK,MAAM,eAAe;EACjD,IAAI,EAAE,OAAO,GAAG,OAAO,IAAI,IAAI,OAAO,CAAC;EACvC,MAAM,MAAM,OAAO,GAAG,eAAe,IAAI;EACzC,OAAO,CAAC;GAAE;GAAM,YAAY,gBAAgB,GAAG;EAAE,CAAC;CACpD,CAAC,GACH,EAAE,aAAa,EAAE,CACnB,EAAA,CACY,KAAK;AACnB,CAAC;;;;;;AAOH,MAAa,sBACX,eAEA,OAAO,IAAI,aAAa;CACtB,MAAM,MAAM,OAAO;CACnB,OAAO,OAAO,QACZ,aACC,cACC,IACG,gBAEC,OAAO,QAAQ,UAAU,aAAa,cAAc,IAAI,OAAO,SAAS,GAAG;EACzE,aAAa;EACb,SAAS;CACX,CAAC,CACH,CAAC,CACA,KACC,OAAO,UAAU,UAAU,IAAI,eAAe;EAAE,WAAW,UAAU;EAAM;CAAM,CAAC,CAAC,CACrF,GAEJ;EAAE,aAAa;EAAG,SAAS;CAAK,CAClC;CACA,OAAO,WAAW;AACpB,CAAC;;;;;;;;;;;;;;;;;;;;;;;AAwBH,MAAa,mBACX,QAKG,OAAO,QAAQ,eAAe,GAAG,GAAG,kBAAkB"}

package/dist/testing.d.ts

@@ -0,0 +1,270 @@
+import { PgDatabase } from "./index.js";
+import { n as MigrationError } from "./migrations-Dp67FrXh.js";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Duration from "effect/Duration";
+import * as Exit from "effect/Exit";
+import { SqlError } from "effect/sql/SqlError";
+import * as Redacted from "effect/Redacted";
+import { AnyRelations } from "drizzle-orm/relations";
+import { PlatformError } from "effect/PlatformError";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Scope from "effect/Scope";
+/**
+ * The environment the resolution reads — the shape of `process.env`, taken
+ * as a parameter so the order is testable against a fake.
+ */
+interface ResolutionEnvironment {
+  readonly [name: string]: string | undefined;
+}
+/** The connection URL for `database` on the configured local server. */
+export declare const connectionUrl: (env: ResolutionEnvironment, database: string) => Redacted.Redacted<string>;
+declare const InvalidDatabasePrefix_base: Schema.Class<InvalidDatabasePrefix, Schema.TaggedStruct<"InvalidDatabasePrefix", {
+  readonly prefix: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The prefix is not a lower-case SQL identifier. */
+export declare class InvalidDatabasePrefix extends InvalidDatabasePrefix_base {
+  get message(): string;
+}
+/**
+ * The deterministic per-checkout database name
+ * `<prefix>_test_<sha256(migrationsDir)[:8]>`: concurrent runs from different
+ * worktrees never collide, and a stale database self-heals on the next run.
+ */
+export declare const testDatabaseName: (options: {
+  readonly prefix: string;
+  readonly migrationsDir: string;
+}) => Effect.Effect<string, InvalidDatabasePrefix>;
+declare const ServerUnreachable_base: Schema.Class<ServerUnreachable, Schema.TaggedStruct<"ServerUnreachable", {
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** One connection attempt against a server's admin database failed. */
+export declare class ServerUnreachable extends ServerUnreachable_base {}
+/**
+ * One connection attempt against a server's admin (`postgres`) database.
+ * Injected into {@link resolveDatabaseSource} so the resolution order can be
+ * exercised without a server; {@link probeServer} is the real one.
+ */
+type ServerProbe = (adminUrl: Redacted.Redacted<string>) => Effect.Effect<void, ServerUnreachable>;
+/** A `SELECT 1` over one short-lived connection. */
+export declare const probeServer: ServerProbe;
+declare const DatabaseUnreachable_base: Schema.Class<DatabaseUnreachable, Schema.TaggedStruct<"DatabaseUnreachable", {
+  readonly server: Schema.String;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** An explicit but unreachable `PG*` target: this run will not fall back to a container. */
+export declare class DatabaseUnreachable extends DatabaseUnreachable_base {
+  get message(): string;
+}
+/** Where a run's database comes from — the resolved decision, before anything is provisioned. */
+type DatabaseSource =
+/** An explicit, already-migrated database: used as-is, never provisioned or torn down. */
+{
+  readonly _tag: "Explicit";
+  readonly url: Redacted.Redacted<string>;
+} |
+/** A reachable local server: this checkout's database is dropped, recreated and migrated on it. */
+{
+  readonly _tag: "LocalServer";
+  readonly adminUrl: Redacted.Redacted<string>;
+  readonly database: string;
+  readonly url: Redacted.Redacted<string>;
+} |
+/** No explicit config and nothing listening: a fresh container is started via Testcontainers. */
+{
+  readonly _tag: "Container";
+  readonly image: string;
+};
+/** The inputs {@link resolveDatabaseSource} reads. */
+interface DatabaseSourceOptions {
+  /** The environment — `process.env` in a global setup. */
+  readonly env: ResolutionEnvironment;
+  /** The migrations directory, as an absolute path: the per-checkout key of the database name. */
+  readonly migrationsDir: string;
+  /** The database-name prefix, a lower-case SQL identifier (the application's name, say). */
+  readonly dbNamePrefix: string;
+  /** The container image the Testcontainers fallback starts (`pgvector/pgvector:pg17`, `postgres:17`, …). */
+  readonly image: string;
+  /** The server probe: {@link probeServer} when absent or `undefined`. A test substitutes its own. */
+  readonly probe?: ServerProbe | undefined;
+}
+/**
+ * Resolve where a run's database comes from, in the order the module doc
+ * describes: an explicit URL, then a reachable local server (an explicit but
+ * unreachable `PG*` target is a {@link DatabaseUnreachable}), then the
+ * Testcontainers fallback. Pure apart from the one probe, which only runs
+ * when no explicit URL is set.
+ */
+export declare const resolveDatabaseSource: (options: DatabaseSourceOptions) => Effect.Effect<DatabaseSource, DatabaseUnreachable | InvalidDatabasePrefix>;
+declare const ContainerStartFailed_base: Schema.Class<ContainerStartFailed, Schema.TaggedStruct<"ContainerStartFailed", {
+  readonly image: Schema.String;
+  readonly server: Schema.String;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** Starting the Testcontainers fallback failed — most often, no Docker daemon. */
+export declare class ContainerStartFailed extends ContainerStartFailed_base {
+  get message(): string;
+}
+/** A provisioned database: its URL, and the source it was resolved from. */
+interface ProvisionedDatabase {
+  readonly url: Redacted.Redacted<string>;
+  readonly source: DatabaseSource;
+}
+/**
+ * How a provisioned database is migrated: handed the new database's URL,
+ * returns how many migrations ran. The default applies the migrations under
+ * {@link ProvisionOptions.migrationsDir} with `./migrations`'
+ * `applyMigrations` over a one-connection `PgClient`.
+ */
+type MigrationRunner<E, R> = (url: Redacted.Redacted<string>) => Effect.Effect<number, E, R>;
+/** The inputs {@link provisionTestDatabase} takes. */
+interface ProvisionOptions<E = never, R = never> extends DatabaseSourceOptions {
+  /**
+   * Replaces the default runner (for a harness whose migrations are not a
+   * drizzle-kit directory); absent or `undefined` keeps the default.
+   */
+  readonly applyMigrations?: MigrationRunner<E, R> | undefined;
+}
+/**
+ * Provision a run's fresh, fully-migrated database — resolve the source,
+ * then drop / create / migrate on a reachable server, or start and migrate a
+ * container — and return its URL. An explicit source is returned as-is.
+ *
+ * Scoped: a started container stops when the scope closes. From a vitest
+ * global setup, hold a `Scope` across the run and close it in the returned
+ * teardown:
+ *
+ * @example
+ * ```ts
+ * // vitest global setup
+ * import * as NodeServices from "@effect/platform-node/NodeServices";
+ * import { provisionTestDatabase } from "@thomasfosterau/effect-drizzle-ext-pg/testing";
+ * import * as Effect from "effect/Effect";
+ * import * as Exit from "effect/Exit";
+ * import * as Redacted from "effect/Redacted";
+ * import * as Scope from "effect/Scope";
+ *
+ * const MIGRATIONS_DIR = "packages/database/migrations";
+ *
+ * export default async function setup() {
+ *   const scope = Effect.runSync(Scope.make());
+ *   const database = await Effect.runPromise(
+ *     provisionTestDatabase({
+ *       env: process.env,
+ *       migrationsDir: MIGRATIONS_DIR,
+ *       dbNamePrefix: "website",
+ *       image: "pgvector/pgvector:pg17",
+ *     }).pipe(Scope.provide(scope), Effect.provide(NodeServices.layer)),
+ *   );
+ *   process.env.DATABASE_URL_TEST = Redacted.value(database.url);
+ *   return () => Effect.runPromise(Scope.close(scope, Exit.void));
+ * }
+ * ```
+ */
+export declare const provisionTestDatabase: <E = MigrationError | PlatformError | SqlError, R = FileSystem.FileSystem | Path.Path>(options: ProvisionOptions<E, R>) => Effect.Effect<ProvisionedDatabase, E | DatabaseUnreachable | InvalidDatabasePrefix | ContainerStartFailed | SqlError | MigrationError | PlatformError, R | FileSystem.FileSystem | Path.Path | Scope.Scope>;
+/**
+ * Whether `error` is a `SqlError` that failed at the connect/acquire seam and
+ * so is safe to retry (when the caller has also confirmed no test body ran).
+ *
+ * Returns `true` for:
+ *  - any reason the driver already flags `isRetryable` (`ConnectionError` from
+ *    an `08xxx` SQLSTATE, `DeadlockError`, `SerializationError`, the timeout
+ *    reasons), and
+ *  - a reason whose `operation` is a connect/acquire seam label, which catches
+ *    the misclassified `UnknownError` the website #1055 flake surfaces as
+ *    (pool "timeout exceeded when trying to connect" / `ECONNRESET`, neither
+ *    of which carries an `08` SQLSTATE).
+ *
+ * Returns `false` for a `UniqueViolation` / `ConstraintError` /
+ * `SqlSyntaxError` raised by a test's own query (`operation === "execute"`),
+ * so genuine test failures are never retried.
+ */
+export declare const isRetryableConnectFailure: (error: unknown) => boolean;
+/**
+ * The always-rollback test transaction runner for one application's
+ * {@link PgDatabase}, built by {@link makeTestTransaction}.
+ *
+ * Only the service KEY matters to these signatures — the handle types are
+ * closed over by the factory — so the interface is parameterised by the key
+ * string alone.
+ */
+export interface TestTransaction<Key extends string> {
+  /**
+   * Runs `effect` inside a transaction that is always rolled back once the
+   * test completes, against a caller-supplied runtime.
+   *
+   * `R` is the runtime's own context. It **must include the `Database`
+   * key**, which is what lets the program below yield the client; that
+   * relationship is not expressible as a generic constraint once `R` can be a
+   * union that also carries unrelated services (a harness's platform binding
+   * stubs, a spec's viewer services), so it is documented here rather than
+   * enforced by the type checker — the same trade-off the ported wrapper
+   * makes.
+   *
+   * `${Key}/CurrentTransaction` is in the ACCEPTED requirement, not in the
+   * runtime's catalogue: nothing provides it as a layer. The runner wraps the
+   * effect in `transact`, so the spec stands in for the handler that opens
+   * the boundary in production, and the requirement is discharged there.
+   */
+  readonly runInTestTransaction: <R, A, E>(runtime: ManagedRuntime.ManagedRuntime<R, SqlError>, effect: Effect.Effect<A, E, R | `${Key}/CurrentTransaction`>) => Promise<A>;
+  /**
+   * {@link runInTestTransaction} with the runtime bound once — the form a
+   * suite exports as its own `withTestTransaction(effect)` helper.
+   */
+  readonly withTestTransaction: <R>(runtime: ManagedRuntime.ManagedRuntime<R, SqlError>) => <A, E>(effect: Effect.Effect<A, E, R | `${Key}/CurrentTransaction`>) => Promise<A>;
+  /**
+   * Run `effect` inside a **SAVEPOINT** and hand back its `Exit`, leaving the
+   * enclosing transaction usable whether it succeeded or failed.
+   *
+   * This is what a spec asserting "the constraint rejects this write" needs.
+   * A statement that raises in PostgreSQL aborts the whole transaction, so a
+   * bare `Effect.exit(tx.insert(…))` captures the expected failure and then
+   * poisons every later statement in the test with `current transaction is
+   * aborted, commands ignored until end of transaction block` — which
+   * surfaces as the *next* query failing, several assertions away from the
+   * cause. Nesting the attempt (`tx.transaction`, a SAVEPOINT on the same
+   * pinned connection) confines the abort to the savepoint: the driver rolls
+   * back to it and the outer transaction, with every fixture the test has
+   * already written, carries on.
+   *
+   * `effect` keeps using the ambient `CurrentTransaction` handle — the
+   * savepoint is a property of the CONNECTION, which `maxConnections: 1`
+   * pins, so nothing has to be re-threaded through a nested handle.
+   *
+   * The `Exit` is returned rather than asserted on, so the caller keeps the
+   * choice: `expect(exit._tag).toBe("Failure")` for a rejection, or a look at
+   * the cause when the message matters.
+   */
+  readonly attemptInSavepoint: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<Exit.Exit<A, E | SqlError>, never, R | `${Key}/CurrentTransaction`>;
+}
+/**
+ * Builds the always-rollback test transaction runner for one application's
+ * database services.
+ *
+ * The services carry the key strings and the `transact` boundary, so the
+ * runner needs nothing else: a suite calls this once next to its
+ * {@link makePgDatabase} call and exports the three helpers.
+ */
+export declare const makeTestTransaction: <Relations extends AnyRelations, Key extends string>(database: PgDatabase<Relations, Key>) => TestTransaction<Key>;
+/**
+ * The `Database` layer an integration suite runs against: the application's
+ * own {@link PgDatabase.layer} over a `PgClient` built from `url`, with the
+ * pool pinned to one connection (see {@link TEST_POOL_MAX_CONNECTIONS}).
+ *
+ * Built once per process and reused by every spec in it. `url` is the
+ * caller's: this library does not read `DATABASE_URL_TEST` or decide how a
+ * test database is provisioned.
+ *
+ * Unlike production, this uses the pinging {@link pgClientFromUrl} on
+ * purpose — a suite that cannot reach its database should fail at layer build
+ * with one legible `SqlError`, not once per spec on the first query.
+ */
+export declare const testDatabaseLayer: <Relations extends AnyRelations, Key extends string>(database: PgDatabase<Relations, Key>, options: {
+  readonly url: Redacted.Redacted<string>;
+  readonly connectTimeout?: Duration.Input | undefined;
+}) => Layer.Layer<Key, SqlError>;
+export type { DatabaseSource, DatabaseSourceOptions, MigrationRunner, ProvisionOptions, ProvisionedDatabase, ResolutionEnvironment, ServerProbe };
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","names":[],"sources":["../src/provisioning.ts","../src/testing.ts"],"mappings":";;;;;;;;;;;;;;;;;;;UA2DiB;YAEL;;;qBAsBC,gBAAa,KACnB,uBAAqB,qBAEzB,SAAS;;;;;qBAgBC,8BAA8B;MAI5B;;;;;;;qBAUF,mBAAgB;WAClB;WACA;MACP,OAAO,eAAe;;;;;qBAgBb,0BAA0B;;;;;;KAU3B,eACV,UAAU,SAAS,qBAChB,OAAO,aAAa;;qBAGZ,aAAa;;;;;;qBAYb,4BAA4B;MAI1B;;;KAWH;;;WAEG;WAA2B,KAAK,SAAS;;;;WAGzC;WACA,UAAU,SAAS;WACnB;WACA,KAAK,SAAS;;;;WAGd;WAA4B;;;UAG1B;;WAEN,KAAK;;WAEL;;WAEA;;WAEA;;WAGA,QAAQ;;;;;;;;;qBAUN,wBAAqB,SACvB,0BACR,OAAO,OAAO,gBAAgB,sBAAsB;;;;;;;qBAkC1C,6BAA6B;MAI3B;;;UAaE;WACN,KAAK,SAAS;WACd,QAAQ;;;;;;;;KASP,gBAAgB,GAAG,MAAM,KAAK,SAAS,qBAAqB,OAAO,eAAe,GAAG;;UAGhF,iBAAiB,WAAW,mBAAmB;;;;;WAMrD,kBAAkB,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAuFnC,wBACX,IAAI,iBAAiB,gBAAgB,UACrC,IAAI,WAAW,aAAa,KAAK,MAAI,SAE5B,iBAAiB,GAAG,OAC5B,OAAO,OACR,qBACE,IACA,sBACA,wBACA,uBACA,WACA,iBACA,eACF,IAAI,WAAW,aAAa,KAAK,OAAO,MAAM;;;;;;;;;;;;;;;;;;qBC7PnC,4BAAyB;;;;;;;;;iBAwGrB,gBAAgB;;;;;;;;;;;;;;;;;;WAkBtB,uBAAuB,GAAG,GAAG,GACpC,SAAS,eAAe,eAAe,GAAG,WAC1C,QAAQ,OAAO,OAAO,GAAG,GAAG,OAAO,8BAChC,QAAQ;;;;;WAMJ,sBAAsB,GAC7B,SAAS,eAAe,eAAe,GAAG,eACtC,GAAG,GAAG,QAAQ,OAAO,OAAO,GAAG,GAAG,OAAO,8BAA8B,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;WAyB5E,qBAAqB,GAAG,GAAG,GAClC,QAAQ,OAAO,OAAO,GAAG,GAAG,OACzB,OAAO,OAAO,KAAK,KAAK,GAAG,IAAI,kBAAkB,OAAO;;;;;;;;;;qBAWlD,sBAAuB,kBAAkB,cAAc,oBAAkB,UAC1E,WAAW,WAAW,SAC/B,gBAAgB;;;;;;;;;;;;;;qBA4HN,oBAAqB,kBAAkB,cAAc,oBAAkB,UACxE,WAAW,WAAW,MAAI;WAEzB,KAAK,SAAS;WACd,iBAAiB,SAAS;MAEpC,MAAM,MAAM,KAAK"}