The `google-spanner-migrations-runner` package provides a robust engine for managing schema migrations in Google Cloud Spanner databases, supporting both Google-managed instances and the Spanner emulator. Currently at version 1.13.0, the library receives frequent updates, with minor versions and bug fixes typically released every few months. Unlike ORM-based migration tools, this runner operates directly with `.sql` files, emphasizing a 'migrations-as-code' approach where developers write and test their SQL scripts. It does not generate schema from application code. Key functionalities include applying migrations from a designated directory, validating SQL files, and maintaining a ledger of applied migrations to prevent re-execution. Migrations are applied transactionally and in a specific order, making file naming conventions crucial for successful database evolution. It also features optional annotations for environment-specific migration execution.
npm install google-spanner-migrations-runnerVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to programmatically initialize and execute Spanner database migrations using the `SpannerMigration` class, setting up the necessary configuration for connection and specifying the migrations directory.
Ensure all SQL statements in migration files are terminated with a semicolon, even if your SQL client typically infers them.
Split migrations that combine different statement types (like `CREATE TABLE` and `INSERT`) into separate `.sql` files, each dedicated to a single statement type.
Plan migration names carefully. If a change is absolutely necessary for an applied migration, create a new migration to reverse or correct the previous one, rather than altering an existing, applied file.
Be aware of Spanner emulator limitations. Test migrations involving advanced features against a real Spanner instance or acknowledge that certain operations might be skipped locally.
Always provide the correct `--env <env-name>` CLI flag or `config.env` programmatic option when running migrations, especially for environment-specific migrations, to avoid false 'failed' records.
Rename your migration `.sql` files to follow the pattern, for example: `00001_create_users_table.sql`.
Separate your migration logic into distinct `.sql` files, ensuring each file contains only one type of SQL operation. For instance, put all schema changes in one file and data inserts in another.
This usually indicates a successful prior run. If you intend to run new migrations, ensure new `.sql` files are added or that existing applied migrations were not altered.
This is often expected in emulator environments. Review Spanner emulator documentation for unsupported features or consider testing these migrations against a live Spanner instance. The migration will still apply on a real Spanner database.