@adecore/database 0.0.1 → 0.16.0-beta.0

package/src/ddl/alter-sqlite.ts

@@ -0,0 +1,93 @@
+import { columnSql, defaultClause } from './column.ts';
+import { createIndexSql, createTableParts } from './create.ts';
+import { atLeast, quote, tableName, type Dialect } from './dialect.ts';
+import type { TableDiff } from './diff.ts';
+import { isAutoIndex, type ColumnDraft, type TableDraft } from './draft.ts';
+import { dropIndexSql } from './statements.ts';
+
+const RENAME_COLUMN = [3, 25];
+const DROP_COLUMN = [3, 35];
+
+/* The clauses `ALTER TABLE .. ADD COLUMN` refuses: a key, a computed value, or a NOT NULL column with nothing to fill the rows with. */
+const addable = (column: ColumnDraft): boolean => {
+    if (column.autoIncrement || (column.generated && column.generatedClause !== null && /\bSTORED\b/i.test(column.generatedClause))) {
+        return false;
+    }
+    const expression = column.defaultValue?.trim() ?? '';
+    if (expression === '') {
+        return column.nullable;
+    }
+    // Only a constant may fill existing rows: not an expression, not the clock.
+    const clause = defaultClause(expression);
+    return !clause.startsWith('(') && !/^CURRENT_|^LOCALTIME|^NOW/i.test(clause) && (column.nullable || !/^NULL$/i.test(clause));
+};
+
+const needsRebuild = (dialect: Dialect, original: TableDraft, diff: TableDiff): boolean => {
+    if (diff.optionsChanged || diff.primaryKeyChanged || diff.droppedForeignKeys.length > 0 || diff.addedForeignKeys.length > 0) {
+        return true;
+    }
+    if (diff.keptColumns.some((kept) => kept.redefined || kept.moved || (kept.renamed && !atLeast(dialect, ...RENAME_COLUMN)))) {
+        return true;
+    }
+    if (diff.addedColumns.some((added) => added.placed || !addable(added.column))) {
+        return true;
+    }
+    if (diff.droppedColumns.length > 0 && !atLeast(dialect, ...DROP_COLUMN)) {
+        return true;
+    }
+    const autoIndexed = new Set(original.indexes.filter((index) => isAutoIndex(index.name)).flatMap((index) => index.columns));
+    if (diff.droppedColumns.some((dropped) => autoIndexed.has(dropped.name))) {
+        return true;
+    }
+    return [...diff.droppedIndexes, ...diff.renamedIndexes.map(({ from }) => from)].some((index) => isAutoIndex(index.name));
+};
+
+/* The steps of https://www.sqlite.org/lang_altertable.html under "Making Other Kinds Of Table Schema Changes", which keep the rows, the indexes and the foreign keys of other tables intact. */
+const rebuildSql = (dialect: Dialect, schema: string, original: TableDraft, draft: TableDraft, diff: TableDiff): string[] => {
+    const temporary = `new_${draft.name}`;
+    const { table, indexes } = createTableParts(dialect, schema, draft, temporary);
+    const copied = diff.keptColumns.filter((kept) => !kept.column.generated);
+    const statements = ['PRAGMA foreign_keys=OFF', 'BEGIN', table];
+    if (copied.length > 0) {
+        const into = copied.map((kept) => quote(dialect, kept.column.name)).join(', ');
+        const from = copied.map((kept) => quote(dialect, kept.original.name)).join(', ');
+        statements.push(`INSERT INTO ${tableName(dialect, schema, temporary)} (${into}) SELECT ${from} FROM ${tableName(dialect, schema, original.name)}`);
+    }
+    statements.push(
+        `DROP TABLE ${tableName(dialect, schema, original.name)}`,
+        `ALTER TABLE ${tableName(dialect, schema, temporary)} RENAME TO ${quote(dialect, draft.name)}`,
+        ...indexes.map((index) => createIndexSql(dialect, schema, draft.name, index)),
+        'PRAGMA foreign_key_check',
+        'COMMIT',
+        'PRAGMA foreign_keys=ON'
+    );
+    return statements;
+};
+
+/* `ALTER TABLE` where SQLite has one, a rebuild of the table for every other change. */
+export const sqliteAlterSql = (dialect: Dialect, schema: string, original: TableDraft, draft: TableDraft, diff: TableDiff): string[] => {
+    if (needsRebuild(dialect, original, diff)) {
+        return rebuildSql(dialect, schema, original, draft, diff);
+    }
+    const target = tableName(dialect, schema, original.name);
+    const statements: string[] = [];
+    for (const index of [...diff.droppedIndexes, ...diff.renamedIndexes.map(({ from }) => from)]) {
+        statements.push(dropIndexSql(dialect, schema, original.name, index.name));
+    }
+    for (const dropped of diff.droppedColumns) {
+        statements.push(`ALTER TABLE ${target} DROP COLUMN ${quote(dialect, dropped.name)}`);
+    }
+    for (const kept of diff.keptColumns.filter((candidate) => candidate.renamed)) {
+        statements.push(`ALTER TABLE ${target} RENAME COLUMN ${quote(dialect, kept.original.name)} TO ${quote(dialect, kept.column.name)}`);
+    }
+    for (const added of diff.addedColumns) {
+        statements.push(`ALTER TABLE ${target} ADD COLUMN ${columnSql(dialect, added.column)}`);
+    }
+    for (const index of [...diff.addedIndexes, ...diff.renamedIndexes.map(({ to }) => to)]) {
+        statements.push(createIndexSql(dialect, schema, original.name, index));
+    }
+    if (diff.renamed) {
+        statements.push(`ALTER TABLE ${target} RENAME TO ${quote(dialect, draft.name)}`);
+    }
+    return statements;
+};

