Integrate Spanner with SQLAlchemy ORM (GoogleSQL dialect)
Stay organized with collections
Save and categorize content based on your preferences.
SQLAlchemy is a Python SQL toolkit and Object
Relational Mapper.
The Spanner dialect for SQLAlchemy lets
SQLAlchemy users to use Spanner databases. The dialect is built on top
of the Spanner API, which is designed in
accordance with PEP-249, and is compatible with
SQLAlchemy versions between 1.1.13 and
1.3.23, and 2.0.
Set up the Spanner dialect for SQLAlchemy
To set up the Spanner dialect for SQLAlchemy in your application, install the
sqlalchemy-spanner package.
As authentication for the Spanner dialect for SQLAlchemy, provide the service account
JSON credentials file location in the
GOOGLE_APPLICATION_CREDENTIALS environment variable. Otherwise, the dialect
can also use the default credentials set in the gcloud CLI
application.
Use the Spanner dialect for SQLAlchemy
For more information about the available features, limitations of the dialect,
recommendations on how to use the dialect, and for code samples, please consult
the reference documentation on
GitHub.
What's next
Check out the code examples on how to use the
Spanner dialect for SQLAlchemy.
View the repository for the Spanner dialect for SQLAlchemy on
GitHub.
File a GitHub issue to report a bug or ask a
question about the Spanner dialect for SQLAlchemy.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[],[],null,["# Integrate Spanner with SQLAlchemy ORM (GoogleSQL dialect)\n\n[SQLAlchemy](https://www.sqlalchemy.org/) is a Python SQL toolkit and Object\nRelational Mapper.\n\nThe [Spanner dialect for SQLAlchemy](https://github.com/googleapis/python-spanner-sqlalchemy) lets\nSQLAlchemy users to use Spanner databases. The dialect is built on top\nof the [Spanner API](https://github.com/googleapis/python-spanner/tree/main/google/cloud/spanner_dbapi), which is designed in\naccordance with [PEP-249](https://www.python.org/dev/peps/pep-0249/), and is compatible with\nSQLAlchemy versions between [1.1.13](https://pypi.org/project/SQLAlchemy/1.1.13/) and\n[1.3.23](https://pypi.org/project/SQLAlchemy/1.3.23/), and [2.0](https://pypi.org/project/SQLAlchemy/2.0.0/).\n\n\n| **PostgreSQL interface note:** To use [PostgreSQL interface for Spanner](/spanner/docs/postgresql-interface) with SQLAlchemy, see [Integrate Spanner with SQLAlchemy 2 ORM (PostgreSQL-dialect)](/spanner/docs/use-sqlalchemy-pg).\n\n\u003cbr /\u003e\n\nSet up the Spanner dialect for SQLAlchemy\n-----------------------------------------\n\nTo set up the Spanner dialect for SQLAlchemy in your application, install the\n[`sqlalchemy-spanner package`](https://pypi.org/project/sqlalchemy-spanner/). \n\n pip3 install sqlalchemy-spanner\n\nAlternatively, you can install from source. \n\n git clone https://github.com/googleapis/python-spanner-sqlalchemy.git\n cd python-spanner-sqlalchemy\n python setup.py install\n\nAs authentication for the Spanner dialect for SQLAlchemy, provide the [service account\nJSON credentials](/docs/authentication/getting-started) file location in the\n`GOOGLE_APPLICATION_CREDENTIALS` environment variable. Otherwise, the dialect\ncan also use the default credentials set in the gcloud CLI\napplication.\n\nUse the Spanner dialect for SQLAlchemy\n--------------------------------------\n\nFor more information about the available features, limitations of the dialect,\nrecommendations on how to use the dialect, and for code samples, please consult\nthe [reference documentation](https://github.com/googleapis/python-spanner-sqlalchemy#readme) on\nGitHub.\n\nWhat's next\n-----------\n\n- Check out the [code examples](https://github.com/googleapis/python-spanner-sqlalchemy/blob/main/samples/snippets.py) on how to use the Spanner dialect for SQLAlchemy.\n- View the repository for the Spanner dialect for SQLAlchemy on [GitHub](https://github.com/googleapis/python-spanner-sqlalchemy).\n- File a [GitHub issue](https://github.com/googleapis/python-spanner-sqlalchemy/issues) to report a bug or ask a question about the Spanner dialect for SQLAlchemy.\n- Learn more about [SQLAlchemy](https://www.sqlalchemy.org/).\n- Learn more about [PyPI](https://pypi.org/).\n- Learn about authorization and authentication credentials in [Getting started with authentication](/docs/authentication/getting-started)."]]
