PlanetScale

PlanetScale is a serverless database platform that supports both MySQL and PostgreSQL, providing horizontal scaling, branching workflows, and zero-downtime schema changes. Alchemy provides resources to manage PlanetScale databases, branches, and access controls programmatically.

Official PlanetScale Documentation | PlanetScale API Reference

Resources

• Database - Create and manage PlanetScale MySQL and PostgreSQL databases with configuration options
• Branch - Create and manage database branches for development workflows
• Password - Create and manage database passwords with specific roles and permissions (MySQL only)
• Role - Create and manage database roles with inherited permissions (PostgreSQL only)

Authentication

PlanetScale authentication is handled via environment variables.

Setting the Token ID and Secret

The token ID and secret can be set by setting the PLANETSCALE_SERVICE_TOKEN_ID and PLANETSCALE_SERVICE_TOKEN environment variables. Alchemy will use those to generate the correct header for the planetscale API.

Directly Setting the API Token

The API token can be set directly by setting the PLANETSCALE_API_TOKEN environment variable. This must follow the format outlined by planetscale here: Authentication.

Overriding per Resource

To support multiple accouns, alchemy allows you to override the authentication token for a resource by setting the serviceTokenId and serviceToken properties on planetscale resources.

MySQL Example

import { Database, Branch, Password } from "alchemy/planetscale";

// Create a MySQL database
const database = await Database("my-app-db", {
  name: "my-app-db",
  organization: "my-org",
  clusterSize: "PS_10",
  allowDataBranching: true,
  automaticMigrations: true,
});

// Create a development branch
const devBranch = await Branch("feature-123", {
  name: "feature-123",
  organization: "my-org",
  database: database,
  parentBranch: "main",
  isProduction: false,
});

// Create passwords for database access (MySQL only)
const readerPassword = await Password("app-reader", {
  name: "app-reader",
  organization: "my-org",
  database: database,
  branchName: "main",
  role: "reader"
});

const writerPassword = await Password("app-writer", {
  name: "app-writer",
  organization: "my-org",
  database: database,
  branchName: devBranch,
  role: "writer",
  ttl: 86400 // 24 hours
});

PostgreSQL Example

import { Database, Branch, Role } from "alchemy/planetscale";

// Create a PostgreSQL database
const pgDatabase = await Database("my-pg-db", {
  name: "my-pg-db",
  organization: "my-org",
  clusterSize: "PS_10",
  kind: "postgresql",
  allowDataBranching: true,
  automaticMigrations: true,
});

// Create a development branch
const devBranch = await Branch("dev-branch", {
  name: "development",
  organization: "my-org",
  database: pgDatabase,
  parentBranch: "main",
  isProduction: false,
});

// Create roles for database access (PostgreSQL only)
const readerRole = await Role("app-reader", {
  database: pgDatabase,
  branch: pgDatabase.defaultBranch,
  inheritedRoles: ["pg_read_all_data", "pg_read_all_settings"],
});

const adminRole = await Role("app-admin", {
  database: pgDatabase,
  branch: devBranch,
  inheritedRoles: ["postgres"],
  ttl: 3600, // 1 hour
});