package/src/ddl/alter.ts

@@ -0,0 +1,29 @@
+import type { TableStructure } from '../protocol/index.ts';
+import { mysqlAlterSql } from './alter-mysql.ts';
+import { sqliteAlterSql } from './alter-sqlite.ts';
+import type { Dialect } from './dialect.ts';
+import { diffOf, type TableDiff } from './diff.ts';
+import { draftOf, type TableDraft } from './draft.ts';
+
+const unchanged = (diff: TableDiff): boolean =>
+    !diff.renamed &&
+    !diff.optionsChanged &&
+    !diff.primaryKeyChanged &&
+    diff.droppedColumns.length === 0 &&
+    diff.addedColumns.length === 0 &&
+    diff.keptColumns.every((kept) => !kept.renamed && !kept.redefined && !kept.moved) &&
+    diff.droppedIndexes.length === 0 &&
+    diff.addedIndexes.length === 0 &&
+    diff.renamedIndexes.length === 0 &&
+    diff.droppedForeignKeys.length === 0 &&
+    diff.addedForeignKeys.length === 0;
+
+/* The fewest statements that turn the table of `structure` into the draft; none when the draft changes nothing. */
+export const alterTableSql = (dialect: Dialect, schema: string, structure: TableStructure, draft: TableDraft): string[] => {
+    const original = draftOf(structure);
+    const diff = diffOf(dialect, original, draft);
+    if (unchanged(diff)) {
+        return [];
+    }
+    return dialect.engine === 'sqlite' ? sqliteAlterSql(dialect, schema, original, draft, diff) : mysqlAlterSql(dialect, schema, original, draft, diff);
+};

package/src/ddl/column.ts

