ts-prorm-orm 1.1.0 → 1.2.0

package/dist/dialects/spanner/index.d.ts

@@ -0,0 +1,660 @@
+/**
+ * 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). All three are selectable
+ * via the `conflictAction` option (`'UPDATE' | 'IGNORE' | 'REPLACE'`) on
+ * `buildInsertQuery()`/`buildUpsertQuery()`; `upsert: true` remains a legacy
+ * alias for `conflictAction: 'UPDATE'`. 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
+ */
+import { Dialect, ColumnDefinition, TableOptions, DropTableOptions, TableDescription, IndexOptions, IndexDefinition, InsertOptions, UpdateOptions as DUpdateOptions, DeleteOptions, SelectOptions, UpsertQueryOptions, CreateExtensionOptions, DropExtensionOptions, ExtensionInfo, FdwForeignServerOptions, FdwAlterForeignServerOptions, FdwUserMappingOptions, FdwForeignTableOptions, FdwImportForeignSchemaOptions, ConstraintDefinition, ViewOptions, DropViewOptions, DropSchemaOptions, DropIndexOptions, DropConstraintOptions } from '../dialect';
+import { Transaction, TransactionOptions, QueryResult, QueryOptions, DataType, WhereOptions, Order, StoredProcedureOptions, DropStoredProcedureOptions, ExecuteStoredProcedureOptions, StreamOptions } from '../../types';
+import { Readable } from 'stream';
+/**
+ * Authentication / connection options for the Spanner dialect.
+ *
+ * Spanner authenticates via Google Application Default Credentials (ADC) by
+ * default - i.e. the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
+ * pointing at a service-account JSON key file, or ambient credentials when
+ * running on GCP (GCE/GKE/Cloud Run metadata server). `keyFilename` and
+ * `credentials` are provided for explicit, non-ADC auth and are passed
+ * straight through to the underlying `Spanner` client constructor.
+ */
+export interface SpannerDialectOptions {
+    /** GCP project ID that owns the Spanner instance */
+    projectId?: string;
+    /** Spanner instance ID (e.g. 'prod-instance') */
+    instanceId: string;
+    /** Spanner database ID within the instance */
+    databaseId: string;
+    /**
+     * Path to a service-account key file. If omitted, falls back to
+     * `GOOGLE_APPLICATION_CREDENTIALS` / ambient Application Default
+     * Credentials, same as the raw `@google-cloud/spanner` client.
+     */
+    keyFilename?: string;
+    /** Explicit service-account credentials object (alternative to keyFilename/ADC) */
+    credentials?: Record<string, any>;
+    /** Override API endpoint (e.g. for the Spanner emulator: 'localhost:9010') */
+    apiEndpoint?: string;
+    /** Use the Spanner emulator (sets emulator-friendly defaults) */
+    emulator?: boolean;
+    /** Query options forwarded to every `database.run()` call (e.g. optimizer version) */
+    queryOptions?: Record<string, any>;
+    /**
+     * Skip the automatic GoogleSQL-dialect check that `connect()` otherwise
+     * performs (see `assertGoogleSqlDialect()`). Set this if you've already
+     * verified the target database's dialect out of band, or when talking to
+     * an emulator/environment where `getDatabaseDialect()` is unavailable.
+     */
+    skipDialectCheck?: boolean;
+}
+/**
+ * Spanner-specific table options: explicit primary key (Spanner's `PRIMARY
+ * KEY (...)` clause is written *after* the column list, unlike every other
+ * dialect in this codebase where PK is a column/table constraint inside the
+ * parens) and interleaving.
+ */
+export interface SpannerTableOptions {
+    /**
+     * Explicit primary key column list and order. If omitted, inferred from
+     * columns whose `ColumnDefinition.primaryKey` is `true`, in declaration
+     * order.
+     */
+    primaryKey?: string[];
+    /** Interleave this table as a child of `parentTable` (`INTERLEAVE IN PARENT ...`) */
+    interleaveInParent?: string;
+    /** `ON DELETE CASCADE` vs. the default `ON DELETE NO ACTION` for interleaved tables */
+    interleaveOnDeleteCascade?: boolean;
+    /** Row deletion policy (Spanner TTL): `OLDER_THAN(column, INTERVAL n DAY)` */
+    rowDeletionPolicy?: {
+        column: string;
+        olderThanDays: number;
+    };
+}
+/**
+ * Options for `createInterleavedTable()`.
+ */
+export interface InterleavedTableOptions extends TableOptions {
+    /** Explicit primary key (must include the parent table's primary key as a prefix) */
+    primaryKey: string[];
+    /** `ON DELETE CASCADE` vs. the default `ON DELETE NO ACTION` */
+    onDeleteCascade?: boolean;
+}
+/**
+ * Which GoogleSQL DML conflict-action variant to emit on primary-key
+ * collision (Spanner has no `ON CONFLICT` clause):
+ *  - `UPDATE`  → `INSERT OR UPDATE INTO`  (overwrite non-key columns)
+ *  - `IGNORE`  → `INSERT OR IGNORE INTO`  (skip the row)
+ *  - `REPLACE` → `INSERT OR REPLACE INTO` (delete-then-reinsert the whole row)
+ */
+export type SpannerConflictAction = 'UPDATE' | 'IGNORE' | 'REPLACE';
+/**
+ * `InsertOptions` extended with Spanner's `conflictAction` selector. The
+ * legacy `upsert: true` boolean remains supported and is equivalent to
+ * `conflictAction: 'UPDATE'`.
+ */
+export interface SpannerInsertOptions extends InsertOptions {
+    conflictAction?: SpannerConflictAction;
+}
+/**
+ * `UpsertQueryOptions` extended with Spanner's `conflictAction` selector
+ * (defaults to `'UPDATE'` when omitted).
+ */
+export interface SpannerUpsertQueryOptions extends UpsertQueryOptions {
+    conflictAction?: SpannerConflictAction;
+}
+/**
+ * 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.
+ */
+export declare class SpannerTransaction extends Transaction {
+    /** The underlying `@google-cloud/spanner` Transaction object */
+    spannerTransaction: any;
+    constructor(spannerTransaction: any, options?: TransactionOptions);
+}
+/**
+ * Google Cloud Spanner dialect class implementing the shared `Dialect` interface.
+ */
+export declare class SpannerDialect implements Dialect {
+    readonly name = "spanner";
+    readonly library = "@google-cloud/spanner";
+    private spannerClient;
+    private instance;
+    private database;
+    private _isConnected;
+    private config;
+    /**
+     * 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.
+     */
+    private pendingTx;
+    constructor(config: SpannerDialectOptions);
+    connect(): Promise<void>;
+    /**
+     * 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).
+     */
+    assertGoogleSqlDialect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnection(): any;
+    isConnected(): boolean;
+    /**
+     * 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: any): boolean;
+    /**
+     * 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).
+     */
+    private buildParams;
+    /**
+     * 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: string, options?: StreamOptions): Readable;
+    /**
+     * 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).
+     */
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    private runDDL;
+    private runRead;
+    /**
+     * 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.
+     */
+    private runDML;
+    escape(value: any): string;
+    /**
+     * 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 (`\'`, `\\`).
+     */
+    private escapeString;
+    /**
+     * GoogleSQL quotes identifiers with backticks (like BigQuery/MySQL), not
+     * double quotes.
+     */
+    escapeId(identifier: string): string;
+    quoteIdentifier(identifier: string): string;
+    quoteTable(tableName: string, schema?: string): string;
+    /**
+     * Replace `@pN` / `@name` placeholders in SQL with escaped literal values.
+     */
+    replaceReplacements(sql: string, replacements?: Record<string, unknown> | unknown[]): string;
+    createSchema(_schema: string): Promise<void>;
+    dropSchema(_schema: string, _options?: DropSchemaOptions): Promise<void>;
+    showAllSchemas(): Promise<string[]>;
+    listSchemas(): Promise<string[]>;
+    createDatabaseSQL(_options: {
+        name: string;
+        encoding?: string;
+        lcCollate?: string;
+        lcCtype?: string;
+        template?: string;
+        tablespace?: string;
+        collate?: string;
+        isTemplate?: boolean;
+    }): string;
+    dropDatabaseSQL(_name: string): string;
+    /**
+     * 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?: string): string;
+    releaseSavepointSQL(_name: string): string;
+    rollbackToSavepointSQL(_name: string): string;
+    createExtension(_extensionName: string, _options?: CreateExtensionOptions): Promise<void>;
+    dropExtension(_extensionName: string, _options?: DropExtensionOptions): Promise<void>;
+    getExtensions(): Promise<ExtensionInfo[]>;
+    hasExtension(_extensionName: string): Promise<boolean>;
+    getDatabaseVersion(): Promise<string>;
+    /**
+     * 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.
+     */
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions & SpannerTableOptions): Promise<void>;
+    private buildConstraintSql;
+    private getColumnDefinitionSql;
+    private getDefaultValue;
+    dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+    /**
+     * 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`.
+     */
+    createInterleavedTable(tableName: string, parentTable: string, columns: Record<string, ColumnDefinition>, options: InterleavedTableOptions): Promise<void>;
+    createPartitionedTable(): Promise<void>;
+    createPartition(): Promise<void>;
+    attachPartition(): Promise<void>;
+    detachPartition(): Promise<void>;
+    dropPartition(): Promise<void>;
+    createView(viewName: string, query: string, options?: ViewOptions): Promise<void>;
+    dropView(viewName: string, options?: DropViewOptions): Promise<void>;
+    showViews(): Promise<string[]>;
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    removeColumn(tableName: string, columnName: string): Promise<void>;
+    changeColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    renameColumn(): Promise<void>;
+    addForeignKey(tableName: string, columnName: string, referencedTableName: string, referencedColumnName: string, options?: any): Promise<void>;
+    /**
+     * 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.
+     */
+    bulkInsert(tableName: string, records: Record<string, any>[], _options?: any): Promise<QueryResult>;
+    /** Mutation API: insert rows (fails if any row's key already exists). */
+    mutationInsert(tableName: string, rows: Record<string, any>[]): Promise<void>;
+    /** Mutation API: update rows (fails if a row's key does not exist). */
+    mutationUpdate(tableName: string, rows: Record<string, any>[]): Promise<void>;
+    /**
+     * 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.
+     */
+    mutationUpsert(tableName: string, rows: Record<string, any>[]): Promise<void>;
+    /** Mutation API: delete rows by primary key. */
+    mutationDelete(tableName: string, keys: (string | number | (string | number)[])[]): Promise<void>;
+    showTables(): Promise<string[]>;
+    showConstraints(tableName: string): Promise<any[]>;
+    addConstraint(tableName: string, options: {
+        type: 'UNIQUE' | 'CHECK' | 'PRIMARY KEY' | 'FOREIGN KEY';
+        fields: string[];
+        name?: string;
+        references?: {
+            table: string;
+            fields: string[];
+        };
+        check?: string;
+    }): Promise<void>;
+    removeConstraint(tableName: string, constraintName: string): Promise<void>;
+    showIndexes(tableName: string): Promise<any[]>;
+    describeTable(tableName: string): Promise<TableDescription>;
+    renameTable(): Promise<void>;
+    /**
+     * 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.
+     */
+    addIndex(tableName: string, indexName: string, fields: string[], options?: IndexOptions): Promise<void>;
+    removeIndex(tableName: string, indexName: string): Promise<void>;
+    createIndex(tableName: string, indexDef: IndexDefinition): Promise<void>;
+    createFulltextIndex(): Promise<void>;
+    createSpatialIndex(): Promise<void>;
+    dropIndex(tableName: string, indexName: string, options?: DropIndexOptions): Promise<void>;
+    createConstraint(tableName: string, constraintDef: ConstraintDefinition): Promise<void>;
+    dropConstraint(tableName: string, constraintName: string, options?: DropConstraintOptions): Promise<void>;
+    changeOwner(): Promise<void>;
+    private static readonly FDW_NOT_SUPPORTED;
+    createForeignDataWrapper(): Promise<void>;
+    dropForeignDataWrapper(): Promise<void>;
+    createForeignServer(): Promise<void>;
+    dropForeignServer(): Promise<void>;
+    createForeignTable(): Promise<void>;
+    buildCreateServerQuery(_name: string, _opts: FdwForeignServerOptions): string;
+    buildAlterServerQuery(_name: string, _opts: FdwAlterForeignServerOptions): string;
+    buildDropServerQuery(): string;
+    buildCreateUserMappingQuery(_opts: FdwUserMappingOptions): string;
+    buildAlterUserMappingQuery(_opts: FdwUserMappingOptions): string;
+    buildDropUserMappingQuery(): string;
+    createUserMapping(): Promise<void>;
+    dropUserMapping(): Promise<void>;
+    buildCreateForeignTableQuery(_tableName: string, _opts: FdwForeignTableOptions): string;
+    buildDropForeignTableQuery(): string;
+    buildImportForeignSchemaQuery(_remoteSchema: string, _serverName: string, _opts?: FdwImportForeignSchemaOptions): string;
+    getServersQuery(): string;
+    private static readonly USER_MGMT_NOT_SUPPORTED;
+    buildCreateUserQuery(): string;
+    buildAlterUserQuery(): string;
+    buildDropUserQuery(): string;
+    getUsersQuery(): string;
+    buildGrantQuery(): string;
+    buildRevokeQuery(): string;
+    buildShowGrantsQuery(): string;
+    buildFlushPrivilegesQuery(): string;
+    buildCreateRoleQuery(roleName: string): string;
+    buildDropRoleQuery(roleName: string): string;
+    buildGrantRoleQuery(role: string, to: any): string;
+    buildRevokeRoleQuery(role: string, from: any): string;
+    getRolesQuery(): string;
+    createSecurityPolicy(): Promise<void>;
+    dropSecurityPolicy(): Promise<void>;
+    private static readonly PROC_NOT_SUPPORTED;
+    createStoredProcedure(_options: StoredProcedureOptions): Promise<void>;
+    createProcedure(options: StoredProcedureOptions): Promise<void>;
+    dropStoredProcedure(_procedureName: string, _options?: DropStoredProcedureOptions): Promise<void>;
+    dropProcedure(procedureName: string, options?: DropStoredProcedureOptions): Promise<void>;
+    executeStoredProcedure(_options: ExecuteStoredProcedureOptions): Promise<QueryResult>;
+    hasStoredProcedure(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    createBitReversedSequence(name: string, options?: {
+        startWithCounter?: number;
+        skipRangeMin?: number;
+        skipRangeMax?: number;
+    }): Promise<void>;
+    dropSequence(name: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    /** SQL fragment to pull the next value from a bit-reversed sequence. */
+    nextBitReversedSequenceValueSql(name: string): string;
+    nextBitReversedSequenceValue(name: string): Promise<number>;
+    /**
+     * 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.
+     */
+    startTransaction(options?: TransactionOptions): Promise<Transaction>;
+    commitTransaction(transaction: Transaction): Promise<void>;
+    rollbackTransaction(transaction: Transaction): Promise<void>;
+    /**
+     * 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()`.
+     */
+    runReadOnlyTransaction<T>(fn: (run: (sql: string, params?: Record<string, unknown>) => Promise<any[]>) => Promise<T>, options?: {
+        strong?: boolean;
+        maxStaleness?: {
+            seconds: number;
+        };
+        exactStaleness?: {
+            seconds: number;
+        };
+        readTimestamp?: Date;
+    }): Promise<T>;
+    /** Resolve the project ID used to build Admin API resource paths. */
+    private getProjectId;
+    private 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`).
+     */
+    createBackup(backupId: string, expireTime: Date, databaseId?: string): Promise<any>;
+    /**
+     * 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.
+     */
+    listBackups(filter?: string): Promise<any[]>;
+    /** Fetch a single backup's metadata by ID. */
+    getBackup(backupId: string): Promise<any>;
+    /** Delete a backup by ID. */
+    deleteBackup(backupId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    restoreDatabase(backupId: string, newDatabaseId: string): Promise<any>;
+    getDataTypeSql(dataType: DataType): string;
+    buildWhereClause(where: WhereOptions, _options?: any): {
+        sql: string;
+        values: any[];
+    };
+    buildOrderClause(order: Order): string;
+    /**
+     * 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?: number | string, offset?: number | string): string;
+    /**
+     * Map a Spanner conflict action (or the legacy `upsert: true` boolean) onto
+     * the corresponding GoogleSQL insert verb. GoogleSQL's DML upsert extension
+     * offers three distinct conflict-action variants (verified against the
+     * GoogleSQL DML reference - Spanner has no `ON CONFLICT` clause):
+     *  - `UPDATE`  → `INSERT OR UPDATE INTO`  (insert, or overwrite the row's non-key columns on PK collision)
+     *  - `IGNORE`  → `INSERT OR IGNORE INTO`  (insert, or silently skip on PK collision)
+     *  - `REPLACE` → `INSERT OR REPLACE INTO` (insert, or delete-then-reinsert the whole row on PK collision)
+     */
+    private insertVerb;
+    /**
+     * Build an INSERT statement. Set `options.upsert` (legacy boolean, ⇒
+     * `INSERT OR UPDATE INTO`) or `options.conflictAction`
+     * (`'UPDATE' | 'IGNORE' | 'REPLACE'`) to emit one of GoogleSQL's three DML
+     * conflict-action upsert variants (Spanner has no `ON CONFLICT` clause). For
+     * bulk/blind writes prefer `mutationInsert()`/`mutationUpsert()` (the
+     * Mutation API) instead - see the file header.
+     */
+    buildInsertQuery(tableName: string, values: Record<string, any>, options?: SpannerInsertOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Build an upsert statement using one of GoogleSQL's `INSERT OR ...` DML
+     * variants. Defaults to `INSERT OR UPDATE INTO`; pass
+     * `options.conflictAction` (`'UPDATE' | 'IGNORE' | 'REPLACE'`) to select
+     * ignore/replace semantics instead. Note this is a *SQL DML* path 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: string, values: Record<string, any>, options?: SpannerUpsertQueryOptions): {
+        sql: string;
+        values: any[];
+    };
+    buildIncrementQuery(tableName: string, fields: string | string[] | Record<string, number>, where: WhereOptions, options?: {
+        by?: number;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    buildUpdateQuery(tableName: string, values: Record<string, any>, where: WhereOptions, options?: DUpdateOptions): {
+        sql: string;
+        values: any[];
+    };
+    buildDeleteQuery(tableName: string, where: WhereOptions, options?: DeleteOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * 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: SelectOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Build a (optionally recursive) CTE-prefixed query -
+     * `WITH [RECURSIVE] name AS (...), ... <mainQuery>` - which GoogleSQL
+     * supports natively, including recursive CTEs (`WITH RECURSIVE`).
+     */
+    buildRecursiveCteQuery(ctes: {
+        name: string;
+        query: string;
+        recursive?: boolean;
+    }[], mainQuery: string): string;
+    /**
+     * 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: string, options?: {
+        partitionBy?: string[];
+        orderBy?: [string, string?][];
+        frame?: string;
+    }): string;
+}