@voltro/database 0.20.2 → 0.22.0

package/dist/sql.d.ts

@@ -550,6 +550,31 @@ export declare interface ColumnSnapshot {
         readonly from: ColumnType;
         readonly using?: string;
     };
+    /**
+     * Bounded text length from `text().maxLength(n)` — carried on BOTH sides.
+     *
+     * DECLARED: from the column definition. LIVE: from introspection, and ONLY when
+     * the dialect materialises a length. An unbounded text family member
+     * (`text`/`longtext`/`mediumtext`/`clob`) leaves this `undefined` rather than
+     * reporting the type's theoretical maximum — mysql answers 4294967295 for
+     * `longtext`, and comparing that against a declared `undefined` would re-emit an
+     * ALTER on every boot forever.
+     *
+     * WHY IT IS HERE AT ALL. It was absent from the snapshot entirely: the value
+     * lived on the column definition, was read only when rendering CREATE DDL, and
+     * never reached the comparison. So the differ was not comparing lengths wrongly
+     * — it could not see them. Adding `.maxLength(n)` to an EXISTING column planned
+     * zero operations and reported "schema is up to date" while the live column
+     * stayed `longtext`. A consumer hit that trying to apply the documented remedy
+     * for MariaDB's hash long-unique, and their contrast is what pinned it: a column
+     * bounded AT CREATION was `varchar(64)` (DDL path, fine), one bounded afterwards
+     * stayed `longtext` (diff path, blind).
+     *
+     * NOT compared on sqlite: it has no length-enforced type, so the declared value
+     * is real and the live side can never report one. Comparing them there would
+     * re-emit forever. See `sameColumnShape`.
+     */
+    readonly maxLength?: number;
     readonly references?: {
         readonly table: string;
         readonly column: string;
@@ -764,30 +789,31 @@ export declare const emitDropColumnDdlMysql: (op: Extract<MigrationOperation, {
 }>) => string;
 
 /**
- * Evolution-aware DDL emitter for framework-managed tables (the
- * `_voltro_*` bookkeeping set + the `voltro_isr_cache` runtime
- * cache). Adds one extra step between CREATE TABLE and CREATE INDEX:
+ * Bootstrap DDL for framework-managed tables — `CREATE TABLE IF NOT EXISTS`, and
+ * deliberately almost nothing else.
  *
- *   ALTER TABLE <t> ADD COLUMN IF NOT EXISTS <col> <type>
+ * It exists for ONE reason: `applyPlan` records into `_voltro_migration_plans`,
+ * so that table has to exist before the planner can run. Everything after
+ * that — columns, indexes, types, nullability — belongs to the planner, which
+ * handles framework tables exactly like user tables, on every dialect.
  *
- * for every column the framework's declared shape carries. Without
- * this the CREATE TABLE IF NOT EXISTS path is fine for fresh DBs but
- * silently no-ops on existing tables — subsequent CREATE INDEX IF
- * NOT EXISTS then PARSE-fails when an index references a column the
- * framework added in a later release that the live DB never picked
- * up (pg error 42703).
+ * IT USED TO DO MORE, AND THAT WAS THE BUG. It also emitted
+ * `ALTER TABLE … ADD COLUMN IF NOT EXISTS` and `CREATE INDEX IF NOT EXISTS`, and
+ * the ADD COLUMN half was POSTGRES-ONLY because that is the dialect with the
+ * syntax. Framework tables were filtered out of the boot planner at the time, so
+ * this was their only evolution path — which meant a framework release that added
+ * a column reached a postgres user's database on boot and a MariaDB user's never,
+ * silently. One `voltro dev`, two behaviours, decided by the driver.
  *
- * Postgres-only — the other dialects' framework-bookkeeping path
- * doesn't suffer this because @effect/sql-cluster / migrationRunner
- * own their own schema. The applier in the per-dialect packages does
- * the equivalent work for their own bookkeeping.
+ * The filter is asymmetric now (see `plannableLive` in `migrations/boot.ts`) and
+ * the planner owns evolution, so the extra steps here are not merely redundant —
+ * they are a second, weaker path, and the index step actively hurt: it ran BEFORE
+ * the planner could add a column, so an index over a newly-added column failed
+ * the boot (pg 42703) rather than waiting one step. Deleted rather than fixed;
+ * fixing it would have kept two paths.
  *
- * For user / plugin / cloud tables this path is wrong — they need the
- * full planner refuse-to-boot semantics on column drops, renames,
- * type changes. Framework bookkeeping is a tighter contract:
- * additive-only column evolution, no destructive changes, no user
- * data ever lives in a `.dropped()` slot. The framework versions
- * its own schema additively + can safely ALTER TABLE forward.
+ * Dialect-uniform now, because there is nothing left in it that only one dialect
+ * can express.
  */
 export declare const emitFrameworkBootstrapSql: (tables: ReadonlyArray<AnyTable>, dialect: DialectId) => string;
 
@@ -1074,16 +1100,6 @@ export declare interface IndexSnapshot {
     readonly expression?: boolean;
 }
 
-/**
- * Read the current shape of the connected database. Dispatched per
- * dialect; supports postgres only.
- *
- * The returned `SchemaSnapshot` is the same shape `declaredSnapshot`
- * produces — they're directly diffable via `planMigrations`.
- *
- * Restricted to the `public` schema today; multi-schema apps will
- * grow a `schema` parameter when we have a real need.
- */
 export declare const introspectSchema: (sql: SqlClient.SqlClient) => Effect.Effect<SchemaSnapshot, SqlError_2>;
 
 /** Type-guard for the discovery walker. */
@@ -1195,6 +1211,15 @@ export declare type MigrationOperation = {
     readonly kind: 'drop-index';
     readonly table: string;
     readonly index: string;
+} | {
+    readonly kind: 'rename-index';
+    readonly table: string;
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: 'rename-table';
+    readonly from: string;
+    readonly to: string;
 } | {
     readonly kind: 'add-unique';
     readonly table: string;
@@ -1705,6 +1730,23 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
     readonly appliedUniques: ReadonlyArray<TableUnique>;
     readonly appliedFullText: ReadonlyArray<TableFullTextIndex>;
     readonly appliedChecks: ReadonlyArray<TableCheck>;
+    /**
+     * The name this table used to have, set by `.renamedFrom('old_name')`.
+     * Named apart from the METHOD that sets it — one interface cannot carry both.
+     *
+     * The table-level twin of a column's `.renamedFrom()`, and it exists for the
+     * same reason: a rename and a drop+create are structurally identical to a
+     * differ (old table gone, new table present) and mean completely different
+     * things. Without the marker the planner has to assume drop + create, which
+     * for a TABLE is data loss, so it refuses — and the rename can only be done
+     * by hand.
+     *
+     * A chained method, matching a column's `.renamedFrom()` — the two mean the
+     * same thing one level apart, so they read the same. It survives every
+     * subsequent `.index(...)` / `.with(...)` because each rebuild spreads its
+     * options through.
+     */
+    readonly previousTableName?: string;
     /**
      * Composite PRIMARY KEY column set, declared via `.primaryKey(['a','b'])`.
      * When set it REPLACES the single-column `id()` PK assumption: no column
@@ -2041,6 +2083,23 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      * says so at boot.
      */
     nonReactive: () => Table<Name, Fields, false, IxNames>;
+    /**
+     * Declare the name this table used to have, so the planner folds what would
+     * otherwise be DROP + CREATE — the loss of every row — into an in-place
+     * `rename-table`.
+     *
+     * Deliberately the SAME SHAPE as a column's `.renamedFrom()`, because the two
+     * mean the same thing one level apart, and a reader who learned one will reach
+     * for the other. It first shipped as a third argument to `table()`; that made
+     * the one API in this family that had to be looked up.
+     *
+     *     export const notes = table('archive_notes', { … }).renamedFrom('notes')
+     *
+     * Drop the marker once the rename has been applied in every environment. A
+     * marker whose old table is absent is a silent no-op, so it can sit in source
+     * across a staged rollout.
+     */
+    renamedFrom: (oldName: string) => Table<Name, Fields, Reactive, IxNames>;
 }
 
 /**
@@ -2164,6 +2223,13 @@ export declare interface TableSnapshot {
      * data exists yet), present from introspection.
      */
     readonly rowCount?: number;
+    /**
+     * The name this table previously had (`table(name, fields, { renamedFrom })`).
+     * DECLARED side only — introspection has no way to know. The planner pairs it
+     * against a live table of that name and folds what would otherwise be
+     * DROP + CREATE into a `rename-table`.
+     */
+    readonly renamedFrom?: string;
 }
 
 declare interface TableUnique {