@atscript/db-mysql 0.1.168 → 0.1.170

package/dist/index.d.cts

@@ -116,6 +116,7 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private static readonly NATIVE_DEFAULT_FNS;
   private _engine;
   private _charset;
+  /** `@db.mysql.collate` on the table; none → the charset's default (see `mysqlDefaultCollation`). */
   private _collation;
   private _autoIncrementStart?;
   private _incrementFields;
@@ -132,6 +133,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
    */
   private _epochAfterRekey;
   private _onUpdateFields;
+  /** Field path → `@db.mysql.charset` of the column. */
+  private _charsetFields;
+  private _space?;
+  /** Memo of {@link _keyTableCharsets} — it also makes its warning fire once. */
+  private _keyTableCharsetsMemo?;
   /** Whether the connected MySQL instance supports native VECTOR type (MySQL 9.0+). */
   private _supportsVector;
   /** Vector fields: physical field name → { dimensions, similarity, indexName }. */
@@ -141,6 +147,7 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private _replaceColumnsMemo?;
   private _fulltextMemo?;
   private _searchIndexesMemo?;
+  private _incrementPkMemo?;
   /**
    * Schema name for INFORMATION_SCHEMA queries — `@db.schema` of the bound
    * table, or `null` (→ `DATABASE()`, the pool's database) when the table
@@ -260,6 +267,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private _uniformIdGroup;
   /** Physical column of the single-column AUTO_INCREMENT primary key, if the table has one. */
   private _autoIncrementPk;
+  /**
+   * Physical column of the primary key's `@db.default.increment` part (if any)
+   * and whether the key is composite — computed once per table.
+   */
+  private _incrementPk;
   /**
    * Splits `rows` into runs that each map to ONE statement with a derivable
    * id sequence. MySQL reports only the first GENERATED id of a statement, and
@@ -298,6 +310,15 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * count — mode 2, the 8.0 default), explicit rows keep their own value.
    */
   private _groupInsertedIds;
+  /**
+   * The inserted id of `row` (see `_resolveInsertedId`). For a COMPOSITE key
+   * with an AUTO_INCREMENT part, `partId` is what the statement generated for
+   * that part — pass it only when exact (a ONE-row INSERT); a row carrying the
+   * part keeps its own value. An explicit `0` in the part counts as absent:
+   * MySQL generates a value for it (unless `NO_AUTO_VALUE_ON_ZERO`), so only
+   * `partId` knows it — without that the id is `undefined`, never a wrong `0`.
+   */
+  private _insertedIdOf;
   supportsInsertIgnore(): boolean;
   /**
    * Standalone (no caller transaction): per chunk ONE optimistic multi-row
@@ -418,6 +439,22 @@ declare class MysqlAdapter extends BaseDbAdapter {
   deleteMany(filter: FilterExpr, opts?: TDbDeleteManyOptions): Promise<TDbDeleteResult>;
   prepareTypeMapper(): Promise<void>;
   ensureTable(opts?: TEnsureTableOptions): Promise<void>;
+  /** The table's collation: `@db.mysql.collate`, else the charset's default one (`utf8mb4_unicode_ci` for `utf8mb4`). */
+  private _tableCollation;
+  /**
+   * Foreign-key column path → the referenced table's character set and
+   * collation, where they differ from this table's (see
+   * `mysqlColumnCharset`). Warns about a foreign-key column whose own
+   * `@db.mysql.charset` / collation is replaced by the referenced column's.
+   */
+  private _keyTableCharsets;
+  private _buildKeyTableCharsets;
+  /**
+   * The key-length prefix an index needs on `field`'s column: a function of
+   * its MAPPED type and its character set (`mysqlColumnCharset`, else the
+   * table's).
+   */
+  private _indexPrefix;
   /** The CREATE TABLE options (engine/charset/collation/increment/ON UPDATE/type mapper). */
   private _tableOptions;
   /** The shared column-definition context for ADD/MODIFY statements. */
