@voltro/database 0.21.0 → 0.22.0

package/dist/sql.d.ts

@@ -789,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;
 
@@ -1210,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;
@@ -1720,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
@@ -2056,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>;
 }
 
 /**
@@ -2179,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 {