@@ -0,0 +1,74 @@
+import { sqlLiteral } from '../sql.ts';
+import { quote, type Dialect } from './dialect.ts';
+import type { ColumnDraft } from './draft.ts';
+
+const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+const STRING = /^'(?:[^']|'')*'$/;
+const KEYWORD = /^(?:NULL|TRUE|FALSE|CURRENT_DATE|CURRENT_TIME(?:\(\d*\))?|CURRENT_TIMESTAMP(?:\(\d*\))?|LOCALTIME(?:STAMP)?(?:\(\d*\))?|NOW\(\d*\))$/i;
+
+/*
+ * The text after `DEFAULT`. A literal and the few keywords both engines take stand as written; any
+ * other expression goes in parentheses, which SQLite and MySQL 8 need for one that is not constant.
+ */
+export const defaultClause = (expression: string): string => {
+    const text = expression.trim();
+    if (NUMBER.test(text) || STRING.test(text) || KEYWORD.test(text)) {
+        return text;
+    }
+    return text.startsWith('(') && text.endsWith(')') ? text : `(${text})`;
+};
+
+export interface ColumnSqlOptions {
+    /* SQLite only: the column is the whole primary key, which an `AUTOINCREMENT` has to be declared on. */
+    readonly inlinePrimaryKey?: boolean;
+}
+
+/* A column's definition without its name: `varchar(255) NOT NULL DEFAULT 'x'`. */
+export const columnSpecSql = (dialect: Dialect, column: ColumnDraft, { inlinePrimaryKey = false }: ColumnSqlOptions = {}): string => {
+    const mysql = dialect.engine === 'mysql';
+    const parts: string[] = [];
+    if (column.type !== '') {
+        parts.push(column.type);
+    }
+    if (column.generated && column.generatedClause !== null) {
+        parts.push(column.generatedClause);
+    }
+    if (inlinePrimaryKey) {
+        parts.push(column.autoIncrement ? 'PRIMARY KEY AUTOINCREMENT' : 'PRIMARY KEY');
+    }
+    // MariaDB takes neither NULL nor NOT NULL after the expression of a computed column.
+    if (column.generated && dialect.flavor === 'mariadb') {
+        // The expression says everything.
+    } else if (!column.nullable) {
+        parts.push('NOT NULL');
+    } else if (mysql) {
+        // MySQL gives a TIMESTAMP column NOT NULL unless it is told otherwise.
+        parts.push('NULL');
+    }
+    if (!column.generated) {
+        if (column.defaultValue !== null && column.defaultValue.trim() !== '') {
+            parts.push(`DEFAULT ${defaultClause(column.defaultValue)}`);
+        }
+        if (mysql && column.autoIncrement) {
+            parts.push('AUTO_INCREMENT');
+        }
+    }
+    if (mysql && column.comment !== '') {
+        parts.push(`COMMENT ${sqlLiteral('mysql', column.comment)}`);
+    }
+    return parts.join(' ');
+};
+
+export const columnSql = (dialect: Dialect, column: ColumnDraft, options?: ColumnSqlOptions): string =>
+    `${quote(dialect, column.name)} ${columnSpecSql(dialect, column, options)}`.trimEnd();
+
+const typeKey = (type: string): string => type.toLowerCase().replace(/\s+/g, ' ').trim();
+
+/* Whether two columns are defined alike, whatever their names. SQLite keeps no comments, so they never differ there. */
+export const sameDefinition = (dialect: Dialect, left: ColumnDraft, right: ColumnDraft): boolean =>
+    typeKey(left.type) === typeKey(right.type) &&
+    left.nullable === right.nullable &&
+    (left.defaultValue ?? '').trim() === (right.defaultValue ?? '').trim() &&
+    left.autoIncrement === right.autoIncrement &&
+    (dialect.engine === 'sqlite' || left.comment === right.comment) &&
+    left.generatedClause === right.generatedClause;

package/src/ddl/create.ts

