ts-prorm-orm 1.1.0

package/dist/dialects/spanner/index.js

@@ -0,0 +1,1768 @@
+"use strict";
+/**
+ * Google Cloud Spanner dialect implementation for the TypeScript ORM
+ *
+ * ---------------------------------------------------------------------------
+ * GoogleSQL vs. the Postgres interface
+ * ---------------------------------------------------------------------------
+ * Cloud Spanner exposes two SQL dialects: **GoogleSQL** (Spanner's native
+ * dialect, close to standard SQL/BigQuery syntax) and a newer **PostgreSQL
+ * interface** (`google-cloud/spanner` `databaseDialect: POSTGRESQL`, wire- and
+ * syntax-compatible with a useful subset of Postgres). This dialect targets
+ * **GoogleSQL**, which is the default/primary Spanner dialect and the one
+ * with full feature coverage (interleaved tables, the Mutation API,
+ * `GENERATE_UUID()`, bit-reversed sequences, `STORING` indexes, fine-grained
+ * IAM/database roles, etc.). The Postgres interface is a compatibility layer
+ * aimed at easing migrations from Postgres and still lags GoogleSQL in
+ * feature parity (e.g. no interleaved tables, different DDL for sequences).
+ * Since this codebase already has a Postgres-wire dialect (`postgres`) and a
+ * Postgres-*compatible* distributed dialect (`cockroachdb`), implementing
+ * Spanner via GoogleSQL is what actually makes it a meaningfully different,
+ * complementary dialect rather than a third near-duplicate of the Postgres
+ * query builder.
+ *
+ * ---------------------------------------------------------------------------
+ * Mutation API vs. SQL DML
+ * ---------------------------------------------------------------------------
+ * Spanner offers two ways to write data:
+ *  1. SQL DML (`INSERT`/`UPDATE`/`DELETE`), run inside a read-write
+ *     transaction (`database.runTransaction()` + `transaction.runUpdate()`).
+ *  2. The **Mutation API** (`table.insert()`/`update()`/`upsert()`/
+ *     `deleteRows()`), which encodes writes as structured mutations rather
+ *     than parsed/planned SQL strings. Mutations are the cheaper, safer path
+ *     for bulk/blind writes: no SQL parsing/planning overhead, no risk of
+ *     conflicting on read-your-writes semantics, and they compose directly
+ *     with `Table#insert/update/upsert/deleteRows`.
+ *
+ * This dialect exposes **both**: `buildUpsertQuery()`/`buildInsertQuery()`
+ * satisfy the shared `Dialect` interface using GoogleSQL's `INSERT OR UPDATE
+ * INTO ... VALUES (...)` upsert statement (Spanner has no `ON CONFLICT`
+ * clause - verified against the GoogleSQL DML reference - but it does support
+ * `INSERT OR UPDATE` / `INSERT OR IGNORE` / `INSERT OR REPLACE` as distinct
+ * conflict-action variants at the language level). **Only `INSERT OR UPDATE
+ * INTO` is currently implemented here** - there is no `conflictAction` option
+ * to select `IGNORE`/`REPLACE` semantics from `buildInsertQuery()`/
+ * `buildUpsertQuery()` yet; that's a gap, not a claim that this dialect wires
+ * up all three. Additionally, `mutationUpsert()`/`mutationInsert()`/
+ * `mutationUpdate()`/`mutationDelete()` and `bulkInsert()` are implemented
+ * using the Mutation API directly and are the **recommended, primary**
+ * mechanism for bulk/blind writes - they are simpler, avoid a SQL round-trip,
+ * and sidestep DML's read-write-transaction requirement entirely.
+ *
+ * ---------------------------------------------------------------------------
+ * Transactions & consistency model
+ * ---------------------------------------------------------------------------
+ * Spanner does **not** have a READ COMMITTED / REPEATABLE READ / SERIALIZABLE
+ * spectrum the way traditional RDBMSes do. Every read-write transaction is
+ * always externally consistent (equivalent to, and often described as
+ * stronger than, SERIALIZABLE) by construction, using TrueTime to assign a
+ * commit timestamp that reflects real-world transaction ordering. There is no
+ * meaningful "isolation level" knob to turn: `startTransaction()` accepts a
+ * `TransactionOptions.isolationLevel` for interface parity with the other
+ * dialects, but the value is ignored (with a warning) rather than silently
+ * mapped to something it isn't. Read-only transactions (strong reads or
+ * stale/bounded-staleness reads) are a distinct concept from read-write
+ * transactions in Spanner and are exposed here via `getSnapshot()`/
+ * `runReadOnlyTransaction()` rather than through `startTransaction()`.
+ *
+ * ---------------------------------------------------------------------------
+ * Hotspot avoidance / auto-generated keys
+ * ---------------------------------------------------------------------------
+ * Spanner shards key ranges across servers by primary key order. A naive
+ * monotonically-increasing integer primary key (the `autoIncrement` pattern
+ * used by every other dialect in this codebase) concentrates all writes on
+ * the single tablet holding the current "tail" of the key range - a hotspot.
+ * Spanner's own docs explicitly discourage monotonic keys. To keep the
+ * `ColumnDefinition.autoIncrement` flag meaningful without reproducing that
+ * anti-pattern, this dialect maps `autoIncrement: true` to a
+ * `STRING(36) DEFAULT (GENERATE_UUID())` column (a random, well-distributed
+ * key) and logs a warning explaining the tradeoff. For callers who need an
+ * ordered-but-distributed numeric key, `createBitReversedSequence()` /
+ * `nextBitReversedSequenceValue()` expose Spanner's bit-reversed sequence
+ * feature (`CREATE SEQUENCE ... OPTIONS (sequence_kind = 'bit_reversed_positive')`),
+ * which produces roughly-increasing-over-time but bit-shuffled values that
+ * spread writes across the keyspace.
+ *
+ * @see https://cloud.google.com/spanner/docs/reference/standard-sql/overview
+ * @see https://cloud.google.com/spanner/docs/reference/standard-sql/dml-syntax#insert_or_update
+ * @see https://cloud.google.com/spanner/docs/schema-and-data-model#choosing_a_primary_key
+ * @see https://cloud.google.com/spanner/docs/reference/standard-sql/data-definition-language#create_sequence
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpannerDialect = exports.SpannerTransaction = void 0;
+// The `@google-cloud/spanner` package is declared as a dependency in
+// package.json (and ships its own TypeScript types), but is intentionally
+// required dynamically here rather than imported via `import ... from
+// '@google-cloud/spanner'`. Using the dynamic `require()` form means this
+// file - and anything that imports it - can be type-checked and unit-tested
+// (against the Jest manual mock in __mocks__/@google-cloud/spanner.js) even
+// in environments where the real package hasn't been installed yet, since
+// TypeScript does not attempt to resolve string literals passed to the
+// ambient `require()` function the way it does for `import` statements.
+// The driver's actual object shapes (Spanner/Instance/Database/Table/
+// Transaction) are treated as `any` below; this mirrors how the rest of this
+// codebase treats third-party driver internals it doesn't want to couple to.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { Spanner } = require('@google-cloud/spanner');
+const types_1 = require("../../types");
+const query_stream_helper_1 = require("../query-stream-helper");
+const prorm_1 = require("../../prorm");
+/**
+ * A Spanner read-write transaction, bridging the driver's callback-based
+ * `database.runTransaction()` API to the imperative
+ * `startTransaction()`/`commitTransaction()`/`rollbackTransaction()` shape
+ * used by every other dialect in this codebase. See `SpannerDialect.
+ * startTransaction()` for how `spannerTransaction`/completion signalling is
+ * wired up.
+ */
+class SpannerTransaction extends types_1.Transaction {
+    constructor(spannerTransaction, options) {
+        super(options);
+        this.spannerTransaction = spannerTransaction;
+    }
+}
+exports.SpannerTransaction = SpannerTransaction;
+/**
+ * Google Cloud Spanner dialect class implementing the shared `Dialect` interface.
+ */
+class SpannerDialect {
+    constructor(config) {
+        this.name = 'spanner';
+        this.library = '@google-cloud/spanner';
+        this.spannerClient = null;
+        this.instance = null;
+        this.database = null;
+        this._isConnected = false;
+        /**
+         * Tracks in-flight `database.runTransaction()` calls started via
+         * `startTransaction()`, keyed by `Transaction#id`. Each entry is the
+         * resolver for the "I'm done with this transaction" promise that the
+         * `runTransaction()` callback returns (and therefore awaits) before the
+         * driver finalizes/retries the attempt. `commitTransaction()`/
+         * `rollbackTransaction()` call the resolver to let the callback - and the
+         * transaction lease - complete.
+         */
+        this.pendingTx = new Map();
+        this.config = { ...config };
+    }
+    // =========================================================================
+    // Connection lifecycle
+    // =========================================================================
+    async connect() {
+        try {
+            this.spannerClient = new Spanner({
+                projectId: this.config.projectId,
+                keyFilename: this.config.keyFilename,
+                credentials: this.config.credentials,
+                apiEndpoint: this.config.apiEndpoint || (this.config.emulator ? 'localhost:9010' : undefined),
+            });
+            this.instance = this.spannerClient.instance(this.config.instanceId);
+            this.database = this.instance.database(this.config.databaseId);
+            this._isConnected = true;
+            if (!this.config.skipDialectCheck) {
+                await this.assertGoogleSqlDialect();
+            }
+        }
+        catch (error) {
+            this._isConnected = false;
+            this.database = null;
+            this.instance = null;
+            this.spannerClient = null;
+            throw new Error(`Failed to connect to Spanner database: ${error}`);
+        }
+    }
+    /**
+     * Verify the connected database is running in **GoogleSQL** dialect mode,
+     * not Spanner's PostgreSQL-interface mode. See the file header: this
+     * entire dialect - DDL (backtick-quoted identifiers, `STRING(n)`/`INT64`
+     * types, trailing `PRIMARY KEY (...)`), DML (`@pN` named parameters,
+     * `INSERT OR UPDATE INTO` upserts), and introspection queries
+     * (`information_schema` queried GoogleSQL-style) - assumes GoogleSQL.
+     * None of it is valid against a database provisioned with
+     * `databaseDialect: POSTGRESQL`, which uses Postgres syntax/wire behavior
+     * instead. Rather than let that surface as a confusing "SQL syntax error"
+     * on the first query, this checks the dialect via the Database Admin API
+     * (`Database#getDatabaseDialect()`, which wraps
+     * `DatabaseAdminClient#getDatabase()` and its `databaseDialect` field) and
+     * fails fast with an actionable error.
+     *
+     * Called automatically by `connect()` unless `skipDialectCheck: true` is
+     * set; also callable directly (e.g. to re-verify after a reconnect, or to
+     * probe a database before wiring up this dialect against it).
+     */
+    async assertGoogleSqlDialect() {
+        if (!this.database) {
+            throw new Error('Not connected to database');
+        }
+        const dialect = await this.database.getDatabaseDialect();
+        if (dialect === 'POSTGRESQL') {
+            throw new Error(`Spanner database "${this.config.databaseId}" (instance "${this.config.instanceId}") is running in ` +
+                'PostgreSQL-interface dialect mode, but this dialect implementation only emits GoogleSQL DDL/DML ' +
+                '(backtick-quoted identifiers, @pN parameters, INSERT OR UPDATE INTO upserts, GoogleSQL data types, ' +
+                'etc.), which the PostgreSQL interface will reject or silently mis-parse. Either point this dialect at ' +
+                'a GOOGLE_STANDARD_SQL-dialect database, or use the `postgres` dialect (Spanner\'s PostgreSQL interface ' +
+                'is wire- and syntax-compatible with a useful subset of it) against this database instead.');
+        }
+    }
+    async disconnect() {
+        if (this.database) {
+            if (typeof this.database.close === 'function') {
+                await this.database.close();
+            }
+            this.database = null;
+            this.instance = null;
+            this.spannerClient = null;
+            this._isConnected = false;
+        }
+    }
+    getConnection() {
+        return this.database;
+    }
+    isConnected() {
+        return this._isConnected && this.database !== null;
+    }
+    /**
+     * Determine whether an error should be retried by the caller. Spanner
+     * surfaces contention on read-write transactions as an `ABORTED` error
+     * (gRPC status code 10); `database.runTransaction()` already retries these
+     * internally, but callers driving their own retry loop around
+     * `startTransaction()`/`commitTransaction()` can use this helper too.
+     */
+    isRetryableError(error) {
+        return !!error && (error.code === 10 || /aborted/i.test(String(error.message || '')));
+    }
+    // =========================================================================
+    // Query execution
+    // =========================================================================
+    /**
+     * Convert an array/object of replacement values into the named-parameter
+     * object Spanner's driver expects (`{ p1: value, ... }` for positional
+     * arrays, passed through as-is for already-named objects matching `@name`
+     * placeholders in the SQL).
+     */
+    buildParams(replacements) {
+        if (!replacements)
+            return {};
+        if (Array.isArray(replacements)) {
+            const params = {};
+            replacements.forEach((value, index) => {
+                params[`p${index + 1}`] = value;
+            });
+            return params;
+        }
+        return { ...replacements };
+    }
+    /**
+     * Stream query results by paging through `sql` via repeated
+     * dialect-appropriate LIMIT/OFFSET queries (see
+     * `createPaginatedQueryStream()` in `src/dialects/query-stream-helper.ts`)
+     * instead of loading the whole result set into memory at once.
+     * @param sql - The SELECT statement to stream
+     * @param options - Streaming options (batch size, backpressure watermark, model mapping)
+     */
+    queryStream(sql, options) {
+        return (0, query_stream_helper_1.createPaginatedQueryStream)(this, sql, options);
+    }
+    /**
+     * Execute a raw SQL query.
+     *
+     * Dispatches based on statement type, since Spanner requires different
+     * driver entry points for each:
+     *  - `CREATE`/`ALTER`/`DROP` -> `database.updateSchema()` (a long-running
+     *    DDL operation).
+     *  - `SELECT`/`WITH` (including recursive CTEs and window functions, which
+     *    GoogleSQL supports natively) -> `database.run()` (single-use read).
+     *  - Everything else (`INSERT`/`UPDATE`/`DELETE`) -> a read-write
+     *    transaction via `runDML()`, since Spanner only allows DML inside a
+     *    transaction (there is no autocommit-single-statement DML path the way
+     *    `pg`/`mysql2` provide).
+     */
+    async query(sql, options) {
+        if (!this.database) {
+            throw new Error('Not connected to database');
+        }
+        const trimmed = sql.trim();
+        const replacements = options?.replacements ?? options?.bind;
+        const params = this.buildParams(replacements);
+        if (/^(CREATE|ALTER|DROP)\b/i.test(trimmed)) {
+            return this.runDDL(trimmed);
+        }
+        if (/^(SELECT|WITH)\b/i.test(trimmed)) {
+            return this.runRead(trimmed, params);
+        }
+        return this.runDML(trimmed, params);
+    }
+    async runDDL(sql) {
+        try {
+            const [operation] = await this.database.updateSchema([sql]);
+            await operation.promise();
+            return { rows: [], rowCount: 0, fields: [] };
+        }
+        catch (error) {
+            throw new Error(`Spanner DDL error: ${error}`);
+        }
+    }
+    async runRead(sql, params) {
+        try {
+            const [rows] = await this.database.run({
+                sql,
+                params: Object.keys(params).length ? params : undefined,
+                json: true,
+                ...this.config.queryOptions,
+            });
+            const fields = rows.length
+                ? Object.keys(rows[0]).map((name) => ({
+                    name,
+                    type: 'unknown',
+                    length: 0,
+                    tableID: 0,
+                    columnID: 0,
+                    nullable: true,
+                    isEnum: false,
+                    isPrimaryKey: false,
+                }))
+                : [];
+            return { rows, rowCount: rows.length, fields };
+        }
+        catch (error) {
+            throw new Error(`Spanner query error: ${error}`);
+        }
+    }
+    /**
+     * Run a DML statement (`INSERT`/`UPDATE`/`DELETE`) inside a fresh
+     * read-write transaction, committing (or rolling back on error)
+     * automatically. This is the "autocommit" convenience path used by
+     * `query()`; for multi-statement transactions, use
+     * `startTransaction()`/`commitTransaction()`/`rollbackTransaction()`
+     * directly and run DML against the returned transaction's connection.
+     */
+    async runDML(sql, params) {
+        const transaction = await this.startTransaction();
+        try {
+            const spannerTx = transaction.spannerTransaction;
+            const [rowCount] = await spannerTx.runUpdate({
+                sql,
+                params: Object.keys(params).length ? params : undefined,
+            });
+            await this.commitTransaction(transaction);
+            return { rows: [], rowCount: rowCount || 0, fields: [] };
+        }
+        catch (error) {
+            await this.rollbackTransaction(transaction);
+            throw new Error(`Spanner DML error: ${error}`);
+        }
+    }
+    // =========================================================================
+    // Escaping / identifiers
+    // =========================================================================
+    escape(value) {
+        if (value instanceof prorm_1.Literal) {
+            return value.val;
+        }
+        if (value === null || value === undefined) {
+            return 'NULL';
+        }
+        if (typeof value === 'string') {
+            return `'${this.escapeString(value)}'`;
+        }
+        if (typeof value === 'number') {
+            return String(value);
+        }
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        if (typeof value === 'boolean') {
+            return value ? 'TRUE' : 'FALSE';
+        }
+        if (value instanceof Date) {
+            // LIMITATION: `escape()` has no column-type context (it's `escape(value:
+            // any): string` on the shared `Dialect` interface, same as every other
+            // dialect in this codebase), so a JS `Date` written into a
+            // `DATEONLY`/`DATE`-typed column is always emitted as a `TIMESTAMP`
+            // literal here, which GoogleSQL will reject for a `DATE` column
+            // (Spanner has no implicit TIMESTAMP -> DATE coercion). Working around
+            // this would require threading the target column's declared type
+            // through every `escape()` call site (query building, replacement
+            // substitution, etc.) - a larger refactor than is justified here since
+            // no other dialect in this codebase does it either. Callers writing to
+            // `DATEONLY` columns should pass a `'YYYY-MM-DD'` string (which is
+            // escaped as a plain string literal below and is valid GoogleSQL DATE
+            // literal syntax) instead of a `Date` object.
+            return `TIMESTAMP '${value.toISOString()}'`;
+        }
+        if (Buffer.isBuffer(value)) {
+            return `B'${value.toString('base64')}'`;
+        }
+        if (Array.isArray(value)) {
+            return `[${value.map((v) => this.escape(v)).join(', ')}]`;
+        }
+        return `'${this.escapeString(JSON.stringify(value))}'`;
+    }
+    /**
+     * Escape a string literal for GoogleSQL. Unlike ANSI-SQL/Postgres (which
+     * escape embedded quotes by doubling them, `''`), GoogleSQL string
+     * literals use C-style backslash escaping (`\'`, `\\`).
+     */
+    escapeString(str) {
+        return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    }
+    /**
+     * GoogleSQL quotes identifiers with backticks (like BigQuery/MySQL), not
+     * double quotes.
+     */
+    escapeId(identifier) {
+        const id = String(identifier ?? '');
+        return `\`${id.replace(/`/g, '``')}\``;
+    }
+    quoteIdentifier(identifier) {
+        return this.escapeId(identifier);
+    }
+    quoteTable(tableName, schema) {
+        // Spanner GoogleSQL databases are not schema-namespaced the way
+        // Postgres databases are (there is no `CREATE SCHEMA` in GoogleSQL);
+        // `schema` is accepted for interface parity but ignored.
+        if (schema) {
+            console.warn(`Spanner: schema "${schema}" was provided to quoteTable(), but Cloud Spanner GoogleSQL has no schema/namespace concept for tables; ignoring.`);
+        }
+        return this.escapeId(tableName);
+    }
+    /**
+     * Replace `@pN` / `@name` placeholders in SQL with escaped literal values.
+     */
+    replaceReplacements(sql, replacements) {
+        if (!replacements) {
+            return sql;
+        }
+        let result = sql;
+        if (Array.isArray(replacements)) {
+            replacements.forEach((value, index) => {
+                const placeholder = new RegExp(`@p${index + 1}\\b`, 'g');
+                result = result.replace(placeholder, this.escape(value));
+            });
+        }
+        else {
+            for (const [key, value] of Object.entries(replacements)) {
+                const placeholder = new RegExp(`@${key}\\b`, 'g');
+                result = result.replace(placeholder, this.escape(value));
+            }
+        }
+        return result;
+    }
+    // =========================================================================
+    // Schemas - Spanner GoogleSQL has no CREATE SCHEMA; not supported
+    // =========================================================================
+    async createSchema(_schema) {
+        throw new Error('Cloud Spanner GoogleSQL has no CREATE SCHEMA/schema-namespace concept for tables.');
+    }
+    async dropSchema(_schema, _options) {
+        throw new Error('Cloud Spanner GoogleSQL has no CREATE SCHEMA/schema-namespace concept for tables.');
+    }
+    async showAllSchemas() {
+        return [];
+    }
+    async listSchemas() {
+        return [];
+    }
+    createDatabaseSQL(_options) {
+        throw new Error('Spanner databases are created via the Admin API (instance.createDatabase()), not SQL DDL.');
+    }
+    dropDatabaseSQL(_name) {
+        throw new Error('Spanner databases are dropped via the Admin API (database.delete()), not SQL DDL.');
+    }
+    /**
+     * Spanner has no `SAVEPOINT`. Savepoints exist to allow partial rollback
+     * within a larger transaction; Spanner read-write transactions are
+     * expected to be short-lived and are retried wholesale on conflict, so
+     * there is no nested-rollback primitive.
+     */
+    createSavepointSQL(_name) {
+        throw new Error('Cloud Spanner does not support SAVEPOINT.');
+    }
+    releaseSavepointSQL(_name) {
+        throw new Error('Cloud Spanner does not support SAVEPOINT.');
+    }
+    rollbackToSavepointSQL(_name) {
+        throw new Error('Cloud Spanner does not support SAVEPOINT.');
+    }
+    // =========================================================================
+    // Extensions - PostgreSQL only
+    // =========================================================================
+    async createExtension(_extensionName, _options) {
+        throw new Error('Extensions are only supported in PostgreSQL');
+    }
+    async dropExtension(_extensionName, _options) {
+        throw new Error('Extensions are only supported in PostgreSQL');
+    }
+    async getExtensions() {
+        throw new Error('Extensions are only supported in PostgreSQL');
+    }
+    async hasExtension(_extensionName) {
+        throw new Error('Extensions are only supported in PostgreSQL');
+    }
+    async getDatabaseVersion() {
+        // Spanner has no SELECT version()-style introspection; the closest
+        // analogue is the dialect/database type itself since engine version is
+        // not user-addressable (Spanner is a fully-managed service).
+        return 'Cloud Spanner (GoogleSQL)';
+    }
+    // =========================================================================
+    // Tables (DDL)
+    // =========================================================================
+    /**
+     * Create a table.
+     *
+     * Notable GoogleSQL DDL differences from every other dialect here:
+     *  - The primary key is declared *after* the closing paren of the column
+     *    list (`) PRIMARY KEY (col1, col2)`), not inline as a column/table
+     *    constraint.
+     *  - There is no `ALTER TABLE ... ADD CONSTRAINT` for primary keys - the
+     *    primary key is fixed at table-creation time.
+     *  - `autoIncrement` columns are mapped to `STRING(36) DEFAULT
+     *    (GENERATE_UUID())` rather than a monotonic counter - see the
+     *    hotspot-avoidance note in the file header.
+     */
+    async createTable(tableName, columns, options) {
+        const columnDefs = [];
+        const inferredPk = [];
+        for (const [columnName, definition] of Object.entries(columns)) {
+            columnDefs.push(this.getColumnDefinitionSql(columnName, definition));
+            if (definition.primaryKey) {
+                inferredPk.push(columnName);
+            }
+        }
+        if (options?.constraints) {
+            for (const constraint of options.constraints) {
+                if (constraint.type === 'PRIMARY KEY')
+                    continue; // handled via PRIMARY KEY (...) clause below
+                const constraintSql = this.buildConstraintSql(constraint);
+                if (constraintSql)
+                    columnDefs.push(constraintSql);
+            }
+        }
+        const primaryKey = options?.primaryKey && options.primaryKey.length ? options.primaryKey : inferredPk;
+        if (!primaryKey.length) {
+            throw new Error(`Spanner: table "${tableName}" needs a primary key (mark a column primaryKey: true, or pass options.primaryKey).`);
+        }
+        let sql = 'CREATE TABLE';
+        if (options?.ifNotExists)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.escapeId(tableName)} (${columnDefs.join(', ')})`;
+        sql += ` PRIMARY KEY (${primaryKey.map((f) => this.escapeId(f)).join(', ')})`;
+        if (options?.interleaveInParent) {
+            sql += `,\nINTERLEAVE IN PARENT ${this.escapeId(options.interleaveInParent)}`;
+            sql += options.interleaveOnDeleteCascade ? ' ON DELETE CASCADE' : ' ON DELETE NO ACTION';
+        }
+        if (options?.rowDeletionPolicy) {
+            sql += `,\nROW DELETION POLICY (OLDER_THAN(${this.escapeId(options.rowDeletionPolicy.column)}, INTERVAL ${options.rowDeletionPolicy.olderThanDays} DAY))`;
+        }
+        if (options?.engine || options?.charset || options?.rowFormat || options?.tablespace) {
+            console.warn('Spanner: engine/charset/rowFormat/tablespace options are not applicable to Cloud Spanner and are ignored.');
+        }
+        await this.query(sql);
+        if (options?.uniqueKeys) {
+            const entries = Array.isArray(options.uniqueKeys)
+                ? options.uniqueKeys.map((uk) => [uk.name, uk.fields])
+                : Object.entries(options.uniqueKeys);
+            for (const [keyName, fields] of entries) {
+                const indexName = keyName || `idx_${tableName}_${fields.join('_')}_unique`;
+                await this.addIndex(tableName, indexName, fields, { unique: true });
+            }
+        }
+        if (options?.indexes) {
+            for (const index of options.indexes) {
+                await this.addIndex(tableName, index.name || `idx_${tableName}_${index.fields.join('_')}`, index.fields, { unique: index.unique, where: index.where, include: index.include });
+            }
+        }
+    }
+    buildConstraintSql(constraint) {
+        const name = constraint.name ? `CONSTRAINT ${this.escapeId(constraint.name)} ` : '';
+        const fields = constraint.fields?.map((f) => this.escapeId(f)).join(', ') || '';
+        switch (constraint.type) {
+            case 'UNIQUE':
+                // GoogleSQL DDL has no inline UNIQUE column/table constraint; model
+                // uniqueness via a UNIQUE INDEX instead (see createTable's
+                // options.uniqueKeys handling / addIndex()).
+                return null;
+            case 'FOREIGN KEY': {
+                if (!constraint.references)
+                    return null;
+                const refField = constraint.references.field;
+                const refFieldSql = Array.isArray(refField)
+                    ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                    : `(${this.escapeId(refField)})`;
+                let fkSql = `${name}FOREIGN KEY (${fields}) REFERENCES ${this.escapeId(constraint.references.table)}${refFieldSql}`;
+                if (constraint.references.onDelete) {
+                    // Spanner only supports ON DELETE CASCADE / NO ACTION for foreign keys.
+                    fkSql += ` ON DELETE ${constraint.references.onDelete}`;
+                }
+                return fkSql;
+            }
+            case 'CHECK':
+                if (!constraint.check)
+                    return null;
+                return `${name}CHECK (${constraint.check})`;
+            case 'PRIMARY KEY':
+                return null; // handled via the trailing PRIMARY KEY (...) clause
+            default:
+                return null;
+        }
+    }
+    getColumnDefinitionSql(columnName, definition) {
+        let sql;
+        if (definition.autoIncrement) {
+            // See the "Hotspot avoidance" note in the file header: Cloud Spanner
+            // explicitly discourages monotonically-increasing primary keys because
+            // they concentrate writes on a single key-range split. Rather than
+            // emulate a counter (which would reproduce the anti-pattern), map
+            // autoIncrement columns to a randomly-distributed UUID default.
+            console.warn(`Spanner: column "${columnName}" was declared autoIncrement; Cloud Spanner has no monotonic ` +
+                `auto-increment (it would hotspot a single key range). Generating "${columnName}" as ` +
+                `STRING(36) DEFAULT (GENERATE_UUID()) instead. For an ordered-but-distributed numeric key, ` +
+                `use createBitReversedSequence()/nextBitReversedSequenceValue() instead.`);
+            sql = `${this.escapeId(columnName)} STRING(36) DEFAULT (GENERATE_UUID())`;
+            if (definition.allowNull === false || definition.primaryKey) {
+                sql += ' NOT NULL';
+            }
+            return sql;
+        }
+        sql = `${this.escapeId(columnName)} ${this.getDataTypeSql(definition.type).replace(/%%COLUMN%%/g, this.escapeId(columnName))}`;
+        if (definition.allowNull === false || definition.primaryKey) {
+            sql += ' NOT NULL';
+        }
+        if (definition.defaultValue !== undefined) {
+            sql += ` DEFAULT (${this.getDefaultValue(definition.defaultValue)})`;
+        }
+        if (definition.references) {
+            const refField = definition.references.field;
+            const refFieldSql = Array.isArray(refField)
+                ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                : `(${this.escapeId(refField)})`;
+            sql += ` REFERENCES ${this.escapeId(definition.references.table)}${refFieldSql}`;
+            if (definition.references.onDelete) {
+                sql += ` ON DELETE ${definition.references.onDelete}`;
+            }
+        }
+        return sql;
+    }
+    getDefaultValue(value) {
+        if (value === null)
+            return 'NULL';
+        if (typeof value === 'string') {
+            if (/^(GENERATE_UUID|CURRENT_TIMESTAMP|PENDING_COMMIT_TIMESTAMP)\s*\(/i.test(value)) {
+                return value;
+            }
+            return `'${this.escapeString(value)}'`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return String(value);
+        if (value instanceof Date)
+            return `TIMESTAMP '${value.toISOString()}'`;
+        if (value && typeof value.toDefaultValue === 'function')
+            return value.toDefaultValue();
+        return `'${this.escapeString(String(value))}'`;
+    }
+    async dropTable(tableName, options) {
+        // Spanner's DROP TABLE has no IF EXISTS/CASCADE; interleaved child tables
+        // and indexes on the table must be dropped first.
+        if (options?.cascade) {
+            console.warn('Spanner: DROP TABLE has no CASCADE - drop dependent indexes/interleaved child tables explicitly first.');
+        }
+        try {
+            await this.query(`DROP TABLE ${this.escapeId(tableName)}`);
+        }
+        catch (error) {
+            if (options?.ifExists)
+                return;
+            throw error;
+        }
+    }
+    /**
+     * Create a table interleaved inside a parent table
+     * (`INTERLEAVE IN PARENT ...`), Spanner's mechanism for physically
+     * co-locating related rows (e.g. Orders interleaved in Customers) so that
+     * point look-ups and joins across the relationship stay within a single
+     * storage split instead of fanning out across the cluster.
+     *
+     * `columns` must include the parent table's primary key column(s) as a
+     * prefix of `options.primaryKey`.
+     */
+    async createInterleavedTable(tableName, parentTable, columns, options) {
+        await this.createTable(tableName, columns, {
+            ...options,
+            primaryKey: options.primaryKey,
+            interleaveInParent: parentTable,
+            interleaveOnDeleteCascade: options.onDeleteCascade,
+        });
+    }
+    // Partitioned tables (PostgreSQL-style declarative partitioning) have no
+    // GoogleSQL equivalent. Spanner distributes/splits data automatically and
+    // transparently based on key ranges and load; there is no user-facing
+    // `PARTITION BY`/`CREATE TABLE ... PARTITION OF` syntax. Interleaved tables
+    // (see createInterleavedTable) and table splitting are the closest
+    // Spanner-native analogues, but they solve a different problem (physical
+    // co-location vs. logical partitioning) and aren't drop-in replacements.
+    async createPartitionedTable() {
+        throw new Error('Cloud Spanner has no declarative table partitioning (PARTITION BY); it distributes data automatically. See createInterleavedTable() for physical co-location.');
+    }
+    async createPartition() {
+        throw new Error('Cloud Spanner has no declarative table partitioning.');
+    }
+    async attachPartition() {
+        throw new Error('Cloud Spanner has no declarative table partitioning.');
+    }
+    async detachPartition() {
+        throw new Error('Cloud Spanner has no declarative table partitioning.');
+    }
+    async dropPartition() {
+        throw new Error('Cloud Spanner has no declarative table partitioning.');
+    }
+    // =========================================================================
+    // Views
+    // =========================================================================
+    async createView(viewName, query, options) {
+        let sql = options?.replace ? 'CREATE OR REPLACE VIEW' : 'CREATE VIEW';
+        sql += ` ${this.escapeId(viewName)} SQL SECURITY INVOKER AS ${query}`;
+        await this.query(sql);
+    }
+    async dropView(viewName, options) {
+        if (options?.cascade) {
+            console.warn('Spanner: DROP VIEW has no CASCADE; drop dependent views explicitly first.');
+        }
+        try {
+            await this.query(`DROP VIEW ${this.escapeId(viewName)}`);
+        }
+        catch (error) {
+            if (options?.ifExists)
+                return;
+            throw error;
+        }
+    }
+    async showViews() {
+        const result = await this.query(`SELECT table_name FROM information_schema.views WHERE table_schema = ''`);
+        return result.rows.map((row) => row.table_name);
+    }
+    // =========================================================================
+    // Columns
+    // =========================================================================
+    async addColumn(tableName, columnName, definition) {
+        const colSql = this.getColumnDefinitionSql(columnName, definition);
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${colSql}`);
+    }
+    async removeColumn(tableName, columnName) {
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} DROP COLUMN ${this.escapeId(columnName)}`);
+    }
+    async changeColumn(tableName, columnName, definition) {
+        // Spanner's ALTER COLUMN can only change nullability/length/default of an
+        // existing column - it cannot change the underlying type across
+        // incompatible families the way Postgres' USING clause can.
+        let sql = `ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} ${this.getDataTypeSql(definition.type).replace(/%%COLUMN%%/g, this.escapeId(columnName))}`;
+        if (definition.allowNull === false)
+            sql += ' NOT NULL';
+        await this.query(sql);
+    }
+    async renameColumn() {
+        throw new Error('Cloud Spanner GoogleSQL has no RENAME COLUMN; add a new column, backfill, and drop the old one.');
+    }
+    async addForeignKey(tableName, columnName, referencedTableName, referencedColumnName, options) {
+        const constraintName = options?.name || `fk_${tableName}_${columnName}`;
+        let sql = `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintName)} FOREIGN KEY (${this.escapeId(columnName)}) REFERENCES ${this.escapeId(referencedTableName)} (${this.escapeId(referencedColumnName)})`;
+        if (options?.onDelete) {
+            // Spanner foreign keys only support ON DELETE CASCADE / NO ACTION (no ON UPDATE).
+            sql += ` ON DELETE ${options.onDelete}`;
+        }
+        await this.query(sql);
+    }
+    // =========================================================================
+    // Bulk insert / Mutation API
+    // =========================================================================
+    /**
+     * Bulk-insert records using the Mutation API (`table.insert()`) rather
+     * than a multi-row SQL `INSERT`. This is the recommended path for bulk
+     * writes on Spanner: mutations skip SQL parsing/planning entirely and are
+     * batched into a single commit.
+     */
+    async bulkInsert(tableName, records, _options) {
+        if (records.length === 0) {
+            return { rows: [], rowCount: 0, fields: [] };
+        }
+        await this.mutationInsert(tableName, records);
+        return { rows: [], rowCount: records.length, fields: [] };
+    }
+    /** Mutation API: insert rows (fails if any row's key already exists). */
+    async mutationInsert(tableName, rows) {
+        if (!this.database)
+            throw new Error('Not connected to database');
+        await this.database.table(tableName).insert(rows);
+    }
+    /** Mutation API: update rows (fails if a row's key does not exist). */
+    async mutationUpdate(tableName, rows) {
+        if (!this.database)
+            throw new Error('Not connected to database');
+        await this.database.table(tableName).update(rows);
+    }
+    /**
+     * Mutation API: upsert rows (insert-or-update by primary key). This is the
+     * **primary/recommended** upsert mechanism for this dialect - see the file
+     * header for the tradeoff vs. `buildUpsertQuery()`'s SQL `INSERT OR
+     * UPDATE` fallback.
+     */
+    async mutationUpsert(tableName, rows) {
+        if (!this.database)
+            throw new Error('Not connected to database');
+        await this.database.table(tableName).upsert(rows);
+    }
+    /** Mutation API: delete rows by primary key. */
+    async mutationDelete(tableName, keys) {
+        if (!this.database)
+            throw new Error('Not connected to database');
+        await this.database.table(tableName).deleteRows(keys);
+    }
+    // =========================================================================
+    // Introspection
+    // =========================================================================
+    async showTables() {
+        const result = await this.query(`SELECT table_name FROM information_schema.tables WHERE table_schema = ''`);
+        return result.rows.map((row) => row.table_name);
+    }
+    async showConstraints(tableName) {
+        const result = await this.query(`SELECT constraint_name, constraint_type FROM information_schema.table_constraints WHERE table_name = @p1`, { replacements: [tableName] });
+        return result.rows;
+    }
+    async addConstraint(tableName, options) {
+        if (options.type === 'PRIMARY KEY') {
+            throw new Error('Cloud Spanner primary keys are fixed at CREATE TABLE time; ALTER TABLE ... ADD CONSTRAINT PRIMARY KEY is not supported.');
+        }
+        if (options.type === 'UNIQUE') {
+            const indexName = options.name || `idx_${tableName}_${options.fields.join('_')}_unique`;
+            await this.addIndex(tableName, indexName, options.fields, { unique: true });
+            return;
+        }
+        const name = options.name || `${tableName}_${options.fields.join('_')}_${options.type.toLowerCase().replace(/\s+/g, '_')}`;
+        const fieldsSql = options.fields.map((f) => this.escapeId(f)).join(', ');
+        let sql = `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(name)} `;
+        if (options.type === 'FOREIGN KEY') {
+            sql += `FOREIGN KEY (${fieldsSql}) REFERENCES ${this.escapeId(options.references.table)} (${options.references.fields.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        else {
+            sql += `CHECK (${options.check})`;
+        }
+        await this.query(sql);
+    }
+    async removeConstraint(tableName, constraintName) {
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} DROP CONSTRAINT ${this.escapeId(constraintName)}`);
+    }
+    async showIndexes(tableName) {
+        const result = await this.query(`SELECT index_name, index_type, is_unique FROM information_schema.indexes WHERE table_name = @p1`, { replacements: [tableName] });
+        return result.rows;
+    }
+    async describeTable(tableName) {
+        const result = await this.query(`SELECT column_name, spanner_type, is_nullable FROM information_schema.columns WHERE table_name = @p1 ORDER BY ordinal_position`, { replacements: [tableName] });
+        const description = {};
+        for (const row of result.rows) {
+            description[row.column_name] = {
+                type: row.spanner_type,
+                allowNull: row.is_nullable === 'YES',
+                defaultValue: null,
+                primaryKey: false,
+                autoIncrement: false,
+            };
+        }
+        return description;
+    }
+    async renameTable() {
+        throw new Error('Cloud Spanner GoogleSQL has no RENAME TABLE; create the new table, backfill, and drop the old one.');
+    }
+    /**
+     * Add a secondary index. `options.include` maps to Spanner's `STORING
+     * (...)` clause - a covering index that duplicates the listed columns
+     * alongside the index entry so lookups can be satisfied without a join
+     * back to the base table.
+     */
+    async addIndex(tableName, indexName, fields, options) {
+        let sql = 'CREATE';
+        if (options?.unique)
+            sql += ' UNIQUE';
+        sql += ` INDEX${options?.ifNotExists ? ' IF NOT EXISTS' : ''} ${this.escapeId(indexName)} ON ${this.escapeId(tableName)} (${fields.map((f) => this.escapeId(f)).join(', ')})`;
+        if (options?.include && options.include.length) {
+            sql += ` STORING (${options.include.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        if (options?.where) {
+            // Spanner has no partial-index WHERE clause; NULL_FILTERED is the
+            // closest analogue (filters out rows with NULL in any indexed key
+            // column) but is not a general predicate.
+            console.warn('Spanner: partial indexes with an arbitrary WHERE predicate are not supported; consider NULL_FILTERED for excluding NULL key columns instead. Ignoring `where`.');
+        }
+        await this.query(sql);
+    }
+    async removeIndex(tableName, indexName) {
+        void tableName; // Spanner's DROP INDEX does not take a table name.
+        await this.query(`DROP INDEX ${this.escapeId(indexName)}`);
+    }
+    async createIndex(tableName, indexDef) {
+        await this.addIndex(tableName, indexDef.name, indexDef.fields, {
+            unique: indexDef.unique,
+            where: indexDef.where,
+        });
+    }
+    async createFulltextIndex() {
+        throw new Error('Cloud Spanner has no MySQL-style FULLTEXT index; use a SEARCH INDEX (GoogleSQL full-text search) via raw DDL instead.');
+    }
+    async createSpatialIndex() {
+        throw new Error('Cloud Spanner has no built-in spatial/geography index support.');
+    }
+    async dropIndex(tableName, indexName, options) {
+        void tableName;
+        try {
+            await this.query(`DROP INDEX ${this.escapeId(indexName)}`);
+        }
+        catch (error) {
+            if (options?.ifExists)
+                return;
+            throw error;
+        }
+    }
+    async createConstraint(tableName, constraintDef) {
+        await this.addConstraint(tableName, {
+            type: constraintDef.type,
+            fields: constraintDef.fields || [],
+            name: constraintDef.name,
+            references: constraintDef.references
+                ? { table: constraintDef.references.table, fields: [constraintDef.references.field] }
+                : undefined,
+            check: constraintDef.check,
+        });
+    }
+    async dropConstraint(tableName, constraintName, options) {
+        try {
+            await this.removeConstraint(tableName, constraintName);
+        }
+        catch (error) {
+            if (options?.ifExists)
+                return;
+            throw error;
+        }
+    }
+    async changeOwner() {
+        throw new Error('Cloud Spanner has no per-object OWNER concept; access is governed by IAM roles/policies and database roles, not object ownership.');
+    }
+    async createForeignDataWrapper() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    async dropForeignDataWrapper() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    async createForeignServer() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    async dropForeignServer() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    async createForeignTable() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildCreateServerQuery(_name, _opts) {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildAlterServerQuery(_name, _opts) {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildDropServerQuery() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildCreateUserMappingQuery(_opts) {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildAlterUserMappingQuery(_opts) {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildDropUserMappingQuery() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    async createUserMapping() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    async dropUserMapping() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildCreateForeignTableQuery(_tableName, _opts) {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildDropForeignTableQuery() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildImportForeignSchemaQuery(_remoteSchema, _serverName, _opts) {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    getServersQuery() {
+        throw new Error(SpannerDialect.FDW_NOT_SUPPORTED);
+    }
+    buildCreateUserQuery() {
+        throw new Error(SpannerDialect.USER_MGMT_NOT_SUPPORTED);
+    }
+    buildAlterUserQuery() {
+        throw new Error(SpannerDialect.USER_MGMT_NOT_SUPPORTED);
+    }
+    buildDropUserQuery() {
+        throw new Error(SpannerDialect.USER_MGMT_NOT_SUPPORTED);
+    }
+    getUsersQuery() {
+        throw new Error(SpannerDialect.USER_MGMT_NOT_SUPPORTED);
+    }
+    buildGrantQuery() {
+        throw new Error(SpannerDialect.USER_MGMT_NOT_SUPPORTED);
+    }
+    buildRevokeQuery() {
+        throw new Error(SpannerDialect.USER_MGMT_NOT_SUPPORTED);
+    }
+    buildShowGrantsQuery() {
+        throw new Error(SpannerDialect.USER_MGMT_NOT_SUPPORTED);
+    }
+    buildFlushPrivilegesQuery() {
+        throw new Error(SpannerDialect.USER_MGMT_NOT_SUPPORTED);
+    }
+    buildCreateRoleQuery(roleName) {
+        // Unlike the rest of this section, GoogleSQL *does* support database
+        // roles - exposed here as a plain SQL builder (not backed by a
+        // full grant/revoke-to-role implementation).
+        return `CREATE ROLE ${this.escapeId(roleName)}`;
+    }
+    buildDropRoleQuery(roleName) {
+        return `DROP ROLE ${this.escapeId(roleName)}`;
+    }
+    buildGrantRoleQuery(role, to) {
+        return `GRANT ROLE ${this.escapeId(role)} TO ROLE ${this.escapeId(String(to))}`;
+    }
+    buildRevokeRoleQuery(role, from) {
+        return `REVOKE ROLE ${this.escapeId(role)} FROM ROLE ${this.escapeId(String(from))}`;
+    }
+    getRolesQuery() {
+        return `SELECT role_name FROM information_schema.enabled_roles`;
+    }
+    // =========================================================================
+    // Row-level security - not supported (no RLS/policy concept in Spanner)
+    // =========================================================================
+    async createSecurityPolicy() {
+        throw new Error('Cloud Spanner has no row-level security / policy concept; enforce row-level access in application code or via views.');
+    }
+    async dropSecurityPolicy() {
+        throw new Error('Cloud Spanner has no row-level security / policy concept; enforce row-level access in application code or via views.');
+    }
+    async createStoredProcedure(_options) {
+        throw new Error(SpannerDialect.PROC_NOT_SUPPORTED);
+    }
+    async createProcedure(options) {
+        return this.createStoredProcedure(options);
+    }
+    async dropStoredProcedure(_procedureName, _options) {
+        throw new Error(SpannerDialect.PROC_NOT_SUPPORTED);
+    }
+    async dropProcedure(procedureName, options) {
+        return this.dropStoredProcedure(procedureName, options);
+    }
+    async executeStoredProcedure(_options) {
+        throw new Error(SpannerDialect.PROC_NOT_SUPPORTED);
+    }
+    async hasStoredProcedure() {
+        return false;
+    }
+    // =========================================================================
+    // Bit-reversed sequences (hotspot-safe ordered keys)
+    // =========================================================================
+    /**
+     * Create a bit-reversed sequence: an ordered-but-shuffled numeric
+     * generator (`CREATE SEQUENCE ... OPTIONS (sequence_kind =
+     * 'bit_reversed_positive')`) that spreads generated values across the
+     * keyspace instead of producing a monotonic run, avoiding the hotspotting
+     * that a plain auto-increment counter would cause.
+     */
+    async createBitReversedSequence(name, options) {
+        let sql = `CREATE SEQUENCE ${this.escapeId(name)} OPTIONS (sequence_kind = 'bit_reversed_positive'`;
+        if (options?.startWithCounter !== undefined) {
+            sql += `, start_with_counter = ${options.startWithCounter}`;
+        }
+        if (options?.skipRangeMin !== undefined && options?.skipRangeMax !== undefined) {
+            sql += `, skip_range_min = ${options.skipRangeMin}, skip_range_max = ${options.skipRangeMax}`;
+        }
+        sql += ')';
+        await this.query(sql);
+    }
+    async dropSequence(name, options) {
+        try {
+            await this.query(`DROP SEQUENCE ${this.escapeId(name)}`);
+        }
+        catch (error) {
+            if (options?.ifExists)
+                return;
+            throw error;
+        }
+    }
+    /** SQL fragment to pull the next value from a bit-reversed sequence. */
+    nextBitReversedSequenceValueSql(name) {
+        return `GET_NEXT_SEQUENCE_VALUE(SEQUENCE ${this.escapeId(name)})`;
+    }
+    async nextBitReversedSequenceValue(name) {
+        const result = await this.query(`SELECT ${this.nextBitReversedSequenceValueSql(name)} AS next_val`);
+        return Number(result.rows[0]?.next_val);
+    }
+    // =========================================================================
+    // Transactions
+    // =========================================================================
+    /**
+     * Start a read-write transaction.
+     *
+     * See the file header: Spanner read-write transactions have no
+     * configurable isolation level - they are always externally consistent by
+     * construction. `options.isolationLevel` is accepted for interface parity
+     * with every other dialect but is ignored (with a warning) rather than
+     * silently mapped to a Spanner concept it doesn't correspond to.
+     *
+     * Implementation note: `database.runTransaction()` is callback-based
+     * (`(err, transaction) => ...`) and keeps the transaction lease open only
+     * as long as the promise returned from that callback is pending. To
+     * expose the imperative `startTransaction()`/`commitTransaction()`/
+     * `rollbackTransaction()` shape used elsewhere in this codebase, this
+     * method opens the transaction, hands the driver a promise that resolves
+     * only once `commitTransaction()`/`rollbackTransaction()` is called (see
+     * `pendingTx`), and returns immediately with the transaction handle.
+     */
+    async startTransaction(options) {
+        if (!this.database) {
+            throw new Error('Not connected to database');
+        }
+        if (options?.isolationLevel) {
+            console.warn(`Spanner: isolation level "${options.isolationLevel}" was requested, but Cloud Spanner read-write ` +
+                'transactions have no configurable isolation level - they are always externally consistent ' +
+                '(TrueTime-ordered, effectively stronger than SERIALIZABLE) by construction. Ignoring.');
+        }
+        let resolveTxn;
+        let rejectTxn;
+        const txnReady = new Promise((resolve, reject) => {
+            resolveTxn = resolve;
+            rejectTxn = reject;
+        });
+        let resolveDone;
+        const done = new Promise((resolve) => {
+            resolveDone = resolve;
+        });
+        this.database.runTransaction((err, txn) => {
+            if (err) {
+                rejectTxn(err);
+                return undefined;
+            }
+            resolveTxn(txn);
+            // The driver awaits this returned promise before finalizing/retrying
+            // the transaction attempt; it resolves once commitTransaction()/
+            // rollbackTransaction() signals completion via `pendingTx`.
+            return done;
+        });
+        const spannerTxn = await txnReady;
+        const transaction = new SpannerTransaction(spannerTxn, options);
+        this.pendingTx.set(transaction.id, resolveDone);
+        return transaction;
+    }
+    async commitTransaction(transaction) {
+        const tx = transaction;
+        await tx.spannerTransaction.commit();
+        this.pendingTx.get(tx.id)?.();
+        this.pendingTx.delete(tx.id);
+        tx.finished = true;
+    }
+    async rollbackTransaction(transaction) {
+        const tx = transaction;
+        if (typeof tx.spannerTransaction.rollback === 'function') {
+            await tx.spannerTransaction.rollback();
+        }
+        this.pendingTx.get(tx.id)?.();
+        this.pendingTx.delete(tx.id);
+        tx.finished = true;
+    }
+    /**
+     * Run a read-only transaction (strong read, or a stale/bounded-staleness
+     * read for lower latency at the cost of recency). This is a distinct
+     * concept from a read-write transaction in Spanner - it takes a
+     * consistent snapshot and never participates in commit/abort/retry - so
+     * it is exposed as its own method rather than forced through
+     * `startTransaction()`.
+     */
+    async runReadOnlyTransaction(fn, options) {
+        if (!this.database)
+            throw new Error('Not connected to database');
+        const [snapshot] = await this.database.getSnapshot(options || { strong: true });
+        try {
+            const run = async (sql, params) => {
+                const [rows] = await snapshot.run({ sql, params, json: true });
+                return rows;
+            };
+            return await fn(run);
+        }
+        finally {
+            snapshot.end();
+        }
+    }
+    // =========================================================================
+    // Backup / restore (Database Admin API)
+    // =========================================================================
+    //
+    // Cloud Spanner backups are a Database Admin API concept, not SQL - there
+    // is no `BACKUP DATABASE` DDL statement the way some other engines have.
+    // These methods wrap `DatabaseAdminClient#createBackup/getBackup/
+    // listBackups/deleteBackup/restoreDatabase` (verified against
+    // `@google-cloud/spanner`'s `v1.DatabaseAdminClient` type definitions -
+    // `node_modules/@google-cloud/spanner/build/src/v1/database_admin_client.d.ts`
+    // - rather than guessed). `createBackup`/`restoreDatabase` both return
+    // long-running operations; these methods await `operation.promise()` so
+    // callers get the finished `Backup`/`Database` resource back directly,
+    // matching the synchronous, promise-returning shape used elsewhere in this
+    // dialect (`runDDL()` does the same for `updateSchema()`).
+    /** Resolve the project ID used to build Admin API resource paths. */
+    getProjectId() {
+        return this.config.projectId || this.spannerClient?.projectId;
+    }
+    getDatabaseAdminClient() {
+        if (!this.spannerClient) {
+            throw new Error('Not connected to database');
+        }
+        return this.spannerClient.getDatabaseAdminClient();
+    }
+    /**
+     * Start a backup of `databaseId` (defaults to this dialect's configured
+     * database), storing it as `backupId` with the given expiration time.
+     * Returns the completed `Backup` resource once the long-running operation
+     * finishes (`Backup.state` will be `READY`).
+     */
+    async createBackup(backupId, expireTime, databaseId) {
+        const adminClient = this.getDatabaseAdminClient();
+        const projectId = this.getProjectId();
+        const instanceId = this.config.instanceId;
+        const dbId = databaseId || this.config.databaseId;
+        const [operation] = await adminClient.createBackup({
+            parent: adminClient.instancePath(projectId, instanceId),
+            backupId,
+            backup: {
+                database: adminClient.databasePath(projectId, instanceId, dbId),
+                expireTime: { seconds: Math.floor(expireTime.getTime() / 1000), nanos: 0 },
+            },
+        });
+        const [backup] = await operation.promise();
+        return backup;
+    }
+    /**
+     * List backups in this dialect's instance. `filter` is a Cloud Spanner
+     * backup filter expression (e.g. `state:READY`,
+     * `database:my-db`) - see `DatabaseAdminClient#listBackups()`'s
+     * `request.filter` for the supported grammar; omit for all backups in the
+     * instance.
+     */
+    async listBackups(filter) {
+        const adminClient = this.getDatabaseAdminClient();
+        const projectId = this.getProjectId();
+        const [backups] = await adminClient.listBackups({
+            parent: adminClient.instancePath(projectId, this.config.instanceId),
+            filter,
+        });
+        return backups;
+    }
+    /** Fetch a single backup's metadata by ID. */
+    async getBackup(backupId) {
+        const adminClient = this.getDatabaseAdminClient();
+        const projectId = this.getProjectId();
+        const [backup] = await adminClient.getBackup({
+            name: adminClient.backupPath(projectId, this.config.instanceId, backupId),
+        });
+        return backup;
+    }
+    /** Delete a backup by ID. */
+    async deleteBackup(backupId) {
+        const adminClient = this.getDatabaseAdminClient();
+        const projectId = this.getProjectId();
+        await adminClient.deleteBackup({
+            name: adminClient.backupPath(projectId, this.config.instanceId, backupId),
+        });
+    }
+    /**
+     * Restore `backupId` into a brand-new database `newDatabaseId` in this
+     * dialect's instance. The new database must not already exist, and must
+     * be created in an instance with the same instance configuration as the
+     * one holding the backup. Returns the completed `Database` resource once
+     * the long-running restore operation finishes.
+     */
+    async restoreDatabase(backupId, newDatabaseId) {
+        const adminClient = this.getDatabaseAdminClient();
+        const projectId = this.getProjectId();
+        const instanceId = this.config.instanceId;
+        const [operation] = await adminClient.restoreDatabase({
+            parent: adminClient.instancePath(projectId, instanceId),
+            databaseId: newDatabaseId,
+            backup: adminClient.backupPath(projectId, instanceId, backupId),
+        });
+        const [database] = await operation.promise();
+        return database;
+    }
+    // =========================================================================
+    // Data types
+    // =========================================================================
+    getDataTypeSql(dataType) {
+        if (typeof dataType === 'string')
+            return dataType;
+        if (!dataType || typeof dataType !== 'object')
+            return 'STRING(MAX)';
+        const dt = dataType;
+        switch (dt.key) {
+            case 'STRING':
+            case 'CHAR':
+                return `STRING(${dt.length || 255})`;
+            case 'TEXT':
+                return 'STRING(MAX)';
+            case 'NUMBER':
+            case 'INTEGER':
+            case 'BIGINT':
+                return 'INT64';
+            case 'FLOAT':
+            case 'DOUBLE':
+                return 'FLOAT64';
+            case 'DECIMAL':
+                return 'NUMERIC';
+            case 'BOOLEAN':
+                return 'BOOL';
+            case 'DATE':
+                return 'TIMESTAMP';
+            case 'DATEONLY':
+                return 'DATE';
+            case 'TIME':
+                console.warn('Spanner: no native TIME type; mapping to STRING(MAX).');
+                return 'STRING(MAX)';
+            case 'BLOB':
+                return `BYTES(${dt.length || 'MAX'})`;
+            case 'UUID':
+                return 'STRING(36)';
+            case 'JSON':
+            case 'JSONB':
+                return 'JSON';
+            case 'ENUM': {
+                const values = dt.values || [];
+                const checkValues = values.map((v) => `'${this.escapeString(v)}'`).join(', ');
+                return `STRING(MAX)${values.length ? ` CHECK (%%COLUMN%% IN (${checkValues}))` : ''}`;
+            }
+            case 'ARRAY': {
+                // Support both 'type' (DataTypes.ARRAY(DataTypes.INTEGER)) and
+                // 'subtype' (a plain { type: 'ARRAY', subtype: 'INTEGER' } literal),
+                // mirroring the postgres/cockroachdb dialects' ARRAY handling.
+                const elementType = dt.type ?? dt.subtype;
+                const elementSql = elementType ? this.getDataTypeSql(elementType) : 'STRING(MAX)';
+                return `ARRAY<${elementSql}>`;
+            }
+            case 'HSTORE':
+                return 'JSON';
+            case 'GEOMETRY':
+                throw new Error('Cloud Spanner has no built-in geometry/geography type.');
+            case 'SET':
+            case 'RANGE':
+            case 'INET':
+            case 'CIDR':
+            case 'MACADDR':
+                console.warn(`Spanner: no native "${dt.key}" type; mapping to STRING(MAX).`);
+                return 'STRING(MAX)';
+            default:
+                return 'STRING(MAX)';
+        }
+    }
+    // =========================================================================
+    // Query building
+    // =========================================================================
+    buildWhereClause(where, _options) {
+        const values = [];
+        if (!where || Object.keys(where).length === 0) {
+            return { sql: '', values };
+        }
+        const nextParam = () => `@p${values.length}`;
+        const buildCondition = (condition) => {
+            if (!condition)
+                return '';
+            const cond = condition;
+            if (cond.$and || cond.$or || cond.$not) {
+                const parts = [];
+                if (cond.$and)
+                    parts.push(`(${cond.$and.map(buildCondition).join(' AND ')})`);
+                if (cond.$or)
+                    parts.push(`(${cond.$or.map(buildCondition).join(' OR ')})`);
+                if (cond.$not)
+                    parts.push(`NOT (${buildCondition(cond.$not)})`);
+                return parts.join(' AND ');
+            }
+            const fieldConditions = [];
+            for (const [key, value] of Object.entries(cond)) {
+                if (key.startsWith('$'))
+                    continue;
+                const col = this.escapeId(key);
+                if (value && typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) {
+                    const v = value;
+                    if (v.$eq !== undefined) {
+                        values.push(v.$eq);
+                        fieldConditions.push(`${col} = ${nextParam()}`);
+                    }
+                    else if (v.$ne !== undefined) {
+                        values.push(v.$ne);
+                        fieldConditions.push(`${col} != ${nextParam()}`);
+                    }
+                    else if (v.$gt !== undefined) {
+                        values.push(v.$gt);
+                        fieldConditions.push(`${col} > ${nextParam()}`);
+                    }
+                    else if (v.$gte !== undefined) {
+                        values.push(v.$gte);
+                        fieldConditions.push(`${col} >= ${nextParam()}`);
+                    }
+                    else if (v.$lt !== undefined) {
+                        values.push(v.$lt);
+                        fieldConditions.push(`${col} < ${nextParam()}`);
+                    }
+                    else if (v.$lte !== undefined) {
+                        values.push(v.$lte);
+                        fieldConditions.push(`${col} <= ${nextParam()}`);
+                    }
+                    else if (v.$like !== undefined) {
+                        values.push(v.$like);
+                        fieldConditions.push(`${col} LIKE ${nextParam()}`);
+                    }
+                    else if (v.$notLike !== undefined) {
+                        values.push(v.$notLike);
+                        fieldConditions.push(`${col} NOT LIKE ${nextParam()}`);
+                    }
+                    else if (v.$iLike !== undefined) {
+                        // GoogleSQL has no ILIKE; approximate case-insensitive LIKE via LOWER().
+                        values.push(String(v.$iLike).toLowerCase());
+                        fieldConditions.push(`LOWER(${col}) LIKE ${nextParam()}`);
+                    }
+                    else if (v.$notILike !== undefined) {
+                        values.push(String(v.$notILike).toLowerCase());
+                        fieldConditions.push(`LOWER(${col}) NOT LIKE ${nextParam()}`);
+                    }
+                    else if (v.$in) {
+                        const inValues = v.$in;
+                        const placeholders = inValues.map((val) => {
+                            values.push(val);
+                            return nextParam();
+                        });
+                        fieldConditions.push(`${col} IN (${placeholders.join(', ')})`);
+                    }
+                    else if (v.$notIn) {
+                        const notInValues = v.$notIn;
+                        const placeholders = notInValues.map((val) => {
+                            values.push(val);
+                            return nextParam();
+                        });
+                        fieldConditions.push(`${col} NOT IN (${placeholders.join(', ')})`);
+                    }
+                    else if (v.$between) {
+                        const [lo, hi] = v.$between;
+                        values.push(lo);
+                        const p1 = nextParam();
+                        values.push(hi);
+                        const p2 = nextParam();
+                        fieldConditions.push(`${col} BETWEEN ${p1} AND ${p2}`);
+                    }
+                    else if (v.$notBetween) {
+                        const [lo, hi] = v.$notBetween;
+                        values.push(lo);
+                        const p1 = nextParam();
+                        values.push(hi);
+                        const p2 = nextParam();
+                        fieldConditions.push(`${col} NOT BETWEEN ${p1} AND ${p2}`);
+                    }
+                    else if (v.$isNull !== undefined) {
+                        fieldConditions.push(`${col} IS ${v.$isNull ? '' : 'NOT '}NULL`);
+                    }
+                    else {
+                        values.push(value);
+                        fieldConditions.push(`${col} = ${nextParam()}`);
+                    }
+                }
+                else if (value === null) {
+                    fieldConditions.push(`${col} IS NULL`);
+                }
+                else {
+                    values.push(value);
+                    fieldConditions.push(`${col} = ${nextParam()}`);
+                }
+            }
+            return fieldConditions.join(' AND ');
+        };
+        const sql = buildCondition(where);
+        return { sql, values };
+    }
+    buildOrderClause(order) {
+        const orderArray = order;
+        if (!orderArray || !Array.isArray(orderArray) || orderArray.length === 0)
+            return '';
+        const parts = orderArray.map((item) => {
+            if (Array.isArray(item)) {
+                const field = typeof item[0] === 'string' ? this.escapeId(item[0]) : item[0];
+                const direction = item[1] ? ` ${item[1]}` : '';
+                return `${field}${direction}`;
+            }
+            if (typeof item === 'string')
+                return this.escapeId(item);
+            return String(item);
+        });
+        return `ORDER BY ${parts.join(', ')}`;
+    }
+    /**
+     * Build a `LIMIT`/`OFFSET` clause. GoogleSQL requires `LIMIT` whenever
+     * `OFFSET` is used (there's no bare `OFFSET n` the way Postgres allows) -
+     * when only an offset is given, this emits a very large LIMIT to satisfy
+     * that requirement.
+     */
+    buildLimitOffset(limit, offset) {
+        let sql = '';
+        if (limit !== undefined) {
+            sql += ` LIMIT ${Number(limit)}`;
+            if (offset !== undefined)
+                sql += ` OFFSET ${Number(offset)}`;
+        }
+        else if (offset !== undefined) {
+            sql += ` LIMIT ${Number.MAX_SAFE_INTEGER} OFFSET ${Number(offset)}`;
+        }
+        return sql;
+    }
+    /**
+     * Build an INSERT statement. When `options.upsert` is set, emits
+     * GoogleSQL's `INSERT OR UPDATE INTO` upsert DML (verified: Spanner has no
+     * `ON CONFLICT` clause; GoogleSQL's DML upsert extension also offers
+     * `INSERT OR IGNORE` / `INSERT OR REPLACE` conflict-action variants, but
+     * only `OR UPDATE` is wired up here - there is no `conflictAction` option
+     * to select the other two). For bulk/blind writes prefer
+     * `mutationInsert()`/`mutationUpsert()` (the Mutation API) instead - see
+     * the file header.
+     */
+    buildInsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const processedValues = [];
+        const placeholders = [];
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                placeholders.push(value.val);
+            }
+            else {
+                processedValues.push(value);
+                placeholders.push(`@p${processedValues.length}`);
+            }
+        }
+        const verb = options?.upsert ? 'INSERT OR UPDATE INTO' : 'INSERT INTO';
+        const sql = `${verb} ${this.escapeId(tableName)} (${columns.map((c) => this.escapeId(c)).join(', ')}) VALUES (${placeholders.join(', ')})`;
+        if (options?.returning) {
+            console.warn('Spanner: GoogleSQL DML has no RETURNING clause; ignoring options.returning.');
+        }
+        return { sql, values: processedValues };
+    }
+    /**
+     * Build an upsert statement using GoogleSQL's `INSERT OR UPDATE INTO`.
+     * Note this is a *SQL DML* fallback for interface parity - the primary,
+     * recommended mechanism for upserts on this dialect is the Mutation API
+     * (`mutationUpsert()` / `database.table(name).upsert(rows)`); see the file
+     * header for why.
+     */
+    buildUpsertQuery(tableName, values, options) {
+        void options;
+        return this.buildInsertQuery(tableName, values, { upsert: true });
+    }
+    buildIncrementQuery(tableName, fields, where, options) {
+        const by = options?.by ?? 1;
+        const setClauses = [];
+        const queryValues = [];
+        const pushField = (field, amount) => {
+            queryValues.push(amount);
+            setClauses.push(`${this.escapeId(field)} = ${this.escapeId(field)} + @p${queryValues.length}`);
+        };
+        if (typeof fields === 'string') {
+            pushField(fields, by);
+        }
+        else if (Array.isArray(fields)) {
+            fields.forEach((field) => pushField(field, by));
+        }
+        else {
+            for (const [field, amount] of Object.entries(fields))
+                pushField(field, amount);
+        }
+        const whereClause = this.buildWhereClause(where);
+        const offset = queryValues.length;
+        const reindexedWhereSql = whereClause.sql.replace(/@p(\d+)/g, (_, n) => `@p${offset + Number(n)}`);
+        queryValues.push(...whereClause.values);
+        let sql = `UPDATE ${this.escapeId(tableName)} SET ${setClauses.join(', ')}`;
+        sql += ` WHERE ${reindexedWhereSql || 'TRUE'}`;
+        return { sql, values: queryValues };
+    }
+    buildUpdateQuery(tableName, values, where, options) {
+        const setClauses = [];
+        const queryValues = [];
+        for (const [key, value] of Object.entries(values)) {
+            if (value instanceof prorm_1.Literal) {
+                setClauses.push(`${this.escapeId(key)} = ${value.val}`);
+            }
+            else {
+                queryValues.push(value);
+                setClauses.push(`${this.escapeId(key)} = @p${queryValues.length}`);
+            }
+        }
+        const whereClause = this.buildWhereClause(where);
+        const offset = queryValues.length;
+        const reindexedWhereSql = whereClause.sql.replace(/@p(\d+)/g, (_, n) => `@p${offset + Number(n)}`);
+        queryValues.push(...whereClause.values);
+        let sql = `UPDATE ${this.escapeId(tableName)} SET ${setClauses.join(', ')}`;
+        // GoogleSQL UPDATE requires a WHERE clause (no unconditional UPDATE).
+        sql += ` WHERE ${reindexedWhereSql || 'TRUE'}`;
+        if (options?.limit) {
+            console.warn('Spanner: UPDATE has no LIMIT clause; ignoring options.limit.');
+        }
+        if (options?.returning) {
+            console.warn('Spanner: GoogleSQL DML has no RETURNING clause; ignoring options.returning.');
+        }
+        return { sql, values: queryValues };
+    }
+    buildDeleteQuery(tableName, where, options) {
+        if (options?.truncate) {
+            // GoogleSQL has no TRUNCATE; DELETE with an always-true predicate is
+            // the standard workaround (Spanner DELETE also requires a WHERE clause).
+            return { sql: `DELETE FROM ${this.escapeId(tableName)} WHERE TRUE`, values: [] };
+        }
+        const whereClause = this.buildWhereClause(where);
+        let sql = `DELETE FROM ${this.escapeId(tableName)} WHERE ${whereClause.sql || 'TRUE'}`;
+        if (options?.limit) {
+            console.warn('Spanner: DELETE has no LIMIT clause; ignoring options.limit.');
+        }
+        if (options?.returning) {
+            console.warn('Spanner: GoogleSQL DML has no RETURNING clause; ignoring options.returning.');
+        }
+        return { sql, values: whereClause.values };
+    }
+    /**
+     * Build a SELECT statement. GoogleSQL supports standard window functions
+     * (`OVER (...)`) and CTEs (including `WITH RECURSIVE`) natively as part of
+     * its query syntax; pass them straight through as raw SQL fragments via
+     * `Literal`/`attributes` (window functions) or `buildRecursiveCteQuery()`
+     * (CTEs) - no special dialect-layer plumbing is required beyond what's
+     * already here, since both are just SELECT-query syntax GoogleSQL parses
+     * natively.
+     */
+    buildSelectQuery(options) {
+        const values = [];
+        let attributesSql = '*';
+        if (options.attributes) {
+            if (Array.isArray(options.attributes)) {
+                attributesSql = options.attributes
+                    .map((attr) => (typeof attr === 'string' ? this.escapeId(attr) : String(attr)))
+                    .join(', ');
+            }
+            else {
+                const exclude = new Set(options.attributes.exclude || []);
+                const include = options.attributes.include || [];
+                attributesSql = include.length
+                    ? include.map((a) => this.escapeId(a)).join(', ')
+                    : Array.from(exclude).length
+                        ? '*'
+                        : '*';
+            }
+        }
+        if (options.distinct) {
+            attributesSql = `DISTINCT ${attributesSql}`;
+        }
+        const tableSql = options.schema
+            ? this.quoteTable(options.tableName, options.schema)
+            : this.escapeId(options.tableName);
+        let sql = `SELECT ${attributesSql} FROM ${tableSql}`;
+        if (options.where) {
+            const whereClause = this.buildWhereClause(options.where);
+            if (whereClause.sql) {
+                sql += ` WHERE ${whereClause.sql}`;
+                values.push(...whereClause.values);
+            }
+        }
+        if (options.group) {
+            const groupFields = Array.isArray(options.group) ? options.group : [options.group];
+            sql += ` GROUP BY ${groupFields.map((f) => this.escapeId(f)).join(', ')}`;
+        }
+        if (options.having) {
+            const offset = values.length;
+            const havingClause = this.buildWhereClause(options.having);
+            const reindexed = havingClause.sql.replace(/@p(\d+)/g, (_, n) => `@p${offset + Number(n)}`);
+            sql += ` HAVING ${reindexed}`;
+            values.push(...havingClause.values);
+        }
+        if (options.order) {
+            const orderClause = this.buildOrderClause(options.order);
+            if (orderClause)
+                sql += ` ${orderClause}`;
+        }
+        sql += this.buildLimitOffset(options.limit, options.offset);
+        if (options.union && options.union.length) {
+            const unionType = options.unionType || 'UNION';
+            for (const unionQuery of options.union) {
+                sql += ` ${unionType} `;
+                const subOptions = {
+                    tableName: unionQuery.model?.tableName || options.tableName,
+                    attributes: unionQuery.attributes,
+                    where: unionQuery.where,
+                    order: unionQuery.order,
+                    limit: unionQuery.limit,
+                    offset: unionQuery.offset,
+                };
+                const offset = values.length;
+                const sub = this.buildSelectQuery(subOptions);
+                const reindexed = sub.sql.replace(/@p(\d+)/g, (_, n) => `@p${offset + Number(n)}`);
+                sql += reindexed;
+                values.push(...sub.values);
+            }
+        }
+        return { sql, values };
+    }
+    /**
+     * Build a (optionally recursive) CTE-prefixed query -
+     * `WITH [RECURSIVE] name AS (...), ... <mainQuery>` - which GoogleSQL
+     * supports natively, including recursive CTEs (`WITH RECURSIVE`).
+     */
+    buildRecursiveCteQuery(ctes, mainQuery) {
+        const recursive = ctes.some((c) => c.recursive);
+        const cteSql = ctes.map((c) => `${this.escapeId(c.name)} AS (${c.query})`).join(', ');
+        return `WITH ${recursive ? 'RECURSIVE ' : ''}${cteSql} ${mainQuery}`;
+    }
+    /**
+     * Build a `ROW_NUMBER()`/`RANK()`/`DENSE_RANK()`-style window function
+     * expression string, for use inside `attributes`/`Literal`. GoogleSQL's
+     * window function syntax matches standard SQL exactly, so this is a thin
+     * convenience wrapper rather than something requiring dialect-specific
+     * translation.
+     */
+    buildWindowFunction(fn, options) {
+        const partition = options?.partitionBy?.length
+            ? `PARTITION BY ${options.partitionBy.map((f) => this.escapeId(f)).join(', ')}`
+            : '';
+        const order = options?.orderBy?.length
+            ? `ORDER BY ${options.orderBy.map(([f, dir]) => `${this.escapeId(f)}${dir ? ` ${dir}` : ''}`).join(', ')}`
+            : '';
+        const frame = options?.frame || '';
+        const overParts = [partition, order, frame].filter(Boolean).join(' ');
+        return `${fn} OVER (${overParts})`;
+    }
+}
+exports.SpannerDialect = SpannerDialect;
+// =========================================================================
+// Foreign Data Wrappers - PostgreSQL-only concept, not applicable to Spanner
+// =========================================================================
+SpannerDialect.FDW_NOT_SUPPORTED = 'Foreign Data Wrappers are a PostgreSQL concept and are not supported by Cloud Spanner. ' +
+    'Spanner federates external data via BigQuery federated queries / Data Boost export, which is out of scope for this ORM.';
+// =========================================================================
+// User / privilege management
+// =========================================================================
+//
+// Spanner does not have classic per-connection database USERs/GRANT-to-user
+// the way MySQL/Postgres do - access is governed by Cloud IAM (at the
+// project/instance/database level) plus, within GoogleSQL, fine-grained
+// "database roles" (`CREATE ROLE` / `GRANT <privilege> ON TABLE t TO ROLE
+// r`). The classic CREATE/ALTER/DROP USER surface has no Spanner analogue
+// at all, so those throw; a full database-roles implementation is out of
+// scope for this pass.
+SpannerDialect.USER_MGMT_NOT_SUPPORTED = 'Cloud Spanner has no per-connection database users; access is governed by Cloud IAM and ' +
+    '(for fine-grained table/column privileges) GoogleSQL database roles (CREATE ROLE / GRANT ... TO ROLE), not CREATE USER.';
+// =========================================================================
+// Stored procedures - not supported (no procedural SQL in GoogleSQL)
+// =========================================================================
+SpannerDialect.PROC_NOT_SUPPORTED = 'Cloud Spanner GoogleSQL has no stored procedures / procedural SQL (no CREATE PROCEDURE, PL/pgSQL, or T-SQL equivalent). Move procedural logic into the application layer.';