@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/src/composites/events-table.ts

@@ -0,0 +1,49 @@
+/**
+ * `EventsTable`: an append-only MergeTree events table, partitioned by month and expired by TTL.
+ *
+ * The table is partitioned by its timestamp (by month unless `partitionBy`
+ * says otherwise) and drops rows older than `ttlDays`. It sets
+ * `ttl_only_drop_parts`, so expiry drops whole parts once every row in them
+ * has expired instead of rewriting parts to remove single rows, which is cheap
+ * when the partition and the TTL follow the same column.
+ */
+
+import { Composite } from "@intentius/chant/composite";
+import { table, type ClickHouseTable } from "../clickhouse/entities";
+
+export interface EventsTableProps {
+  /** The table's name, `name` or `database.name`. */
+  name: string;
+  /** Every column except the timestamp, as SQL: `user_id UUID, kind LowCardinality(String)`. */
+  columns: string;
+  /** The sort key. Put the columns queries filter on first: `(kind, user_id, ts)`. */
+  orderBy: string;
+  /** The timestamp column (default `ts`). TTL and the default partition key read it. */
+  timestamp?: string;
+  /** The timestamp's type (default `DateTime`): a Date, DateTime or DateTime64. */
+  timestampType?: string;
+  /** Days a row is kept (default 90). */
+  ttlDays?: number;
+  /** The partition key (default `toYYYYMM(<timestamp>)`). Keep it no finer than a day. */
+  partitionBy?: string;
+}
+
+export type EventsTableMembers = {
+  table: ClickHouseTable;
+};
+
+/** An append-only MergeTree events table, partitioned by its timestamp and expired by TTL. */
+export const EventsTable = Composite<EventsTableProps, EventsTableMembers>((props) => {
+  const ts = props.timestamp ?? "ts";
+  const events = table`
+    CREATE TABLE ${props.name} (
+      ${props.columns},
+      ${ts} ${props.timestampType ?? "DateTime"}
+    )
+    ENGINE = MergeTree
+    PARTITION BY ${props.partitionBy ?? `toYYYYMM(${ts})`}
+    ORDER BY ${props.orderBy}
+    TTL ${ts} + INTERVAL ${props.ttlDays ?? 90} DAY
+    SETTINGS ttl_only_drop_parts = 1`;
+  return { table: events };
+}, "EventsTable");

package/src/composites/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The sql lexicon's composites: tables and views that are usually declared
+ * together, built from each dialect's `table`, `index` and `view` tags so every
+ * field keeps its provenance. `./clickhouse` and `./postgres` are what the two
+ * dialect subpaths export.
+ */
+
+export * from "./clickhouse";
+export * from "./postgres";

package/src/composites/join-table.ts

