@smart-data-engines/sde 0.1.0-dev.0

package/dist/engines/_write-fences.d.ts

@@ -0,0 +1,51 @@
+import type { Row } from '../session.js';
+import { type FenceBackend, type FenceMetadata } from '../write-fence.js';
+interface PgTransport {
+    query(sql: string, values?: readonly unknown[]): Promise<readonly Row[]>;
+    transaction(body: () => Promise<void>): Promise<void>;
+    busy(): boolean;
+}
+interface ChTransport {
+    query(sql: string): Promise<readonly Row[]>;
+    command(sql: string): Promise<void>;
+    literal(value: unknown): string;
+}
+export declare class PostgresFences implements FenceBackend {
+    private readonly transport;
+    private readonly quote;
+    constructor(transport: PgTransport);
+    private idle;
+    metadata(table: string): Promise<FenceMetadata>;
+    addColumn(table: string): Promise<void>;
+    addConstraint(table: string, name: string, expression: string): Promise<void>;
+    dropConstraint(table: string, name: string): Promise<void>;
+    drain(table: string, options: {
+        projectId: string;
+        hold: string;
+    }): Promise<void>;
+    restore(table: string, options: {
+        projectId: string;
+        hold: string;
+    }): Promise<void>;
+}
+export declare class ClickHouseFences implements FenceBackend {
+    private readonly transport;
+    private readonly quote;
+    constructor(transport: ChTransport);
+    private table;
+    metadata(table: string): Promise<FenceMetadata>;
+    addColumn(table: string): Promise<void>;
+    addConstraint(table: string, name: string, expression: string): Promise<void>;
+    dropConstraint(table: string, name: string): Promise<void>;
+    private drainLog;
+    drain(table: string, options: {
+        projectId: string;
+        hold: string;
+    }): Promise<void>;
+    restore(table: string, options: {
+        projectId: string;
+        hold: string;
+    }): Promise<void>;
+}
+export declare function fenceIO<T>(operation: () => Promise<T>): Promise<T>;
+export {};

package/dist/engines/_write-fences.js

