@voltro/database 0.78.0 → 0.79.1

package/dist/sql.d.ts

@@ -603,6 +603,12 @@ declare interface ChangeStreamGap {
     readonly downForMs?: number;
 }
 
+/** A live table's columns that carry a character set, with it. */
+export declare const charsetColumnsOf: (table: TableSnapshot) => ReadonlyArray<{
+    readonly column: string;
+    readonly charset: string;
+}>;
+
 /** Partition into ≤`n`-sized chunks (disjoint, complete). Exported for the
  *  batching regression test — the introspection's correctness reduces to this
  *  producing a complete, non-overlapping partition of the table list. */
@@ -1685,6 +1691,25 @@ export declare interface ColumnSnapshot {
      * blocks a masking export until classified.
      */
     readonly safe?: boolean;
+    /**
+     * The character set a STRING column is stored in — MySQL / MariaDB only, and
+     * only on columns the engine gives one (text, varchar, enum; never json,
+     * which is `utf8mb4` on MariaDB and charset-less on MySQL by construction,
+     * and never a number, a date or bytes).
+     *
+     * Live side: what `information_schema.columns.character_set_name` reports.
+     * Declared side: the store's declared charset (`store: { dialect, charset }`
+     * in `app.config.ts`), stamped on every string column — ABSENT when the app
+     * declares none. The planner compares it only when BOTH sides carry one, so
+     * an undeclared app never plans a conversion; and the fingerprint never
+     * hashes it, because a live reading against an absent declaration would part
+     * every table's two hashes forever. `storeCharset.ts` carries the reason.
+     *
+     * A `string`, not `MysqlCharset`: the reader reports whatever the column is
+     * in (`latin1` is real), and a conversion FROM it is exactly what the
+     * declaration is for. Only the declared side is limited to the two.
+     */
+    readonly charset?: string;
     /**
      * Type PARAMETERS for the three `ColumnType`s whose DDL is not determined by
      * the type tag alone — `vector(n)`, `array(of)`, `enum(name, values)`.
@@ -1724,10 +1749,39 @@ export declare interface ColumnSnapshot {
     };
 }
 
+/**
+ * Does the declared column render a STRING type on the mysql family — the
+ * columns a declared charset is stamped on? Mirrors `sqlType(_, 'mariadb')`:
+ * text (LONGTEXT / VARCHAR / TEXT), enum (`ENUM(...)`), a typeid/ulid `id`
+ * (VARCHAR(64)) and a text-stored `reference` (VARCHAR(64)). A numeric id or
+ * reference is BIGINT; json / array are JSON; bytes is LONGBLOB — none carry a
+ * character set. `raw` is the user's own DDL, which the framework does not
+ * read, so it is left alone on both sides.
+ */
+export declare const columnTakesCharset: (col: Pick<ColumnSnapshot, "type" | "idScheme" | "idStorage" | "referenceStorage">) => boolean;
+
 declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
 
 declare type ColumnType_2 = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
 
+/** A live foreign key a charset conversion has to carry across the rewrite. */
+export declare interface ConvertCharsetForeignKey {
+    /** Catalog name of the constraint. */
+    readonly name: string;
+    /** The child (referencing) side. */
+    readonly table: string;
+    readonly column: string;
+    readonly targetTable: string;
+    readonly targetColumn: string;
+    readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    readonly onUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    /** Which operation re-creates it after the rewrite: this table's, or the
+     *  other endpoint's (`'peer'` — that table converts in the same plan and
+     *  sorts after this one). Dropping is done by whichever runs first; both
+     *  tolerate an already-absent constraint. */
+    readonly restore: 'here' | 'peer';
+}
+
 /** The tables a plan CREATEs — the set every same-plan operation is checked against. */
 export declare const createdTablesOf: (operations: ReadonlyArray<PlannedOperation>) => ReadonlySet<string>;
 
@@ -2260,13 +2314,24 @@ declare interface DataStore {
     storedTables?(): ReadonlyArray<StoredTableShape>;
 }
 
+export declare const declaredSnapshot: (tables: ReadonlyArray<TableLike>, dialect?: DialectId, options?: DeclaredSnapshotOptions) => SchemaSnapshot;
+
 /**
  * Build a `SchemaSnapshot` from an array of `TableLike` declarations.
  * Caller is responsible for passing the FULL set of tables (user-
  * declared + framework). The fingerprint over this snapshot is what the
  * boot-time prod check compares against `_voltro_migration_plans`.
  */
-export declare const declaredSnapshot: (tables: ReadonlyArray<TableLike>, dialect?: DialectId) => SchemaSnapshot;
+export declare interface DeclaredSnapshotOptions {
+    /**
+     * The store's declared character set (`store: { dialect, charset }`) —
+     * stamped on every string column so the planner can compare it with what the
+     * database reports. MySQL / MariaDB only: on any other dialect a charset is a
+     * configuration error and is refused here rather than ignored, so a
+     * declaration that cannot take effect never reads as one that did.
+     */
+    readonly charset?: MysqlCharset | undefined;
+}
 
 /** The NOTIFY channel a schema emits on when none is configured. */
 export declare const DEFAULT_CDC_CHANNEL = "framework_changes";
@@ -2325,6 +2390,9 @@ export declare const describeOutcome: (outcome: BootMigrationOutcome, dialectId:
 /** `bf_links`, `bf_links.ticket_key` — the spelling a message uses. */
 export declare const describeProbe: (probe: SchemaProbe) => string;
 
+/** One line per finding, for the CLI and the doctor. */
+export declare const describeStoreCharsetFinding: (f: StoreCharsetFinding) => string;
+
 /**
  * Parse `VOLTRO_DESTRUCTIVE_OK`.
  *
@@ -2535,6 +2603,32 @@ export declare const emitAddIndexMysql: (op: Extract<MigrationOperation, {
     kind: "add-index";
 }>, declared: ReadonlyArray<TableLike>, engine?: MysqlEngine) => string;
 
+/**
+ * The statements of a `convert-charset` operation, in order:
+ *
+ *   1. drop every foreign key that touches the table (either end) — the
+ *      engines refuse to change the charset of a column a constraint holds;
+ *   2. ONE `ALTER TABLE` that MODIFYs each declared string column to its
+ *      declared definition plus `CHARACTER SET`, and sets the table default —
+ *      a single rewrite, not one per column, and never the json columns;
+ *   3. re-create the constraints this operation owns (`restore: 'here'`); the
+ *      ones between two converting tables come back with the later table.
+ *
+ * Every column is rendered from the DECLARATION (`emitModifyColumnMysql` is
+ * the same renderer the type and nullability operations use), because MODIFY
+ * redefines the column and the declaration is the shape the plan converges
+ * to. A generated column keeps its expression — MODIFY without it would drop
+ * the generation — and a column keeps its column-level CHECK (`checks`, read
+ * by `columnLevelChecksMysql`) for the same reason.
+ */
+export declare const emitConvertCharsetMysql: (op: Extract<MigrationOperation, {
+    kind: "convert-charset";
+}>, declared: ReadonlyArray<TableLike>, checks?: ReadonlyMap<string, string>) => {
+    readonly drops: ReadonlyArray<string>;
+    readonly rewrite: string;
+    readonly restores: ReadonlyArray<string>;
+};
+
 export declare const emitCreateTableMssql: (op: Extract<MigrationOperation, {
     kind: "create-table";
 }>) => ReadonlyArray<string>;
@@ -2613,7 +2707,7 @@ cdcChannel?: string) => string;
  * containers are a deliberate non-goal (each tenant namespace is
  * self-contained for its own tables).
  */
-export declare const emitNamespacedSchemaSql: (tables: ReadonlyArray<AnyTable>, dialect: DialectId, namespace: string, sqliteFile?: string) => string;
+export declare const emitNamespacedSchemaSql: (tables: ReadonlyArray<AnyTable>, dialect: DialectId, namespace: string, sqliteFile?: string, options?: SchemaEmitOptions) => string;
 
 /**
  * DDL that creates a tenant's namespace CONTAINER, per dialect:
@@ -2629,12 +2723,17 @@ export declare const emitNamespacedSchemaSql: (tables: ReadonlyArray<AnyTable>,
  * errors if the alias is already attached, which the migrator treats as
  * "already provisioned".
  */
-export declare const emitNamespaceProvisionDdl: (namespace: string, dialect: DialectId, sqliteFile?: string) => string;
+export declare const emitNamespaceProvisionDdl: (namespace: string, dialect: DialectId, sqliteFile?: string, 
+/** The declared store charset (mysql family) — the new database's default,
+ *  so its tables inherit the declaration rather than the server default.
+ *  `IF NOT EXISTS` leaves an existing database's default alone (measured on
+ *  both engines); the tables' own column charsets still land. */
+charset?: MysqlCharset) => string;
 
 export declare const emitSchemaSql: (entities: ReadonlyArray<AnyTable | AnyView>, dialect: DialectId, 
 /** NOTIFY channel for the reactive triggers. Must match the store's
  *  `cdcChannel`, or writes emit where nothing is listening. */
-cdcChannel?: string) => string;
+cdcChannel?: string, options?: SchemaEmitOptions) => string;
 
 declare type EmptyMerge = unknown;
 
