GCP.SQL reference

Backup

Source: packages/gcp/src/SQL/Backup.ts

An on-demand Cloud SQL backup (projects/{project}/backups/{backup}).

The create API assigns the backup id. Alchemy stamps ownership into description so list / pnpm nuke:gcp can find leaked rows. Changing instance or location replaces the backup. Description, ttlDays, and expiryTime are create-time for on-demand backups; FINAL backups can update description and expiration in place.

Backup: Creating a Backup

On-demand backup of a Cloud SQL instance

const instance = yield* GCP.SQL.Instance("AppDb", {
  tier: "db-f1-micro",
  backup: { enabled: true },
});
const backup = yield* GCP.SQL.Backup("Nightly", {
  instance: instance.instanceName,
});

Description, location, and TTL

const backup = yield* GCP.SQL.Backup("Nightly", {
  instance: instance.instanceName,
  location: "us",
  description: "pre-release",
  ttlDays: 7,
});

BackupRun

Source: packages/gcp/src/SQL/BackupRun.ts

An on-demand Cloud SQL backup run (projects/{project}/instances/{instance}/backupRuns/{id}).

Insert assigns the run id. Alchemy stamps ownership into description so list / pnpm nuke:gcp can find leaked rows. Changing instance or location replaces the run. Description is create-only — backup runs have no update API.

BackupRun: Creating a Backup Run

On-demand backup of a Cloud SQL instance

const instance = yield* GCP.SQL.Instance("AppDb", {
  tier: "db-f1-micro",
  backup: { enabled: true },
});
const backup = yield* GCP.SQL.BackupRun("Nightly", {
  instance: instance.instanceName,
});

Description and location

const backup = yield* GCP.SQL.BackupRun("Nightly", {
  instance: instance.instanceName,
  location: "us",
  description: "pre-release",
});

Connect

Source: packages/gcp/src/SQL/Connect.ts

Runtime binding that connects a Cloud Run service to a Cloud SQL instance over the Cloud SQL Unix socket — no public IP allow-list, no VPC.

Binding it at init grants roles/cloudsql.client on the project under an IAM Condition naming only this instance, mounts the instance as the service’s cloudsql volume (the socket appears at /cloudsql/{connectionName}), and grants roles/secretmanager.secretAccessor on the password secret. The returned Effect reads the password and resolves a ConnectionInfo on each execution; no socket is opened. Provide ConnectHttp. Cloud Run services only.

Connect: Connecting with Drizzle

const connect = yield* GCP.SQL.Connect(instance, {
  database,
  user,
  passwordSecret,
});
const db = yield* Drizzle.Postgres(
  connect.pipe(Effect.map((info) => info.url)),
);
// …provided with Effect.provide(GCP.SQL.ConnectHttp)

ConnectHttp

Source: packages/gcp/src/SQL/ConnectHttp.ts Kind: Layer · Provides: GCP.SQL.Connect

HTTP implementation of Connect: reads the password through GCP.SecretManager.ReadSecret and connects over the Cloud Run cloudsql socket volume.

Database

Source: packages/gcp/src/SQL/Database.ts

A logical database inside a Cloud SQL instance.

Cloud SQL databases have no labels field. list enumerates non-system databases on alchemy-labeled instances so pnpm nuke:gcp can find leaked rows without dropping mysql / postgres / template1.

Changing instance or databaseName replaces the database. charset and collation update in place where the engine allows.

Database: Creating a Database

Generated name on a Cloud SQL instance

const instance = yield* GCP.SQL.Instance("AppDb", {
  tier: "db-f1-micro",
  backup: { enabled: false },
});
const database = yield* GCP.SQL.Database("App", {
  instance: instance.instanceName,
});

Explicit name, charset, and collation

const database = yield* GCP.SQL.Database("App", {
  instance: instance.instanceName,
  databaseName: "app_production",
  charset: "utf8mb4",
  collation: "utf8mb4_unicode_ci",
});