@@ -0,0 +1,57 @@
+/**
+ * `JoinTable`: the table of a many-to-many relation, with both foreign keys indexed.
+ *
+ * The primary key is `(<leftColumn>, <rightColumn>)`, which also serves
+ * lookups from the left side. The reverse index on `(<rightColumn>,
+ * <leftColumn>)` serves lookups from the right and keeps deletes of a
+ * referenced row off a table scan (SQLPG102). Each foreign key cascades by
+ * default, so deleting a row on either side removes its links.
+ */
+
+import { Composite } from "@intentius/chant/composite";
+import { index, table, type PostgresIndex, type PostgresSchema, type PostgresTable } from "../postgres/entities";
+
+export interface JoinTableProps {
+  /** The table's name, unqualified. The reverse index is `<name>_reverse_idx`. */
+  name: string;
+  /** The schema the table lives in: the entity, or its name (default `public`). */
+  schema?: PostgresSchema | string;
+  /** The table on the left of the relation, as the entity. */
+  left: PostgresTable;
+  /** The column on the left table the key references (default `id`). */
+  leftKey?: string;
+  /** The join table's column holding the left key: `user_id`. */
+  leftColumn: string;
+  /** The left column's type (default `bigint`). */
+  leftType?: string;
+  /** The table on the right of the relation, as the entity. */
+  right: PostgresTable;
+  /** The column on the right table the key references (default `id`). */
+  rightKey?: string;
+  /** The join table's column holding the right key: `team_id`. */
+  rightColumn: string;
+  /** The right column's type (default `bigint`). */
+  rightType?: string;
+  /** What happens to a link when the row it references is deleted (default `CASCADE`). */
+  onDelete?: string;
+}
+
+export type JoinTableMembers = {
+  table: PostgresTable;
+  reverseIndex: PostgresIndex;
+};
+
+/** The table of a many-to-many relation: two foreign keys, a composite primary key and the reverse index. */
+export const JoinTable = Composite<JoinTableProps, JoinTableMembers>((props) => {
+  const schema = props.schema ?? "public";
+  const links = table`
+    CREATE TABLE ${schema}.${props.name} (
+      ${props.leftColumn} ${props.leftType ?? "bigint"} NOT NULL REFERENCES ${props.left} (${props.leftKey ?? "id"}) ON DELETE ${props.onDelete ?? "CASCADE"},
+      ${props.rightColumn} ${props.rightType ?? "bigint"} NOT NULL REFERENCES ${props.right} (${props.rightKey ?? "id"}) ON DELETE ${props.onDelete ?? "CASCADE"},
+      created_at timestamptz NOT NULL DEFAULT now(),
+      PRIMARY KEY (${props.leftColumn}, ${props.rightColumn})
+    )`;
+  const reverse = index`
+    CREATE INDEX ${`${props.name}_reverse_idx`} ON ${links} (${props.rightColumn}, ${props.leftColumn})`;
+  return { table: links, reverseIndex: reverse };
+}, "JoinTable");

package/src/composites/postgres.ts

@@ -0,0 +1,7 @@
+/** The Postgres composites, exported at `@intentius/chant-lexicon-sql/postgres`. */
+
+export { SoftDeleteTable, type SoftDeleteTableProps, type SoftDeleteTableMembers } from "./soft-delete-table";
+export { AuditLogTable, type AuditLogTableProps, type AuditLogTableMembers } from "./audit-log-table";
+export { JoinTable, type JoinTableProps, type JoinTableMembers } from "./join-table";
+export { TenantTable, type TenantTableProps, type TenantTableMembers } from "./tenant-table";
+export { RefreshedView, type RefreshedViewProps, type RefreshedViewMembers } from "./refreshed-view";

package/src/composites/refreshed-view.ts

@@ -0,0 +1,46 @@
+/**
+ * `RefreshedView`: a materialized view with the unique index that lets it refresh concurrently.
+ *
+ * `REFRESH MATERIALIZED VIEW CONCURRENTLY` needs at least one unique index
+ * over plain columns, and without it every refresh takes an ACCESS EXCLUSIVE
+ * lock that blocks readers (SQLPG111). The composite declares the view and
+ * that index together, so a view cannot be added without one. The view reads
+ * `source` by reference, so the build orders them and the view's lineage
+ * names the source's columns.
+ */
+
+import { Composite } from "@intentius/chant/composite";
+import { index, view, type PostgresIndex, type PostgresRelation, type PostgresSchema, type PostgresView } from "../postgres/entities";
+
+export interface RefreshedViewProps {
+  /** The view's name, unqualified. The index is `<name>_key`. */
+  name: string;
+  /** The schema the view lives in: the entity, or its name (default `public`). */
+  schema?: PostgresSchema | string;
+  /** The table or view the materialized view reads, as the entity. */
+  source: PostgresRelation;
+  /** The select list, each computed item aliased: `region, count(*) AS orders, sum(total) AS revenue`. */
+  select: string;
+  /** The grouping key: `region`. */
+  groupBy: string;
+  /** The columns of the unique index, which must identify one row of the result (default `groupBy`). */
+  uniqueOn?: string;
+}
+
+export type RefreshedViewMembers = {
+  view: PostgresView;
+  uniqueIndex: PostgresIndex;
+};
+
+/** A materialized view over a source, with the unique index that allows REFRESH ... CONCURRENTLY. */
+export const RefreshedView = Composite<RefreshedViewProps, RefreshedViewMembers>((props) => {
+  const schema = props.schema ?? "public";
+  const summary = view`
+    CREATE MATERIALIZED VIEW ${schema}.${props.name} AS
+    SELECT ${props.select}
+    FROM ${props.source}
+    GROUP BY ${props.groupBy}`;
+  const key = index`
+    CREATE UNIQUE INDEX ${`${props.name}_key`} ON ${summary} (${props.uniqueOn ?? props.groupBy})`;
+  return { view: summary, uniqueIndex: key };
+}, "RefreshedView");

