@sebspark/spanner-migrate

spanner-migrate is a CLI tool for managing schema migrations for Google Cloud Spanner. It simplifies schema evolution by allowing you to create, apply, rollback, and track migrations.

---

Installation

Install @sebspark/spanner-migrate as a global package:

``zsh
yarn add -D @sebspark/spanner-migrate
`

---

CLI Commands

spanner-migrate provides several commands for managing database migrations in Google Spanner.

$3

`sh
spanner-migrate init
`

Initializes a .spanner-migrate.config.json file by prompting for:
- Spanner instance name
- One or more database configurations
- Optional Google Cloud project name

$3

`sh
spanner-migrate create [--database ]
spanner-migrate create add users table
spanner-migrate create --database=mydb add users table
`

Creates a new migration file with the specified description.

- If --database (-d) is provided, it uses the specified database.
- If multiple databases exist and none is specified, the user is prompted to select one.
- The filename is generated from the description (_add_users_table.sql).

$3

`sh
spanner-migrate up
spanner-migrate up --database
spanner-migrate up --database --max
`

Applies pending migrations.

- If no --database and --max are provided, applies all migrations to all databases.
- If --database (-d) is provided, applies migrations only to that database.
- If --max (-m) is provided, limits the number of migrations applied (requires --database).
- --max must be an integer greater than 0.

$3

`sh
spanner-migrate down
spanner-migrate down --database
`

Rolls back the last applied migration.

- If a single database exists, it is automatically selected.
- If multiple databases exist, --database is required.
- The specified --database must exist.

$3

`sh
spanner-migrate status
spanner-migrate status --database
`

Displays migration status.

- If --database is specified, shows status for that database.
- If no --database is provided, shows status for all configured databases.

$3

`sh
spanner-migrate --help
spanner-migrate --help
`

Displays help for the CLI or a specific command.

---

Programmatic Usage

In addition to the CLI, spanner-migrate can be used as a Node.js module to manage migrations programmatically.

$3

`typescript
import { init, create, up, down, status } from '@sebspark/spanner-migrate'
`

$3

`typescript
import { init, type Config } from '@sebspark/spanner-migrate'

const config: Config = {
instance: {
name: 'my-instance',
databases: [
{ name: 'mydb', migrationsPath: './migrations' },
],
},
projectId: 'my-gcp-project',
}

await init(config, '.spanner-migrate.config.json')
`

Writes the given configuration to a .spanner-migrate.config.json file.

$3

`typescript
import { create, type DatabaseConfig } from '@sebspark/spanner-migrate'

const databaseConfig: DatabaseConfig = {
name: 'mydb',
migrationsPath: './migrations',
}

await create(databaseConfig, 'add users table')
`

Creates a new migration file for the specified database.

$3

`typescript
import { up, type Config, type DatabaseConfig } from '@sebspark/spanner-migrate'

// Load configuration
const config: Config = / Load from file or define inline /

// Apply all migrations to all databases
await up(config)

// Apply all migrations to a specific database
const databaseConfig: DatabaseConfig = config.instance.databases[0]
await up(config, databaseConfig)

// Apply up to 5 migrations to a specific database
await up(config, databaseConfig, 5)
`

- Applies pending migrations.
- If a database is specified, only applies migrations to that database.
- If max is specified, applies at most max migrations.

$3

`typescript
import { up, type Config, type DatabaseConfig } from '@sebspark/spanner-migrate'

const config: Config = / Load from file /
const databaseConfig: DatabaseConfig = config.instance.databases[0]

// Roll back the last applied migration
await down(config, databaseConfig)
`

- Rolls back the last applied migration for the specified database.
- Requires a database to be specified.

$3

`typescript
import { up, type Config, type DatabaseConfig } from '@sebspark/spanner-migrate'

const config: Config = / Load from file /

// Check status for all databases
const migrationStatus = await status(config)
console.log(migrationStatus)

// Check status for a specific database
const databaseConfig = config.instance.databases[0]
const migrationStatusSingle = await status(config, [databaseConfig])
console.log(migrationStatusSingle)
`

- Displays applied and pending migrations for one or more databases.
- If a specific database is provided, only its status is shown.

Running on Spanner Emulator

If you want to test your migrations against a Spanner Emulator, you will need to set:

`typescript
process.env.SPANNER_EMULATOR_HOST = 'localhost:'
``

License

Apache-2.0