@@ -453,6 +490,58 @@ declare class MysqlAdapter extends BaseDbAdapter {
   /** Live columns of `tableName`, read through `exec` (a held connection, or the pool). */
   private _readColumns;
   syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
+  /**
+   * Runs `fn` (the MODIFYs of `fields`) with the live foreign keys over those
+   * columns dropped — this table's own and those of any table referencing
+   * them, its own included — and re-creates them, as they were, after: also
+   * when `fn` throws. Nothing is dropped when a constraint could not be
+   * re-created over the new types (see {@link _liftable}): MySQL then refuses
+   * the MODIFY as it always did. A constraint that cannot be re-created is
+   * named, with its DDL, in the error (after `fn`'s own).
+   */
+  private _withForeignKeysLifted;
+  /**
+   * Re-creates `fks` (dropped by {@link _withForeignKeysLifted}) — one
+   * `ALTER TABLE` per table, with `foreign_key_checks` off on this connection
+   * so MySQL adds them in place instead of rebuilding the table (the rows
+   * met them before the change). A table whose statement fails has its
+   * constraints re-tried one by one. Returns those that could not be
+   * re-created.
+   */
+  private _restoreForeignKeys;
+  /**
+   * Whether every constraint of `fks` can be re-created once `fields` have
+   * their new types: each column pair of a constraint that the change touches
+   * stays compatible — the new type against the other side's live column (or
+   * its new type, on this table): integers of the same type and signedness,
+   * `CHAR` / `VARCHAR` either way with the same collation, anything else the
+   * same type. Otherwise nothing is lifted (and MySQL refuses the change, as
+   * it did before foreign keys were lifted) — a dropped constraint must
+   * never be lost to a column outside this run.
+   */
+  private _liftable;
+  /**
+   * The collation each of `fields` (string columns) has after its MODIFY:
+   * the definition's own `COLLATE`, else the default of its `CHARACTER SET`,
+   * else the table's.
+   */
+  private _newCollations;
+  /**
+   * The live foreign keys over any of `columns` of this table: its own (by
+   * their columns) and those referencing them (by the referenced columns),
+   * each with every column, in key order.
+   */
+  private _foreignKeysOver;
+  /**
+   * Before `fields` are modified: drops the managed indexes that key more of
+   * a column than its new type allows — a full key on a column becoming
+   * TEXT (ER 1170), or on a VARCHAR growing past the key-part limit (ER
+   * 1071). Index sync re-creates them with the prefix the new type needs.
+   * Primary keys, FULLTEXT and unmanaged indexes are left alone.
+   */
+  private _dropIndexesOutgrown;
+  /** `DROP INDEX name` on this table (logged). */
+  private _dropIndex;
   recreateTable(): Promise<void>;
   dropTable(): Promise<void>;
   copyFromJsonColumn(source: string, targets: readonly TJsonCopyTarget[]): Promise<void>;
@@ -462,6 +551,8 @@ declare class MysqlAdapter extends BaseDbAdapter {
   dropTableByName(tableName: string): Promise<void>;
   dropViewByName(viewName: string): Promise<void>;
   renameTable(oldName: string): Promise<void>;
+  /** Keeps the space: {@link typeMapper} asks it which fields a foreign key references. */
+  registerSpace(space: DbSpace): void;
   typeMapper(field: TDbFieldMeta): string;
   protected _syncIndexes(dryRun: boolean): Promise<TIndexChange[]>;
   syncForeignKeys(): Promise<TForeignKeyChange[]>;
@@ -469,6 +560,13 @@ declare class MysqlAdapter extends BaseDbAdapter {
   planForeignKeys(): Promise<TForeignKeyChange[]>;
   private _syncForeignKeys;
   dropForeignKeys(fkFieldKeys: string[]): Promise<void>;
+  /**
+   * Drops a foreign-key constraint over `columns` (in key order), then the
+   * index InnoDB created for it: an unnamed constraint gets an index named
+   * after its first column, which outlives the constraint — and would block
+   * that column from becoming TEXT once it no longer references anything
+   * (ER 1170). An index another constraint still needs is kept (ER 1553).
+   */
   private _dropFkConstraint;
   /** Queries INFORMATION_SCHEMA for existing FK constraints, grouped by constraint name → column names. */
   private _getExistingFkConstraints;

package/dist/index.d.mts

@@ -116,6 +116,7 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private static readonly NATIVE_DEFAULT_FNS;
   private _engine;
   private _charset;
+  /** `@db.mysql.collate` on the table; none → the charset's default (see `mysqlDefaultCollation`). */
   private _collation;
   private _autoIncrementStart?;
   private _incrementFields;
@@ -132,6 +133,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
    */
   private _epochAfterRekey;
   private _onUpdateFields;
+  /** Field path → `@db.mysql.charset` of the column. */
+  private _charsetFields;
+  private _space?;
+  /** Memo of {@link _keyTableCharsets} — it also makes its warning fire once. */
+  private _keyTableCharsetsMemo?;
   /** Whether the connected MySQL instance supports native VECTOR type (MySQL 9.0+). */
   private _supportsVector;
   /** Vector fields: physical field name → { dimensions, similarity, indexName }. */
@@ -141,6 +147,7 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private _replaceColumnsMemo?;
   private _fulltextMemo?;
   private _searchIndexesMemo?;
+  private _incrementPkMemo?;
   /**
    * Schema name for INFORMATION_SCHEMA queries — `@db.schema` of the bound
    * table, or `null` (→ `DATABASE()`, the pool's database) when the table
@@ -260,6 +267,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private _uniformIdGroup;
   /** Physical column of the single-column AUTO_INCREMENT primary key, if the table has one. */
   private _autoIncrementPk;
+  /**
+   * Physical column of the primary key's `@db.default.increment` part (if any)
+   * and whether the key is composite — computed once per table.
+   */
+  private _incrementPk;
   /**
    * Splits `rows` into runs that each map to ONE statement with a derivable
    * id sequence. MySQL reports only the first GENERATED id of a statement, and
@@ -298,6 +310,15 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * count — mode 2, the 8.0 default), explicit rows keep their own value.
    */
   private _groupInsertedIds;
+  /**
+   * The inserted id of `row` (see `_resolveInsertedId`). For a COMPOSITE key
+   * with an AUTO_INCREMENT part, `partId` is what the statement generated for
+   * that part — pass it only when exact (a ONE-row INSERT); a row carrying the
+   * part keeps its own value. An explicit `0` in the part counts as absent:
+   * MySQL generates a value for it (unless `NO_AUTO_VALUE_ON_ZERO`), so only
+   * `partId` knows it — without that the id is `undefined`, never a wrong `0`.
+   */
+  private _insertedIdOf;
   supportsInsertIgnore(): boolean;
   /**
    * Standalone (no caller transaction): per chunk ONE optimistic multi-row
@@ -418,6 +439,22 @@ declare class MysqlAdapter extends BaseDbAdapter {
   deleteMany(filter: FilterExpr, opts?: TDbDeleteManyOptions): Promise<TDbDeleteResult>;
   prepareTypeMapper(): Promise<void>;
   ensureTable(opts?: TEnsureTableOptions): Promise<void>;
+  /** The table's collation: `@db.mysql.collate`, else the charset's default one (`utf8mb4_unicode_ci` for `utf8mb4`). */
+  private _tableCollation;
+  /**
+   * Foreign-key column path → the referenced table's character set and
+   * collation, where they differ from this table's (see
+   * `mysqlColumnCharset`). Warns about a foreign-key column whose own
+   * `@db.mysql.charset` / collation is replaced by the referenced column's.
+   */
+  private _keyTableCharsets;
+  private _buildKeyTableCharsets;
+  /**
+   * The key-length prefix an index needs on `field`'s column: a function of
+   * its MAPPED type and its character set (`mysqlColumnCharset`, else the
+   * table's).
+   */
+  private _indexPrefix;
   /** The CREATE TABLE options (engine/charset/collation/increment/ON UPDATE/type mapper). */
   private _tableOptions;
   /** The shared column-definition context for ADD/MODIFY statements. */
@@ -453,6 +490,58 @@ declare class MysqlAdapter extends BaseDbAdapter {
   /** Live columns of `tableName`, read through `exec` (a held connection, or the pool). */
   private _readColumns;
   syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
+  /**
+   * Runs `fn` (the MODIFYs of `fields`) with the live foreign keys over those
+   * columns dropped — this table's own and those of any table referencing
+   * them, its own included — and re-creates them, as they were, after: also
+   * when `fn` throws. Nothing is dropped when a constraint could not be
+   * re-created over the new types (see {@link _liftable}): MySQL then refuses
+   * the MODIFY as it always did. A constraint that cannot be re-created is
+   * named, with its DDL, in the error (after `fn`'s own).
+   */
+  private _withForeignKeysLifted;
+  /**
+   * Re-creates `fks` (dropped by {@link _withForeignKeysLifted}) — one
+   * `ALTER TABLE` per table, with `foreign_key_checks` off on this connection
+   * so MySQL adds them in place instead of rebuilding the table (the rows
+   * met them before the change). A table whose statement fails has its
+   * constraints re-tried one by one. Returns those that could not be
+   * re-created.
+   */
+  private _restoreForeignKeys;
+  /**
+   * Whether every constraint of `fks` can be re-created once `fields` have
+   * their new types: each column pair of a constraint that the change touches
+   * stays compatible — the new type against the other side's live column (or
+   * its new type, on this table): integers of the same type and signedness,
+   * `CHAR` / `VARCHAR` either way with the same collation, anything else the
+   * same type. Otherwise nothing is lifted (and MySQL refuses the change, as
+   * it did before foreign keys were lifted) — a dropped constraint must
+   * never be lost to a column outside this run.
+   */
+  private _liftable;
+  /**
+   * The collation each of `fields` (string columns) has after its MODIFY:
+   * the definition's own `COLLATE`, else the default of its `CHARACTER SET`,
+   * else the table's.
+   */
+  private _newCollations;
+  /**
+   * The live foreign keys over any of `columns` of this table: its own (by
+   * their columns) and those referencing them (by the referenced columns),
+   * each with every column, in key order.
+   */
+  private _foreignKeysOver;
+  /**
+   * Before `fields` are modified: drops the managed indexes that key more of
+   * a column than its new type allows — a full key on a column becoming
+   * TEXT (ER 1170), or on a VARCHAR growing past the key-part limit (ER
+   * 1071). Index sync re-creates them with the prefix the new type needs.
+   * Primary keys, FULLTEXT and unmanaged indexes are left alone.
+   */
+  private _dropIndexesOutgrown;
+  /** `DROP INDEX name` on this table (logged). */
+  private _dropIndex;
   recreateTable(): Promise<void>;
   dropTable(): Promise<void>;
   copyFromJsonColumn(source: string, targets: readonly TJsonCopyTarget[]): Promise<void>;
@@ -462,6 +551,8 @@ declare class MysqlAdapter extends BaseDbAdapter {
   dropTableByName(tableName: string): Promise<void>;
   dropViewByName(viewName: string): Promise<void>;
   renameTable(oldName: string): Promise<void>;
+  /** Keeps the space: {@link typeMapper} asks it which fields a foreign key references. */
+  registerSpace(space: DbSpace): void;
   typeMapper(field: TDbFieldMeta): string;
   protected _syncIndexes(dryRun: boolean): Promise<TIndexChange[]>;
   syncForeignKeys(): Promise<TForeignKeyChange[]>;
@@ -469,6 +560,13 @@ declare class MysqlAdapter extends BaseDbAdapter {
   planForeignKeys(): Promise<TForeignKeyChange[]>;
   private _syncForeignKeys;
   dropForeignKeys(fkFieldKeys: string[]): Promise<void>;
+  /**
+   * Drops a foreign-key constraint over `columns` (in key order), then the
+   * index InnoDB created for it: an unnamed constraint gets an index named
+   * after its first column, which outlives the constraint — and would block
+   * that column from becoming TEXT once it no longer references anything
+   * (ER 1170). An index another constraint still needs is kept (ER 1553).
+   */
   private _dropFkConstraint;
   /** Queries INFORMATION_SCHEMA for existing FK constraints, grouped by constraint name → column names. */
   private _getExistingFkConstraints;