package/src/composites/replacing-table.ts

@@ -0,0 +1,49 @@
+/**
+ * `ReplacingTable`: a ReplacingMergeTree table with a version column.
+ *
+ * ReplacingMergeTree keeps one row per sort key. When a merge meets rows with
+ * the same key it keeps the one with the highest version, so writing a row
+ * again with a higher version is how an update is expressed. Until a merge
+ * runs, a query sees every version; read with `FINAL`, or aggregate with
+ * `argMax`, when the latest row is what you want.
+ *
+ * Every field is built from a parameter or fixed by the template, inside the
+ * subset `chant build` interprets, so a drift on the table is reported against
+ * the parameter that produced the field when the composite is interpreted.
+ */
+
+import { Composite } from "@intentius/chant/composite";
+import { table, type ClickHouseTable } from "../clickhouse/entities";
+
+export interface ReplacingTableProps {
+  /** The table's name, `name` or `database.name`. */
+  name: string;
+  /** Every column except the version column, as SQL: `id UInt64, email String`. */
+  columns: string;
+  /** The sort key, which is also the key rows are deduplicated by: `id` or `(tenant_id, id)`. */
+  orderBy: string;
+  /** The version column (default `version`). The row with the highest version survives a merge. */
+  version?: string;
+  /** The version column's type (default `UInt64`): a UInt, Date, DateTime or DateTime64. */
+  versionType?: string;
+  /** A `PARTITION BY` expression. Left out by default: a deduplicating table is usually small enough not to need one. */
+  partitionBy?: string;
+}
+
+export type ReplacingTableMembers = {
+  table: ClickHouseTable;
+};
+
+/** A ReplacingMergeTree table that keeps the highest version of each row, with its version column. */
+export const ReplacingTable = Composite<ReplacingTableProps, ReplacingTableMembers>((props) => {
+  const version = props.version ?? "version";
+  const replacing = table`
+    CREATE TABLE ${props.name} (
+      ${props.columns},
+      ${version} ${props.versionType ?? "UInt64"}
+    )
+    ENGINE = ReplacingMergeTree(${version})
+    ${props.partitionBy ? `PARTITION BY ${props.partitionBy}` : ""}
+    ORDER BY ${props.orderBy}`;
+  return { table: replacing };
+}, "ReplacingTable");

package/src/composites/rollup-view.ts

@@ -0,0 +1,55 @@
+/**
+ * `RollupView`: a materialized view that rolls a source table up into its own target table.
+ *
+ * The target is a SummingMergeTree (or another engine named by `engine`)
+ * sorted by the rollup's grouping key. The materialized view writes into it
+ * with `TO`, so the target is an ordinary table that can be queried, altered
+ * and backfilled on its own, and dropping the view leaves the data. Every
+ * column the select list writes has to be one the target declares
+ * (SQLCH110), so alias each select item to a target column.
+ *
+ * The view reads `source` by reference, so it depends on the source and on
+ * its target, and the build orders all three.
+ */
+
+import { Composite } from "@intentius/chant/composite";
+import { table, view, type ClickHouseRelation, type ClickHouseTable, type ClickHouseView } from "../clickhouse/entities";
+
+export interface RollupViewProps {
+  /** The target table's name. The view is `<name>_mv`. */
+  name: string;
+  /** The table or view the rollup reads, as the entity: `events`. */
+  source: ClickHouseRelation;
+  /** The target's columns, as SQL: `day Date, kind LowCardinality(String), n UInt64`. */
+  columns: string;
+  /** The select list, each item aliased to a target column: `toDate(ts) AS day, kind, count() AS n`. */
+  select: string;
+  /** The grouping key: `day, kind`. */
+  groupBy: string;
+  /** The target's sort key (default `groupBy` in parentheses). Summing collapses rows that share it. */
+  orderBy?: string;
+  /** The target's engine (default `SummingMergeTree`). Use `AggregatingMergeTree` for `-State` columns. */
+  engine?: string;
+  /** The target's partition key. Left out by default. */
+  partitionBy?: string;
+}
+
+export type RollupViewMembers = {
+  table: ClickHouseTable;
+  view: ClickHouseView;
+};
+
+/** A materialized view that rolls a source table up into a target table it declares beside it. */
+export const RollupView = Composite<RollupViewProps, RollupViewMembers>((props) => {
+  const target = table`
+    CREATE TABLE ${props.name} (${props.columns})
+    ENGINE = ${props.engine ?? "SummingMergeTree"}
+    ${props.partitionBy ? `PARTITION BY ${props.partitionBy}` : ""}
+    ORDER BY ${props.orderBy ?? `(${props.groupBy})`}`;
+  const rollup = view`
+    CREATE MATERIALIZED VIEW ${`${props.name}_mv`} TO ${target} AS
+    SELECT ${props.select}
+    FROM ${props.source}
+    GROUP BY ${props.groupBy}`;
+  return { table: target, view: rollup };
+}, "RollupView");

