Weave Code
Laravel Spanner Laravel Package
colopl/laravel-spanner
Laravel database driver for Google Cloud Spanner. Adds Eloquent and query builder support so applications can use Spanner as a familiar backend with models, migrations, transactions, and session handling, simplifying integration with Google's globally distributed database.
colopl/laravel-spanner adds a native Google Cloud Spanner driver to Laravel, letting you use Eloquent models, the query builder, and migrations against a globally distributed, horizontally scalable database without leaving Laravel's familiar database layer.
- Eloquent and Query Builder support via a custom connection driver
- Schema builder and migration support for Spanner DDL
- Session pooling and connection management for high concurrency
- Transaction handling, including read-write and stale reads
- Support for interleaved tables and composite primary keys
Frequently asked questions about Laravel Spanner
- What is colopl/laravel-spanner and what does it do?
- It is a Laravel database driver that connects Laravel applications to Google Cloud Spanner, exposing Spanner through Laravel's database layer. It brings Eloquent models, query builder support, schema migrations, transactions, and Spanner-specific features to services that need globally distributed, horizontally scalable SQL storage.
- Which Laravel and PHP versions does colopl/laravel-spanner v12 support?
- The v12 line is currently a beta, with v12.0.0-beta2 as the noted release, so confirm the exact Laravel and PHP constraints in the package's composer.json and README before upgrading. The technical assessment explicitly lists Laravel and PHP version constraints as an open question rather than a settled fact. Pin the version you validate and re-check constraints on every Laravel major upgrade.
- How do I install colopl/laravel-spanner in a Laravel application?
- Install it with Composer using composer require colopl/laravel-spanner, then add a Spanner connection in config/database.php with your GCP project, instance, and database details. Authenticate through Google Cloud Application Default Credentials or an equivalent service account setup, and confirm the required PHP extensions and Cloud SDK are available. Isolate the Spanner connection so other parts of the app can keep using conventional databases during a pilot.
- Does colopl/laravel-spanner support Eloquent, the query builder, and transactions?
- Yes. The driver supports Eloquent models, the query builder, transactions, and schema migrations, which is the main reason to use it over hand-rolled Spanner clients. Keep in mind that Spanner SQL, indexes, and transaction retry semantics differ from MySQL and PostgreSQL, so raw SQL and database-specific functions should be reviewed carefully.
- How do schema migrations and DDL work with the Spanner driver?
- Schema migrations are supported through the driver, but Spanner DDL has different rules and latency characteristics than MySQL or PostgreSQL DDL. Plan DDL changes in explicit migration windows with rollback paths, and test them against both the emulator and staging. Treat schema and primary-key design as a first-class Spanner exercise rather than a direct port from an existing database.
- Is colopl/laravel-spanner v12.0.0-beta2 safe for production?
- Treat v12.0.0-beta2 as a beta: the only noted change is session cleanup when dropping a database, and beta status itself is the primary technical risk. It can be acceptable for a pilot or non-critical service if you pin the version, run integration and load tests, and explicitly accept the risk. Gate broader production promotion on the beta exiting or on a documented risk acceptance with an operational runbook.
- Can I test colopl/laravel-spanner with the Google Cloud Spanner emulator?
- You can use the Spanner emulator for local and CI testing, but the assessment warns that emulator and production parity must be proven for your test matrix. Keep conventional databases for local development unless the emulator covers your team's needs, and validate transaction retries, session lifecycle, and DDL behaviour in staging before production. Parallel tests and database-drop teardown are worth exercising given the beta2 session-clearing change.
- What should I audit before moving an existing MySQL or PostgreSQL app to Spanner?
- Inventory raw SQL, database-specific functions, transactions, locks, indexes, foreign-key assumptions, and migration patterns before committing. Audit packages that assume MySQL or PostgreSQL behaviour, including queue, session, cache, migration, and testing packages, and check Octane and long-running worker compatibility. Spanner performance depends heavily on schema design, primary-key choices, interleaving, and hotspot avoidance, so load-test with realistic worker counts and processing-unit sizing.
- What does the v12.0.0-beta2 session cleanup change affect?
- The beta2 change clears sessions when a database is dropped, which mainly improves test and tenant teardown workflows. Because it touches connection and session lifecycle, validate it in test database-drop flows, parallel test runs, and long-running workers, and confirm it cannot invalidate active sessions you still need. Watch for session leaks or pool exhaustion in production-like load tests.
- When should I avoid colopl/laravel-spanner, and what are the alternatives?
- Avoid it for small workloads where Spanner cost, schema discipline, and operational overhead outweigh the benefits, and where a conventional database already fits. Alternatives include staying on MySQL or PostgreSQL for ordinary Laravel apps, or using the official Google Cloud Spanner client directly for non-Laravel services. If you adopt it, assign an internal owner for driver upgrades, schema governance, cost modelling, and incident response, because support for the Laravel integration layer is community-based.
Weaver
How can I help you explore Laravel packages today?