okmodel 0.4.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 okmodel is a catalog-first TypeScript ORM, PostgreSQL first. Other SQL databases are the direction. CI runs PostgreSQL 15 to 18. The schema is the single source. Migrations and queries come from it.
 
-Version 0.4.0. Apache-2.0.
+Version 0.5.0. Apache-2.0.
 
 ## Contents
 
@@ -58,6 +58,8 @@ Version 0.4.0. Apache-2.0.
   - [Reference data](#reference-data)
   - [Backfill](#backfill)
   - [Testing](#testing)
+  - [Topology](#topology)
+  - [Reference app](#reference-app)
   - [Startup](#startup)
   - [Protected targets](#protected-targets)
 - [Commands](#commands)
@@ -990,6 +992,83 @@ export default async function seed(t: {
 bunx okm seed seed.ts
 ```
 
+### Topology
+
+`connect({ primary, replicas }, options)` opens one pool per endpoint. An automatic read chooses a replica that has replayed at least as far as this client's last committed write. `routing.consistency` is `"session"` by default. `"eventual"` does not keep that watermark. `routing.maxLag` is a duration (`"5s"`, `"500ms"`, `"2m"`) or a size (`"16MB"`, `"512KB"`, `"1GB"`, `"4096B"`). A bare number is rejected. `find({ route: "primary" })` reads the primary. `find({ route: "replica" })` requires a replica that satisfies the same watermark and lag, and it does not fall back to the primary. `db.using("primary")` or `db.using("replica")` returns a client that forces that route. That client has no `close` and no `using`. `onRoute` receives `{ op, endpoint, reason }`. A throw from it is ignored. A string or an existing pool is one endpoint and serves either `route` from it, and it has no `using`.
+
+The watermark is one value for the whole `connect()`. The root, `for()`, `unscoped()`, `using()`, and `reserve()` share it. A write through any of them moves it for the others. A watermark per `for()` client is not in this version.
+
+When replicas are configured and consistency is `"session"`, a committed write reads `pg_current_wal_insert_lsn()` before its promise resolves. That is one extra round trip: on the primary pool after an autocommit `execute` or `batch`, and on the reserved connection after a successful `COMMIT`. A rollback does not read it. `"eventual"`, and a connect with no replicas, do not read it either.
+
+`routing.select` picks among the replicas that passed health, the watermark, and `maxLag`. The default is `"weighted"`. `weighted` is smooth weighted round-robin. Equal weights take turns. A weight of `0` is rejected. `roundRobin` ignores weights and rotates through the eligible replicas. `leastConnections` uses the replica with the fewest statements already in flight on this client. A tie follows configuration order. `latencyAware` uses the replica with the lowest moving average of round-trip time. A function receives each candidate as `{ name, weight, inflight, latencyMs, lag }` and `{ op: "read" }`. `lag` is the number of bytes the replica is behind the primary, or `null` when that distance is unknown. The function returns one of those objects or its `name`. It runs only when an automatic read has two or more candidates.
+
+A write, a batch, a transaction, or a locking read on a replica route is OKM1840. `route: "replica"` or `using("replica")` with no eligible replica is OKM1843, including a topology with no replicas. An automatic read with `routing.fallback: "error"` and no eligible replica is OKM1844. A migrate target that carries `primary`, `replicas`, `weight`, or `pool` is OKM1845. Waiting for a connection past `timeouts.acquire` is OKM1846, and that wait stays on the endpoint's own pool. The rules are in [topology](https://github.com/omqkhafi/okmodel/blob/main/docs/topology.md).
+
+A replica whose pool is at its maximum, with no idle connection and callers waiting, is skipped. If every replica that can serve the read is in that state, the read uses the primary and `onRoute` reports `fallback:saturated`. When healthy replicas exist and none has caught up, or none is inside `maxLag`, the reason is `fallback:behind`. `route: "replica"` still uses a saturated replica, and it still requires the watermark and `maxLag`.
+
+`replicas.ts`:
+
+```ts
+import { connect } from "okmodel/pg/postgresjs";
+
+import schema from "./schema.ts";
+
+const url = process.env.DATABASE_URL;
+if (url === undefined || url.length === 0) throw new Error("DATABASE_URL is not set");
+const east = process.env.REPLICA_URL;
+if (east === undefined || east.length === 0) throw new Error("REPLICA_URL is not set");
+const west = process.env.REPLICA_URL_WEST ?? east;
+
+const endpoints = {
+  primary: url,
+  replicas: [{ url: east, weight: 2, name: "east" }, west],
+};
+
+const db = await connect(endpoints, {
+  schema,
+  routing: { probe: "1s", fallback: "primary", consistency: "session", select: "weighted" },
+  onRoute(event) {
+    // { op: "read", endpoint: "east", reason: "auto:east" }
+    void event;
+  },
+});
+
+await db.notes.find({ limit: 50 });
+await db.notes.find({ limit: 50, route: "primary" });
+await db.notes.find({ limit: 50, route: "replica" });
+const replica = db.using("replica");
+await replica.notes.find({ limit: 50 });
+await db.close();
+
+const eventual = await connect(endpoints, {
+  schema,
+  routing: { consistency: "eventual" },
+});
+await eventual.notes.find({ limit: 50 });
+await eventual.close();
+
+for (const select of ["roundRobin", "leastConnections", "latencyAware"] as const) {
+  const client = await connect(endpoints, { schema, routing: { select } });
+  await client.notes.find({ limit: 1 });
+  await client.close();
+}
+
+const custom = await connect(endpoints, {
+  schema,
+  routing: {
+    select(candidates) {
+      return candidates[0] ?? "east";
+    },
+  },
+});
+await custom.notes.find({ limit: 1 });
+await custom.close();
+```
+
+### Reference app
+
+The worked example is a project tracker: workspaces as tenants, archive, a function, two views, three generated migrations, and this topology. It is a private package in the repository, not on npm. CI runs it on the primary and two standbys. Board reads go to a replica. A read just after a write, with replay paused, comes back from the primary. The report uses `route: "replica"`. See the [example app](https://github.com/omqkhafi/okmodel/blob/main/docs/example-app.md) and the [reference app notes](https://github.com/omqkhafi/okmodel/blob/main/packages/reference-app/README.md).
+
 ### Startup
 
 `connect()` compares the app with `okm_history`. A database that is ahead by expand migrations still opens. Ahead by a contract migration, or behind the app, is OKM1520 and names the migration. `okm migrate status` prints the same states, plus `failed at step N (resume with okm migrate apply)`.
@@ -1064,7 +1143,7 @@ Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each rel
 - [x] [0.2](https://github.com/omqkhafi/okmodel/milestone/2) — Hidden and sensitive fields, validation, traits, tenancy, archive and restore, richer relations, presets, transactions, and operators for JSON, arrays, ranges, and search.
 - [x] [0.3](https://github.com/omqkhafi/okmodel/milestone/3) — Extensions, domains, functions, triggers, views, roles, and grants.
 - [x] [0.4](https://github.com/omqkhafi/okmodel/milestone/4) — Safer migration plans, backfill, drift checks, provisioning, reference data, and a testing package.
-- [ ] [0.5](https://github.com/omqkhafi/okmodel/milestone/5) — A primary with replicas, read routing, and a reference app.
+- [x] [0.5](https://github.com/omqkhafi/okmodel/milestone/5) — A primary with replicas, read routing, and a reference app.
 
 `okmodel/internal` has no stability promise. Names on that subpath can change or disappear in any release.
 
@@ -1076,11 +1155,11 @@ Measured on this release.
 
 |                                              | Minified |   Gzip | Cold import |
 | -------------------------------------------- | -------: | -----: | ----------: |
-| Runtime entry                                |    5,288 |  2,026 |    2.563 ms |
-| App startup (10 tables, one find)            |   89,461 | 29,720 |   13.379 ms |
-| App startup, every 0.2 feature in use (full) |  119,936 | 39,121 |   13.745 ms |
+| Runtime entry                                |    5,288 |  2,026 |    2.347 ms |
+| App startup (10 tables, one find)            |   89,751 | 29,801 |   15.061 ms |
+| App startup, every 0.2 feature in use (full) |  120,132 | 39,162 |   15.956 ms |
 
-The full app has column tenancy, `archivable()`, `timestamps()`, validation rules, `one`, `many` and `manyThrough` relations, presets, and calls `include`, `page`, `aggregate`, `tx` and `batch`. A feature costs bytes only in an app that uses it: the full app is 30,475 minified and 9,401 gzip bytes above the plain one. The runtime entry and the plain app are gated. The full app is printed, not gated.
+The full app has column tenancy, `archivable()`, `timestamps()`, validation rules, `one`, `many` and `manyThrough` relations, presets, and calls `include`, `page`, `aggregate`, `tx` and `batch`. A feature costs bytes only in an app that uses it: the full app is 30,381 minified and 9,361 gzip bytes above the plain one. The runtime entry and the plain app are gated. The full app is printed, not gated. The plain app's cold import on this sample is above the 15 ms local reference. That figure is printed and is not a gate.
 
 The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/blob/main/docs/size.md).
 
@@ -1092,5 +1171,6 @@ The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/b
 - [Backfill](https://github.com/omqkhafi/okmodel/blob/main/docs/backfill.md)
 - [Provisioning](https://github.com/omqkhafi/okmodel/blob/main/docs/provisioning.md)
 - [Testing](https://github.com/omqkhafi/okmodel/blob/main/docs/testing.md)
+- [Topology](https://github.com/omqkhafi/okmodel/blob/main/docs/topology.md)
 - [Known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md)
 - [Changelog](https://github.com/omqkhafi/okmodel/blob/main/changelog.md)

package/dist/contracts/catalog/document.d.ts

@@ -62,6 +62,26 @@ export declare function serializeCatalog(source: Catalog): string;
  * @returns Lowercase hex digest
  */
 export declare function catalogHash(source: Catalog): string;
+/**
+ * The catalog `connect()` compares with `okm_meta` (D208).
+ *
+ * Roles, grants, and default privileges come from the migration config, not
+ * the schema, so they are left out. A `schema()` catalog never has them, so
+ * `connect()` hashes it unchanged. `okm check` still verifies them. A
+ * catalog without them is returned as is.
+ *
+ * @param source - Catalog document
+ * @returns The catalog without role, grant, and default-privilege objects
+ */
+export declare function startupCatalog(source: Catalog): Catalog;
+/**
+ * {@link catalogHash} of {@link startupCatalog}. The hash `okm_meta` and
+ * `okm_history` store, and the one `connect()` computes.
+ *
+ * @param source - Catalog document
+ * @returns Lowercase hex digest
+ */
+export declare function startupHash(source: Catalog): string;
 /**
  * Loads a build artifact without validating objects.
  *

package/dist/contracts/driver.d.ts

@@ -61,6 +61,13 @@ export type ExecuteOptions = {
      * A deadline is kind `timeout`.
      */
     readonly timeout?: number;
+    /**
+     * Read routing hint.
+     *
+     * Drivers ignore it. A topology router reads it. Absent, the router
+     * classifies the statement.
+     */
+    readonly route?: "primary" | "replica";
 };
 /** Column names and parameter count from a describe. */
 export type DescribeResult = {

package/dist/dialects/pg/introspect.d.ts

@@ -39,6 +39,12 @@ export type CatalogQuery = {
  * @returns A checked catalog
  */
 export declare function introspectSchema(runner: CatalogQuery, concrete: string, logical?: string, options?: IntrospectOptions): Promise<Catalog>;
+/**
+ * A function's argument types as a grant names them, for `pg_proc p`.
+ *
+ * Types only, comma-separated, no spaces. Argument names are left out.
+ */
+export declare const FUNCTION_ARG_TYPES = "replace(oidvectortypes(p.proargtypes), ' ', '')";
 /**
  * Applies one expression as a check and reads Postgres's reprint.
  *

package/dist/dialects/pg/role/sql.d.ts

@@ -42,6 +42,16 @@ export declare function privilegeSql(before: readonly CatalogObject[], after: re
  * @returns The role, or `undefined` when the statement is not `CREATE ROLE`
  */
 export declare function createdRoleName(sql: string): string | undefined;
+/**
+ * Runs a plan's `CREATE ROLE` so a role another session created first is not an error.
+ *
+ * Roles belong to the cluster. Two databases provisioned at once both find the
+ * role absent, and the second `CREATE ROLE` fails on `pg_authid`.
+ *
+ * @param sql - A `CREATE ROLE` statement from the plan
+ * @returns The statement in a `DO` block that ignores a duplicate role
+ */
+export declare function createRoleOnce(sql: string): string;
 /**
  * Reports whether a statement creates or alters a role.
  *

package/dist/dialects/pg/schema.d.ts

@@ -144,6 +144,13 @@ type ApplySchemaTraits<TTable, TFields, TTraits> = TTable extends {
     readonly "~insert": InsertFrom<TFields>;
     readonly "~update": UpdateFrom<TFields>;
 } & HasArchive<TTraits> & PresetsOfList<TTraits>;
+/**
+ * `~views` when `schema({ views })` declared any, so `db.views` is typed.
+ * Nothing at runtime carries the key.
+ */
+type SchemaViews<TViews extends readonly unknown[]> = TViews extends readonly [] ? unknown : {
+    readonly "~views": TViews;
+};
 /**
  * Compiles tables into a catalog.
  *
@@ -156,19 +163,21 @@ type ApplySchemaTraits<TTable, TFields, TTraits> = TTable extends {
  */
 export declare function schema<const TTables extends readonly AnyTable[], const TTraits extends readonly {
     readonly fields: Readonly<Record<string, object>>;
-}[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined>(config: Omit<SchemaInput<TTables>, "traits" | "tenancy" | "validation"> & {
+}[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined, const TViews extends readonly unknown[] = readonly []>(config: Omit<SchemaInput<TTables>, "traits" | "tenancy" | "validation" | "views"> & {
     readonly traits: TTraits;
     readonly tenancy?: TTenancy;
     readonly validation?: TValidation;
-}): [TValidation] extends [undefined] ? TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> : TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> & {
+    readonly views?: TViews;
+}): ([TValidation] extends [undefined] ? TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> : TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> & {
     readonly "~validation": TValidation;
-};
-export declare function schema<const TTables extends readonly AnyTable[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined>(config: Omit<SchemaInput<TTables>, "tenancy" | "validation"> & {
+}) & SchemaViews<TViews>;
+export declare function schema<const TTables extends readonly AnyTable[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined, const TViews extends readonly unknown[] = readonly []>(config: Omit<SchemaInput<TTables>, "tenancy" | "validation" | "views"> & {
     readonly tenancy?: TTenancy;
     readonly validation?: TValidation;
-}): [TValidation] extends [undefined] ? TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> : TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> & {
+    readonly views?: TViews;
+}): ([TValidation] extends [undefined] ? TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> : TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> & {
     readonly "~validation": TValidation;
-};
+}) & SchemaViews<TViews>;
 /**
  * Registers a hook from an opt-in module.
  *

package/dist/dialects/pg/view/index.d.ts

@@ -34,10 +34,15 @@ export type ViewOptions = {
  *
  * `contribute` builds the catalog record. Column dependencies are filled
  * from `pg_depend` by scratch verification, not at this call.
+ *
+ * @typeParam N - View name
+ * @typeParam C - Declared output columns
  */
-export type ViewDeclaration = {
-    readonly name: string;
+export type ViewDeclaration<N extends string = string, C extends readonly ViewColumnInput[] = readonly ViewColumnInput[]> = {
+    readonly name: N;
     readonly schema: string;
+    /** Declared columns, for types only. `db.views` reads them. */
+    readonly "~columns"?: C;
     /**
      * Catalog record for this declaration.
      *
@@ -73,10 +78,15 @@ export type MaterializedViewOptions = ViewOptions & {
  * One declared materialized view.
  *
  * Identity is `(namespace, name)`. Indexes are separate catalog objects.
+ *
+ * @typeParam N - Materialized view name
+ * @typeParam C - Declared output columns
  */
-export type MaterializedViewDeclaration = {
-    readonly name: string;
+export type MaterializedViewDeclaration<N extends string = string, C extends readonly ViewColumnInput[] = readonly ViewColumnInput[]> = {
+    readonly name: N;
     readonly schema: string;
+    /** Declared columns, for types only. `db.views` reads them. */
+    readonly "~columns"?: C;
     /**
      * Catalog records for this declaration.
      *
@@ -100,7 +110,9 @@ export type MaterializedViewDeclaration = {
  * @param options - Columns and query
  * @returns The definition object `schema({ views })` stores
  */
-export declare function view(name: string, options: ViewOptions): ViewDeclaration;
+export declare function view<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, options: ViewOptions & {
+    readonly columns: C;
+}): ViewDeclaration<N, C>;
 /**
  * Declares a materialized view.
  *
@@ -111,4 +123,6 @@ export declare function view(name: string, options: ViewOptions): ViewDeclaratio
  * @param options - Columns, query, indexes, and refresh mode
  * @returns The definition object `schema({ views })` stores
  */
-export declare function materializedView(name: string, options: MaterializedViewOptions): MaterializedViewDeclaration;
+export declare function materializedView<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, options: MaterializedViewOptions & {
+    readonly columns: C;
+}): MaterializedViewDeclaration<N, C>;

package/dist/dialects/pg/view/scratch.d.ts

@@ -2,8 +2,8 @@
  * Verifies declared views on a scratch schema.
  *
  * Domain and enum types from the catalog are created there, then the tables,
- * then each view. `pg_get_viewdef` replaces the author query and `pg_depend`
- * supplies column edges (D117).
+ * then the functions a view may call, then each view. `pg_get_viewdef`
+ * replaces the author query and `pg_depend` supplies column edges (D117).
  * The scratch schema is dropped before this returns. Plans never use it.
  */
 import type { Catalog } from "../../../contracts/catalog/types.js";

package/dist/runtime/pg/bun.d.ts

@@ -1,13 +1,14 @@
 /**
  * `connect` for Bun.sql (`okmodel/pg/bun`).
  *
- * One URL or an existing pool is one endpoint. The client is typed by the
- * schema passed in. This entry runs on Bun. Node cannot load the `bun` import
- * inside the adapter.
+ * A string or an existing pool is one endpoint. A `{ primary, replicas }` object
+ * loads the topology module. The client is typed by the schema passed in.
+ * This entry runs on Bun. Node cannot load the `bun` import inside the adapter.
  */
 import type { DriverPool } from "../../contracts/driver.js";
 import type { QuerySchema } from "../../dialects/pg/model.js";
 import { type BunSqlConfig } from "../../adapters/pg/bunsql.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
 import type { ConnectOptions, Connected } from "../types.js";
 export { open, type BunSqlConfig, type BunSqlTls } from "../../adapters/pg/bunsql.js";
 export { capabilities, hasCapability, readCapability } from "../../adapters/pg/bunsql.js";
@@ -15,16 +16,20 @@ export { DriverError } from "../../adapters/error.js";
 /** A connection string or a pool from {@link open}. */
 export type BunSqlTarget = string | DriverPool;
 /** Driver options `connect` forwards to {@link open}. */
-export type BunSqlConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<BunSqlConfig, "url">;
+export type BunSqlConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<BunSqlConfig, "url"> & TopologyOptions;
 /**
- * Connects one Postgres endpoint through Bun.sql and returns a client for `schema`.
+ * Connects one Postgres endpoint through Bun.sql, or a primary and its replicas.
+ *
+ * A string or a pool is one endpoint. A topology loads on demand and the promise
+ * resolves to the client. Reads use the first healthy replica.
  *
  * Named prepared statements are off unless `prepared` is `"named"`.
  * `prepared: "named"` is not for transaction-mode poolers.
  *
  * @typeParam S - Schema
- * @param target - URL or an existing pool
+ * @param target - URL, an existing pool, or `{ primary, replicas }`
  * @param options - Schema, errors, logger, and driver options
- * @returns The client. Await `connected` for the dialect check
+ * @returns The client. A topology returns a promise. Await `connected` for the dialect check
  */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: BunSqlConnectOptions<S>): Promise<RoutedClient<S>>;
 export declare function connect<const S extends QuerySchema>(target: BunSqlTarget, options: BunSqlConnectOptions<S>): Connected<S>;

package/dist/runtime/pg/bun.js

@@ -11,10 +11,13 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/kkzwp3d2.js";
+} from "../../shared/bt9sfq0z.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/nkc9sfqb.js").then((mod) => mod.default(target, options, open5));
+  }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open5({
     url: target,

package/dist/runtime/pg/pg.d.ts

@@ -1,12 +1,14 @@
 /**
  * `connect` for node-postgres (`okmodel/pg/pg`).
  *
- * One URL or an existing pool is one endpoint. The client is typed by the
- * schema passed in, not by `Register`.
+ * A string or an existing pool is one endpoint. A `{ primary, replicas }` object
+ * loads the topology module. The client is typed by the schema passed in, not
+ * by `Register`.
  */
 import type { DriverPool } from "../../contracts/driver.js";
 import type { QuerySchema } from "../../dialects/pg/model.js";
 import { type NodePostgresConfig } from "../../adapters/pg/nodepostgres.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
 import type { ConnectOptions, Connected } from "../types.js";
 export { open, type NodePostgresConfig } from "../../adapters/pg/nodepostgres.js";
 export { capabilities, hasCapability, readCapability } from "../../adapters/pg/nodepostgres.js";
@@ -14,16 +16,20 @@ export { DriverError } from "../../adapters/error.js";
 /** A connection string or a pool from {@link open}. */
 export type NodePostgresTarget = string | DriverPool;
 /** Driver options `connect` forwards to {@link open}. */
-export type NodePostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<NodePostgresConfig, "url">;
+export type NodePostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<NodePostgresConfig, "url"> & TopologyOptions;
 /**
- * Connects one Postgres endpoint through node-postgres and returns a client for `schema`.
+ * Connects one Postgres endpoint through node-postgres, or a primary and its replicas.
+ *
+ * A string or a pool is one endpoint. A topology loads on demand and the promise
+ * resolves to the client. Reads use the first healthy replica.
  *
  * Named prepared statements are off unless `prepared` is `"named"`.
  * `prepared: "named"` is not for transaction-mode poolers.
  *
  * @typeParam S - Schema
- * @param target - URL or an existing pool
+ * @param target - URL, an existing pool, or `{ primary, replicas }`
  * @param options - Schema, errors, logger, and driver options
- * @returns The client. Await `connected` for the dialect check
+ * @returns The client. A topology returns a promise. Await `connected` for the dialect check
  */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: NodePostgresConnectOptions<S>): Promise<RoutedClient<S>>;
 export declare function connect<const S extends QuerySchema>(target: NodePostgresTarget, options: NodePostgresConnectOptions<S>): Connected<S>;

package/dist/runtime/pg/pg.js

@@ -11,10 +11,13 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/kkzwp3d2.js";
+} from "../../shared/bt9sfq0z.js";
 
 // src/runtime/pg/pg.ts
 function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/nkc9sfqb.js").then((mod) => mod.default(target, options, open4));
+  }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open4({
     url: target,

package/dist/runtime/pg/pglite.d.ts

@@ -2,10 +2,13 @@
  * `connect` for PGlite (`okmodel/pg/pglite`).
  *
  * Opening a database is async. An existing pool is reused and not closed.
+ * A `{ primary, replicas }` object loads the topology module. A replica URL is
+ * that endpoint's data directory.
  */
 import type { DriverPool } from "../../contracts/driver.js";
 import type { QuerySchema } from "../../dialects/pg/model.js";
 import { type PgliteConfig } from "../../adapters/pg/pglite.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
 import type { ConnectOptions, Connected } from "../types.js";
 export { open, type PgliteConfig } from "../../adapters/pg/pglite.js";
 export { capabilities, hasCapability, readCapability } from "../../adapters/pg/pglite.js";
@@ -13,13 +16,18 @@ export { DriverError } from "../../adapters/error.js";
 /** A data directory, a pool from {@link open}, or omitted for memory. */
 export type PgliteTarget = string | DriverPool | undefined;
 /** Driver options `connect` forwards to {@link open}. */
-export type PgliteConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PgliteConfig, "dataDir">;
+export type PgliteConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PgliteConfig, "dataDir"> & TopologyOptions;
 /**
- * Connects one PGlite endpoint and returns a client for `schema`.
+ * Connects one PGlite endpoint, or a primary and its replicas, and returns a client for `schema`.
+ *
+ * A string, a pool, or an omitted target is one endpoint. A topology loads on
+ * demand. Reads use the first healthy replica. A replica `url` is that
+ * endpoint's data directory.
  *
  * @typeParam S - Schema
- * @param target - Data directory, existing pool, or omitted for memory
+ * @param target - Data directory, existing pool, omitted for memory, or `{ primary, replicas }`
  * @param options - Schema, errors, and logger
  * @returns The client
  */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: PgliteConnectOptions<S>): Promise<RoutedClient<S>>;
 export declare function connect<const S extends QuerySchema>(target: PgliteTarget, options: PgliteConnectOptions<S>): Promise<Connected<S>>;

package/dist/runtime/pg/pglite.js

@@ -11,10 +11,13 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/kkzwp3d2.js";
+} from "../../shared/bt9sfq0z.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/nkc9sfqb.js").then((mod) => mod.default(target, options, open3));
+  }
   const pool = isPool(target) ? target : await open3({
     ...target !== undefined ? { dataDir: target } : {},
     ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {}

package/dist/runtime/pg/postgresjs.d.ts

@@ -1,12 +1,14 @@
 /**
  * `connect` for postgres.js (`okmodel/pg/postgresjs`).
  *
- * One URL or an existing pool is one endpoint. The client is typed by the
- * schema passed in, not by `Register`.
+ * A string or an existing pool is one endpoint. A `{ primary, replicas }` object
+ * loads the topology module. The client is typed by the schema passed in, not
+ * by `Register`.
  */
 import type { DriverPool } from "../../contracts/driver.js";
 import type { QuerySchema } from "../../dialects/pg/model.js";
 import { type PostgresJsConfig } from "../../adapters/pg/postgresjs.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
 import type { ConnectOptions, Connected } from "../types.js";
 export { open, type PostgresJsConfig } from "../../adapters/pg/postgresjs.js";
 export { capabilities, hasCapability, readCapability } from "../../adapters/pg/postgresjs.js";
@@ -14,16 +16,20 @@ export { DriverError } from "../../adapters/error.js";
 /** A connection string or a pool from {@link open}. */
 export type PostgresTarget = string | DriverPool;
 /** Driver options `connect` forwards to {@link open}. */
-export type PostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PostgresJsConfig, "url">;
+export type PostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PostgresJsConfig, "url"> & TopologyOptions;
 /**
- * Connects one Postgres endpoint and returns a client for `schema`.
+ * Connects one Postgres endpoint, or a primary and its replicas, and returns a client for `schema`.
+ *
+ * A string or a pool is one endpoint. A topology loads on demand and the promise
+ * resolves to the client. Reads use the first healthy replica.
  *
  * Named prepared statements are off unless `prepared` is `"named"`.
  * `prepared: "named"` is not for transaction-mode poolers.
  *
  * @typeParam S - Schema
- * @param target - URL or an existing pool
+ * @param target - URL, an existing pool, or `{ primary, replicas }`
  * @param options - Schema, errors, logger, and driver options
- * @returns The client. Await `connected` for the dialect check
+ * @returns The client. A topology returns a promise. Await `connected` for the dialect check
  */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: PostgresConnectOptions<S>): Promise<RoutedClient<S>>;
 export declare function connect<const S extends QuerySchema>(target: PostgresTarget, options: PostgresConnectOptions<S>): Connected<S>;

package/dist/runtime/pg/postgresjs.js

@@ -11,10 +11,13 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/kkzwp3d2.js";
+} from "../../shared/bt9sfq0z.js";
 
 // src/runtime/pg/postgresjs.ts
 function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/nkc9sfqb.js").then((mod) => mod.default(target, options, open2));
+  }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open2({
     url: target,

package/dist/runtime/plan.d.ts

@@ -41,9 +41,11 @@ export type ReadCall = {
     readonly build?: ReadBuild;
     /** Writes the end of the statement, after `limit`. A row lock sets it. */
     readonly tail?: (sink: Sink) => void;
-    /** The caller's `signal` and `timeout`. They never enter the plan or its key. */
+    /** The caller's `signal`, `timeout`, and `route`. They never enter the plan or its key. */
     readonly signal?: AbortSignal;
     readonly timeout?: number;
+    /** `"primary"` or `"replica"`. Absent means the router classifies the statement. */
+    readonly route?: "primary" | "replica";
     /** Set by `for()` or `unscoped()`. Absent on a schema with no tenancy. */
     readonly scope?: CallScope;
     /** Inspect lines from the tenancy object. Absent when the schema has no tenancy. */

package/dist/runtime/tenancy/index.js

@@ -11,7 +11,7 @@ import {
 } from "../../shared/tmbdywx0.js";
 import {
   quote
-} from "../../shared/xrfnq5k8.js";
+} from "../../shared/qgvt8nx1.js";
 import {
   assertIdentifier2
 } from "../../shared/nfzc5z0w.js";