package/src/composites/sharded-table.ts

@@ -0,0 +1,49 @@
+/**
+ * `ShardedTable`: a ReplicatedMergeTree table on every node of a cluster and the Distributed table that spreads reads and writes across it.
+ *
+ * Both tables are created `ON CLUSTER`. The local table, `<name>_local`, holds
+ * each shard's rows and replicates them within the shard; with no engine
+ * arguments it takes the server's default replication path. The Distributed
+ * table, `<name>`, holds no data: an insert goes to one shard by the sharding
+ * key, and a query runs on every shard and merges the results.
+ *
+ * The Distributed table reads the local one by reference, so the build creates
+ * the local table first. Give `name` without a database: the Distributed
+ * engine names its table in the current database.
+ */
+
+import { Composite } from "@intentius/chant/composite";
+import { table, type ClickHouseTable } from "../clickhouse/entities";
+
+export interface ShardedTableProps {
+  /** The Distributed table's name, unqualified. The local table is `<name>_local`. */
+  name: string;
+  /** The cluster both tables are created on, as the server's `remote_servers` names it. */
+  cluster: string;
+  /** The columns, as SQL. Both tables declare the same list. */
+  columns: string;
+  /** The local table's sort key. */
+  orderBy: string;
+  /** The expression that picks a shard for an inserted row (default `rand()`). */
+  shardingKey?: string;
+  /** The local table's partition key. Left out by default. */
+  partitionBy?: string;
+}
+
+export type ShardedTableMembers = {
+  local: ClickHouseTable;
+  distributed: ClickHouseTable;
+};
+
+/** A ReplicatedMergeTree table on every node of a cluster and the Distributed table over it. */
+export const ShardedTable = Composite<ShardedTableProps, ShardedTableMembers>((props) => {
+  const local = table`
+    CREATE TABLE ${`${props.name}_local`} ON CLUSTER ${props.cluster} (${props.columns})
+    ENGINE = ReplicatedMergeTree
+    ${props.partitionBy ? `PARTITION BY ${props.partitionBy}` : ""}
+    ORDER BY ${props.orderBy}`;
+  const distributed = table`
+    CREATE TABLE ${props.name} ON CLUSTER ${props.cluster} (${props.columns})
+    ENGINE = Distributed(${props.cluster}, currentDatabase(), ${local}, ${props.shardingKey ?? "rand()"})`;
+  return { local, distributed };
+}, "ShardedTable");

package/src/composites/soft-delete-table.ts

