turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/schema-builder.d.ts

@@ -0,0 +1,354 @@
+/**
+ * turbine-orm — Schema Builder
+ *
+ * TypeScript-first schema definition API. Define your database schema
+ * as plain objects — no method chaining, no DSL. Fully type-checked,
+ * JSON-serializable, and easy to read.
+ *
+ * @example
+ * ```ts
+ * import { defineSchema } from 'turbine-orm';
+ *
+ * export default defineSchema({
+ *   users: {
+ *     id:        { type: 'serial', primaryKey: true },
+ *     email:     { type: 'text', unique: true, notNull: true },
+ *     name:      { type: 'text', notNull: true },
+ *     bio:       { type: 'text' },
+ *     role:      { type: 'varchar', maxLength: 50, default: "'user'" },
+ *     orgId:     { type: 'bigint', notNull: true, references: 'organizations.id' },
+ *     createdAt: { type: 'timestamp', default: 'now()' },
+ *   },
+ * });
+ * ```
+ */
+import type { ReferentialAction, SchemaMetadata } from './schema.js';
+export type { ReferentialAction } from './schema.js';
+/** Shorthand type names that map to Postgres column types */
+export type ColumnTypeName = 'serial' | 'bigserial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'varchar' | 'boolean' | 'timestamp' | 'timestamptz' | 'date' | 'json' | 'jsonb' | 'uuid' | 'real' | 'double' | 'numeric' | 'bytea' | 'enum' | 'vector';
+/** Foreign key reference with optional referential actions. */
+export interface ReferenceDef {
+    /** REFERENCES target in "table.column" form. */
+    target: string;
+    /** `ON DELETE` action. Omit for the Postgres default (`NO ACTION`). */
+    onDelete?: ReferentialAction;
+    /** `ON UPDATE` action. Omit for the Postgres default (`NO ACTION`). */
+    onUpdate?: ReferentialAction;
+}
+/** Column definition as a plain object. This is what users write. */
+export interface ColumnDef {
+    /** Column type (required) */
+    type: ColumnTypeName;
+    /** PRIMARY KEY constraint */
+    primaryKey?: boolean;
+    /** NOT NULL constraint */
+    notNull?: boolean;
+    /** Explicitly nullable */
+    nullable?: boolean;
+    /** UNIQUE constraint */
+    unique?: boolean;
+    /** DEFAULT expression (raw SQL, e.g. 'now()' or "'active'") */
+    default?: string;
+    /**
+     * REFERENCES target. Either the "table.column" string form or an object with
+     * referential actions ({@link ReferenceDef}).
+     */
+    references?: string | ReferenceDef;
+    /** Max length for varchar columns */
+    maxLength?: number;
+    /** Enum type name — required when `type: 'enum'`. */
+    enumName?: string;
+    /** pgvector dimension count — required when `type: 'vector'`. */
+    dimensions?: number;
+    /** When true, the column is an array of `type` (e.g. `text[]`). */
+    array?: boolean;
+    /** Column-level `CHECK` expression (raw SQL, e.g. `price >= 0`). */
+    check?: string;
+    /**
+     * Marks this column as personally identifiable information (PII). Purely a
+     * code-first declaration: it carries onto {@link ColumnConfig.pii} and, via
+     * `schemaDefToMetadata` / codegen, onto
+     * {@link import('./schema.js').ColumnMetadata.pii}. A PII column is excluded
+     * from default projections (read back only via an explicit `select` or
+     * `includePii: true`) and redacted by Studio. Introspection never auto-tags PII.
+     */
+    pii?: boolean;
+}
+/** Postgres-level column type (uppercase, as used in DDL) */
+export type ColumnType = 'SERIAL' | 'BIGSERIAL' | 'BIGINT' | 'INTEGER' | 'SMALLINT' | 'TEXT' | 'BOOLEAN' | 'TIMESTAMPTZ' | 'JSONB' | 'UUID' | 'REAL' | 'DOUBLE PRECISION' | 'NUMERIC' | 'BYTEA' | 'DATE' | 'VARCHAR' | 'ENUM' | 'VECTOR';
+export interface ColumnConfig {
+    type: ColumnType;
+    isPrimaryKey: boolean;
+    isNotNull: boolean;
+    isNullable: boolean;
+    isUnique: boolean;
+    defaultValue: string | null;
+    referencesTarget: string | null;
+    maxLength: number | null;
+    /** FK `ON DELETE` action, or null for the Postgres default. */
+    onDelete: ReferentialAction | null;
+    /** FK `ON UPDATE` action, or null for the Postgres default. */
+    onUpdate: ReferentialAction | null;
+    /** Enum type name when `type === 'ENUM'`, else null. */
+    enumName: string | null;
+    /** pgvector dimensions when `type === 'VECTOR'`, else null. */
+    vectorDimensions: number | null;
+    /** Whether the column is an array of its base type. */
+    isArray: boolean;
+    /** Column-level `CHECK` expression, or null. */
+    check: string | null;
+    /** Whether this column is tagged as PII (personally identifiable information). */
+    pii: boolean;
+}
+/**
+ * Explicit many-to-many relation declaration for the code-first schema.
+ *
+ * Auto-detecting m2m from a junction table is intentionally conservative (a
+ * junction with payload columns is treated as a first-class entity, not a join
+ * table — see `introspect.ts`). This declaration lets users opt in to an m2m
+ * relation explicitly, mirroring how Prisma/Drizzle require an explicit
+ * `@relation` / `relation()` for join tables.
+ *
+ * All names are the JS-facing accessor / camelCase field names you wrote in
+ * `defineSchema({ ... })`; they are normalized to snake_case when merged into
+ * the introspected {@link SchemaMetadata} via {@link applyManyToManyRelations}.
+ */
+export interface ManyToManyDef {
+    /** Relation field name on the source table (e.g. `tags`). */
+    name: string;
+    /** Target table accessor (e.g. `tags`). */
+    target: string;
+    /** Junction (join) table accessor (e.g. `postsTags`). */
+    through: string;
+    /** Junction column(s) referencing the SOURCE table's PK. */
+    sourceKey: string | readonly string[];
+    /** Junction column(s) referencing the TARGET table's PK. */
+    targetKey: string | readonly string[];
+    /**
+     * Optional: the SOURCE table's referenced column(s) that `sourceKey` points
+     * at. Defaults to `id`. Use for sources keyed on a non-`id` / composite PK.
+     */
+    references?: string | readonly string[];
+}
+/** A table-level named (or unnamed) `CHECK` constraint. */
+export interface CheckDef {
+    /** Optional constraint name → `CONSTRAINT "name" CHECK (...)`. */
+    name?: string;
+    /** Raw SQL boolean expression, e.g. `price > cost`. */
+    expression: string;
+}
+/** A plain (column-list) index declaration. */
+export interface ColumnIndexDef {
+    /** camelCase field name(s) the index covers. */
+    columns: string[];
+    /** Whether the index enforces uniqueness. */
+    unique?: boolean;
+    /** Optional explicit index name (auto-derived when omitted). */
+    name?: string;
+}
+/**
+ * A doc-field expression index on a JSON document column (PowDB ≥ 0.13).
+ * Indexes the value at `docField-><path>` inside the json document, so a
+ * `JsonFilter`/`orderBy` on that path can use an index instead of a scan.
+ */
+export interface DocFieldIndexDef {
+    /** camelCase field name of the json document column. */
+    docField: string;
+    /** JSON path into the document: string keys and integer array indexes. */
+    path: (string | number)[];
+    /** Whether the expression index enforces uniqueness. */
+    unique?: boolean;
+    /** Optional explicit index name (auto-derived when omitted). */
+    name?: string;
+}
+/**
+ * A single index declaration on a table: either a plain column-list index
+ * ({@link ColumnIndexDef}) or a doc-field expression index into a json column
+ * ({@link DocFieldIndexDef}).
+ *
+ * Consumed by the PowDB DDL generator (`powqlSchemaDDL`), carried onto
+ * {@link import('./schema.js').IndexMetadata} by `schemaDefToMetadata`, and
+ * since 0.36 emitted as `CREATE [UNIQUE] INDEX` by the SQL DDL generators:
+ * `schemaToSQL` emits plain column-list indexes, and `schemaDiff` adds ones
+ * missing from the live database (matching by name; it warns on definition
+ * mismatches and never drops). Doc-field indexes stay PowDB-only.
+ */
+export type SchemaIndexDef = ColumnIndexDef | DocFieldIndexDef;
+/** Type guard: is this index declaration a doc-field expression index? */
+export declare function isDocFieldIndexDef(idx: SchemaIndexDef): idx is DocFieldIndexDef;
+export interface TableDef {
+    /**
+     * DDL-facing table name (snake_case). This is the name used when generating
+     * `CREATE TABLE` and other DDL statements. Set automatically during
+     * `defineSchema()` by converting the JS-facing accessor key from camelCase
+     * to snake_case (e.g. `postTags` → `post_tags`).
+     */
+    name: string;
+    /**
+     * JS-facing accessor name (camelCase). This is the original key the user
+     * supplied to `defineSchema({ ... })` and is used as the property name on
+     * the generated `TurbineClient` (e.g. `db.postTags`). For schemas that
+     * already use snake_case keys, this matches `name`.
+     */
+    accessor: string;
+    /** Column definitions keyed by camelCase field name */
+    columns: Record<string, ColumnConfig>;
+    /**
+     * Optional composite primary key. When present, takes precedence over any
+     * column-level `primaryKey: true` flags. Column names listed here are the
+     * camelCase JS-facing field names — they will be converted to snake_case
+     * when emitted as a `PRIMARY KEY (...)` table constraint.
+     */
+    primaryKey?: readonly string[];
+    /**
+     * Explicit many-to-many relations declared on this table. These never affect
+     * DDL emission (junction tables are still ordinary `CREATE TABLE`s); they are
+     * consumed by {@link applyManyToManyRelations} to enrich an introspected
+     * {@link SchemaMetadata} with `manyToMany` {@link RelationDef}s.
+     */
+    manyToMany?: readonly ManyToManyDef[];
+    /** Table-level `CHECK` constraints. */
+    checks?: readonly CheckDef[];
+    /**
+     * Index declarations for this table (plain column indexes and/or PowDB
+     * doc-field expression indexes). Consumed by the PowDB DDL generator
+     * (`powqlSchemaDDL`) and carried onto `IndexMetadata` by
+     * `schemaDefToMetadata`; the SQL DDL generators do not consume them yet.
+     */
+    indexes?: readonly SchemaIndexDef[];
+}
+/**
+ * User-facing input shape for a single table when using the object format.
+ * The optional `primaryKey` field declares a composite primary key.
+ */
+export interface TableInput {
+    /** Optional composite primary key (camelCase field names) */
+    primaryKey?: readonly string[];
+    /** Optional explicit many-to-many relations on this table */
+    manyToMany?: readonly ManyToManyDef[];
+    /** Optional table-level CHECK constraints */
+    checks?: readonly CheckDef[];
+    /** Optional index declarations (plain column and/or doc-field expression) */
+    indexes?: readonly SchemaIndexDef[];
+    /** Column definitions keyed by camelCase field name */
+    [columnName: string]: ColumnDef | readonly string[] | readonly ManyToManyDef[] | readonly CheckDef[] | readonly SchemaIndexDef[] | undefined;
+}
+export interface SchemaDef {
+    /**
+     * All tables keyed by their JS-facing accessor name (camelCase, exactly as
+     * the user wrote them in `defineSchema({ ... })`). The DDL-facing snake_case
+     * name is available as `tables[key].name`.
+     */
+    tables: Record<string, TableDef>;
+    /**
+     * Schema-level enum declarations (`CREATE TYPE "<name>" AS ENUM (...)`),
+     * keyed by DDL enum type name → ordered labels. Consumed by `schema-sql.ts`
+     * to emit `CREATE TYPE` before the tables that reference them and by
+     * `generate.ts` for string-literal union codegen. Omitted when no enums are
+     * declared (back-compat with `{ tables }`-only consumers).
+     */
+    enums?: Record<string, readonly string[]>;
+}
+/** Options accepted by {@link defineSchema}. */
+export interface DefineSchemaOptions {
+    /**
+     * Schema-level enum declarations, keyed by DDL enum type name → ordered
+     * labels. Columns opt in via `{ type: 'enum', enumName: '<name>' }`.
+     */
+    enums?: Record<string, readonly string[]>;
+}
+/** Input format: table name -> column defs (object format) or TableDef (legacy builder) */
+type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef | TableInput>;
+/**
+ * Define the full database schema using plain objects.
+ *
+ * @example
+ * ```ts
+ * export default defineSchema({
+ *   users: {
+ *     id:    { type: 'serial', primaryKey: true },
+ *     email: { type: 'text', unique: true, notNull: true },
+ *     name:  { type: 'text', notNull: true },
+ *   },
+ *   posts: {
+ *     id:     { type: 'serial', primaryKey: true },
+ *     userId: { type: 'bigint', notNull: true, references: 'users.id' },
+ *     title:  { type: 'text', notNull: true },
+ *   },
+ * });
+ * ```
+ */
+export declare function defineSchema(input: SchemaInput, options?: DefineSchemaOptions): SchemaDef;
+export declare class ColumnBuilder {
+    private _config;
+    constructor();
+    serial(): this;
+    bigserial(): this;
+    bigint(): this;
+    integer(): this;
+    smallint(): this;
+    text(): this;
+    varchar(length: number): this;
+    boolean(): this;
+    timestamp(): this;
+    timestamptz(): this;
+    date(): this;
+    json(): this;
+    jsonb(): this;
+    uuid(): this;
+    real(): this;
+    doublePrecision(): this;
+    numeric(): this;
+    bytea(): this;
+    primaryKey(): this;
+    notNull(): this;
+    nullable(): this;
+    unique(): this;
+    default(val: string): this;
+    references(target: string, opts?: {
+        onDelete?: ReferentialAction;
+        onUpdate?: ReferentialAction;
+    }): this;
+    check(expression: string): this;
+    pii(): this;
+    array(): this;
+    build(): ColumnConfig;
+}
+/** @deprecated Use defineSchema() with plain objects instead */
+type ColumnProxy = {
+    [K in 'serial' | 'bigserial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'boolean' | 'timestamp' | 'timestamptz' | 'date' | 'json' | 'jsonb' | 'uuid' | 'real' | 'doublePrecision' | 'numeric' | 'bytea']: () => ColumnBuilder;
+} & {
+    varchar: (length: number) => ColumnBuilder;
+};
+/** @deprecated Use defineSchema() with plain objects instead */
+export declare const column: ColumnProxy;
+/** @deprecated Use defineSchema() with plain objects instead */
+export declare function table(columns: Record<string, ColumnBuilder>): TableDef;
+/**
+ * Merge the explicit `manyToMany` declarations from a code-first {@link SchemaDef}
+ * into an introspected {@link SchemaMetadata}, returning a new metadata object
+ * with the `manyToMany` {@link RelationDef}s added.
+ *
+ * This is the runtime bridge for the code-first m2m API: `defineSchema` only
+ * produces DDL, so after `introspect()`ing the live database you call this to
+ * attach the m2m relations you declared. It is PURELY ADDITIVE — existing
+ * belongsTo/hasMany/hasOne relations are preserved, and a declared relation is
+ * skipped (not overwritten) if its name already exists on the source table.
+ *
+ * @example
+ * ```ts
+ * const def = defineSchema({
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            manyToMany: [{ name: 'tags', target: 'tags', through: 'postsTags',
+ *                           sourceKey: 'postId', targetKey: 'tagId' }] },
+ *   tags:  { id: { type: 'serial', primaryKey: true } },
+ *   postsTags: { postId: { type: 'integer', references: 'posts.id' },
+ *                tagId:  { type: 'integer', references: 'tags.id' },
+ *                primaryKey: ['postId', 'tagId'] },
+ * });
+ * let meta = await introspect({ connectionString });
+ * meta = applyManyToManyRelations(meta, def);
+ * ```
+ */
+export declare function applyManyToManyRelations(meta: SchemaMetadata, def: SchemaDef): SchemaMetadata;
+export { camelToSnake } from './schema.js';

package/dist/cjs/schema-metadata.d.ts

@@ -0,0 +1,83 @@
+/**
+ * turbine-orm — defineSchema() → SchemaMetadata bridge
+ *
+ * Converts a code-first {@link SchemaDef} (the output of `defineSchema()`)
+ * into the runtime {@link SchemaMetadata} shape that the query builder,
+ * `TurbineClient`, and the non-SQL engines consume — without touching a
+ * live database.
+ *
+ * Why this exists: the historical converter path (`introspect()` +
+ * `generate()`) requires a running SQL database, but code-first engines
+ * (PowDB, in-memory SQLite bootstraps, tests) only have the `SchemaDef`.
+ * `schemaDefToMetadata()` is the pure-function equivalent: its output
+ * matches what `turbine generate` would emit into `metadata.ts` for the
+ * same schema, minus the pieces only a live catalog can know (real index
+ * names, constraint names, view flags).
+ *
+ * Parity notes (ground truth = introspect.ts + generate.ts):
+ *   - Relations are derived from `references:` exactly like introspection
+ *     derives them from foreign keys: a `belongsTo` on the child table and
+ *     a `hasMany` on the parent, with the same disambiguation rules when
+ *     multiple FKs point at the same target.
+ *   - Pure junction tables (2-column composite PK that IS the two
+ *     single-column FKs to two distinct tables, no payload columns) get
+ *     the same conservative auto-`manyToMany` treatment as introspection.
+ *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
+ *     {@link applyManyToManyRelations} (additive, never clobbering).
+ *   - `indexes` carries any declared `TableDef.indexes` (plain column and/or
+ *     PowDB doc-field expression indexes); a table with none declared gets
+ *     `[]`, which keeps `schemaHasIndexInfo()` false so the index advisor and
+ *     the dev-mode missing-index warning stay silent instead of producing
+ *     blanket false positives. Doc-field (docPath) indexes are ignored by the
+ *     advisor, so a doc-only index set never flips `schemaHasIndexInfo()`.
+ *
+ * @example
+ * ```ts
+ * import { defineSchema, schemaDefToMetadata } from 'turbine-orm';
+ *
+ * const def = defineSchema({
+ *   users: { id: { type: 'serial', primaryKey: true }, name: { type: 'text', notNull: true } },
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            userId: { type: 'integer', notNull: true, references: 'users.id' } },
+ * });
+ * const metadata = schemaDefToMetadata(def);
+ * // → usable anywhere SchemaMetadata is expected (e.g. turbinePowDB, TurbineClient)
+ * ```
+ */
+import { type SchemaMetadata } from './schema.js';
+import { type SchemaDef } from './schema-builder.js';
+/**
+ * Convert a code-first {@link SchemaDef} into runtime {@link SchemaMetadata}.
+ *
+ * Pure function — no database connection, no side effects, input untouched.
+ * The output is shaped identically to the `SCHEMA` constant `turbine generate`
+ * emits from introspection, so it can be handed to any consumer that expects
+ * introspected metadata: `new TurbineClient(config, metadata)`,
+ * `turbinePowDB(..., metadata)`, `QueryInterface`, the index advisor, etc.
+ *
+ * What maps:
+ *   - Columns → full {@link ColumnMetadata} (snake_case name, camelCase field,
+ *     pg type names, TS types, nullability, defaults, `isGenerated` for
+ *     serial/bigserial, array + varchar length info, date-column tracking).
+ *   - Column-level `primaryKey` and table-level composite `primaryKey`.
+ *   - `unique: true` columns → single-column `uniqueColumns` entries.
+ *   - `references:` FKs → `belongsTo` (child) + `hasMany` (parent) relations,
+ *     including `onDelete`/`onUpdate` actions (the `'no action'` default is
+ *     omitted, matching introspection).
+ *   - Pure junction tables → auto-detected `manyToMany` relations (same
+ *     conservative rules as introspection).
+ *   - Explicit `manyToMany` declarations → merged additively.
+ *   - Schema-level `enums`.
+ *
+ * What maps (continued):
+ *   - `indexes` → declared `TableDef.indexes` become `IndexMetadata` (plain
+ *     column indexes and PowDB doc-field expression indexes, the latter
+ *     carrying `docPath`). A table with no declared indexes gets `[]`, keeping
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no false
+ *     positives on index-less code-first metadata.
+ *
+ * What SchemaDef cannot express (and how it degrades):
+ *   - Views → never marked (`isView` is introspection-only).
+ *   - Composite foreign keys → `references:` is single-column by design.
+ */
+export declare function schemaDefToMetadata(def: SchemaDef): SchemaMetadata;

package/dist/cjs/schema-sql.d.ts

@@ -0,0 +1,217 @@
+/**
+ * turbine-orm — Schema SQL Generator
+ *
+ * Converts a SchemaDef (from defineSchema) into executable DDL statements.
+ * Also provides diff and push commands for syncing schema to a live database.
+ */
+import { type DestructiveStatement } from './cli/destructive.js';
+import { type Dialect } from './dialect.js';
+import { ValidationError } from './errors.js';
+import { type ReferentialAction } from './schema.js';
+import { type ColumnIndexDef, type SchemaDef, type TableDef } from './schema-builder.js';
+export interface SchemaSqlOptions {
+    /** SQL dialect used for DDL generation. Defaults to PostgreSQL. */
+    dialect?: Dialect;
+    /**
+     * How to handle the pgvector extension when the schema contains a `vector`
+     * column. `'auto'` (default) prepends `CREATE EXTENSION IF NOT EXISTS vector;`
+     * — appropriate for `push`. `'manual'` emits a leading comment only, so the
+     * generated `.sql` migration doesn't silently require superuser privileges.
+     */
+    extensions?: 'auto' | 'manual';
+}
+/** Map a {@link ReferentialAction} to its SQL keyword form. */
+export declare function referentialActionToSql(action: ReferentialAction): string;
+/**
+ * Convert a SchemaDef into an ordered array of SQL DDL statements.
+ *
+ * Returns CREATE TABLE statements (in dependency order based on references)
+ * followed by CREATE INDEX statements for foreign key columns.
+ */
+export declare function schemaToSQL(schema: SchemaDef, options?: SchemaSqlOptions): string[];
+/**
+ * Compare a declared plain index against a pg_indexes `indexdef` string.
+ * Returns a human-readable description of the first mismatch (uniqueness or
+ * column list), or null when the definitions agree. Expression/partial indexes
+ * in the DB never structurally match a plain column list, which is the
+ * intended outcome: the operator gets a warning rather than a silent skip.
+ */
+export declare function describeIndexDefMismatch(idx: ColumnIndexDef, indexdef: string): string | null;
+/**
+ * Pure decision for the "index exists in the DB but is not declared" warning
+ * pass. Extracted so the scope rule is unit-testable without a live database.
+ *
+ * The pass runs only when the table opts into index management by DEFINING an
+ * `indexes` array (`indexesDefined: true`), even when that array is empty or
+ * all-doc-field: deleting the last declared index must NOT silence the pass.
+ * Tables with no `indexes` key stay silent (the user is not managing indexes
+ * there). Recognized names (declared, unique-constraint / FK-column, `*_pkey`)
+ * are never flagged; everything else in the DB yields one warning.
+ */
+export declare function undeclaredIndexWarnings(opts: {
+    tableName: string;
+    indexesDefined: boolean;
+    dbIndexNames: Iterable<string>;
+    declaredNames: ReadonlySet<string>;
+    recognizedNames: ReadonlySet<string>;
+}): string[];
+export interface AlterColumnDef {
+    /** Column name in snake_case */
+    column: string;
+    /** What changed */
+    action: 'add' | 'drop' | 'alter_type' | 'set_not_null' | 'drop_not_null' | 'set_default' | 'drop_default' | 'add_unique' | 'drop_unique';
+    /** SQL fragment for the alteration */
+    sql: string;
+    /** SQL to reverse this change (for DOWN migrations) */
+    reverseSql: string;
+}
+export interface AlterDef {
+    /** Table name */
+    table: string;
+    /** Column-level alterations */
+    columns: AlterColumnDef[];
+}
+export interface DiffResult {
+    /** Tables that exist in schema but not in DB — need CREATE TABLE */
+    create: TableDef[];
+    /** Tables that exist in both but differ — need ALTER TABLE */
+    alter: AlterDef[];
+    /** Table names that exist in DB but not in schema — would need DROP TABLE */
+    drop: string[];
+    /** SQL statements to execute the diff (UP direction) */
+    statements: string[];
+    /** SQL statements to reverse the diff (DOWN direction, for migrations) */
+    reverseStatements: string[];
+    /**
+     * Human-readable warnings for changes the diff detected but refuses to apply
+     * automatically because they are destructive or otherwise unsafe (enum value
+     * removal/reorder, etc.). Never executed — surfaced for the operator.
+     */
+    warnings?: string[];
+}
+/** A FK's current referential actions as read from the DB. */
+export interface DbForeignKey {
+    constraintName: string;
+    column: string;
+    targetTable: string;
+    targetColumn: string;
+    onDelete: ReferentialAction;
+    onUpdate: ReferentialAction;
+}
+/**
+ * Build the `ADD CONSTRAINT ... FOREIGN KEY` statement for a FK with the given
+ * referential actions. Default (`no action`) clauses are omitted, matching how
+ * Postgres normalizes them, so re-diffing is stable.
+ */
+export declare function buildAddForeignKeyStatement(table: string, constraintName: string, column: string, targetTable: string, targetColumn: string, onDelete: ReferentialAction, onUpdate: ReferentialAction, dialect?: Dialect): string;
+/**
+ * Decide whether a FK's referential actions changed. When they differ, returns
+ * the DROP + ADD CONSTRAINT statements (and their reverse) — Postgres has no
+ * `ALTER CONSTRAINT` for referential actions, so drop-and-recreate is the only
+ * path. Returns null when the actions already match.
+ */
+export declare function diffReferentialAction(table: string, db: DbForeignKey, schemaOnDelete: ReferentialAction, schemaOnUpdate: ReferentialAction, dialect?: Dialect): {
+    statements: string[];
+    reverseStatements: string[];
+} | null;
+/**
+ * Compute append-only enum value changes. Returns `ALTER TYPE ... ADD VALUE`
+ * statements for labels present in the schema but not the DB (in order), plus a
+ * destructive warning for any DB label the schema dropped or any reorder —
+ * Postgres cannot remove or reorder enum values without recreating the type.
+ */
+export declare function diffEnumValues(enumName: string, schemaLabels: readonly string[], dbLabels: readonly string[], dialect?: Dialect): {
+    statements: string[];
+    warnings: string[];
+};
+/** A check constraint as declared or read from the DB. */
+export interface CheckSpec {
+    /** Constraint name. Always emitted through `dialect.quoteIdentifier`. */
+    name: string;
+    /**
+     * RAW SQL boolean expression (e.g. `price >= 0`), emitted VERBATIM into the
+     * `CHECK (...)` clause.
+     *
+     * This is a deliberate escape hatch: a CHECK body is an arbitrary SQL
+     * expression, so it cannot be quoted, parameterized, or validated by the DDL
+     * builder without reimplementing the server's expression parser. The contract
+     * is therefore on the caller: the expression MUST come from the project's own
+     * schema definition (a `defineSchema` literal or an introspected constraint),
+     * and must NEVER be built from user input, request data, or any other
+     * untrusted source. Anything interpolated into it runs with the privileges of
+     * the migration.
+     */
+    expression: string;
+}
+/**
+ * Diff a table's CHECK constraints (matched by name). Adds constraints missing
+ * from the DB, drops DB constraints absent from the schema, and drop+adds when a
+ * same-named constraint's expression changed. Expression comparison is a naive
+ * whitespace-insensitive match — semantically-equal-but-different-spelled
+ * expressions may re-emit (documented; harmless drop+add).
+ */
+export declare function diffCheckConstraints(table: string, schemaChecks: readonly CheckSpec[], dbChecks: readonly CheckSpec[], dialect?: Dialect): {
+    statements: string[];
+    reverseStatements: string[];
+};
+/**
+ * Compare a SchemaDef against a live Postgres database and return the diff.
+ *
+ * Connects to the database, inspects the public schema, and computes what
+ * DDL is needed to make the database match the schema definition.
+ */
+export declare function schemaDiff(schema: SchemaDef, connectionString: string): Promise<DiffResult>;
+/**
+ * Scan a set of diff statements for data-destroying operations, using the same
+ * conservative scanner (`scanDestructiveSql`) that gates `migrate up`/`down`.
+ * Push mostly emits additive DDL, but a type change surfaces as a lossy
+ * `ALTER COLUMN ... TYPE` cast, exactly the kind of silent data loss `push`
+ * must never apply without an explicit opt-in.
+ */
+export declare function findDestructivePushStatements(statements: readonly string[]): DestructiveStatement[];
+export interface PushResult {
+    /** Number of statements executed */
+    statementsExecuted: number;
+    /** The SQL statements that were run */
+    statements: string[];
+    /** Tables created */
+    tablesCreated: string[];
+    /** Tables altered */
+    tablesAltered: string[];
+}
+/**
+ * Thrown by {@link schemaPush} when the diff contains data-destroying statements
+ * and `allowDestructive` was not set. A typed subclass of {@link ValidationError}
+ * (same `TURBINE_E003` code, no new taxonomy entry) so callers can branch on
+ * `instanceof DestructivePushRefusal` instead of sniffing the message text. The
+ * offending statements are carried on `.destructive` for programmatic display.
+ */
+export declare class DestructivePushRefusal extends ValidationError {
+    /** The destructive statements the push refused to apply. */
+    readonly destructive: DestructiveStatement[];
+    constructor(destructive: DestructiveStatement[]);
+}
+/**
+ * Push a schema definition to a live database.
+ *
+ * Computes the diff, then executes the resulting DDL statements in a
+ * single transaction. It will NOT drop tables or columns.
+ *
+ * Data-loss gate: if the diff contains a destructive statement (e.g. a lossy
+ * `ALTER COLUMN ... TYPE` cast), `schemaPush` throws a
+ * {@link DestructivePushRefusal} (a {@link ValidationError} subclass carrying
+ * the offending statements on `.destructive`) listing the statements UNLESS
+ * `allowDestructive: true` is passed. The CLI (`turbine push`) catches this and
+ * prompts for the same typed confirmation as `migrate up`; programmatic callers
+ * must opt in explicitly.
+ */
+export declare function schemaPush(schema: SchemaDef, connectionString: string, options?: {
+    dryRun?: boolean;
+    allowDestructive?: boolean;
+    precomputedDiff?: DiffResult;
+}): Promise<PushResult>;
+/**
+ * Generate the full DDL as a single formatted string.
+ * Useful for printing or saving to a .sql file.
+ */
+export declare function schemaToSQLString(schema: SchemaDef, options?: SchemaSqlOptions): string;