@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/schema/schema-differ.d.ts

@@ -1,5 +1,6 @@
 import type { SchemaCatalog } from './catalog.js';
 import type * as AST from '../parser/ast.js';
+import type { SqlValue } from '../common/types.js';
 export type RenamePolicy = 'allow' | 'require-hint' | 'deny';
 export type RenameKind = 'table' | 'view' | 'index' | 'constraint';
 export interface RenameOp {
@@ -18,14 +19,58 @@ export interface SchemaDiff {
     tablesToCreate: string[];
     tablesToDrop: string[];
     tablesToAlter: TableAlterDiff[];
+    /**
+     * Maintained tables whose declared backing module drifted from the live backing
+     * — a destructive, incarnation-minting migration realized as drop+recreate (the
+     * DROP rides {@link tablesToDrop} under the actual name; the recreate, which
+     * re-materializes the body into the new module, rides {@link tablesToCreate}).
+     * Recorded separately for the apply-time `allow_destructive` gate and for
+     * diagnostics: `diff schema` surfaces the DDL unconditionally (read-only
+     * preview), while `apply schema` refuses unless acknowledged. Distinct from a
+     * non-destructive body re-attach (`set maintained as`), which preserves the
+     * incarnation. See `docs/materialized-views.md` § Declarative-schema integration.
+     */
+    maintainedModuleMigrations: Array<{
+        name: string;
+        fromModule: string;
+        toModule: string;
+    }>;
     viewsToCreate: string[];
     viewsToDrop: string[];
     indexesToCreate: string[];
     indexesToDrop: string[];
     assertionsToCreate: string[];
     assertionsToDrop: string[];
+    /**
+     * In-place metadata-tag changes on name-matched views / indexes (whole-set
+     * replacement; `tags: {}` clears). These take the new `ALTER … SET TAGS`
+     * primitive rather than a drop+recreate. A maintained table is a TABLE now, so
+     * its tag-only change rides `TableAlterDiff.tableTagsChange` (`ALTER TABLE …
+     * SET TAGS`) — there is no separate materialized-view tag bucket.
+     */
+    viewTagsChanges: Array<{
+        name: string;
+        tags: Record<string, SqlValue>;
+    }>;
+    indexTagsChanges: Array<{
+        name: string;
+        tags: Record<string, SqlValue>;
+    }>;
     /** Renames detected via `quereus.id` / `quereus.previous_name` hints. */
     renames: RenameOp[];
+    /**
+     * Logical-schema lens attaches: declared logical tables not yet registered
+     * as a lens body. Only populated for a logical declared schema. Carries no
+     * migration DDL — the lens compiler attaches at apply time, not via DDL.
+     */
+    lensToAttach: string[];
+    /**
+     * Logical-schema lens detaches: registered lens bodies absent from the
+     * declaration. A logical removal detaches the lens and **never** drops basis
+     * storage (see `docs/lens.md` § Deployment) — so this is emitted *instead of*
+     * a basis-table drop.
+     */
+    lensToDetach: string[];
 }
 export interface ColumnAttributeChange {
     columnName: string;
@@ -40,6 +85,19 @@ export interface ColumnAttributeChange {
      *   Expression = set to given expression
      */
     defaultValue?: AST.Expression | null;
+    /**
+     * Desired collation (canonical, e.g. `'NOCASE'`) when the declared column's
+     * COLLATE differs from actual. Omitted = no change. Absent and `'BINARY'` are
+     * treated as equal (no spurious diff). Emitted as `SET COLLATE <name>`.
+     */
+    collation?: string;
+    /**
+     * Desired metadata tag set (whole-set replacement) when the declared column
+     * tags differ from actual. Omitted = no change; `{}` = clear all tags. Rename
+     * hints (`quereus.id` / `quereus.previous_name`) are excluded from the drift
+     * comparison but kept verbatim in the emitted set.
+     */
+    tags?: Record<string, SqlValue>;
 }
 export interface TableAlterDiff {
     tableName: string;
@@ -48,8 +106,27 @@ export interface TableAlterDiff {
     columnsToAlter: ColumnAttributeChange[];
     /** Column renames discovered via `quereus.id` / `quereus.previous_name` on declared columns. */
     columnsToRename: ColumnRenameOp[];
-    /** Constraint renames discovered via tag hints (table-level named constraints only). */
+    /** Constraint renames discovered via tag hints (user-named CHECK / UNIQUE / FK). */
     constraintsToRename?: ColumnRenameOp[];
+    /**
+     * User-named constraints to remove via `DROP CONSTRAINT <name>`: those present
+     * in the actual catalog but absent from the declaration (and not consumed by a
+     * rename), PLUS the old side of a **body change** — a name-matched constraint
+     * whose canonical body drifted is realized as drop-old + add-new (it pairs with
+     * an entry in {@link constraintsToAdd}).
+     */
+    constraintsToDrop?: string[];
+    /**
+     * Declared user-named constraints to install via `ALTER TABLE … ADD
+     * <constraint-fragment>`: those absent from the actual catalog (and not a rename
+     * target), PLUS the new side of a **body change** (paired with a
+     * {@link constraintsToDrop} entry under the old name). Each entry is the full
+     * constraint DDL fragment (`constraint <name> check (...)` with any tags) the
+     * `ADD` primitive consumes. ADD applies a CHECK in place; a UNIQUE / FOREIGN
+     * KEY add routes through the module's `addConstraint`, re-validating existing
+     * rows (so a body-change recreate re-validates against the new rule).
+     */
+    constraintsToAdd?: string[];
     primaryKeyChange?: {
         oldPkColumns: string[];
         newPkColumns: Array<{
@@ -57,11 +134,90 @@ export interface TableAlterDiff {
             direction?: 'asc' | 'desc';
         }>;
     };
+    /**
+     * Desired table-level metadata tag set (whole-set replacement) when the declared
+     * table tags differ from actual. Omitted = no change; `{}` = clear all tags.
+     */
+    tableTagsChange?: Record<string, SqlValue>;
+    /**
+     * Per named table-level constraint whose declared tags drifted from actual.
+     * Whole-set replacement; `tags: {}` clears. Name-matched constraints only.
+     */
+    constraintTagsChanges?: Array<{
+        constraintName: string;
+        tags: Record<string, SqlValue>;
+    }>;
+    /**
+     * Maintained-table (derivation) transition. Attach or re-attach a derivation:
+     * `alter table … set maintained [(cols)] as <body>` (any `with defaults (…)` rides
+     * inside the body). Emitted LATE (after table creates/alters), where the target's
+     * final shape and the body's sources must already exist. Set on: a fresh attach
+     * (declared maintained, live plain) and a re-attach (both maintained, body
+     * drift). On a same-shape re-attach this is the only op (content reconcile /
+     * refresh — no recreate).
+     *
+     * `columns` carries the DECLARED rename list verbatim: the names array for an
+     * explicit maintained form (`mv (a, c)` / `maintained (a, c) as`) — rendered as the
+     * `(cols)` form so the verb positionally renames the body and reshapes the backing
+     * — or `undefined` for an implicit/sugar-without-list MV, where the verb stays
+     * implicit (the body's natural names follow). The differ never synthesizes or
+     * compares renames; it hands the verb the authored list and the verb does the
+     * reshape (and re-records `derivation.columns`).
+     */
+    setMaintained?: {
+        columns?: ReadonlyArray<string>;
+        select: AST.QueryExpr;
+    };
+    /**
+     * Detach a derivation: `alter table … drop maintained` (the table keeps its
+     * rows and becomes writable). Emitted EARLY (before table alters/drops) — a
+     * detach must precede column ops on the table and may precede a drop of its
+     * former source. Set on: a detach (declared plain, live maintained) and the
+     * reshape leg of a re-attach with a concurrent shape change (detach → column
+     * ops → {@link setMaintained}).
+     */
+    dropMaintained?: boolean;
+    /**
+     * When {@link tableTagsChange} is set on a table that is STILL maintained at the
+     * point the alter block's SET TAGS runs (live-maintained and NOT detached early
+     * in this same diff), the tag edit must go through `ALTER MATERIALIZED VIEW …
+     * SET TAGS` rather than `ALTER TABLE … SET TAGS`: the TABLE verb fires
+     * `table_modified`, not `materialized_view_modified`, so a store-backed catalog
+     * would never re-persist the maintained-table entry — and the runtime ALTER
+     * TABLE handler rejects a tag action on a maintained table outright. A detach
+     * (or re-attach reshape leg) runs its `drop maintained` EARLY, so by tag time
+     * the table is plain and the ordinary ALTER TABLE path applies (flag absent).
+     */
+    maintainedTags?: boolean;
+    /**
+     * Set when a name-matched maintained table's declared backing module drifted
+     * from the live backing (BOTH sides maintained). A backing-module move
+     * physically relocates the table to a different store and mints a new
+     * incarnation — there is no in-place move primitive — so it must take a
+     * destructive drop+recreate, NOT any of the alter ops above. This flag signals
+     * {@link computeSchemaDiff} to route the table to drop+recreate (and record a
+     * {@link SchemaDiff.maintainedModuleMigrations} entry) instead of pushing this
+     * alter diff; the recreate subsumes any concurrent body / tag / shape op also
+     * present on this diff. `fromModule` / `toModule` are the normalized backing
+     * labels (`name` or `name(args)`) for the diagnostic.
+     */
+    maintainedModuleMigration?: {
+        fromModule: string;
+        toModule: string;
+    };
 }
 /**
  * Computes the difference between declared schema and actual catalog
  */
-export declare function computeSchemaDiff(declaredSchema: AST.DeclareSchemaStmt, actualCatalog: SchemaCatalog, policy?: RenamePolicy): SchemaDiff;
+export declare function computeSchemaDiff(declaredSchema: AST.DeclareSchemaStmt, actualCatalog: SchemaCatalog, policy?: RenamePolicy, 
+/**
+ * Session `default_collation` used to resolve an omitted COLLATE on the *declared*
+ * side, matching how the CREATE path resolves it for a fresh `apply`. Defaults to
+ * `'BINARY'` so direct callers (and the existing test suite, which runs under the
+ * BINARY session default) keep byte-for-byte identical diffs. The emitters thread
+ * the live `default_collation` session option.
+ */
+defaultCollation?: string): SchemaDiff;
 /**
  * Serializes a schema diff to JSON string
  */

package/dist/src/schema/schema-differ.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-differ.d.ts","sourceRoot":"","sources":["../../../src/schema/schema-differ.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAA2C,MAAM,cAAc,CAAC;AAC3F,OAAO,KAAK,KAAK,GAAG,MAAM,kBAAkB,CAAC;AAgB7C,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,cAAc,GAAG,MAAM,CAAC;AAE7D,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,YAAY,CAAC;AAEnE,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,yEAAyE;IACzE,OAAO,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,qBAAqB,EAAE,CAAC;IACxC,gGAAgG;IAChG,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,wFAAwF;IACxF,mBAAmB,CAAC,EAAE,cAAc,EAAE,CAAC;IACvC,gBAAgB,CAAC,EAAE;QAClB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,YAAY,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;SAAE,CAAC,CAAC;KAClE,CAAC;CACF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAChC,cAAc,EAAE,GAAG,CAAC,iBAAiB,EACrC,aAAa,EAAE,aAAa,EAC5B,MAAM,GAAE,YAAsB,GAC5B,UAAU,CAoLZ;AAieD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAE5D;AAqCD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CA6FpF"}
+{"version":3,"file":"schema-differ.d.ts","sourceRoot":"","sources":["../../../src/schema/schema-differ.ts"],"names":[],"mappings":"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"}