@@ -0,0 +1,92 @@
+import { sqlLiteral } from '../sql.ts';
+import { columnSql } from './column.ts';
+import { columnList, quote, sqliteSchemaPrefix, tableName, type Dialect } from './dialect.ts';
+import { isAutoIndex, type ForeignKeyDraft, type IndexDraft, type TableDraft } from './draft.ts';
+import type { TableOptions } from './parse.ts';
+
+const INDENT = '    ';
+
+/* `CONSTRAINT name FOREIGN KEY (...) REFERENCES t (...) ON UPDATE .. ON DELETE ..`, shared by a create and an `ADD`. */
+export const foreignKeySql = (dialect: Dialect, schema: string, foreignKey: ForeignKeyDraft): string => {
+    const sqlite = dialect.engine === 'sqlite';
+    // SQLite cannot name another schema in a reference, and MySQL needs one only for another database.
+    const target =
+        sqlite || foreignKey.referencedSchema === '' || foreignKey.referencedSchema === schema
+            ? quote(dialect, foreignKey.referencedTable)
+            : `${quote(dialect, foreignKey.referencedSchema)}.${quote(dialect, foreignKey.referencedTable)}`;
+    const parts = [
+        ...(foreignKey.name === '' ? [] : [`CONSTRAINT ${quote(dialect, foreignKey.name)}`]),
+        `FOREIGN KEY (${columnList(dialect, foreignKey.columns)})`,
+        `REFERENCES ${target} (${columnList(dialect, foreignKey.referencedColumns)})`
+    ];
+    if (foreignKey.onUpdate !== null) {
+        parts.push(`ON UPDATE ${foreignKey.onUpdate}`);
+    }
+    if (foreignKey.onDelete !== null) {
+        parts.push(`ON DELETE ${foreignKey.onDelete}`);
+    }
+    return parts.join(' ');
+};
+
+/* `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ...`: the options that say something, and with `against` only those that differ from it. */
+export const mysqlOptionsSql = (options: TableOptions, against?: TableOptions): string[] => {
+    // Only a comment can be emptied; an engine, a character set or a collation has no empty value to ask for.
+    const changed = (field: 'engine' | 'charset' | 'collation' | 'comment'): boolean =>
+        options[field] !== against?.[field] && (options[field] !== '' || (field === 'comment' && against !== undefined));
+    return [
+        ...(changed('engine') ? [`ENGINE=${options.engine}`] : []),
+        ...(changed('charset') ? [`DEFAULT CHARSET=${options.charset}`] : []),
+        ...(changed('collation') ? [`COLLATE=${options.collation}`] : []),
+        ...(changed('comment') ? [`COMMENT=${sqlLiteral('mysql', options.comment)}`] : [])
+    ];
+};
+
+const sqliteOptionsSql = (options: TableOptions): string[] => [...(options.strict ? ['STRICT'] : []), ...(options.withoutRowid ? ['WITHOUT ROWID'] : [])];
+
+const inlineIndexSql = (dialect: Dialect, index: IndexDraft): string =>
+    [index.unique ? 'UNIQUE INDEX' : 'INDEX', ...(index.name === '' ? [] : [quote(dialect, index.name)]), `(${columnList(dialect, index.columns)})`].join(' ');
+
+/* `CREATE [UNIQUE] INDEX name ON table (columns)`. */
+export const createIndexSql = (dialect: Dialect, schema: string, table: string, index: Pick<IndexDraft, 'name' | 'columns' | 'unique'>): string =>
+    `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX ${dialect.engine === 'sqlite' ? sqliteSchemaPrefix(dialect, schema) : ''}${quote(dialect, index.name)} ON ${tableName(dialect, dialect.engine === 'sqlite' ? '' : schema, table)} (${columnList(dialect, index.columns)})`;
+
+export interface CreateParts {
+    readonly table: string;
+    /* SQLite creates its indexes after the table, where MySQL declares them inside it. */
+    readonly indexes: readonly IndexDraft[];
+}
+
+/* The `CREATE TABLE` of a draft under a name of the caller's choosing, which a rebuild uses for the table it fills before the swap. */
+export const createTableParts = (dialect: Dialect, schema: string, draft: TableDraft, name: string): CreateParts => {
+    const sqlite = dialect.engine === 'sqlite';
+    // SQLite declares AUTOINCREMENT on the column itself, which then is the whole primary key; a WITHOUT ROWID table has no rowid to count.
+    const autoColumn =
+        sqlite && draft.primaryKey.length === 1 && !draft.options.withoutRowid
+            ? draft.columns.find((column) => column.name === draft.primaryKey[0] && column.autoIncrement)?.name
+            : undefined;
+    const lines = draft.columns.map((column) => columnSql(dialect, column, { inlinePrimaryKey: column.name === autoColumn }));
+    if (draft.primaryKey.length > 0 && autoColumn === undefined) {
+        lines.push(`PRIMARY KEY (${columnList(dialect, draft.primaryKey)})`);
+    }
+    const separate: IndexDraft[] = [];
+    for (const index of draft.indexes) {
+        if (!sqlite) {
+            lines.push(inlineIndexSql(dialect, index));
+        } else if (isAutoIndex(index.name) && index.unique) {
+            lines.push(`UNIQUE (${columnList(dialect, index.columns)})`);
+        } else if (!isAutoIndex(index.name)) {
+            separate.push(index);
+        }
+    }
+    for (const foreignKey of draft.foreignKeys) {
+        lines.push(foreignKeySql(dialect, schema, foreignKey));
+    }
+    const options = sqlite ? sqliteOptionsSql(draft.options).join(', ') : mysqlOptionsSql(draft.options).join(' ');
+    const head = `CREATE TABLE ${tableName(dialect, schema, name)} (\n${lines.map((line) => INDENT + line).join(',\n')}\n)`;
+    return { table: options === '' ? head : `${head} ${options}`, indexes: separate };
+};
+
+export const createTableSql = (dialect: Dialect, schema: string, draft: TableDraft): string[] => {
+    const { table, indexes } = createTableParts(dialect, schema, draft, draft.name);
+    return [table, ...indexes.map((index) => createIndexSql(dialect, schema, draft.name, index))];
+};