Database: Migrations

Apply migrations over the Data API

const instance = yield* GCP.SQL.Instance("AppDb", {
  databaseVersion: "POSTGRES_17",
  dataApiAccess: true,
});
const password = yield* Alchemy.Random("AppPassword");
const user = yield* GCP.SQL.User("App", {
  instance: instance.instanceName,
  password: password.text,
});
const database = yield* GCP.SQL.Database("App", {
  instance: instance.instanceName,
  migrations: "./migrations",
  migrationsUser: user.userName,
  migrationsPassword: password.text,
});

Migrations run as migrationsUser through instances.executeSql, so the deploying machine needs no route to the database. The deploying identity needs cloudsql.instances.executeSql and Secret Manager access: the password is staged in a regional secret while migrations run.

Apply migrations through the Cloud SQL connector

const database = yield* GCP.SQL.Database("App", {
  instance: instance.instanceName,
  migrations: "./migrations",
  migrationsTransport: "connector",
  migrationsUser: user.userName,
  migrationsPassword: password.text,
});

The connector logs in with an ephemeral client certificate from the SQL Admin API, so the instance needs no authorized networks. The deploying machine needs a route to its IP: the public IP (the default), or the private IP from inside its network. Install pg (PostgreSQL) or mysql2 (MySQL).

Migrations generated by Drizzle

const schema = yield* Drizzle.Schema("Schema", {
  schema: "./src/schema.ts",
  out: "./migrations",
});
const database = yield* GCP.SQL.Database("App", {
  instance: instance.instanceName,
  migrations: schema,
  migrationsUser: user.userName,
  migrationsPassword: password.text,
});

ExecuteSql

Source: packages/gcp/src/SQL/ExecuteSql.ts

Runtime binding for Cloud SQL instances.executeSql.

Bind this operation to an Instance in a Function/Action init phase. Provide ExecuteSqlHttp. The instance must allow the Execute SQL API (dataApiAccess: true).

Grants roles/cloudsql.instanceUser (cloudsql.instances.executeSql, get, login) on the project under an IAM Condition naming only this instance.

ExecuteSql: Executing SQL

const executeSql = yield* GCP.SQL.ExecuteSql(db);
const result = yield* executeSql({
  body: {
    sqlStatement: "SELECT 1",
    database: "mysql",
    user: "root",
  },
});

ExecuteSqlHttp

Source: packages/gcp/src/SQL/ExecuteSqlHttp.ts Kind: Layer · Provides: GCP.SQL.ExecuteSql

HTTP implementation of ExecuteSql.

GetInstance

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

Runtime binding for Cloud SQL instances.get.

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

Grants roles/cloudsql.viewer on the project under an IAM Condition naming only this instance (Cloud SQL has no instance-level IAM policy).

GetInstance: Observing Instances

const getInstance = yield* GCP.SQL.GetInstance(db);
const live = yield* getInstance();

GetInstanceHttp

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

HTTP implementation of GetInstance.

GetUser

Source: packages/gcp/src/SQL/GetUser.ts

Runtime binding for Cloud SQL users.get.

Bind this operation to a User in a Function/Action init phase. Provide GetUserHttp.

Grants roles/cloudsql.viewer on the project, unconditioned: Cloud SQL has no instance-level IAM policy, cloudsql.users.get is not matched by an IAM Condition on the instance name, and no narrower predefined role carries it.

GetUser: Observing Users

const getUser = yield* GCP.SQL.GetUser(appUser);
const live = yield* getUser();

GetUserHttp

Source: packages/gcp/src/SQL/GetUserHttp.ts Kind: Layer · Provides: GCP.SQL.GetUser

HTTP implementation of GetUser.

Instance

Source: packages/gcp/src/SQL/Instance.ts

A Cloud SQL database instance.

Changing instanceName, region, or the databaseVersion engine replaces the instance; a major version upgrade within the same engine runs in place. Provisioning typically takes several minutes (often 5–15).

