GCP.Spanner reference

Database

Source: src/GCP/Spanner/Database.ts

A Cloud Spanner database inside an instance.

Spanner databases have no labels field. list enumerates databases on alchemy-labeled instances so pnpm nuke:gcp can find leaked rows. Changing instance, databaseId, dialect, CMEK, or extra DDL replaces the database. Drop protection updates in place.

Database: Creating a Database

Generated name on a Spanner instance

const instance = yield* GCP.Spanner.Instance("App", {});
const database = yield* GCP.Spanner.Database("AppDb", {
  instance: instance.instanceId,
});

Explicit id, dialect, and extra DDL

const database = yield* GCP.Spanner.Database("AppDb", {
  instance: instance.instanceId,
  databaseId: "appdb",
  extraStatements: [
    "CREATE TABLE Users (UserId INT64 NOT NULL) PRIMARY KEY (UserId)",
  ],
});

Database: Querying

const executeSql = yield* GCP.Spanner.ExecuteSql(database);
const result = yield* executeSql({ sql: "SELECT 1 AS n" });

Database: Reading Schema

const getDdl = yield* GCP.Spanner.GetDdl(database);
const { statements } = yield* getDdl();

ExecuteSql

Source: src/GCP/Spanner/ExecuteSql.ts

Runtime binding for Spanner sessions.executeSql.

Bind this operation to a Database in a Function/Action init phase. Provide ExecuteSqlHttp. Statements run on one multiplexed session per database, created on first use and reused for the life of the runtime instance.

ExecuteSql: Executing SQL

const executeSql = yield* GCP.Spanner.ExecuteSql(database);
const result = yield* executeSql({ sql: "SELECT 1 AS n" });

ExecuteSqlHttp

Source: src/GCP/Spanner/ExecuteSqlHttp.ts Kind: Layer · Provides: GCP.Spanner.ExecuteSql

HTTP implementation of ExecuteSql.

Reuses one multiplexed session per database for the life of the runtime instance (multiplexed sessions serve concurrent requests and are never deleted by the client). A session the server has dropped (SessionNotFound) is replaced once and the statement retried.

GetDdl

Source: src/GCP/Spanner/GetDdl.ts

Runtime binding for Spanner databases.getDdl.

Bind this operation to a Database in a Function/Action init phase. Provide GetDdlHttp.

GetDdl: Reading Schema

const getDdl = yield* GCP.Spanner.GetDdl(database);
const { statements } = yield* getDdl();

GetDdlHttp

Source: src/GCP/Spanner/GetDdlHttp.ts Kind: Layer · Provides: GCP.Spanner.GetDdl

HTTP implementation of GetDdl.

GetInstance

Source: src/GCP/Spanner/GetInstance.ts

Runtime binding for Cloud Spanner instances.get.

Bind this operation to an Instance in a Function/Action init phase. Provide GetInstanceHttp.

GetInstance: Observing Instances

const getInstance = yield* GCP.Spanner.GetInstance(instance);
const live = yield* getInstance();

GetInstanceHttp

Source: src/GCP/Spanner/GetInstanceHttp.ts Kind: Layer · Provides: GCP.Spanner.GetInstance

HTTP implementation of GetInstance.

Instance

Source: src/GCP/Spanner/Instance.ts

A Cloud Spanner instance.

Changing instanceId, config, or instanceType replaces the instance. Display name, labels, compute capacity, edition, backup schedule, and autoscaling update in place. Create, update, and delete are long-running operations — a 100 processing-unit regional instance typically takes one to two minutes.

Instance: Creating an Instance

Generated name, 100 processing units

const instance = yield* GCP.Spanner.Instance("App", {});

Explicit id, config, and labels

const instance = yield* GCP.Spanner.Instance("App", {
  instanceId: "app-spanner",
  config: "regional-us-central1",
  displayName: "app-spanner",
  processingUnits: 100,
  labels: { env: "prod" },
});

Instance: Observing Instances

const getInstance = yield* GCP.Spanner.GetInstance(instance);
const live = yield* getInstance();

InstanceConfig

Source: src/GCP/Spanner/InstanceConfig.ts