package/src/ddl/dialect.ts

@@ -0,0 +1,53 @@
+import type { Engine, ServerInfo } from '../protocol/index.ts';
+import { qualifiedName, quoteIdentifier } from '../sql.ts';
+
+/* The SQL a server speaks: the engine picks the quoting and the shape of a statement, the version what that server can do without a rebuild. */
+export interface Dialect {
+    readonly flavor: ServerInfo['flavor'];
+    readonly engine: Engine;
+    /* The numbers of the version, such as `[3, 45, 1]`; empty when the server's text holds none. */
+    readonly version: readonly number[];
+}
+
+const VERSION = /(\d+(?:\.\d+)*)/;
+
+export const dialectOf = (server: ServerInfo): Dialect => ({
+    flavor: server.flavor,
+    engine: server.flavor === 'sqlite' ? 'sqlite' : 'mysql',
+    version: (VERSION.exec(server.version)?.[1] ?? '')
+        .split('.')
+        .filter((part) => part !== '')
+        .map(Number)
+});
+
+/* Whether the server is at least this version. A version nobody could read counts as new enough. */
+export const atLeast = (dialect: Dialect, ...wanted: number[]): boolean => {
+    if (dialect.version.length === 0) {
+        return true;
+    }
+    for (let i = 0; i < wanted.length; i++) {
+        const have = dialect.version[i] ?? 0;
+        if (have !== wanted[i]) {
+            return have > wanted[i]!;
+        }
+    }
+    return true;
+};
+
+export const quote = (dialect: Dialect, name: string): string => quoteIdentifier(dialect.engine, name);
+
+/* SQLite reads an unqualified name as `main`, so only an attached schema is spelled out. */
+const schemaOf = (dialect: Dialect, schema: string): string | undefined =>
+    schema === '' || (dialect.engine === 'sqlite' && schema === 'main') ? undefined : schema;
+
+/* A table with its schema in front, when the statement needs one. */
+export const tableName = (dialect: Dialect, schema: string, table: string): string =>
+    qualifiedName({ engine: dialect.engine, table, schema: schemaOf(dialect, schema) });
+
+/* SQLite puts the schema in front of the name of an index, where MySQL names the table it is on. */
+export const sqliteSchemaPrefix = (dialect: Dialect, schema: string): string => {
+    const named = schemaOf(dialect, schema);
+    return named === undefined ? '' : `${quote(dialect, named)}.`;
+};
+
+export const columnList = (dialect: Dialect, columns: readonly string[]): string => columns.map((column) => quote(dialect, column)).join(', ');

package/src/ddl/diff.ts

