turbine-orm 0.81.0 → 0.90.0

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

@@ -106,6 +106,42 @@ export interface DiffResult {
      * removal/reorder, etc.). Never executed, surfaced for the operator.
      */
     warnings?: string[];
+    /**
+     * The members of `warnings` the diff cannot decide are real. Postgres rewrites
+     * a CHECK expression when it stores it, so a named check whose text differs
+     * from the schema's is usually the same constraint. They are printed like any
+     * other warning, but {@link driftWarnings} leaves them out, so a gate does not
+     * fail forever on a database that was just pushed.
+     */
+    inexactWarnings?: string[];
+    /**
+     * Type changes in `statements` that can never lose a value (see
+     * {@link isLosslessWidening}). The destructive gate skips exactly these
+     * statements; every other `ALTER COLUMN ... TYPE` is still flagged.
+     */
+    widenings?: TypeWidening[];
+    /**
+     * Parts of the database this diff did NOT compare, as sentences. "Already in
+     * sync" is only a claim about what was compared, so a caller that says it
+     * lists these beside it.
+     */
+    notCompared?: string[];
+}
+/**
+ * The warnings in a diff that report a real difference between the database and
+ * the schema file: everything in `warnings` except the entries the diff marked
+ * as possibly cosmetic ({@link DiffResult.inexactWarnings}). `push --dry-run
+ * --exit-code` fails on these.
+ */
+export declare function driftWarnings(diff: Pick<DiffResult, 'warnings' | 'inexactWarnings'>): string[];
+/** One lossless `ALTER COLUMN ... TYPE` in a {@link DiffResult}. */
+export interface TypeWidening {
+    /** The exact statement, as it appears in `DiffResult.statements`. */
+    statement: string;
+    /** The column's current type, as SQL. */
+    from: string;
+    /** The type the statement changes it to, as SQL. */
+    to: string;
 }
 /** A FK's current referential actions as read from the DB. */
 export interface DbForeignKey {
@@ -133,10 +169,18 @@ export declare function diffReferentialAction(table: string, db: DbForeignKey, s
     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.
+ * Compute the enum changes needed to make the database's labels match the
+ * schema's, KEEPING THE DECLARED ORDER.
+ *
+ * An enum's order is observable: it decides `ORDER BY`, `<` and `MIN`/`MAX` on
+ * the column. A new label therefore goes where the schema declares it, not
+ * wherever the end of the type happens to be: `ADD VALUE 'x' AFTER 'prev'`, or
+ * `BEFORE 'next'` when it leads. A label that belongs at the end emits the bare
+ * `ADD VALUE`, which is what every earlier version emitted for it.
+ *
+ * Postgres cannot remove or reorder values in place, so a database label the
+ * schema dropped, and a declared order the database does not already have, are
+ * warnings (never statements): the type has to be recreated by hand.
  */
 export declare function diffEnumValues(enumName: string, schemaLabels: readonly string[], dbLabels: readonly string[], dialect?: Dialect): {
     statements: string[];
@@ -195,6 +239,11 @@ export interface SchemaDiffOptions {
  * computes what DDL is needed to make the database match the schema definition.
  */
 export declare function schemaDiff(schema: SchemaDef, connectionString: string, options?: SchemaDiffOptions): Promise<DiffResult>;
+/**
+ * What {@link schemaDiff} never looks at, whatever the database holds. Kept
+ * beside the diff so the sentence cannot outlive the code it describes.
+ */
+export declare const NEVER_COMPARED: string;
 /** The type-relevant subset of {@link DbColumn}, so {@link planTypeChange} stays testable. */
 export interface DbColumnType {
     udtName: string;
@@ -258,6 +307,27 @@ export type TypeChangePlan = {
  * constraint the schema never had the vocabulary to ask for.
  */
 export declare function planTypeChange(config: ColumnConfig, dbCol: DbColumnType, column: string): TypeChangePlan;
+/**
+ * True when changing a column from `from` to `to` can never lose, round,
+ * truncate or reject a value: every value of the old type is representable
+ * unchanged in the new one. The vocabulary is deliberately small, and anything
+ * outside it answers false (the destructive gate then treats the statement as
+ * it always has):
+ *
+ *   - `varchar(n)` to `varchar(m)` with m >= n, to bare `varchar`, to `text`
+ *   - `smallint` to `integer` to `bigint`
+ *   - any integer type to `numeric`, or to `numeric(p, s)` when it still holds
+ *     the integer's digits
+ *   - `numeric(p, s)` to a numeric with at least as many integer digits and at
+ *     least as many decimal places (a bare `numeric` has no bound)
+ *   - arrays of the above, element by element
+ *
+ * Not a widening, on purpose: `text` to `varchar(n)`, anything to a smaller
+ * type, `timestamp` to `timestamptz` (re-reads the value in the session zone),
+ * `real` to `double precision` (the stored digits change when printed), and
+ * `json` to `jsonb` (drops duplicate keys).
+ */
+export declare function isLosslessWidening(from: string, to: string): boolean;
 /**
  * Scan a set of diff statements for data-destroying operations, using the same
  * conservative scanner (`scanDestructiveSql`) that gates `migrate up`/`down`.
@@ -265,7 +335,7 @@ export declare function planTypeChange(config: ColumnConfig, dbCol: DbColumnType
  * `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 declare function findDestructivePushStatements(statements: readonly string[], widenings?: readonly TypeWidening[]): DestructiveStatement[];
 export interface PushResult {
     /** Number of statements executed */
     statementsExecuted: number;