A user-managed Cloud Spanner instance configuration.

User-managed configs clone a Google-managed baseConfig and add at least one optional read-only replica. Only displayName and labels update in place; changing instanceConfigId, baseConfig, or replicas replaces the config. Create, update, and delete are long-running. Google-managed configs cannot be created or deleted.

InstanceConfig: Creating an Instance Config

Clone regional-us-central1 with an optional replica

const config = yield* GCP.Spanner.InstanceConfig("Custom", {
  baseConfig: "regional-us-central1",
  displayName: "custom-us-central1",
  labels: { env: "test" },
});

Explicit id and replica list

const config = yield* GCP.Spanner.InstanceConfig("Custom", {
  instanceConfigId: "custom-us-central1-ro",
  baseConfig: "regional-us-central1",
  replicas: [
    { location: "us-central1", type: "READ_WRITE" },
    { location: "us-central1", type: "READ_WRITE" },
    { location: "us-central1", type: "READ_WRITE" },
    { location: "us-east1", type: "READ_ONLY" },
  ],
});

InstancesBackup

Source: src/GCP/Spanner/InstancesBackup.ts

A Cloud Spanner backup of a database, stored on the parent instance.

Backups have no labels field. Alchemy treats a backup as owned when its parent instance carries Alchemy labels, so list / pnpm nuke:gcp can find it. Changing backupId, instance, database, versionTime, or encryption replaces the backup. expireTime updates in place.

InstancesBackup: Creating a Backup

7-day backup of an existing database

const backup = yield* GCP.Spanner.InstancesBackup("Nightly", {
  instance: instance.instanceId,
  database: database.databaseId,
});

Explicit id and expiration

const backup = yield* GCP.Spanner.InstancesBackup("Nightly", {
  instance: instance.name,
  database: database.name,
  backupId: "nightly",
  expireTime: "2026-12-31T00:00:00Z",
});

InstancesDatabasesBackupSchedule

Source: src/GCP/Spanner/InstancesDatabasesBackupSchedule.ts

An automated backup schedule on a Cloud Spanner database.

Schedules have no labels field. Alchemy treats a schedule as owned when its parent instance carries Alchemy labels, so list / pnpm nuke:gcp can find it. Changing backupScheduleId, instance, database, or incremental replaces the schedule. Cron, retention, and encryption update in place.

InstancesDatabasesBackupSchedule: Creating a Backup Schedule

Daily full backup retained for 7 days

const schedule = yield* GCP.Spanner.InstancesDatabasesBackupSchedule(
  "Nightly",
  {
    instance: instance.instanceId,
    database: database.databaseId,
    spec: { cron: "0 2 * * *" },
    retentionDuration: "604800s",
  },
);

Explicit id

const schedule = yield* GCP.Spanner.InstancesDatabasesBackupSchedule(
  "Nightly",
  {
    instance: instance.name,
    database: database.name,
    backupScheduleId: "nightly",
    spec: { cron: "0 2 * * 0" },
    retentionDuration: "1209600s",
  },
);

InstancesInstancePartition

Source: src/GCP/Spanner/InstancesInstancePartition.ts

A Cloud Spanner instance partition for geo-partitioned data placement.

Instance partitions have no labels field. Alchemy treats a partition as owned when its parent instance carries Alchemy labels, so list / pnpm nuke:gcp can find it. Geo-partitioning requires Enterprise Plus and typically a dual-region or multi-region parent instance. Changing instancePartitionId, instance, or config replaces the partition. Display name, compute capacity, and autoscaling update in place.

InstancesInstancePartition: Creating an Instance Partition

1000 processing units in a second region

const partition = yield* GCP.Spanner.InstancesInstancePartition(
  "West",
  {
    instance: instance.instanceId,
    config: "regional-us-west1",
    processingUnits: 1000,
  },
);

Explicit id and node count

const partition = yield* GCP.Spanner.InstancesInstancePartition(
  "West",
  {
    instance: instance.name,
    instancePartitionId: "west",
    config: "regional-us-west1",
    displayName: "west-partition",
    nodeCount: 1,
  },
);