@@ -0,0 +1,164 @@
+import { sameDefinition } from './column.ts';
+import type { Dialect } from './dialect.ts';
+import type { ColumnDraft, ForeignKeyDraft, IndexDraft, TableDraft } from './draft.ts';
+import type { TableOptions } from './parse.ts';
+
+export interface KeptColumn {
+    readonly original: ColumnDraft;
+    readonly column: ColumnDraft;
+    readonly renamed: boolean;
+    readonly redefined: boolean;
+    /* It sits elsewhere among the columns that stay, which only a position clause can say. */
+    readonly moved: boolean;
+    /* The column before it in the draft, or `null` when it is the first. */
+    readonly after: string | null;
+}
+
+export interface AddedColumn {
+    readonly column: ColumnDraft;
+    /* Whether a column that stays comes after it, so that it cannot simply go to the end. */
+    readonly placed: boolean;
+    readonly after: string | null;
+}
+
+export interface RenamedIndex {
+    readonly from: IndexDraft;
+    readonly to: IndexDraft;
+}
+
+export interface TableDiff {
+    readonly renamed: boolean;
+    readonly droppedColumns: readonly ColumnDraft[];
+    readonly keptColumns: readonly KeptColumn[];
+    readonly addedColumns: readonly AddedColumn[];
+    readonly primaryKeyChanged: boolean;
+    /* As the original named them: an index that is gone and one that has to be made again. */
+    readonly droppedIndexes: readonly IndexDraft[];
+    readonly addedIndexes: readonly IndexDraft[];
+    readonly renamedIndexes: readonly RenamedIndex[];
+    readonly droppedForeignKeys: readonly ForeignKeyDraft[];
+    readonly addedForeignKeys: readonly ForeignKeyDraft[];
+    readonly optionsChanged: boolean;
+}
+
+const sameList = (left: readonly string[], right: readonly string[]): boolean => left.length === right.length && left.every((name, at) => name === right[at]);
+
+/* The positions of a longest run that already is in order: those columns can stay where they are. */
+const longestRun = (positions: readonly number[]): ReadonlySet<number> => {
+    const length: number[] = [];
+    const previous: number[] = [];
+    let best = -1;
+    for (let i = 0; i < positions.length; i++) {
+        length[i] = 1;
+        previous[i] = -1;
+        for (let before = 0; before < i; before++) {
+            if (positions[before]! < positions[i]! && length[before]! + 1 > length[i]!) {
+                length[i] = length[before]! + 1;
+                previous[i] = before;
+            }
+        }
+        if (best < 0 || length[i]! > length[best]!) {
+            best = i;
+        }
+    }
+    const run = new Set<number>();
+    for (let at = best; at >= 0; at = previous[at]!) {
+        run.add(at);
+    }
+    return run;
+};
+
+const OPTION_FIELDS: readonly (keyof TableOptions)[] = ['engine', 'charset', 'collation', 'comment', 'withoutRowid', 'strict'];
+
+const matches = (original: { readonly name: string; readonly key: string }, draft: { readonly originalName: string | null; readonly key: string }): boolean =>
+    draft.originalName !== null && (original.name === '' ? draft.key === original.key : draft.originalName === original.name);
+
+/* What a draft changes in the table it came from, told apart by the names items kept. */
+export const diffOf = (dialect: Dialect, original: TableDraft, draft: TableDraft): TableDiff => {
+    const survivors = draft.columns.filter((column) => column.originalName !== null);
+    const renames = new Map(survivors.map((column) => [column.originalName!, column.name]));
+    const project = (names: readonly string[]): string[] => names.map((name) => renames.get(name) ?? name);
+    const originalOf = (name: string): ColumnDraft | undefined => original.columns.find((column) => column.name === name);
+
+    const positions = survivors.map((column) => original.columns.findIndex((candidate) => candidate.name === column.originalName));
+    const staying = longestRun(positions);
+    let survivor = 0;
+    const keptColumns: KeptColumn[] = [];
+    const addedColumns: AddedColumn[] = [];
+    draft.columns.forEach((column, at) => {
+        const after = at === 0 ? null : draft.columns[at - 1]!.name;
+        if (column.originalName === null) {
+            addedColumns.push({ column, placed: draft.columns.slice(at + 1).some((later) => later.originalName !== null), after });
+            return;
+        }
+        const rank = survivor++;
+        const before = originalOf(column.originalName);
+        if (before === undefined) {
+            return;
+        }
+        keptColumns.push({
+            original: before,
+            column,
+            renamed: before.name !== column.name,
+            redefined: !sameDefinition(dialect, before, column),
+            moved: !staying.has(rank),
+            after
+        });
+    });
+
+    const droppedColumns = original.columns.filter((column) => !survivors.some((kept) => kept.originalName === column.name));
+
+    const droppedIndexes: IndexDraft[] = [];
+    const addedIndexes = draft.indexes.filter((index) => index.originalName === null);
+    const renamedIndexes: RenamedIndex[] = [];
+    for (const before of original.indexes) {
+        const after = draft.indexes.find((index) => matches(before, index));
+        if (after === undefined) {
+            droppedIndexes.push(before);
+        } else if (!sameList(project(before.columns), after.columns) || before.unique !== after.unique) {
+            droppedIndexes.push(before);
+            addedIndexes.push(after);
+        } else if (before.name !== after.name) {
+            renamedIndexes.push({ from: before, to: after });
+        }
+    }
+
+    const droppedForeignKeys: ForeignKeyDraft[] = [];
+    const addedForeignKeys = draft.foreignKeys.filter((key) => key.originalName === null);
+    for (const before of original.foreignKeys) {
+        const after = draft.foreignKeys.find((key) => matches(before, key));
+        const same =
+            after !== undefined &&
+            before.name === after.name &&
+            sameList(project(before.columns), after.columns) &&
+            before.referencedSchema === after.referencedSchema &&
+            before.referencedTable === after.referencedTable &&
+            sameList(before.referencedColumns, after.referencedColumns) &&
+            before.onUpdate === after.onUpdate &&
+            before.onDelete === after.onDelete;
+        if (!same) {
+            droppedForeignKeys.push(before);
+            if (after !== undefined) {
+                addedForeignKeys.push(after);
+            }
+        }
+    }
+
+    return {
+        renamed: original.name !== draft.name,
+        droppedColumns,
+        keptColumns,
+        addedColumns,
+        primaryKeyChanged: !sameList(project(original.primaryKey), draft.primaryKey),
+        droppedIndexes,
+        addedIndexes,
+        renamedIndexes,
+        droppedForeignKeys,
+        addedForeignKeys,
+        optionsChanged: OPTION_FIELDS.some((field) => original.options[field] !== draft.options[field])
+    };
+};
+
+/* Whether applying the draft removes a column, and with it the data in it. */
+export const dropsColumns = (original: TableDraft, draft: TableDraft): boolean =>
+    original.columns.some((column) => !draft.columns.some((kept) => kept.originalName === column.name));