@@ -0,0 +1,189 @@
+/** Native fencing DDL for dedicated provisioning connections. No placement decision lives here. */
+import { EngineError, MigrationRefused } from '../errors.js';
+import { QUOTE } from '../schema.js';
+import { DRAIN_TABLE, EPOCH_COLUMN, fenceState } from '../write-fence.js';
+function held(metadata, projectId, hold) {
+    const state = fenceState(metadata);
+    if (state.projectId !== projectId || !state.holds.includes(hold)) {
+        throw new MigrationRefused("the requested project's write barrier is not installed");
+    }
+}
+export class PostgresFences {
+    transport;
+    quote = QUOTE['postgres'];
+    constructor(transport) {
+        this.transport = transport;
+    }
+    idle() {
+        if (this.transport.busy()) {
+            throw new MigrationRefused('write-fence DDL cannot run inside an application transaction');
+        }
+    }
+    async metadata(table) {
+        const quoted = this.quote(table);
+        const rows = await this.transport.query('SELECT c.oid::text AS identity, c.relkind AS kind, EXISTS (SELECT 1 FROM pg_inherits i ' +
+            'WHERE i.inhrelid=c.oid OR i.inhparent=c.oid) AS inherits FROM pg_class c ' +
+            'WHERE c.oid=to_regclass($1)', [quoted]);
+        if (rows.length !== 1)
+            throw new EngineError('write-fence table does not exist');
+        const row = rows[0];
+        if (row['kind'] !== 'r' || row['inherits'] !== false) {
+            throw new MigrationRefused('write fences support ordinary PostgreSQL tables without inheritance');
+        }
+        const columns = await this.transport.query("SELECT a.atttypid='bigint'::regtype AS typed, a.attnotnull AS required, " +
+            'a.attgenerated AS generated, pg_get_expr(d.adbin,d.adrelid) AS expression FROM pg_attribute a ' +
+            'LEFT JOIN pg_attrdef d ON d.adrelid=a.attrelid AND d.adnum=a.attnum ' +
+            'WHERE a.attrelid=to_regclass($1) AND a.attname=$2 AND NOT a.attisdropped', [quoted, EPOCH_COLUMN]);
+        const column = columns[0];
+        const valid = column !== undefined && column['typed'] === true && column['required'] === true &&
+            column['generated'] === '' && (column['expression'] === '0' || column['expression'] === "'0'::bigint");
+        const constraints = await this.transport.query("SELECT conname AS name, pg_get_constraintdef(oid) AS expression FROM pg_constraint " +
+            "WHERE conrelid=to_regclass($1) AND contype='c'", [quoted]);
+        return {
+            identity: String(row['identity']), column: valid ? 'valid' : columns.length > 0 ? 'conflict' : 'absent',
+            constraints: Object.fromEntries(constraints.map((item) => [String(item['name']), String(item['expression'])])),
+        };
+    }
+    async addColumn(table) {
+        this.idle();
+        await this.transport.query(`ALTER TABLE ${this.quote(table)} ADD COLUMN IF NOT EXISTS ` +
+            `${this.quote(EPOCH_COLUMN)} bigint NOT NULL DEFAULT 0`);
+    }
+    async addConstraint(table, name, expression) {
+        this.idle();
+        if (name in (await this.metadata(table)).constraints)
+            return;
+        const predicate = expression === '1' ? 'true' : expression === '0' ? 'false' : expression;
+        await this.transport.query(`ALTER TABLE ${this.quote(table)} ADD CONSTRAINT ${this.quote(name)} ` +
+            `CHECK (${predicate}) NOT VALID`);
+    }
+    async dropConstraint(table, name) {
+        this.idle();
+        await this.transport.query(`ALTER TABLE ${this.quote(table)} DROP CONSTRAINT IF EXISTS ${this.quote(name)}`);
+    }
+    async drain(table, options) {
+        this.idle();
+        await this.transport.transaction(async () => {
+            await this.transport.query(`LOCK TABLE ${this.quote(table)} IN SHARE ROW EXCLUSIVE MODE`);
+            held(await this.metadata(table), options.projectId, options.hold);
+        });
+    }
+    async restore(table, options) {
+        held(await this.metadata(table), options.projectId, options.hold);
+    }
+}
+export class ClickHouseFences {
+    transport;
+    quote = QUOTE['clickhouse'];
+    constructor(transport) {
+        this.transport = transport;
+    }
+    table(table) {
+        return this.transport.query('SELECT toString(uuid) AS identity, engine, ' +
+            'formatQuery(create_table_query) AS definition FROM system.tables ' +
+            'WHERE database=currentDatabase() AND name=' + this.transport.literal(table));
+    }
+    async metadata(table) {
+        const databases = await this.transport.query('SELECT engine FROM system.databases WHERE name=currentDatabase()');
+        if (databases.length !== 1 || databases[0]?.['engine'] !== 'Atomic') {
+            throw new MigrationRefused('write fences require a local Atomic ClickHouse database');
+        }
+        const rows = await this.table(table);
+        if (rows.length !== 1) {
+            throw new EngineError('write-fence table does not exist or is detached; resume the same operation');
+        }
+        const row = rows[0];
+        if (row['engine'] !== 'MergeTree' && row['engine'] !== 'ReplacingMergeTree') {
+            throw new MigrationRefused('write fences support local MergeTree and ReplacingMergeTree tables');
+        }
+        const columns = await this.transport.query('SELECT type, default_kind, default_expression FROM system.columns ' +
+            'WHERE database=currentDatabase() AND table=' + this.transport.literal(table) +
+            ' AND name=' + this.transport.literal(EPOCH_COLUMN));
+        const column = columns[0];
+        const valid = columns.length === 1 && column?.['type'] === 'Int64' &&
+            column['default_kind'] === 'DEFAULT' && column['default_expression'] === '0';
+        const constraints = {};
+        const pattern = /^\s*CONSTRAINT\s+[`"]?(__sde_f_[A-Za-z0-9_]+)[`"]?\s+CHECK\s+([^\n]+)/gm;
+        for (const match of String(row['definition']).matchAll(pattern)) {
+            constraints[match[1]] = match[2].trimEnd().replace(/,$/, '');
+        }
+        return {
+            identity: String(row['identity']), column: valid ? 'valid' : columns.length > 0 ? 'conflict' : 'absent',
+            constraints,
+        };
+    }
+    async addColumn(table) {
+        await this.transport.command(`ALTER TABLE ${this.quote(table)} ADD COLUMN IF NOT EXISTS ` +
+            `${this.quote(EPOCH_COLUMN)} Int64 DEFAULT 0`);
+    }
+    async addConstraint(table, name, expression) {
+        await this.transport.command(`ALTER TABLE ${this.quote(table)} ADD CONSTRAINT IF NOT EXISTS ` +
+            `${this.quote(name)} CHECK ${expression}`);
+    }
+    async dropConstraint(table, name) {
+        await this.transport.command(`ALTER TABLE ${this.quote(table)} DROP CONSTRAINT IF EXISTS ${this.quote(name)}`);
+    }
+    async drainLog() {
+        await this.transport.command(`CREATE TABLE IF NOT EXISTS ${this.quote(DRAIN_TABLE)} (` +
+            'table_name String, table_uuid UUID, project_id FixedString(32), hold String) ' +
+            'ENGINE=MergeTree ORDER BY (table_uuid, project_id, hold)');
+        const columns = await this.transport.query('SELECT name,type FROM system.columns WHERE database=currentDatabase() ' +
+            'AND table=' + this.transport.literal(DRAIN_TABLE) + ' ORDER BY name');
+        const actual = columns.map((row) => [row['name'], row['type']]);
+        const expected = [['hold', 'String'], ['project_id', 'FixedString(32)'], ['table_name', 'String'], ['table_uuid', 'UUID']];
+        if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+            throw new MigrationRefused('the reserved write-fence drain log has an incompatible schema');
+        }
+        const kinds = await this.transport.query('SELECT engine FROM system.tables WHERE database=currentDatabase() AND name=' +
+            this.transport.literal(DRAIN_TABLE));
+        if (kinds.length !== 1 || kinds[0]?.['engine'] !== 'MergeTree') {
+            throw new MigrationRefused('the reserved write-fence drain log has an incompatible engine');
+        }
+    }
+    async drain(table, options) {
+        const metadata = await this.metadata(table);
+        held(metadata, options.projectId, options.hold);
+        await this.drainLog();
+        const values = [table, metadata.identity, options.projectId, options.hold].map(this.transport.literal);
+        await this.transport.command(`INSERT INTO ${this.quote(DRAIN_TABLE)} ` +
+            '(table_name, table_uuid, project_id, hold) SETTINGS async_insert=0, wait_for_async_insert=1 ' +
+            `VALUES (${values.join(', ')})`);
+        await this.transport.command(`DETACH TABLE ${this.quote(table)} PERMANENTLY SYNC`);
+        await this.transport.command(`ATTACH TABLE ${this.quote(table)}`);
+        const after = await this.metadata(table);
+        if (after.identity !== metadata.identity)
+            throw new EngineError('the write-fence table identity changed while draining it');
+        held(after, options.projectId, options.hold);
+    }
+    async restore(table, options) {
+        if ((await this.table(table)).length > 0) {
+            held(await this.metadata(table), options.projectId, options.hold);
+            return;
+        }
+        const literal = this.transport.literal;
+        const records = await this.transport.query(`SELECT DISTINCT toString(table_uuid) AS identity FROM ${this.quote(DRAIN_TABLE)} ` +
+            `WHERE table_name=${literal(table)} AND project_id=${literal(options.projectId)} AND hold=${literal(options.hold)}`);
+        const detached = await this.transport.query('SELECT toString(uuid) AS identity FROM system.detached_tables ' +
+            `WHERE database=currentDatabase() AND table=${literal(table)} AND is_permanently=1`);
+        if (records.length !== 1 || detached.length !== 1 || records[0]?.['identity'] !== detached[0]?.['identity']) {
+            throw new MigrationRefused('no matching durable intent for this detached write-fence table');
+        }
+        await this.transport.command(`ATTACH TABLE ${this.quote(table)}`);
+        const metadata = await this.metadata(table);
+        if (metadata.identity !== records[0]?.['identity'])
+            throw new EngineError('the restored write-fence table has another identity');
+        held(metadata, options.projectId, options.hold);
+    }
+}
+export async function fenceIO(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof EngineError || error instanceof MigrationRefused)
+            throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new EngineError('write-fence operation failed; inspect or resume its state: ' + detail);
+    }
+}
+//# sourceMappingURL=_write-fences.js.map