@@ -3315,6 +3414,8 @@ export declare const isAlreadySatisfied: (err: unknown, rules: ReadonlyArray<Alr
 /** Type-guard for the discovery walker. */
 export declare const isFileMigration: (value: unknown) => value is FileMigration;
 
+export declare const isMysqlCharset: (value: unknown) => value is MysqlCharset;
+
 /** Type guard — narrows an unknown value to a {@link RawSqlFragment}. */
 export declare const isRawSqlFragment: (value: unknown) => value is RawSqlFragment;
 
@@ -3487,6 +3588,16 @@ export declare interface MigrationLockScope {
     readonly schema?: string | undefined;
 }
 
+/**
+ * How a migration file becomes a module. The default imports the file itself;
+ * a caller that holds the app's modules already — `voltro serve` from its
+ * precompiled bundle — passes its own, so a boot that only ASKS what is pending
+ * does not import each file's source and, through it, a second copy of this
+ * package's whole migration graph. Measured on a boot with two migrations:
+ * ~290 ms of held event loop, after the port was already answering probes.
+ */
+export declare type MigrationModuleImporter = (file: string) => Promise<Record<string, unknown>>;
+
 /**
  * A migration context was built without a SQL client — over the in-memory
  * store, the shape a unit test uses — and the body reached a surface that
@@ -3643,6 +3754,30 @@ export declare type MigrationOperation = {
     readonly validation: 'value' | 'container';
     readonly previousValidation: 'value' | 'container' | 'unverified' | 'absent';
     readonly dropConstraints: ReadonlyArray<string>;
+}
+/**
+* Bring every string column of ONE table to the declared character set —
+* MySQL / MariaDB only. A table REWRITE: each named column is `MODIFY`ed to
+* its declared definition plus `CHARACTER SET`, and the table's default is
+* set so a later `ADD COLUMN` inherits it. json columns are never in
+* `columns` (their charset is the engine's, not the declaration's).
+*
+* `foreignKeys` are the constraints that touch this table — either end —
+* because neither engine changes the character set of a column a foreign
+* key holds (MariaDB 1832/1833, MySQL 3780). Each is dropped before the
+* rewrite and re-created after it; `restore` says which endpoint's operation
+* re-creates it, so a constraint between two converting tables comes back
+* only once both sides are at the target (the later of the two, by name).
+*/
+| {
+    readonly kind: 'convert-charset';
+    readonly table: string;
+    readonly charset: MysqlCharset;
+    /** The string columns to rewrite, in declaration order. */
+    readonly columns: ReadonlyArray<string>;
+    /** The character sets those columns are in today (for the plan line). */
+    readonly from: ReadonlyArray<string>;
+    readonly foreignKeys: ReadonlyArray<ConvertCharsetForeignKey>;
 };
 
 /**
@@ -3881,6 +4016,16 @@ declare interface MixinIndex {
     readonly kindOptions?: IndexKindOptions;
 }
 
+export declare const MYSQL_CHARSETS: ReadonlyArray<MysqlCharset>;
+
+/**
+ * The character sets a store can declare for its string columns on MySQL /
+ * MariaDB. `utf8mb4` holds every Unicode scalar; `utf8mb3` (the engines' old
+ * `utf8`) stops at three bytes and refuses emoji and most supplementary-plane
+ * characters with errno 1366.
+ */
+export declare type MysqlCharset = 'utf8mb3' | 'utf8mb4';
+
 /** Which engine a `mysql`-dialect connection is actually talking to. */
 export declare type MysqlEngine = 'mysql' | 'mariadb';
 
@@ -3903,6 +4048,11 @@ export declare type MysqlEngine = 'mysql' | 'mariadb';
  */
 export declare const mysqlIndexPrefixFor: (col: ColumnSnapshot | undefined) => number | undefined;
 
+export declare interface NamespaceCharsetReport {
+    readonly namespace: string;
+    readonly findings: ReadonlyArray<StoreCharsetFinding>;
+}
+
 /**
  * Type-narrowing migration marker. Tells the planner that this column
  * previously had type `from` and is now being narrowed/converted to its
@@ -4066,7 +4216,9 @@ export declare const parseEnumCheck: (clause: string) => {
  */
 export declare const pendingFileMigrationIds: (sql: SqlClient.SqlClient, projectRoot: string, 
 /** Absent: BOTH phases — a gate that asks "is anything pending at all". */
-phase?: MigrationPhase) => Effect.Effect<ReadonlyArray<string>, unknown>;
+phase?: MigrationPhase, 
+/** How each file is imported — see {@link MigrationModuleImporter}. */
+importModule?: MigrationModuleImporter) => Effect.Effect<ReadonlyArray<string>, unknown>;
 
 /**
  * What `runFileBasedMigrations` would execute next, with the one fact a deploy
@@ -4128,6 +4280,16 @@ export declare interface PlanInput {
      * CLI populates it from `VOLTRO_DB_IGNORE_TABLES` (comma-separated names).
      */
     readonly ignoreTables?: ReadonlyArray<string>;