Instance: Creating an Instance

Generated name, MySQL 8.0 shared-core

const db = yield* GCP.SQL.Instance("AppDb", {});

Explicit name, labels, and backups off

const db = yield* GCP.SQL.Instance("AppDb", {
  instanceName: "app-db",
  region: "us-central1",
  databaseVersion: "MYSQL_8_0",
  tier: "db-f1-micro",
  labels: { env: "prod" },
  backup: { enabled: false },
  deletionProtectionEnabled: false,
});

Instance: PostgreSQL

const db = yield* GCP.SQL.Instance("AppDb", {
  databaseVersion: "POSTGRES_15",
  rootPassword: "change-me",
  tier: "db-f1-micro",
});

Instance: Private IP and SSL

const network = yield* GCP.Compute.Network("Vpc", {
  autoCreateSubnetworks: false,
});
const range = yield* GCP.Compute.GlobalAddress("PsaRange", {
  addressType: "INTERNAL",
  purpose: "VPC_PEERING",
  network: network.selfLink,
  prefixLength: 20,
});
const psa = yield* GCP.ServiceNetworking.Connection("Psa", {
  network: network.networkName,
  reservedPeeringRanges: [range.addressName],
});
const db = yield* GCP.SQL.Instance("Control", {
  databaseVersion: "POSTGRES_17",
  tier: "db-custom-2-8192",
  ipConfiguration: {
    ipv4Enabled: false,
    privateNetwork: psa.network,
    sslMode: "ENCRYPTED_ONLY",
  },
});
// db.privateIpAddress is reachable from inside the VPC

Instance: Backups and Storage

const db = yield* GCP.SQL.Instance("AppDb", {
  databaseVersion: "POSTGRES_17",
  backup: {
    enabled: true,
    retainedBackups: 14,
    transactionLogRetentionDays: 7,
    startTime: "03:00",
  },
  storageAutoResize: true,
});

SslCert

Source: packages/gcp/src/SQL/SslCert.ts

A Cloud SQL client SSL certificate.

Insert returns the private key once; it is stored on the resource and cannot be recovered from the API later. Certificates have no labels field. list enumerates certs on alchemy-labeled instances so pnpm nuke:gcp can find leaked rows. Changing instance or commonName replaces the certificate. The new certificate is not usable until the instance is restarted.

SslCert: Creating a Certificate

Generated common name on a Cloud SQL instance

const instance = yield* GCP.SQL.Instance("AppDb", {
  tier: "db-f1-micro",
  backup: { enabled: false },
});
const cert = yield* GCP.SQL.SslCert("Client", {
  instance: instance.instanceName,
});

Explicit common name

const cert = yield* GCP.SQL.SslCert("Client", {
  instance: instance.instanceName,
  commonName: "app-client",
});

User

Source: packages/gcp/src/SQL/User.ts

A database user on a Cloud SQL instance.

Cloud SQL users have no labels field. list enumerates non-system users on alchemy-labeled instances so pnpm nuke:gcp can find leaked rows without dropping root / postgres / cloudsqladmin.

Changing instance, userName, host, or type replaces the user. password, databaseRoles, and passwordPolicy update in place.

User: Creating a User

Generated name on a Cloud SQL instance

const instance = yield* GCP.SQL.Instance("AppDb", {
  tier: "db-f1-micro",
  backup: { enabled: false },
});
const appUser = yield* GCP.SQL.User("AppUser", {
  instance: instance.instanceName,
  password: "change-me",
});

Explicit MySQL user and host

const appUser = yield* GCP.SQL.User("AppUser", {
  instance: instance.instanceName,
  userName: "app",
  host: "%",
  password: "change-me",
  type: "BUILT_IN",
});

User: IAM Users

const iamUser = yield* GCP.SQL.User("IamUser", {
  instance: instance.instanceName,
  userName: "alice@example.com",
  type: "CLOUD_IAM_USER",
});