package/dist/engines/_write-fences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_write-fences.js","sourceRoot":"","sources":["../../src/engines/_write-fences.ts"],"names":[],"mappings":"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"}

package/dist/engines/clickhouse.d.ts

@@ -0,0 +1,193 @@
+import { type ReadColumn, type ReadPlan } from '../query.js';
+import { WriteFence } from '../write-fence.js';
+import type { PhysicalFinding } from '../physical.js';
+import type { PhysicalLayout } from '../placement.js';
+import type { Row } from '../session.js';
+/** Milliseconds, and the same argument as the PostgreSQL adapter's constant of the same name. */
+export declare const CONNECT_TIMEOUT_MS = 10000;
+/**
+ * Milliseconds, for the version exchange `connect()` performs.
+ *
+ * Set to something different from the connect bound on purpose. **Opening is bounded tightly;
+ * reading is not, past this exchange** - an analytical query legitimately takes minutes and a
+ * library that timed it out would be deciding something about the caller's workload. The handshake
+ * is the one exchange this library knows the shape of.
+ *
+ * The reference implementation reaches the same place through its driver's `send_receive_timeout`,
+ * and that is measured rather than assumed: with that bound at 15 seconds, a 23-second and a
+ * 24-second query both returned normally, so the bound does not cut a slow query. Here the
+ * distinction is structural instead - only the handshake request carries a timeout - which is one
+ * fewer thing to be right about.
+ */
+export declare const HANDSHAKE_TIMEOUT_MS = 15000;
+export declare class ClickHouseEngine {
+    readonly dialect = "clickhouse";
+    private readonly usage;
+    private readonly target;
+    private trust;
+    private open;
+    private serverVersion;
+    constructor(dsn: string);
+    /**
+     * Ask the server what it is, with a bound on how long that may take.
+     *
+     * The equivalent of the reference implementation's driver handshake, and it exists for the same
+     * measurement: a host that accepts the TCP connection and never answers hung a call for as long
+     * as the test would wait. Here the reason is one layer up - the TCP connect succeeds, so a connect
+     * bound never fires, and what is left is the wait for a response.
+     */
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    /** What the server said it is, or null before `connect()`. Read by nothing; useful in a report. */
+    get version(): string | null;
+    private ensureOpen;
+    /**
+     * One HTTP exchange.
+     *
+     * The handshake has a receive-inactivity default. Later queries retain their unbounded
+     * default unless the caller supplies send_receive_timeout. Neither is an absolute execution
+     * deadline; server-side max_execution_time can constrain the workload itself.
+     */
+    private send;
+    private query;
+    private command;
+    /** DDL capability; use a dedicated connection separate from application traffic. */
+    writeFence(table: string, options: {
+        projectId: string;
+    }): WriteFence;
+    ensureSchema(layout: PhysicalLayout, options: {
+        readonly keys: Readonly<Record<string, readonly string[]>>;
+    }): Promise<PhysicalFinding[]>;
+    /**
+     * Check that what exists is what the map describes, for the reason the PostgreSQL adapter does:
+     * `CREATE TABLE IF NOT EXISTS` accepts a table of that name whatever shape it is in.
+     *
+     * A missing column is refused; an extra one is allowed, because a client may have added one
+     * outside SDE and the map has no opinion about it.
+     *
+     * **Types too, and here they need no normalising at all.** Measured against every type this
+     * library renders: `system.columns.type` returns the exact string we wrote, down to the space in
+     * `Decimal(12, 2)` and the quotes in `DateTime64(6, 'UTC')`. So the comparison is literal, and
+     * it is literal on purpose - a renderer that started emitting a different spelling of the same
+     * type would fail this, which is the right way round for a document we sign.
+     */
+    /** Check existing physical columns without issuing DDL; report the physical design. */
+    validateSchema(layout: PhysicalLayout, options?: {
+        readonly keys?: Readonly<Record<string, readonly string[]>>;
+    }): Promise<PhysicalFinding[]>;
+    /**
+     * Sort key, partition and data-skipping indexes as the catalogue reports them.
+     *
+     * The catalogue formats expressions, so they are parsed into names (`parseIdentifierList`)
+     * rather than compared with a string we predict: 24.8 leaves `select` bare and quotes `null`, and
+     * a formatting rule that moved between releases would turn a correct table into a refusal. An
+     * expression the parser does not understand is reported as it stands.
+     *
+     * `system.tables` is filtered by the login's own table privileges, so a restricted runtime login
+     * reads it without a grant. `system.data_skipping_indices` needs an explicit one (measured, 24.8:
+     * code 497), so it is read only when a table declares an index, and a login without the grant
+     * gets "unverified" rather than a failed session - a check about performance must not become the
+     * outage requirement 3.6 forbids. Provisioning refuses on it, since "could not look" is not
+     * "looked and agreed".
+     */
+    private physicalFindings;
+    private verifySchema;
+    private insertRows;
+    insert(table: string, values: Readonly<Row>): Promise<void>;
+    /**
+     * One row by key, with `FINAL` so a superseded row is never returned.
+     *
+     * Without `FINAL` a key that has been saved twice returns whichever duplicate the scan reaches
+     * first until a merge happens - which is to say, nondeterministically the old value. Paying for
+     * `FINAL` on a point read is the cheaper half of that trade.
+     */
+    /** One HTTP batch, without a cross-block transactional guarantee. */
+    insertMany(table: string, rows: readonly Readonly<Row>[]): Promise<void>;
+    get(table: string, key: Readonly<Row>): Promise<Row | null>;
+    selectRows(table: string, plan: ReadPlan): Promise<Row[]>;
+    countRows(table: string, plan: ReadPlan): Promise<bigint>;
+    summarizeRows(table: string, plan: ReadPlan, column: ReadColumn): Promise<Readonly<Row>>;
+    /**
+     * Each table's bytes and its secondary index bytes, from active parts. Numbers only.
+     *
+     * One statement: `system.tables` says which names exist - readable by a runtime login without
+     * any grant, and only for its own tables - and `system.parts` what their active parts occupy,
+     * which needs the column grant in `STORAGE_COLUMNS`. An empty table has no parts and reads 0
+     * bytes; a missing one is absent, because a missing table is not an empty one.
+     */
+    storageSizes(tables: readonly string[]): Promise<Map<string, readonly [number, number]>>;
+    count(table: string): Promise<number>;
+    mapWatermark(): Promise<number | null>;
+    recordMapVersion(version: number, options: {
+        readonly modelVersion: string;
+    }): Promise<void>;
+    /**
+     * Rows in key order, strictly after one key and up to another inclusive, with `FINAL`.
+     *
+     * `FINAL` here is not tidiness: without it a key saved twice returns two rows until a merge
+     * happens, and the next page starts strictly after that key - so one of the duplicates is read
+     * and the other is not, which for a backfill means copying a row this engine considers
+     * superseded.
+     */
+    keyRange(table: string, order: readonly string[], options?: {
+        readonly after?: readonly unknown[];
+        readonly upto?: readonly unknown[];
+        readonly limit?: number;
+    }): Promise<Row[]>;
+    nthKey(table: string, order: readonly string[], options: {
+        readonly position: number;
+    }): Promise<unknown[] | null>;
+    /**
+     * Insert rows. Idempotence here is the table's, not the statement's.
+     *
+     * There is no `ON CONFLICT` to ask for: a `ReplacingMergeTree` keeps the newest row for a key and
+     * collapses the rest at merge time, so recopying a chunk after a crash converges instead of
+     * raising. Not the same mechanism as the PostgreSQL adapter's, which is exactly why the live
+     * tests run a backfill in every direction rather than in one.
+     */
+    copyIn(table: string, rows: readonly Row[]): Promise<void>;
+    backfillMarker(options: {
+        readonly materialization: string;
+        readonly entity: string;
+    }): Promise<number>;
+    recordBackfillMarker(options: {
+        readonly materialization: string;
+        readonly entity: string;
+        readonly rows: number;
+    }): Promise<void>;
+    /**
+     * Refuses. There is no transaction here to give you.
+     *
+     * A no-op that ran the body would be the friendlier signature and the worse library: the caller
+     * would believe a group of writes was atomic, and would find out otherwise from the state of the
+     * data rather than from an exception.
+     *
+     * The way out is not a flag. Declare the atomicity - `atomicWith` on the entity - and the planner
+     * is then obliged to place those entities in one group, and one group is one engine, so it will
+     * not be this one.
+     */
+    transaction<T>(_body: () => Promise<T>): Promise<T>;
+}
+/**
+ * A SQL literal for one value, and **the only place in this file that escapes a string**.
+ *
+ * Exported so it can be checked directly, because the alternative is checking it through a server
+ * and a server reinterprets escapes inside identifiers: a table name carrying a backslash comes
+ * back as a *different* name rather than as a syntax error, so a live test on one cannot isolate
+ * this rule. `adapters.test.ts` pins the two characters and also refuses a second escaper anywhere
+ * else in this file - which is the class of defect that produced it, found by CodeQL as
+ * `js/incomplete-sanitization`.
+ *
+ * ClickHouse's HTTP interface has no bound parameters in the sense the PostgreSQL protocol does -
+ * it has `param_name` substitution, which needs the declared type of every parameter in the query
+ * text. So these are rendered, and the rendering is **total**: every kind this library can hold has
+ * a branch, and an unknown kind throws rather than falling through to a string. A value that
+ * reached a query as an unquoted `[object Object]` would be a syntax error at best.
+ */
+/**
+ * The columns of `system.parts` a storage measurement reads, and all a runtime login is granted.
+ * ClickHouse 24.8 refuses `system.parts` to a login with only table grants; a column grant on these
+ * names lets it read the parts of its own tables and no others (measured).
+ */
+export declare const STORAGE_COLUMNS: readonly ["database", "table", "active", "bytes_on_disk", "secondary_indices_compressed_bytes", "secondary_indices_marks_bytes"];
+export declare function literal(value: unknown): string;