+    /**
+     * The store's declared character set — `store: { dialect, charset }` in
+     * `app.config.ts`. MySQL / MariaDB only; `declaredSnapshot` refuses it for
+     * any other dialect. Declared, every table the app declares is CREATED with
+     * it and, when a live table's string columns are stored otherwise, CONVERTED
+     * to it (`convert-charset`, a table rewrite that carries the table's foreign
+     * keys across). Absent, nothing is planned about character sets — see
+     * `storeCharset.ts` for why that is the default and what is reported instead.
+     */
+    readonly charset?: MysqlCharset | undefined;
 }
 
 /**
@@ -5280,6 +5442,9 @@ export declare interface RunPlannedMigrationsCtx {
     /** How long a soft-drop snapshot may sit before the boot warns about it
      *  (`database.softDropRetentionDays`; default 7). */
     readonly softDropRetentionDays?: number;
+    /** The store's declared character set (`store: { dialect, charset }`),
+     *  MySQL / MariaDB only — threaded into every plan this boot computes. */
+    readonly charset?: MysqlCharset | undefined;
 }
 
 /**
@@ -5295,6 +5460,9 @@ export declare interface RunPlannedMigrationsCtx {
  */
 export declare const runSchemaOp: (sql: SqlClient.SqlClient, op: MigrationSchemaOp, live: SchemaSnapshot) => Effect.Effect<void, SqlError_2>;
 