@@ -0,0 +1,61 @@
+/**
+ * `SoftDeleteTable`: a table whose rows carry created and updated timestamps and are deleted by marking them.
+ *
+ * The composite appends `created_at` and `updated_at` (both `timestamptz NOT
+ * NULL DEFAULT now()`) and a nullable `deleted_at` to the columns it is
+ * given. A row is live while `deleted_at` is null. The `<name>_live` view
+ * reads the live rows (it sets `security_invoker`, so row-level security on
+ * the table applies to whoever reads the view), and a partial index on the
+ * live rows keeps lookups by the key the app uses off the dead ones.
+ *
+ * Postgres has no column default that follows an update: the app, or a
+ * trigger it owns, sets `updated_at`.
+ */
+
+import { Composite } from "@intentius/chant/composite";
+import { index, literal, table, view, type PostgresIndex, type PostgresSchema, type PostgresTable, type PostgresView } from "../postgres/entities";
+
+export interface SoftDeleteTableProps {
+  /** The table's name, unqualified. The view is `<name>_live`. */
+  name: string;
+  /** The schema the table, its index and its view live in: the entity, or its name (default `public`). */
+  schema?: PostgresSchema | string;
+  /** Every column except the three the composite adds, as SQL, with the primary key: `id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, title text NOT NULL`. */
+  columns: string;
+  /** The column the live-rows index covers: the one the app looks rows up by, as SQL (default `id`). */
+  liveKey?: string;
+  /** The table's comment, which also covers its columns for SQLPG112 (default: says rows are soft-deleted). */
+  comment?: string;
+  /** The creation timestamp column (default `created_at`). */
+  createdAt?: string;
+  /** The update timestamp column (default `updated_at`). */
+  updatedAt?: string;
+  /** The deletion timestamp column (default `deleted_at`). Null means the row is live. */
+  deletedAt?: string;
+}
+
+export type SoftDeleteTableMembers = {
+  table: PostgresTable;
+  live: PostgresView;
+  liveIndex: PostgresIndex;
+};
+
+/** A table with created and updated timestamps and a soft-delete column, a view of its live rows and an index over them. */
+export const SoftDeleteTable = Composite<SoftDeleteTableProps, SoftDeleteTableMembers>((props) => {
+  const schema = props.schema ?? "public";
+  const deleted = props.deletedAt ?? "deleted_at";
+  const rows = table`
+    CREATE TABLE ${schema}.${props.name} (
+      ${props.columns},
+      ${props.createdAt ?? "created_at"} timestamptz NOT NULL DEFAULT now(),
+      ${props.updatedAt ?? "updated_at"} timestamptz NOT NULL DEFAULT now(),
+      ${deleted} timestamptz
+    );
+    COMMENT ON TABLE ${schema}.${props.name} IS ${literal(props.comment ?? "Soft-deleted: a row is live while its deletion timestamp is null")}`;
+  const live = view`
+    CREATE VIEW ${schema}.${`${props.name}_live`} WITH (security_invoker = true) AS
+    SELECT * FROM ${rows} WHERE ${deleted} IS NULL`;
+  const liveIndex = index`
+    CREATE INDEX ${`${props.name}_live_idx`} ON ${rows} (${props.liveKey ?? "id"}) WHERE ${deleted} IS NULL`;
+  return { table: rows, live, liveIndex };
+}, "SoftDeleteTable");

package/src/composites/tenant-table.ts

@@ -0,0 +1,50 @@
+/**
+ * `TenantTable`: a multi-tenant table whose tenant key leads every key and index.
+ *
+ * The composite adds the tenant column (`NOT NULL`) in front of the columns it
+ * is given, makes the primary key `(<tenant>, <primaryKey>)` and creates one
+ * index on `(<tenant>, <indexOn>)`. With the tenant first in each, a query
+ * scoped to one tenant reads one contiguous range of every index, and no index
+ * serves a cross-tenant scan by accident. Row-level security is separate: a
+ * policy on the table is what keeps one tenant's role out of another's rows.
+ */
+
+import { Composite } from "@intentius/chant/composite";
+import { index, table, type PostgresIndex, type PostgresSchema, type PostgresTable } from "../postgres/entities";
+
+export interface TenantTableProps {
+  /** The table's name, unqualified. The index is `<name>_tenant_idx`. */
+  name: string;
+  /** The schema the table lives in: the entity, or its name (default `public`). */
+  schema?: PostgresSchema | string;
+  /** Every column except the tenant's, as SQL: `id bigint GENERATED ALWAYS AS IDENTITY, title text NOT NULL`. */
+  columns: string;
+  /** The columns that, after the tenant, make a row unique: `id`. */
+  primaryKey: string;
+  /** The columns the secondary index covers after the tenant: `created_at DESC`. */
+  indexOn: string;
+  /** The tenant column (default `tenant_id`). */
+  tenant?: string;
+  /** The tenant column's type (default `uuid`). */
+  tenantType?: string;
+}
+
+export type TenantTableMembers = {
+  table: PostgresTable;
+  index: PostgresIndex;
+};
+
+/** A multi-tenant table with the tenant key first in its primary key and its index. */
+export const TenantTable = Composite<TenantTableProps, TenantTableMembers>((props) => {
+  const schema = props.schema ?? "public";
+  const tenant = props.tenant ?? "tenant_id";
+  const rows = table`
+    CREATE TABLE ${schema}.${props.name} (
+      ${tenant} ${props.tenantType ?? "uuid"} NOT NULL,
+      ${props.columns},
+      PRIMARY KEY (${tenant}, ${props.primaryKey})
+    )`;
+  const byTenant = index`
+    CREATE INDEX ${`${props.name}_tenant_idx`} ON ${rows} (${tenant}, ${props.indexOn})`;
+  return { table: rows, index: byTenant };
+}, "TenantTable");

