Cloud Spanner support for Django
================================
|GA| |pypi| |versions|
`Cloud Spanner`_ is the world's first fully managed relational database service
to offer both strong consistency and horizontal scalability for
mission-critical online transaction processing (OLTP) applications. With Cloud
Spanner you enjoy all the traditional benefits of a relational database; but
unlike any other relational database service, Cloud Spanner scales horizontally
to hundreds or thousands of servers to handle the biggest transactional
workloads.
- `Client Library Documentation`_
- `Product Documentation`_
.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg
:target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability
.. |pypi| image:: https://img.shields.io/pypi/v/django-google-spanner.svg
:target: https://pypi.org/project/django-google-spanner/
.. |versions| image:: https://img.shields.io/pypi/pyversions/django-google-spanner.svg
:target: https://pypi.org/project/django-google-spanner/
.. _Cloud Spanner: https://cloud.google.com/spanner/
.. _Client Library Documentation: https://googleapis.dev/python/django-google-spanner/latest/index.html
.. _Product Documentation: https://cloud.google.com/spanner/docs
Quick Start
-----------
In order to use this library, you first need to go through the following steps:
1. `Select or create a Cloud Platform project.`_
2. `Enable billing for your project.`_
3. `Enable the Google Cloud Spanner API.`_
4. `Setup Authentication.`_
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
.. _Enable the Google Cloud Spanner API.: https://cloud.google.com/spanner
.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
This package provides a `3rd-party database backend
<https://docs.djangoproject.com/en/2.2/ref/databases/#using-a-3rd-party-database-backend>`__
for using `Cloud Spanner <https://cloud.google.com/spanner>`__ with the `Django
ORM <https://docs.djangoproject.com/en/2.2/topics/db/>`__. It uses the `Cloud
Spanner Python client library <https://github.com/googleapis/python-spanner>`__
under the hood.
Installation
------------
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
create isolated Python and Django environments. The basic problem it addresses is one of
dependencies and versions, and indirectly permissions.
With `virtualenv`_, it's possible to install this library without needing system
install permissions, and without clashing with the installed system
dependencies.
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
Supported versions
~~~~~~~~~~~~~~~~~~
The library supports `Django 2.2
<https://docs.djangoproject.com/en/2.2/>`_, and `Django 3.2
<https://docs.djangoproject.com/en/3.2/>`_.
Both versions are long-term support (LTS) releases for the
`Django project<https://www.djangoproject.com/download/#supported-versions>_`.
The minimum required Python version is 3.6.
.. code:: shell
pip3 install django==3.2
Installing the package
~~~~~~~~~~~~~~~~~~~~~~
To install from PyPI:
.. code:: shell
pip3 install django-google-spanner
To install from source:
.. code:: shell
git clone git@github.com:googleapis/python-spanner-django.git
cd python-spanner-django
pip3 install -e .
Creating a Cloud Spanner instance and database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you don't already have a Cloud Spanner database, or want to start from
scratch for a new Django application, you can `create a new instance
<https://cloud.google.com/spanner/docs/getting-started/python#create_an_instance>`__
and `database
<https://cloud.google.com/spanner/docs/getting-started/python#create_a_database>`__
using the Google Cloud SDK:
.. code:: shell
gcloud spanner instances create $INSTANCE --config=regional-us-central1 --description="New Django Instance" --nodes=1
gcloud spanner databases create $DB --instance $INSTANCE
Configuring ``settings.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This package provides a Django application named ``django_spanner``. To use the
Cloud Spanner database backend, the application needs to installed and
configured:
- Add ``django_spanner`` as the first entry in ``INSTALLED_APPS``:
.. code:: python
INSTALLED_APPS = [
'django_spanner',
...
]
- Edit the ``DATABASES`` setting to point to an existing Cloud Spanner database:
.. code:: python
DATABASES = {
'default': {
'ENGINE': 'django_spanner',
'PROJECT': '$PROJECT',
'INSTANCE': '$INSTANCE',
'NAME': '$DATABASE',
}
}
Transaction support in autocommit mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Django version 4.2 and higher by default supports transactions in autocommit mode.
A transaction is automatically started if you define an
[atomic block](https://docs.djangoproject.com/en/4.2/topics/db/transactions/#controlling-transactions-explicitly).
Django version 3.2 and earlier did not support transactions in autocommit mode with Spanner.
You can enable transactions in autocommit mode with Spanner with the
`ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` configuration option.
- To enable transactions in autocommit mode in V3.2, set the flag `ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` to True in your settings.py file.
- To disable transactions in autocommit mode in V4.2, set the flag `ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` to False in your settings.py file.
Set credentials and project environment variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You'll need to download a service account JSON key file and point to it using an environment variable:
.. code:: shell
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
export GOOGLE_CLOUD_PROJECT=gcloud_project
Apply the migrations
~~~~~~~~~~~~~~~~~~~~
Please run:
.. code:: shell
$ python3 manage.py migrate
That'll take a while to run. After this you should be able to see the tables and indexes created in your Cloud Spanner console.
Create a Django admin user
~~~~~~~~~~~~~~~~~~~~~~~~~~~
First you’ll need to create a user who can login to the admin site. Run the following command:
.. code:: shell
$ python3 manage.py createsuperuser
which will then produce a prompt which will allow you to create your super user
.. code:: shell
Username: admin
Email address: admin@example.com
Password: **********
Password (again): **********
Superuser created successfully.
Login as admin
~~~~~~~~~~~~~~
Now, run the server
.. code:: shell
python3 manage.py runserver
Then visit http://127.0.0.1:8000/admin/
Create and register your first model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Please follow the guides in https://docs.djangoproject.com/en/2.2/intro/tutorial02/#creating-models
to create and register the model to the Django’s automatically-generated admin site.
How it works
------------
Overall design
~~~~~~~~~~~~~~
.. figure:: https://raw.githubusercontent.com/googleapis/python-spanner-django/main/assets/overview.png
:alt: "Overall Design"
Internals
~~~~~~~~~
.. figure:: https://raw.githubusercontent.com/googleapis/python-spanner-django/main/assets/internals.png
:alt: "Internals"
Executing a query
~~~~~~~~~~~~~~~~~
Here is an example of how to add a row for Model Author, save it and later query it using Django
.. code:: shell
>>> author_kent = Author( first_name="Arthur", last_name="Kent", rating=Decimal("4.1"),)
>>> author_kent.save()
>>> qs1 = Author.objects.all().values("first_name", "last_name")
How to contribute
~~~~~~~~~~~~~~~~~
Contributions to this library are always welcome and highly encouraged.
See `CONTRIBUTING <https://github.com/googleapis/python-spanner-django/blob/main/CONTRIBUTING.md>`_ for more information on how to get started.
Please note that this project is released with a Contributor Code of Conduct.
By participating in this project you agree to abide by its terms. See the `Code
of Conduct <https://github.com/googleapis/python-spanner-django/blob/main/CODE_OF_CONDUCT.md>`_ for more information.
Limitations
~~~~~~~~~~~
Spanner has certain limitations of its own. The full set of limitations is documented
`here <https://cloud.google.com/spanner/quotas#schema_limits>`__.
It is recommended that you go through that list.
Django spanner has a set of limitations as well, which you can find
`here <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations.rst>`__.
Features from spanner that are not supported in Django-spanner are listed
`here <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations-spanner.rst>`__.
Raw data
{
"_id": null,
"home_page": "https://github.com/googleapis/python-spanner-django",
"name": "django-google-spanner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Google LLC",
"author_email": "googleapis-packages@google.com",
"download_url": "https://files.pythonhosted.org/packages/31/5d/e77af0bdc79c2410e96a699b922f8882523515e99036ff21ba38363fa6d0/django-google-spanner-4.0.1.tar.gz",
"platform": null,
"description": "Cloud Spanner support for Django\n================================\n\n|GA| |pypi| |versions|\n\n`Cloud Spanner`_ is the world's first fully managed relational database service\nto offer both strong consistency and horizontal scalability for\nmission-critical online transaction processing (OLTP) applications. With Cloud\nSpanner you enjoy all the traditional benefits of a relational database; but\nunlike any other relational database service, Cloud Spanner scales horizontally\nto hundreds or thousands of servers to handle the biggest transactional\nworkloads.\n\n\n- `Client Library Documentation`_\n- `Product Documentation`_\n\n.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg\n :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability\n.. |pypi| image:: https://img.shields.io/pypi/v/django-google-spanner.svg\n :target: https://pypi.org/project/django-google-spanner/\n.. |versions| image:: https://img.shields.io/pypi/pyversions/django-google-spanner.svg\n :target: https://pypi.org/project/django-google-spanner/\n.. _Cloud Spanner: https://cloud.google.com/spanner/\n.. _Client Library Documentation: https://googleapis.dev/python/django-google-spanner/latest/index.html\n.. _Product Documentation: https://cloud.google.com/spanner/docs\n\nQuick Start\n-----------\n\nIn order to use this library, you first need to go through the following steps:\n\n1. `Select or create a Cloud Platform project.`_\n2. `Enable billing for your project.`_\n3. `Enable the Google Cloud Spanner API.`_\n4. `Setup Authentication.`_\n\n.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project\n.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project\n.. _Enable the Google Cloud Spanner API.: https://cloud.google.com/spanner\n.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html\n\nThis package provides a `3rd-party database backend\n<https://docs.djangoproject.com/en/2.2/ref/databases/#using-a-3rd-party-database-backend>`__\nfor using `Cloud Spanner <https://cloud.google.com/spanner>`__ with the `Django\nORM <https://docs.djangoproject.com/en/2.2/topics/db/>`__. It uses the `Cloud\nSpanner Python client library <https://github.com/googleapis/python-spanner>`__\nunder the hood.\n\nInstallation\n------------\n\nInstall this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to\ncreate isolated Python and Django environments. The basic problem it addresses is one of\ndependencies and versions, and indirectly permissions.\n\nWith `virtualenv`_, it's possible to install this library without needing system\ninstall permissions, and without clashing with the installed system\ndependencies.\n\n.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/\n\n\nSupported versions\n~~~~~~~~~~~~~~~~~~\n\nThe library supports `Django 2.2\n<https://docs.djangoproject.com/en/2.2/>`_, and `Django 3.2\n<https://docs.djangoproject.com/en/3.2/>`_.\nBoth versions are long-term support (LTS) releases for the\n`Django project<https://www.djangoproject.com/download/#supported-versions>_`.\nThe minimum required Python version is 3.6.\n\n.. code:: shell\n\n pip3 install django==3.2\n\n\nInstalling the package\n~~~~~~~~~~~~~~~~~~~~~~\n\nTo install from PyPI:\n\n.. code:: shell\n\n pip3 install django-google-spanner\n\n\nTo install from source:\n\n.. code:: shell\n\n git clone git@github.com:googleapis/python-spanner-django.git\n cd python-spanner-django\n pip3 install -e .\n\n\nCreating a Cloud Spanner instance and database\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf you don't already have a Cloud Spanner database, or want to start from\nscratch for a new Django application, you can `create a new instance\n<https://cloud.google.com/spanner/docs/getting-started/python#create_an_instance>`__\nand `database\n<https://cloud.google.com/spanner/docs/getting-started/python#create_a_database>`__\nusing the Google Cloud SDK:\n\n.. code:: shell\n\n gcloud spanner instances create $INSTANCE --config=regional-us-central1 --description=\"New Django Instance\" --nodes=1\n gcloud spanner databases create $DB --instance $INSTANCE\n\n\nConfiguring ``settings.py``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis package provides a Django application named ``django_spanner``. To use the\nCloud Spanner database backend, the application needs to installed and\nconfigured:\n\n- Add ``django_spanner`` as the first entry in ``INSTALLED_APPS``:\n\n .. code:: python\n\n INSTALLED_APPS = [\n 'django_spanner',\n ...\n ]\n\n- Edit the ``DATABASES`` setting to point to an existing Cloud Spanner database:\n\n .. code:: python\n\n DATABASES = {\n 'default': {\n 'ENGINE': 'django_spanner',\n 'PROJECT': '$PROJECT',\n 'INSTANCE': '$INSTANCE',\n 'NAME': '$DATABASE',\n }\n }\n\nTransaction support in autocommit mode\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nDjango version 4.2 and higher by default supports transactions in autocommit mode.\nA transaction is automatically started if you define an\n[atomic block](https://docs.djangoproject.com/en/4.2/topics/db/transactions/#controlling-transactions-explicitly).\n\nDjango version 3.2 and earlier did not support transactions in autocommit mode with Spanner.\nYou can enable transactions in autocommit mode with Spanner with the\n`ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` configuration option.\n\n- To enable transactions in autocommit mode in V3.2, set the flag `ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` to True in your settings.py file.\n- To disable transactions in autocommit mode in V4.2, set the flag `ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` to False in your settings.py file.\n\n\nSet credentials and project environment variables\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nYou'll need to download a service account JSON key file and point to it using an environment variable:\n\n.. code:: shell\n\n export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json\n export GOOGLE_CLOUD_PROJECT=gcloud_project\n\n\nApply the migrations\n~~~~~~~~~~~~~~~~~~~~\n\nPlease run:\n\n.. code:: shell\n\n $ python3 manage.py migrate\n\nThat'll take a while to run. After this you should be able to see the tables and indexes created in your Cloud Spanner console.\n\n\nCreate a Django admin user\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\nFirst you\u2019ll need to create a user who can login to the admin site. Run the following command:\n\n.. code:: shell\n\n $ python3 manage.py createsuperuser\n\nwhich will then produce a prompt which will allow you to create your super user\n\n.. code:: shell\n\n Username: admin\n Email address: admin@example.com\n Password: **********\n Password (again): **********\n Superuser created successfully.\n\n\nLogin as admin\n~~~~~~~~~~~~~~\nNow, run the server\n\n.. code:: shell\n\n python3 manage.py runserver\n\nThen visit http://127.0.0.1:8000/admin/\n\nCreate and register your first model\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPlease follow the guides in https://docs.djangoproject.com/en/2.2/intro/tutorial02/#creating-models\nto create and register the model to the Django\u2019s automatically-generated admin site.\n\nHow it works\n------------\n\nOverall design\n~~~~~~~~~~~~~~\n\n.. figure:: https://raw.githubusercontent.com/googleapis/python-spanner-django/main/assets/overview.png\n :alt: \"Overall Design\"\n\nInternals\n~~~~~~~~~\n\n.. figure:: https://raw.githubusercontent.com/googleapis/python-spanner-django/main/assets/internals.png\n :alt: \"Internals\"\n\n\nExecuting a query\n~~~~~~~~~~~~~~~~~\n\nHere is an example of how to add a row for Model Author, save it and later query it using Django\n\n.. code:: shell\n\n >>> author_kent = Author( first_name=\"Arthur\", last_name=\"Kent\", rating=Decimal(\"4.1\"),)\n >>> author_kent.save()\n >>> qs1 = Author.objects.all().values(\"first_name\", \"last_name\")\n\n\nHow to contribute\n~~~~~~~~~~~~~~~~~\n\nContributions to this library are always welcome and highly encouraged.\n\nSee `CONTRIBUTING <https://github.com/googleapis/python-spanner-django/blob/main/CONTRIBUTING.md>`_ for more information on how to get started.\n\nPlease note that this project is released with a Contributor Code of Conduct.\nBy participating in this project you agree to abide by its terms. See the `Code \nof Conduct <https://github.com/googleapis/python-spanner-django/blob/main/CODE_OF_CONDUCT.md>`_ for more information.\n\n\nLimitations\n~~~~~~~~~~~\n\nSpanner has certain limitations of its own. The full set of limitations is documented\n`here <https://cloud.google.com/spanner/quotas#schema_limits>`__.\nIt is recommended that you go through that list.\n\nDjango spanner has a set of limitations as well, which you can find\n`here <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations.rst>`__.\n\nFeatures from spanner that are not supported in Django-spanner are listed \n`here <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations-spanner.rst>`__.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Bridge to enable using Django with Spanner.",
"version": "4.0.1",
"project_urls": {
"Homepage": "https://github.com/googleapis/python-spanner-django"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "263604391f82624940aac6087c9ef4975670d4d7662631aa96f889afc1b6d066",
"md5": "3d00e146f71ecddd03d51478e1f14cd1",
"sha256": "bd31b856c9cfa63f91aa69bd0824a5fbc138aa517c20214ebdeeefbe08eb8a4a"
},
"downloads": -1,
"filename": "django_google_spanner-4.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d00e146f71ecddd03d51478e1f14cd1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 86638,
"upload_time": "2024-05-07T08:03:16",
"upload_time_iso_8601": "2024-05-07T08:03:16.990087Z",
"url": "https://files.pythonhosted.org/packages/26/36/04391f82624940aac6087c9ef4975670d4d7662631aa96f889afc1b6d066/django_google_spanner-4.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "315de77af0bdc79c2410e96a699b922f8882523515e99036ff21ba38363fa6d0",
"md5": "4ef4e48395788aa78d11df2b1863ec25",
"sha256": "091aa1377bad887941a5473897ba7ebd7b25eaa012f0a86f14d60ccaee42c179"
},
"downloads": -1,
"filename": "django-google-spanner-4.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4ef4e48395788aa78d11df2b1863ec25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 70012,
"upload_time": "2024-05-07T08:03:18",
"upload_time_iso_8601": "2024-05-07T08:03:18.722609Z",
"url": "https://files.pythonhosted.org/packages/31/5d/e77af0bdc79c2410e96a699b922f8882523515e99036ff21ba38363fa6d0/django-google-spanner-4.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-07 08:03:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "googleapis",
"github_project": "python-spanner-django",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "django-google-spanner"
}
JSON