+/** Runs one Effect over the connection — the shape `ManagedRuntime.runPromise` and a store's `run` share. */
+export declare type RunSql = <A>(effect: Effect.Effect<A, SqlError_2, SqlClient.SqlClient>) => Promise<A>;
+
 /**
  * Effect that applies the emitted DDL to the provided SqlClient. Splits
  * on `;` only outside dollar-quoted blocks (the postgres NOTIFY trigger
@@ -5320,11 +5488,22 @@ export declare const runSchemaOp: (sql: SqlClient.SqlClient, op: MigrationSchema
  * absent → `DB_SCHEMA` from the environment, the same configuration the
  * connection's `search_path` pin reads.
  */
-export declare interface SchemaApplyOptions {
+export declare interface SchemaApplyOptions extends SchemaEmitOptions {
     readonly retryFilter?: (error: unknown) => RetryDecision;
     readonly lockSchema?: string;
 }
 
+export declare interface SchemaEmitOptions {
+    /**
+     * The store's declared character set — MySQL / MariaDB only. Every CREATE
+     * TABLE carries it as the table default, so the bring-up path creates the
+     * same tables the planner's `create-table` does. Refused for any other
+     * dialect (a declaration that cannot take effect must not read as one that
+     * did).
+     */
+    readonly charset?: MysqlCharset | undefined;
+}
+
 /** What a schema operation on the migration context found to do. */
 export declare type SchemaOpOutcome = 'applied' | 'already-absent' | 'already-present';
 
@@ -5518,6 +5697,57 @@ export declare interface SquashResult {
     readonly snapshotId: string;
 }
 
+/** The declared snapshot's tables with the store charset stamped on every string column. */
+export declare const stampDeclaredCharset: (tables: ReadonlyArray<TableSnapshot>, charset: MysqlCharset) => ReadonlyArray<TableSnapshot>;
+
+/**
+ * What to do about the findings, once. Names the real config field and the
+ * command that applies it; nothing here is an env var.
+ */
+export declare const STORE_CHARSET_REMEDY: string;
+
+/**
+ * One table the store's character set is wrong about.
+ *
+ *  - `disagrees-with-declaration` — the app declares a charset and these
+ *    columns are stored in another one. The plan carries the conversion; the
+ *    doctor names it for the operator who has not run `voltro db plan`.
+ *  - `json-outruns-text` — no declaration, and the table has a json column
+ *    (which holds every Unicode character on both engines) next to string
+ *    columns that do not. The reported symptom, as a line.
+ *  - `mixed` — no declaration, no json, and the table's string columns are not
+ *    all in one charset: a column converted by hand, or a column added under a
+ *    different database default. Two columns of one declaration disagree about
+ *    what a string is.
+ */
+export declare interface StoreCharsetFinding {
+    readonly table: string;
+    readonly kind: 'disagrees-with-declaration' | 'json-outruns-text' | 'mixed';
+    /** The columns that are not where they should be, with the charset they are in. */
+    readonly columns: ReadonlyArray<{
+        readonly column: string;
+        readonly charset: string;
+    }>;
+    /** What the finding measures against: the declaration, or `utf8mb4` for json. */
+    readonly expected: string;
+}
+
+/**
+ * The tables whose string columns cannot hold what they should. Pure — over a
+ * live snapshot the caller has already read — so `voltro db plan`, `voltro
+ * doctor` and a test can ask the same question of the same reading.
+ *
+ * Zero findings on a healthy database is the contract: a `utf8mb4` database
+ * with no declaration reports nothing, and so does any database whose every
+ * string column matches its declaration. Measured against both engines in
+ * `storeCharset.integration.test.ts`.
+ */
+export declare const storeCharsetFindings: (input: {
+    readonly live: SchemaSnapshot;
+    readonly dialect: DialectId;
+    readonly charset?: MysqlCharset | undefined;
+}) => ReadonlyArray<StoreCharsetFinding>;
+
 /** One table as a store that has no catalog can describe it. See {@link DataStore.storedTables}. */
 declare interface StoredTableShape {
     /** The table's name, unqualified by any namespace the reporting view is bound to. */
@@ -6159,6 +6389,20 @@ declare interface TableUnique {
     };
 }
 
+/**
+ * The tenant databases whose string columns are stored otherwise than the
+ * declaration — or, undeclared, otherwise than their json columns. Only the
+ * charset facts are read (type kind, charset), which is all the question
+ * needs; a full introspection per tenant would be a catalog scan per tenant.
+ *
+ * Empty on a server with no tenant database, and empty when every tenant
+ * agrees. Namespaces come out sorted.
+ */
+export declare const tenantNamespaceCharsetFindings: (run: RunSql, options: {
+    readonly charset?: MysqlCharset | undefined;
+    readonly dialect?: "mysql" | "mariadb";
+}) => Promise<ReadonlyArray<NamespaceCharsetReport>>;
+
 /**
  * A `transactional` migration whose body committed the transaction from
  * inside — DDL on the MySQL family, or an explicit COMMIT. The body's work
@@ -6288,6 +6532,17 @@ export declare const VOLTRO_MIGRATION_LOCK_KEY = 6322741009312437n;
 /** Index-free for the same reason `_voltro_migration_ops` is: at most a row or two, ever. */
 export declare const _voltroDeploysTable: TableLike;
 
+/**
+ * Walk for migration files. Recursive; skips common build dirs.
+ * Returns absolute paths sorted by basename (= timestamp-ordered
+ * because the convention puts the timestamp at the start).
+ *
+ * Exported for `voltro build`, which must bundle exactly the files this walk
+ * finds: every one `voltro serve` loads that is not in the bundle is imported
+ * from source instead.
+ */
+export declare const walkMigrationFiles: (root: string) => Promise<ReadonlyArray<string>>;
+
 /**
  * One aggregate column in a `SELECT` projection — `COUNT(*)`,
  * `SUM(amount) AS total`, etc. Built via the `count() / sum() /