package/src/config.ts

@@ -0,0 +1,157 @@
+/**
+ * The `sql` namespace in `chant.config.ts`.
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-sql";   // brings the `sql` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["sql"],
+ *   sql: {
+ *     dialect: "clickhouse",
+ *     profiles: {
+ *       staging: { url: "http://clickhouse.staging:8123", user: { env: "CH_USER" }, password: { env: "CH_PASSWORD" } },
+ *       prod: { url: "https://clickhouse.example.com:8443", user: { env: "CH_USER" }, password: { env: "CH_PROD_PASSWORD" }, databases: ["analytics"] },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * A profile is keyed by chant environment, as `grafana.profiles.<env>` is:
+ * the server `chant import --from <env>`, `chant lifecycle diff <env> --live`
+ * and `plan` read. Credentials are named by their environment variable, never
+ * written in the config. An environment with no profile falls back to
+ * `CLICKHOUSE_URL`, `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD`, or for
+ * Postgres `POSTGRES_URL`, `POSTGRES_USER` and `POSTGRES_PASSWORD`. A profile
+ * whose `url` is `postgres://` or `postgresql://` is a Postgres server.
+ *
+ * `dialect` names the database a project's schema is for. Declarations carry
+ * their dialect in their own type (a ClickHouse table is `ClickHouse::Table`),
+ * so the setting is for the things a declaration cannot answer: which dialect
+ * a live environment is read as on import, and which dialect's checks run on
+ * output that names none. It defaults to `clickhouse`, the first dialect.
+ * `postgres` is the second (#3289). A list (`dialect: ["clickhouse",
+ * "postgres"]`) is accepted for a workspace with members of more than one
+ * dialect (#3047 question 1); one build still holds one dialect.
+ *
+ * `provider` (#3282) names the managed Postgres service, on the namespace or
+ * on one profile: `sql: { dialect: "postgres", provider: "rds" }`, or
+ * `profiles: { prod: { url, provider: "aurora" } }`. A provider's data lives
+ * in `@intentius/chant-lexicon-sql/postgres` (`providerData`).
+ */
+
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+import { PLANNED_SQL_DIALECTS, SQL_DIALECTS } from "./dialects";
+import { POSTGRES_PROVIDERS } from "./postgres/providers/types";
+import { POSTGRES_MAJORS } from "./spec/postgres-pin";
+
+const envRef = z.strictObject({ env: z.string() });
+
+/** The managed Postgres service an environment runs on (#3282). */
+const providerName = z.enum(POSTGRES_PROVIDERS, {
+  error: () => `expected a Postgres provider (${POSTGRES_PROVIDERS.join(", ")})`,
+});
+
+export const sqlProfileSchema = z.strictObject({
+  /**
+   * Where the server is. ClickHouse: the base URL of its HTTP interface
+   * (`http://clickhouse:8123`). Postgres: a connection URL
+   * (`postgres://db.internal:5432/shop`), with no password in it; the scheme
+   * is what makes a profile a Postgres one.
+   */
+  url: z.string(),
+  /** The user, named by its environment variable. `default` when omitted. */
+  user: envRef.optional(),
+  /** The password, named by its environment variable. */
+  password: envRef.optional(),
+  /**
+   * The databases this environment's schema lives in. Import reads these and
+   * nothing else; when omitted, every database except the server's own
+   * (`system`, `information_schema`, `INFORMATION_SCHEMA`).
+   */
+  databases: z.array(z.string()).optional(),
+  /** The database an unqualified declaration is created in. `default` when omitted. */
+  defaultDatabase: z.string().optional(),
+  /**
+   * Postgres: the schemas this environment's schema lives in. Import and
+   * observation read these and nothing else; when omitted, every schema except
+   * the server's own (`pg_catalog`, `information_schema`, `pg_toast`, the temp
+   * schemas).
+   */
+  schemas: z.array(z.string()).optional(),
+  /** Postgres: the schema an unqualified declaration is created in. `public` when omitted. */
+  defaultSchema: z.string().optional(),
+  /**
+   * The managed service this environment's Postgres runs on, when it differs
+   * from `sql.provider`. Import reads the provider's own roles, schemas and
+   * extensions as foreign.
+   */
+  provider: providerName.optional(),
+  /**
+   * Postgres apply: how long one statement waits for its lock before it
+   * fails (`lock_timeout`), in milliseconds, so a change blocked behind a
+   * long query fails fast instead of queueing every query behind it. 5000
+   * when omitted.
+   */
+  lockTimeoutMs: z.number().int().nonnegative().optional(),
+  /**
+   * Postgres apply: the `statement_timeout` for a statement that changes only
+   * the catalog, in milliseconds. 60000 when omitted.
+   */
+  statementTimeoutMs: z.number().int().nonnegative().optional(),
+  /**
+   * Postgres apply: the `statement_timeout` for a statement that reads or
+   * rewrites every row (a table rewrite, a constraint validation, a
+   * `CONCURRENTLY` index build), in milliseconds. 0, no limit, when omitted.
+   */
+  scanTimeoutMs: z.number().int().nonnegative().optional(),
+});
+
+const dialectName = z.enum(SQL_DIALECTS);
+
+/** Why a `dialect` value is refused: a planned dialect is "not implemented yet", anything else unknown. */
+function dialectError(input: unknown): string {
+  const names = Array.isArray(input) ? input : [input];
+  const planned = names.find((n): n is string => typeof n === "string" && (PLANNED_SQL_DIALECTS as readonly string[]).includes(n));
+  if (planned !== undefined) {
+    return `the ${planned} dialect is not implemented yet; the implemented dialects are ${SQL_DIALECTS.join(", ")}`;
+  }
+  return `expected a dialect (${SQL_DIALECTS.join(", ")}) or a non-empty list of them`;
+}
+
+export const sqlConfigSchema = z.strictObject({
+  /** The dialect, or the dialects, the project's schema is for. */
+  dialect: z.union([dialectName, z.array(dialectName).min(1)], { error: (iss) => dialectError(iss.input) }).optional(),
+  /**
+   * The managed Postgres service the project deploys to (`rds`, `aurora`,
+   * `cloud-sql`, `azure`, `neon`, `supabase`). SQLPG004 reads it to refuse an
+   * extension the provider does not allow. Omit it for a self-hosted server.
+   */
+  provider: providerName.optional(),
+  /**
+   * The Postgres major the project targets. The editor completes and hovers
+   * only what that major has (a function added in 18 is not offered at 16);
+   * without it, the newest supported major is used.
+   */
+  postgresMajor: z
+    .number()
+    .int()
+    .refine((n) => POSTGRES_MAJORS.includes(n), { error: `expected a supported Postgres major (${POSTGRES_MAJORS.join(", ")})` })
+    .optional(),
+  /** One server per chant environment. */
+  profiles: z.record(z.string(), sqlProfileSchema).optional(),
+});
+
+export type SqlProfile = z.infer<typeof sqlProfileSchema>;
+
+export type SqlConfig = z.infer<typeof sqlConfigSchema>;
+
+declare module "@intentius/chant/config" {
+  interface ChantConfig {
+    sql?: SqlConfig;
+  }
+}
+
+/** Compile-time proof that the augmentation above reaches `ChantConfig`. */
+export type SqlConfigNamespace = NonNullable<ChantConfig["sql"]>;