sqlalchemy-spanner

What it is and what it does

sqlalchemy-spanner is a SQLAlchemy dialect that bridges the gap between SQLAlchemy's ORM and query abstractions and Google Cloud Spanner's database engine. It wraps the Spanner DB API (which implements PEP-249) to allow developers to use familiar SQLAlchemy patterns—table definitions, insert/update/delete operations, and select queries—against a Spanner instance without writing raw SQL or using the lower-level Spanner client directly.

The dialect supports Spanner-specific features like interleaved tables, commit timestamps, and unique constraints, and integrates with Alembic for schema migrations. It requires active Google Cloud credentials and a configured Spanner project, instance, and database. The package depends on sqlalchemy, google-cloud-spanner, and alembic, and supports Python 3.10 through 3.14. However, the repository is archived and abandoned, with no commits since March 2026, which may pose risks for long-term maintenance and compatibility.

Use it for:

• Build a web application using SQLAlchemy ORM that persists data to Cloud Spanner without rewriting queries for a different database dialect.
• Migrate an existing SQLAlchemy application from a traditional SQL database to Cloud Spanner by swapping the connection URL.
• Define and manage Spanner schema using SQLAlchemy's declarative table API and Alembic migrations instead of raw DDL.
• Leverage Spanner's interleaved tables and commit-timestamp features through SQLAlchemy's table constructor options.
• Use SQLAlchemy's query builder and ORM relationships to work with Spanner data in a Python application.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides a SQLAlchemy dialect that enables applications to use SQLAlchemy's ORM and query API against Google Cloud Spanner databases.

Yes, but with caution. The package is functional and has low install friction, but its abandoned status (no commits since March 2026) means no active maintenance or support for future SQLAlchemy or Spanner API changes. Install it only if you are committed to maintaining a fork or if your application's SQLAlchemy and Spanner dependencies are locked to versions known to work with this dialect. For new projects, verify whether a maintained alternative exists or whether direct use of the Spanner client is more appropriate.

Install

sqlalchemy-spanner on PyPI

pip install sqlalchemy-spanner

uv add sqlalchemy-spanner

poetry add sqlalchemy-spanner

Installing sqlalchemy-spanner

Before you install

Low install friction with a pure-Python wheel. However, the package is marked as abandoned with no commits since 2026-03-13, raising concerns about future maintenance and compatibility with newer SQLAlchemy or Spanner API versions.

License in practice

Licensed under Apache 2.0 (permissive), allowing use in most commercial and open-source projects without significant restrictions.

Quickstart

pip install sqlalchemy-spanner

from sqlalchemy import create_engine, MetaData, Table

engine = create_engine(
    "spanner+spanner:///projects/project-id/instances/instance-id/databases/database-id"
)
metadata = MetaData(bind=engine)
table = Table("users", metadata, autoload=True)

with engine.begin() as connection:
    result = connection.execute(table.select())

Requires Google Cloud Spanner credentials configured via Application Default Credentials or passed explicitly; requires Python 3.10 or later.

Verify before relying

• Whether the abandoned status affects compatibility with current SQLAlchemy 2.x releases and recent Spanner API changes.
• Whether community forks or alternative maintained dialects exist for Spanner.
• Performance characteristics and known limitations beyond those listed in the documentation excerpt.

Package facts

Evidence: sqlalchemy_spanner-1.19.0-py3-none-any.whl

Tags

More Front-Ends packages