Skip to content

GCP.Spanner reference

Source: packages/gcp/src/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.

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)",
],
});
const executeSql = yield* GCP.Spanner.ExecuteSql(database);
const result = yield* executeSql({ sql: "SELECT 1 AS n" });
const getDdl = yield* GCP.Spanner.GetDdl(database);
const { statements } = yield* getDdl();
const database = yield* GCP.Spanner.Database("AppDb", {
instance: instance.instanceId,
migrations: "./migrations",
});

Each file in ./migrations holds GoogleSQL (or PostgreSQL, with databaseDialect: "POSTGRESQL") statements separated by ;. Migrations run as the deploying identity, which needs spanner.databases.updateDdl and spanner.databases.write.

Database.lookup references a database Alchemy doesn’t manage (created in the console or by another stack). It is read during plan/deploy, never created, updated or deleted, and binds like a declared database.

const database = GCP.Spanner.Database.lookup({
databaseId: "my-database",
instance: "my-instance",
});

Source: packages/gcp/src/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.

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

Source: packages/gcp/src/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.

Source: packages/gcp/src/Spanner/GetDdl.ts

Runtime binding for Spanner databases.getDdl.

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

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

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

HTTP implementation of GetDdl.

Source: packages/gcp/src/Spanner/GetInstance.ts

Runtime binding for Cloud Spanner instances.get.

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

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

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

HTTP implementation of GetInstance.

Source: packages/gcp/src/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.

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" },
});
const getInstance = yield* GCP.Spanner.GetInstance(instance);
const live = yield* getInstance();

Instance.lookup references an instance Alchemy doesn’t manage (created in the console or by another stack). It is read during plan/deploy, never created, updated or deleted, and binds like a declared instance.

const instance = GCP.Spanner.Instance.lookup({ instanceId: "my-instance" });

Source: packages/gcp/src/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

Section titled “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" },
],
});

InstanceConfig: Looking up an existing instance config

Section titled “InstanceConfig: Looking up an existing instance config”

InstanceConfig.lookup references an instance config Alchemy doesn’t manage (created in the console or by another stack). It is read during plan/deploy, never created, updated or deleted, and binds like a declared instance config.

const instanceConfig = GCP.Spanner.InstanceConfig.lookup({
instanceConfigId: "my-instance-config",
});

Source: packages/gcp/src/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.

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",
});

InstancesBackup: Looking up an existing instances backup

Section titled “InstancesBackup: Looking up an existing instances backup”

InstancesBackup.lookup references an instances backup Alchemy doesn’t manage (created in the console or by another stack). It is read during plan/deploy, never created, updated or deleted, and binds like a declared instances backup.

const instancesBackup = GCP.Spanner.InstancesBackup.lookup({
backupId: "my-backup",
instance: "my-instance",
});

Source: packages/gcp/src/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

Section titled “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",
},
);

InstancesDatabasesBackupSchedule: Looking up an existing instances databases backup schedule

Section titled “InstancesDatabasesBackupSchedule: Looking up an existing instances databases backup schedule”

InstancesDatabasesBackupSchedule.lookup references an instances databases backup schedule Alchemy doesn’t manage (created in the console or by another stack). It is read during plan/deploy, never created, updated or deleted, and binds like a declared instances databases backup schedule.

const instancesDatabasesBackupSchedule = GCP.Spanner.InstancesDatabasesBackupSchedule.lookup({
backupScheduleId: "my-backup-schedule",
instance: "my-instance",
database: "my-database",
});

Source: packages/gcp/src/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

Section titled “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,
},
);

InstancesInstancePartition: Looking up an existing instances instance partition

Section titled “InstancesInstancePartition: Looking up an existing instances instance partition”

InstancesInstancePartition.lookup references an instances instance partition Alchemy doesn’t manage (created in the console or by another stack). It is read during plan/deploy, never created, updated or deleted, and binds like a declared instances instance partition.

const instancesInstancePartition = GCP.Spanner.InstancesInstancePartition.lookup({
instancePartitionId: "my-instance-partition",
instance: "my-instance",
});