package/src/ddl/draft.ts

@@ -0,0 +1,136 @@
+import type { ForeignKeyInfo, TableStructure } from '../protocol/index.ts';
+import { generatedClausesOf, NO_OPTIONS, optionsOf, type TableOptions } from './parse.ts';
+
+/*
+ * Every item keeps the name it had in the structure it came from, so a rename is told apart from a
+ * drop plus an add. `originalName` is `null` for an item the person added. `key` is stable while
+ * the item is edited, which a name is not.
+ */
+export interface ColumnDraft {
+    readonly key: string;
+    readonly originalName: string | null;
+    readonly name: string;
+    /* The type as typed, such as `varchar(255)`; empty for an SQLite column without one. */
+    readonly type: string;
+    readonly nullable: boolean;
+    /* An SQL expression such as `'draft'` or `CURRENT_TIMESTAMP`; `null` is no default. */
+    readonly defaultValue: string | null;
+    readonly autoIncrement: boolean;
+    /* Empty for no comment. */
+    readonly comment: string;
+    /* A column the server computes. It is read only here: its clause travels along unchanged. */
+    readonly generated: boolean;
+    /* `GENERATED ALWAYS AS (...) STORED` as the table's DDL says it; `null` when the DDL did not show it. */
+    readonly generatedClause: string | null;
+}
+
+export interface IndexDraft {
+    readonly key: string;
+    readonly originalName: string | null;
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+}
+
+export interface ForeignKeyDraft {
+    readonly key: string;
+    /* An SQLite foreign key without a name has the empty string; `null` is a key the person added. */
+    readonly originalName: string | null;
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly referencedSchema: string;
+    readonly referencedTable: string;
+    readonly referencedColumns: readonly string[];
+    /* `null` is the engine's default. */
+    readonly onUpdate: string | null;
+    readonly onDelete: string | null;
+}
+
+export interface TableDraft {
+    /* `null` for a table that does not exist yet. */
+    readonly originalName: string | null;
+    readonly name: string;
+    readonly columns: readonly ColumnDraft[];
+    /* Names of columns of the draft, in key order. */
+    readonly primaryKey: readonly string[];
+    /* Without the primary key, which has its own field. */
+    readonly indexes: readonly IndexDraft[];
+    readonly foreignKeys: readonly ForeignKeyDraft[];
+    readonly options: TableOptions;
+}
+
+let counter = 0;
+
+/* A key no other item of this page has. */
+export const nextKey = (): string => `new-${++counter}`;
+
+export const emptyColumn = (name = ''): ColumnDraft => ({
+    key: nextKey(),
+    originalName: null,
+    name,
+    type: '',
+    nullable: true,
+    defaultValue: null,
+    autoIncrement: false,
+    comment: '',
+    generated: false,
+    generatedClause: null
+});
+
+export const emptyDraft = (): TableDraft => ({
+    originalName: null,
+    name: '',
+    columns: [],
+    primaryKey: [],
+    indexes: [],
+    foreignKeys: [],
+    options: NO_OPTIONS
+});
+
+/* SQLite names the index behind a `UNIQUE` or `PRIMARY KEY` constraint itself; such an index cannot be created or dropped by name. */
+export const isAutoIndex = (name: string): boolean => name.startsWith('sqlite_autoindex_');
+
+const foreignKeyDraftOf = (foreignKey: ForeignKeyInfo, at: number): ForeignKeyDraft => ({
+    key: `foreign-key:${at}`,
+    originalName: foreignKey.name ?? '',
+    name: foreignKey.name ?? '',
+    columns: foreignKey.columns,
+    referencedSchema: foreignKey.referencedSchema,
+    referencedTable: foreignKey.referencedTable,
+    referencedColumns: foreignKey.referencedColumns,
+    onUpdate: foreignKey.onUpdate,
+    onDelete: foreignKey.onDelete
+});
+
+/* The draft that changes nothing: what a structure already says. */
+export const draftOf = (structure: TableStructure): TableDraft => {
+    const clauses = generatedClausesOf(structure.ddl);
+    return {
+        originalName: structure.name,
+        name: structure.name,
+        columns: structure.columns.map((column) => ({
+            key: `column:${column.name}`,
+            originalName: column.name,
+            name: column.name,
+            type: column.type,
+            nullable: column.nullable,
+            defaultValue: column.defaultValue,
+            autoIncrement: column.autoIncrement,
+            comment: column.comment ?? '',
+            generated: column.generated,
+            generatedClause: column.generated ? (clauses.get(column.name) ?? null) : null
+        })),
+        primaryKey: structure.primaryKey,
+        indexes: structure.indexes
+            .filter((index) => !index.primary)
+            .map((index) => ({
+                key: `index:${index.name}`,
+                originalName: index.name,
+                name: index.name,
+                columns: index.columns,
+                unique: index.unique
+            })),
+        foreignKeys: structure.foreignKeys.map(foreignKeyDraftOf),
+        options: optionsOf(structure)
+    };
+};

package/src/ddl/index.ts

@@ -0,0 +1,10 @@
+export { alterTableSql } from './alter.ts';
+export { columnSpecSql, defaultClause } from './column.ts';
+export { createIndexSql, createTableSql } from './create.ts';
+export { atLeast, dialectOf, type Dialect } from './dialect.ts';
+export { diffOf, dropsColumns, type TableDiff } from './diff.ts';
+export { draftOf, emptyColumn, emptyDraft, isAutoIndex, nextKey, type ColumnDraft, type ForeignKeyDraft, type IndexDraft, type TableDraft } from './draft.ts';
+export { NO_OPTIONS, optionsOf, type TableOptions } from './parse.ts';
+export { dropIndexSql, dropTableSql, dropViewSql, renameTableSql, truncateTableSql } from './statements.ts';
+export { FOREIGN_KEY_ACTIONS, MYSQL_CHARSETS, MYSQL_ENGINES, collationSuggestionsOf, typeSuggestionsOf } from './types.ts';
+export { validateDraft, type DraftProblem } from './validate.ts';