@eltjs/elt-sqlite 0.0.0-stage → 0.1.0

package/dist/sqlite-column.js

@@ -0,0 +1,306 @@
+import { FileRead, isCalendarDate, isTimestamp } from '@eltjs/elt';
+// STRICT tables accept only these types, so dates and times are their
+// canonical ISO text, which sorts in time order, and exact decimals are text.
+const storageTypes = {
+    text: 'TEXT',
+    integer: 'INTEGER',
+    int64: 'INTEGER',
+    real: 'REAL',
+    decimal: 'TEXT',
+    blob: 'BLOB',
+    boolean: 'INTEGER',
+    date: 'TEXT',
+    timestamp: 'TEXT',
+    local_timestamp: 'TEXT',
+    local_time: 'TEXT',
+    // An object of scalar fields, only as an item of an array column.
+    object: 'TEXT',
+};
+// The kind that stores each string format; base64 text loads as its bytes.
+const formatKinds = {
+    'date-time': 'timestamp',
+    date: 'date',
+    'date-time-local': 'local_timestamp',
+    'time-local': 'local_time',
+    int64: 'int64',
+    decimal: 'decimal',
+    base64: 'blob',
+};
+const plainKinds = new Set([
+    'text',
+    'integer',
+    'real',
+    'blob',
+    'boolean',
+    'date',
+    'timestamp',
+    'object',
+]);
+// GLOB for a fraction of a second with exactly this many digits.
+const fraction = (precision) => precision === 0 ? '' : `.${'[0-9]'.repeat(precision)}`;
+// Whether the first 19 characters name a real second of the calendar.
+const realSecond = (name) => `strftime('%Y-%m-%dT%H:%M:%S', substr(${name}, 1, 19)) IS substr(${name}, 1, 19)`;
+// A CHECK that keeps a value of the kind in its canonical form.
+export function canonical(kind, name, format) {
+    switch (kind) {
+        case 'boolean':
+            return ` CHECK (${name} IN (0, 1))`;
+        case 'date':
+            return ` CHECK (date(${name}) IS ${name})`;
+        case 'timestamp': {
+            const precision = format?.name === 'date-time' ? format.precision : 3;
+            return precision === 3
+                ? ` CHECK (strftime('%Y-%m-%dT%H:%M:%fZ', ${name}) IS ${name})`
+                : ` CHECK (${realSecond(name)} AND substr(${name}, 20) GLOB '${fraction(precision)}Z')`;
+        }
+        case 'local_timestamp':
+            return format?.name === 'date-time-local'
+                ? ` CHECK (${realSecond(name)} AND substr(${name}, 20) GLOB '${fraction(format.precision)}')`
+                : '';
+        case 'local_time':
+            return format?.name === 'time-local'
+                ? ` CHECK (time(substr(${name}, 1, 8)) IS substr(${name}, 1, 8) AND substr(${name}, 9) GLOB '${fraction(format.precision)}')`
+                : '';
+        default:
+            return '';
+    }
+}
+export class SQLiteColumn {
+    // The record field the column holds.
+    field;
+    // What SQLite calls the column, which the table it belongs to decides.
+    name;
+    type;
+    kind;
+    isPrimaryKey;
+    nullable;
+    optional;
+    // An array of kind, stored as a JSON array in TEXT.
+    array;
+    fileRead;
+    constructor(field, type, options) {
+        if (typeof field !== 'string')
+            throw new TypeError('A column holds a field named by a string');
+        if (typeof type === 'string' && !plainKinds.has(type))
+            throw new TypeError('Unsupported SQLite column type');
+        this.type = type;
+        const kind = typeof type === 'string' ? type : formatKinds[type.name];
+        this.array = options.array ?? false;
+        if (this.array && (kind === 'blob' || options.primaryKey))
+            throw new TypeError('Array columns hold scalar values or objects and cannot be keys');
+        this.fileRead = options.fileRead;
+        if (this.fileRead !== undefined &&
+            (!(this.fileRead instanceof FileRead) || this.fileRead.name !== field))
+            throw new TypeError('Column file read must match its field');
+        this.field = field;
+        this.name = options.name ?? field;
+        this.kind = kind;
+        this.isPrimaryKey = options.primaryKey;
+        this.nullable = !options.primaryKey && options.nullable;
+        this.optional = !options.primaryKey && options.optional;
+        Object.freeze(this);
+    }
+    primaryKey() {
+        return new SQLiteColumn(this.field, this.type, {
+            nullable: false,
+            optional: false,
+            primaryKey: true,
+            array: this.array,
+            fileRead: this.fileRead,
+            name: this.name,
+        });
+    }
+    notNull() {
+        return new SQLiteColumn(this.field, this.type, {
+            nullable: false,
+            optional: false,
+            primaryKey: this.isPrimaryKey,
+            array: this.array,
+            fileRead: this.fileRead,
+            name: this.name,
+        });
+    }
+    from(file) {
+        if (this.array || (this.kind !== 'blob' && this.kind !== 'text'))
+            throw new TypeError('Files require a BLOB column, parsed TEXT or a stored TEXT reference');
+        return new SQLiteColumn(this.field, this.kind, {
+            nullable: this.nullable,
+            optional: this.optional,
+            primaryKey: this.isPrimaryKey,
+            fileRead: new FileRead(this.field, file, this.fileRead?.parser),
+            name: this.name,
+        });
+    }
+    parse(parser) {
+        if (this.kind !== 'text')
+            throw new TypeError('Document parsing requires a TEXT column');
+        if (this.fileRead === undefined)
+            throw new TypeError('Select a source file before selecting a parser');
+        return new SQLiteColumn(this.field, this.kind, {
+            nullable: this.nullable,
+            optional: this.optional,
+            primaryKey: this.isPrimaryKey,
+            fileRead: new FileRead(this.field, this.fileRead.file, parser),
+            name: this.name,
+        });
+    }
+    // This column as the table names it.
+    named(name) {
+        return new SQLiteColumn(this.field, this.type, {
+            nullable: this.nullable,
+            optional: this.optional,
+            primaryKey: this.isPrimaryKey,
+            array: this.array,
+            fileRead: this.fileRead,
+            name,
+        });
+    }
+    get quotedName() {
+        return `"${this.name.replaceAll('"', '""')}"`;
+    }
+    // Original file bytes live in a chunk table; the column keeps the file's id.
+    get storesFile() {
+        return this.kind === 'blob' && this.fileRead !== undefined;
+    }
+    get storageType() {
+        if (this.array)
+            return 'TEXT';
+        return this.storesFile ? 'INTEGER' : storageTypes[this.kind];
+    }
+    // The column's type as readers see it in the catalog.
+    get dataType() {
+        if (this.storesFile)
+            return 'integer';
+        return this.array ? `${this.#typeName}[]` : this.#typeName;
+    }
+    // The kind with the precision and scale its format declares, as SQL writes
+    // them; a timestamp of milliseconds is the plain kind.
+    get #typeName() {
+        const { type } = this;
+        if (typeof type === 'string')
+            return type;
+        switch (type.name) {
+            case 'date-time':
+                return type.precision === 3
+                    ? this.kind
+                    : `${this.kind}(${type.precision})`;
+            case 'date-time-local':
+            case 'time-local':
+                return `${this.kind}(${type.precision})`;
+            case 'decimal':
+                return type.precision === undefined
+                    ? this.kind
+                    : `${this.kind}(${[type.precision, type.scale ?? []].join(',')})`;
+            default:
+                return this.kind;
+        }
+    }
+    get definition() {
+        const check = this.array
+            ? ` CHECK (json_valid(${this.quotedName}) AND json_type(${this.quotedName}) = 'array')`
+            : canonical(this.kind, this.quotedName, typeof this.type === 'string' ? undefined : this.type);
+        // A field the stream requires stays nullable in storage: rows loaded
+        // before it was added have no value for it. Records are still checked for
+        // it when they are written (encode).
+        return `${this.quotedName} ${this.storageType}${this.isPrimaryKey ? ' PRIMARY KEY NOT NULL' : ''}${check}`;
+    }
+    encode(record) {
+        if (record === null || typeof record !== 'object' || Array.isArray(record))
+            throw new TypeError(`Record is missing field ${JSON.stringify(this.field)}`);
+        if (!Object.hasOwn(record, this.field)) {
+            if (this.optional)
+                return null;
+            throw new TypeError(`Record is missing field ${JSON.stringify(this.field)}`);
+        }
+        const value = Reflect.get(record, this.field);
+        if (value === null && this.nullable)
+            return null;
+        const { type } = this;
+        if (this.array) {
+            if (Array.isArray(value) &&
+                value.every((element) => this.#element(element)))
+                return JSON.stringify(value);
+            throw new TypeError(`Field ${JSON.stringify(this.field)} requires an array of ${this.kind}${this.nullable ? ' or null' : ' (not null)'}`);
+        }
+        if (typeof type !== 'string') {
+            if (typeof value === 'string' && type.accepts(value)) {
+                if (type.name === 'int64')
+                    return BigInt(value);
+                if (type.name === 'base64')
+                    return Buffer.from(value, 'base64');
+                return value;
+            }
+            throw new TypeError(`Field ${JSON.stringify(this.field)} requires a canonical ${type.name} value${this.nullable ? ' or null' : ' (not null)'}`);
+        }
+        switch (type) {
+            case 'text':
+                if (typeof value === 'string')
+                    return value;
+                break;
+            case 'boolean':
+                if (typeof value === 'boolean')
+                    return Number(value);
+                break;
+            case 'integer':
+                if ((typeof value === 'bigint' &&
+                    value >= -(2n ** 63n) &&
+                    value < 2n ** 63n) ||
+                    (typeof value === 'number' && Number.isSafeInteger(value)))
+                    return value;
+                break;
+            case 'date':
+                if (isCalendarDate(value))
+                    return value;
+                break;
+            case 'timestamp':
+                if (isTimestamp(value))
+                    return value;
+                break;
+            case 'real':
+                if (typeof value === 'number' && Number.isFinite(value))
+                    return value;
+                break;
+            case 'blob':
+                if (this.storesFile) {
+                    if (typeof value === 'number' && Number.isSafeInteger(value))
+                        return value;
+                }
+                else if (value instanceof Uint8Array)
+                    return value;
+                break;
+            // An object is only an array's item, which the array branch encodes.
+            case 'object':
+        }
+        throw new TypeError(`Field ${JSON.stringify(this.field)} requires ${this.kind}${this.nullable ? ' or null' : ' (not null)'}`);
+    }
+    // Whether a JSON array element keeps this kind's value exactly.
+    #element(value) {
+        const { type } = this;
+        if (typeof type !== 'string')
+            return typeof value === 'string' && type.accepts(value);
+        switch (type) {
+            case 'text':
+                return typeof value === 'string';
+            case 'boolean':
+                return typeof value === 'boolean';
+            case 'integer':
+                return Number.isSafeInteger(value);
+            case 'real':
+                return typeof value === 'number' && Number.isFinite(value);
+            case 'date':
+                return isCalendarDate(value);
+            case 'timestamp':
+                return isTimestamp(value);
+            case 'object':
+                return (value !== null &&
+                    typeof value === 'object' &&
+                    !Array.isArray(value) &&
+                    Object.values(value).every((field) => field === null ||
+                        typeof field === 'string' ||
+                        typeof field === 'boolean' ||
+                        (typeof field === 'number' && Number.isFinite(field))));
+            default:
+                return false;
+        }
+    }
+}

package/dist/sqlite-columns.d.ts

@@ -0,0 +1,14 @@
+import { type Stream } from '@eltjs/elt';
+import { SQLiteColumn } from './sqlite-column.ts';
+export declare class SQLiteColumns {
+    static fromSchema({ properties, required, }: Stream['jsonSchema']): readonly SQLiteColumn[];
+    text(field: string): SQLiteColumn;
+    integer(field: string): SQLiteColumn;
+    int64(field: string): SQLiteColumn;
+    real(field: string): SQLiteColumn;
+    date(field: string): SQLiteColumn;
+    timestamp(field: string): SQLiteColumn;
+    localTimestamp(field: string, precision: number): SQLiteColumn;
+    blob(field: string): SQLiteColumn;
+    boolean(field: string): SQLiteColumn;
+}

package/dist/sqlite-columns.js

@@ -0,0 +1,118 @@
+import { Int64Format, LocalTimestampFormat, declaredFormat, } from '@eltjs/elt';
+import { SQLiteColumn } from './sqlite-column.js';
+function scalarType(name, type, format) {
+    switch (type) {
+        case 'string':
+            return format ?? 'text';
+        case 'integer':
+            return 'integer';
+        case 'number':
+            return 'real';
+        case 'boolean':
+            return 'boolean';
+        case 'object':
+            return 'object';
+        default:
+            throw new TypeError(`Unsupported JSON Schema type for field ${name}: ${type}`);
+    }
+}
+// SQLite column declarations are independent of a source or connection.
+export class SQLiteColumns {
+    // Scalars, and arrays of scalars or of objects as JSON arrays in TEXT.
+    // String formats keep their kind, as in Postgres.
+    static fromSchema({ properties, required = [], }) {
+        if (properties === undefined)
+            throw new TypeError('SQLite requires an object schema with explicit properties');
+        const requiredFields = new Set(required);
+        for (const name of requiredFields)
+            if (!Object.hasOwn(properties, name))
+                throw new TypeError(`Schema does not describe field ${name}`);
+        return Object.entries(properties).map(([name, field]) => {
+            const types = typeof field.type === 'string' ? [field.type] : field.type;
+            if (new Set(types).size !== types.length)
+                throw new TypeError(`Unsupported JSON Schema type for field ${name}`);
+            const valueTypes = types.filter((type) => type !== 'null');
+            const valueType = valueTypes[0];
+            if (valueType === undefined || valueTypes.length !== 1)
+                throw new TypeError(`SQLite requires one scalar type for field ${name}`);
+            const array = valueType === 'array';
+            const items = array ? field.items : undefined;
+            if (array && items === undefined)
+                throw new TypeError(`Unsupported JSON Schema items for field ${name}`);
+            const format = declaredFormat(items ?? field);
+            return new SQLiteColumn(name, scalarType(name, items?.type ?? valueType, format), {
+                nullable: types.includes('null'),
+                optional: !requiredFields.has(name),
+                primaryKey: false,
+                array,
+            });
+        });
+    }
+    text(field) {
+        return new SQLiteColumn(field, 'text', {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+    integer(field) {
+        return new SQLiteColumn(field, 'integer', {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+    // A signed 64-bit integer, which a stream spells as decimal text (format
+    // int64), so a value past Number.MAX_SAFE_INTEGER keeps every digit.
+    int64(field) {
+        return new SQLiteColumn(field, new Int64Format(), {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+    real(field) {
+        return new SQLiteColumn(field, 'real', {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+    date(field) {
+        return new SQLiteColumn(field, 'date', {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+    timestamp(field) {
+        return new SQLiteColumn(field, 'timestamp', {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+    // A wall-clock date and time with no zone and precision digits of a second
+    // (format date-time-local), as SQL Server's datetime2 holds it.
+    localTimestamp(field, precision) {
+        return new SQLiteColumn(field, new LocalTimestampFormat(precision), {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+    blob(field) {
+        return new SQLiteColumn(field, 'blob', {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+    boolean(field) {
+        return new SQLiteColumn(field, 'boolean', {
+            nullable: true,
+            optional: false,
+            primaryKey: false,
+        });
+    }
+}

package/dist/sqlite-deduplicating-writer.d.ts

@@ -0,0 +1,21 @@
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite';
+import type { CopyConfiguration, Deduplication, KeyValue } from '@eltjs/elt';
+import type { SQLiteColumn } from './sqlite-column.ts';
+import type { SQLiteTable } from './sqlite-table.ts';
+import { SQLiteWriter } from './sqlite-writer.ts';
+export declare class SQLiteDeduplicatingWriter extends SQLiteWriter {
+    #private;
+    readonly deduplication: Deduplication;
+    readonly keys: readonly SQLiteColumn[];
+    readonly cursor?: SQLiteColumn;
+    constructor(configuration: CopyConfiguration, path: string, table: SQLiteTable);
+    protected get replaces(): boolean;
+    protected inspect(database: DatabaseSync): void;
+    protected initialize(database: DatabaseSync, replacing: boolean): void;
+    protected replace(database: DatabaseSync): void;
+    protected build(database: DatabaseSync, into: string): void;
+    protected adopt(database: DatabaseSync): void;
+    protected merge(database: DatabaseSync, stage: string, loadedAt: string, into: string): void;
+    protected encode(record: unknown): SQLInputValue[];
+    protected deletionKeys(key: Readonly<Record<string, KeyValue>>): readonly [readonly SQLiteColumn[], SQLInputValue[]];
+}

package/dist/sqlite-deduplicating-writer.js

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+import { SQLiteColumns } from './sqlite-columns.js';
+import { SQLiteWriter, op, seq } from './sqlite-writer.js';
+export class SQLiteDeduplicatingWriter extends SQLiteWriter {
+    deduplication;
+    keys;
+    cursor;
+    constructor(configuration, path, table) {
+        super(configuration, path, table);
+        this.deduplication = configuration.deduplication();
+        const inferred = SQLiteColumns.fromSchema(configuration.stream.jsonSchema);
+        const column = (field) => {
+            const selected = table.columns.find((column) => column.field === field);
+            if (selected === undefined)
+                throw new TypeError(`Deduplication requires destination column ${field}`);
+            if (selected.dataType !==
+                inferred.find((column) => column.field === field)?.dataType)
+                throw new TypeError(`Deduplication column ${field} must preserve the source scalar type`);
+            return selected;
+        };
+        this.keys = Object.freeze(this.deduplication.primaryKey.map(column));
+        const { cursorField } = this.deduplication;
+        this.cursor = cursorField === undefined ? undefined : column(cursorField);
+        Object.freeze(this);
+    }
+    get replaces() {
+        return this.configuration.destinationSyncMode === 'overwrite_dedup';
+    }
+    // Named after the table and its key, so a changed key builds a new index
+    // and an unchanged one is never rebuilt.
+    get #dedupIndex() {
+        return `_elt_dedup_${createHash('sha256')
+            .update(JSON.stringify([this.table.name, this.keys.map((key) => key.name)]))
+            .digest('hex')}`;
+    }
+    // A stored table the load merges into must hold keys and cursors of the
+    // stream's types, none null, and no key twice, which its index forbids once
+    // it exists.
+    inspect(database) {
+        const existing = database
+            .prepare(`PRAGMA table_info(${this.table.quotedName})`)
+            .all();
+        const tracked = this.cursor === undefined ? this.keys : [...this.keys, this.cursor];
+        for (const column of tracked) {
+            if (!existing.some((field) => field.name === column.name && field.type === column.storageType))
+                throw new TypeError(`Existing deduplication column ${column.name} has an incompatible storage type`);
+        }
+        if (database
+            .prepare(`SELECT 1 FROM ${this.table.quotedName} WHERE ${tracked.map((column) => `${column.quotedName} IS NULL`).join(' OR ')} LIMIT 1`)
+            .get())
+            throw new TypeError('Existing deduplication keys and cursors must be non-null');
+        if (database
+            .prepare(`SELECT 1 FROM sqlite_schema WHERE "type" = 'index' AND "name" = ?`)
+            .get(this.#dedupIndex) === undefined &&
+            database
+                .prepare(`SELECT 1 FROM ${this.table.quotedName} GROUP BY ${this.keys.map((column) => `${column.quotedName} COLLATE BINARY`).join(', ')} HAVING count(*) > 1 LIMIT 1`)
+                .get())
+            throw new TypeError('Existing rows repeat a deduplication key; replace them with overwrite_dedup before deduplicating incrementally');
+    }
+    // A replacing load keeps none of the stored rows: its index is built once
+    // the commit has emptied the table.
+    initialize(database, replacing) {
+        if (replacing)
+            this.dropDedupIndexes(database, this.#dedupIndex);
+        else
+            this.#index(database);
+    }
+    replace(database) {
+        super.replace(database);
+        this.#index(database);
+    }
+    // The target's key index, built only when it does not exist yet.
+    #index(database) {
+        this.dropDedupIndexes(database, this.#dedupIndex);
+        this.#unique(database, `"${this.#dedupIndex}"`, this.table.quotedName);
+    }
+    #unique(database, name, on) {
+        database.exec(`CREATE UNIQUE INDEX IF NOT EXISTS ${name} ON ${on} (${this.keys.map((column) => `${column.quotedName} COLLATE BINARY`).join(', ')})`);
+    }
+    // A reload's hidden target merges on its key from its first commit; SQLite
+    // cannot rename an index, so the target's own is built once it is swapped in.
+    get #provisionalIndex() {
+        return `"${this.#dedupIndex}_next"`;
+    }
+    build(database, into) {
+        this.#unique(database, this.#provisionalIndex, into);
+    }
+    adopt(database) {
+        database.exec(`DROP INDEX IF EXISTS ${this.#provisionalIndex}`);
+        this.#index(database);
+    }
+    // The result of applying the staged operations one at a time: a staged
+    // DELETE removes its key, and only records after a key's last DELETE count.
+    // replace keeps the newest extraction, so a restated fact overwrites the
+    // loaded one; cursor_newer keeps the greatest cursor (the first on ties) and
+    // the guard that rejects out-of-order replay.
+    merge(database, stage, loadedAt, into) {
+        const keys = this.keys.map((column) => column.quotedName);
+        const same = (left, right) => keys.map((key) => `${left}.${key} = ${right}.${key}`).join(' AND ');
+        database.exec(`DELETE FROM ${into} WHERE (${keys.join(', ')}) IN (SELECT ${keys.join(', ')} FROM ${stage} WHERE ${op} = 'D')`);
+        const { cursor } = this;
+        const guarded = this.configuration.dedupPolicy !== 'replace' && cursor !== undefined;
+        const order = guarded
+            ? `"staged".${cursor.quotedName} COLLATE BINARY DESC, "staged".${seq}`
+            : `"staged".${seq} DESC`;
+        // Rank identifiers only: sorting whole mail bodies/files multiplies temporary disk usage.
+        const columns = this.table.columns.map((column) => column.quotedName);
+        database
+            .prepare(`WITH "deleted" AS (SELECT ${keys.join(', ')}, max(${seq}) AS "_elt_last" FROM ${stage} WHERE ${op} = 'D' GROUP BY ${keys.join(', ')}), "ranked" AS (SELECT "staged".${seq}, row_number() OVER (PARTITION BY ${keys.map((key) => `"staged".${key}`).join(', ')} ORDER BY ${order}) AS "_elt_rank" FROM ${stage} AS "staged" LEFT JOIN "deleted" ON ${same('"deleted"', '"staged"')} WHERE "staged".${op} = 'R' AND ("deleted"."_elt_last" IS NULL OR "staged".${seq} > "deleted"."_elt_last")) ` +
+            `INSERT INTO ${into} AS "_elt_target" (${this.fields.join(', ')}) SELECT ${columns.join(', ')}, ? FROM ${stage} WHERE ${seq} IN (SELECT ${seq} FROM "ranked" WHERE "_elt_rank" = 1) ORDER BY ${seq} ` +
+            `ON CONFLICT (${keys.map((key) => `${key} COLLATE BINARY`).join(', ')}) DO UPDATE SET ${this.fields.map((field) => `${field} = excluded.${field}`).join(', ')}${guarded ? ` WHERE excluded.${cursor.quotedName} COLLATE BINARY > "_elt_target".${cursor.quotedName}` : ''}`)
+            .run(loadedAt);
+    }
+    encode(record) {
+        this.deduplication.key(record);
+        if (this.cursor !== undefined)
+            this.deduplication.cursor(record);
+        return super.encode(record);
+    }
+    deletionKeys(key) {
+        this.deduplication.key(key);
+        return [this.keys, this.keys.map((column) => column.encode(key))];
+    }
+}

package/dist/sqlite-descriptions.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare const descriptions = "\"_elt_descriptions\"";
+export type ColumnDescription = {
+    readonly description: string | null;
+    readonly dataType?: string;
+};
+export declare function createDescriptions(database: DatabaseSync): void;
+export declare function describe(database: DatabaseSync, relation: string, description: string, columns: Readonly<Record<string, ColumnDescription>>): void;

package/dist/sqlite-descriptions.js

@@ -0,0 +1,37 @@
+import { Declaration } from '@zukhruf/sqlite-drift';
+import { identifiers } from './sqlite-identifiers.js';
+// SQLite has no COMMENT ON. Relation and column meanings live here instead,
+// beside what they describe, and the catalog view shows them to readers.
+export const descriptions = '"_elt_descriptions"';
+const descriptionsTable = new Declaration([
+    `CREATE TABLE ${descriptions} ("relation" TEXT NOT NULL COLLATE NOCASE, "column" TEXT NOT NULL COLLATE NOCASE, "data_type" TEXT, "description" TEXT NOT NULL, PRIMARY KEY ("relation", "column")) STRICT`,
+], { rows: 'replace' });
+// A table another version declared otherwise is replaced; the next commit or
+// publication of each relation describes it again.
+export function createDescriptions(database) {
+    descriptionsTable.apply(database);
+}
+// Replaces what a relation says about itself and its columns; a column
+// without a description says nothing, as a Postgres comment set to NULL. A
+// column without a stated type keeps the type SQLite declares for it, read
+// here because the catalog view cannot: shells keep a schema untrusted, which
+// refuses pragma functions inside views.
+export function describe(database, relation, description, columns) {
+    createDescriptions(database);
+    database.exec(`DELETE FROM ${descriptions} WHERE "relation" NOT IN (SELECT "name" FROM sqlite_schema)`);
+    database
+        .prepare(`DELETE FROM ${descriptions} WHERE "relation" = ?`)
+        .run(relation);
+    const declared = new Map(database
+        .prepare('SELECT "name", "type" FROM pragma_table_info(?)')
+        .all(relation)
+        .map(({ name, type }) => [
+        identifiers.key(String(name)),
+        String(type).toLowerCase() || null,
+    ]));
+    const insert = database.prepare(`INSERT INTO ${descriptions} ("relation", "column", "data_type", "description") VALUES (?, ?, ?, ?)`);
+    insert.run(relation, '', null, description);
+    for (const [column, { description, dataType }] of Object.entries(columns))
+        if (description !== null)
+            insert.run(relation, column, dataType ?? declared.get(identifiers.key(column)) ?? null, description);
+}

package/dist/sqlite-destination.d.ts

@@ -0,0 +1,19 @@
+import type { CopyConfiguration, Load, PipelineClock } from '@eltjs/elt';
+import { Destination } from '@eltjs/elt';
+import type { SQLiteColumn } from './sqlite-column.ts';
+import { SQLiteColumns } from './sqlite-columns.ts';
+import { SQLiteTable } from './sqlite-table.ts';
+import type { SQLiteWriter } from './sqlite-writer.ts';
+export declare class SQLiteDestination extends Destination<SQLiteTable> {
+    readonly supportedDestinationSyncModes: readonly ["overwrite", "append", "append_dedup", "overwrite_dedup"];
+    readonly path: string;
+    constructor({ path }: {
+        path: string;
+    });
+    location(target: SQLiteTable): string;
+    load({ clock, }: {
+        clock: PipelineClock;
+    }): Promise<Load<SQLiteTable>>;
+    table(name: string, configure?: (columns: SQLiteColumns) => readonly SQLiteColumn[]): SQLiteTable;
+    createWriter(configuration: CopyConfiguration, target: SQLiteTable): SQLiteWriter;
+}