Skip to content

Commit d5c4e99

Browse files
jskeetjskeet
committed
chore: complete migration of django-google-spanner to librarian
The README.rst change is just using a full copy of the parent README.rst instead of an include. (That is then consistent with all other packages.)
1 parent 64ac5f1 commit d5c4e99

3 files changed

Lines changed: 296 additions & 11 deletions

File tree

‎librarian.yaml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,6 @@ libraries:
7777
client_documentation_override: https://googleapis.dev/python/db-dtypes/latest/index.html
7878
- name: django-google-spanner
7979
version: 4.0.3
80-
skip_generate: true
8180
python:
8281
library_type: INTEGRATION
8382
name_pretty_override: Cloud Spanner Django

‎packages/django-google-spanner/.repo-metadata.json‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
{
2-
"name": "django-google-spanner",
3-
"name_pretty": "Cloud Spanner Django",
4-
"product_documentation": "https://cloud.google.com/spanner/docs/",
2+
"api_shortname": "django-google-spanner",
53
"client_documentation": "https://googleapis.dev/python/django-google-spanner/latest",
4+
"distribution_name": "django-google-spanner",
65
"issue_tracker": "https://issuetracker.google.com/issues?q=componentid:190851%2B%20status:open",
7-
"release_level": "stable",
86
"language": "python",
97
"library_type": "INTEGRATION",
10-
"repo": "googleapis/google-cloud-python",
11-
"distribution_name": "django-google-spanner",
12-
"requires_billing": true,
13-
"api_shortname": "django-google-spanner"
14-
}
8+
"name": "django-google-spanner",
9+
"name_pretty": "Cloud Spanner Django",
10+
"product_documentation": "https://cloud.google.com/spanner/docs/",
11+
"release_level": "stable",
12+
"repo": "googleapis/google-cloud-python"
13+
}

‎packages/django-google-spanner/docs/README.rst‎

Lines changed: 288 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,288 @@
1-
.. include:: ../README.rst
1+
Cloud Spanner support for Django
2+
================================
3+
4+
|GA| |pypi| |versions|
5+
6+
`Cloud Spanner`_ is the world's first fully managed relational database service
7+
to offer both strong consistency and horizontal scalability for
8+
mission-critical online transaction processing (OLTP) applications. With Cloud
9+
Spanner you enjoy all the traditional benefits of a relational database; but
10+
unlike any other relational database service, Cloud Spanner scales horizontally
11+
to hundreds or thousands of servers to handle the biggest transactional
12+
workloads.
13+
14+
15+
- `Client Library Documentation`_
16+
- `Product Documentation`_
17+
18+
.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg
19+
:target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability
20+
.. |pypi| image:: https://img.shields.io/pypi/v/django-google-spanner.svg
21+
:target: https://pypi.org/project/django-google-spanner/
22+
.. |versions| image:: https://img.shields.io/pypi/pyversions/django-google-spanner.svg
23+
:target: https://pypi.org/project/django-google-spanner/
24+
.. _Cloud Spanner: https://cloud.google.com/spanner/
25+
.. _Client Library Documentation: https://googleapis.dev/python/django-google-spanner/latest/index.html
26+
.. _Product Documentation: https://cloud.google.com/spanner/docs
27+
28+
Quick Start
29+
-----------
30+
31+
In order to use this library, you first need to go through the following steps:
32+
33+
1. `Select or create a Cloud Platform project.`_
34+
2. `Enable billing for your project.`_
35+
3. `Enable the Google Cloud Spanner API.`_
36+
4. `Setup Authentication.`_
37+
38+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
39+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
40+
.. _Enable the Google Cloud Spanner API.: https://cloud.google.com/spanner
41+
.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
42+
43+
This package provides a `3rd-party database backend
44+
<https://docs.djangoproject.com/en/4.2/ref/databases/#using-a-3rd-party-database-backend>`__
45+
for using `Cloud Spanner <https://cloud.google.com/spanner>`__ with the `Django
46+
ORM <https://docs.djangoproject.com/en/4.2/topics/db/>`__. It uses the `Cloud
47+
Spanner Python client library <https://github.com/googleapis/python-spanner>`__
48+
under the hood.
49+
50+
Installation
51+
------------
52+
53+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
54+
create isolated Python and Django environments. The basic problem it addresses is one of
55+
dependencies and versions, and indirectly permissions.
56+
57+
With `virtualenv`_, it's possible to install this library without needing system
58+
install permissions, and without clashing with the installed system
59+
dependencies.
60+
61+
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
62+
63+
64+
Supported versions
65+
~~~~~~~~~~~~~~~~~~
66+
67+
The library supports `Django 3.2
68+
<https://docs.djangoproject.com/en/3.2/>`_, and `Django 4.2
69+
<https://docs.djangoproject.com/en/4.2/>`_.
70+
Both versions are long-term support (LTS) releases for the
71+
`Django project<https://www.djangoproject.com/download/#supported-versions>_`.
72+
The minimum required Python version is 3.6.
73+
74+
.. code:: shell
75+
76+
pip3 install django==3.2
77+
78+
79+
Installing the package
80+
~~~~~~~~~~~~~~~~~~~~~~
81+
82+
To install from PyPI:
83+
84+
.. code:: shell
85+
86+
pip3 install django-google-spanner
87+
88+
89+
To install from source:
90+
91+
.. code:: shell
92+
93+
git clone git@github.com:googleapis/google-cloud-python.git
94+
cd python-spanner-django
95+
pip3 install -e .
96+
97+
98+
Creating a Cloud Spanner instance and database
99+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100+
101+
If you don't already have a Cloud Spanner database, or want to start from
102+
scratch for a new Django application, you can `create a new instance
103+
<https://cloud.google.com/spanner/docs/getting-started/python#create_an_instance>`__
104+
and `database
105+
<https://cloud.google.com/spanner/docs/getting-started/python#create_a_database>`__
106+
using the Google Cloud SDK:
107+
108+
.. code:: shell
109+
110+
gcloud spanner instances create $INSTANCE --config=regional-us-central1 --description="New Django Instance" --nodes=1
111+
gcloud spanner databases create $DB --instance $INSTANCE
112+
113+
114+
Configuring ``settings.py``
115+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
116+
117+
This package provides a Django application named ``django_spanner``. To use the
118+
Cloud Spanner database backend, the application needs to installed and
119+
configured:
120+
121+
- Add ``django_spanner`` as the first entry in ``INSTALLED_APPS``:
122+
123+
.. code:: python
124+
125+
INSTALLED_APPS = [
126+
'django_spanner',
127+
...
128+
]
129+
130+
- Edit the ``DATABASES`` setting to point to an existing Cloud Spanner database:
131+
132+
.. code:: python
133+
134+
DATABASES = {
135+
'default': {
136+
'ENGINE': 'django_spanner',
137+
'PROJECT': '$PROJECT',
138+
'INSTANCE': '$INSTANCE',
139+
'NAME': '$DATABASE',
140+
}
141+
}
142+
143+
Configuring primary key generation
144+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145+
146+
The Spanner Django engine by default uses random int64 values that are generated
147+
by the client as primary key values. This default is applied to all databases that are
148+
configured, including databases that use a different engine than Spanner. You can
149+
disable this behavior with the RANDOM_ID_GENERATION_ENABLED setting:
150+
151+
.. code:: python
152+
153+
DATABASES = {
154+
'default': {
155+
'ENGINE': 'django_spanner',
156+
'PROJECT': '$PROJECT',
157+
'INSTANCE': '$INSTANCE',
158+
'NAME': '$DATABASE',
159+
'RANDOM_ID_GENERATION_ENABLED': false,
160+
}
161+
}
162+
163+
164+
165+
Transaction support in autocommit mode
166+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167+
168+
Django version 4.2 and higher by default supports transactions in autocommit mode.
169+
A transaction is automatically started if you define an
170+
[atomic block](https://docs.djangoproject.com/en/4.2/topics/db/transactions/#controlling-transactions-explicitly).
171+
172+
Django version 3.2 and earlier did not support transactions in autocommit mode with Spanner.
173+
You can enable transactions in autocommit mode with Spanner with the
174+
`ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` configuration option.
175+
176+
- To enable transactions in autocommit mode in V3.2, set the flag `ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` to True in your settings.py file.
177+
- To disable transactions in autocommit mode in V4.2, set the flag `ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` to False in your settings.py file.
178+
179+
180+
Set credentials and project environment variables
181+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182+
You'll need to download a service account JSON key file and point to it using an environment variable:
183+
184+
.. code:: shell
185+
186+
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
187+
export GOOGLE_CLOUD_PROJECT=gcloud_project
188+
189+
190+
Apply the migrations
191+
~~~~~~~~~~~~~~~~~~~~
192+
193+
Please run:
194+
195+
.. code:: shell
196+
197+
$ python3 manage.py migrate
198+
199+
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.
200+
201+
202+
Create a Django admin user
203+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
204+
First you’ll need to create a user who can login to the admin site. Run the following command:
205+
206+
.. code:: shell
207+
208+
$ python3 manage.py createsuperuser
209+
210+
which will then produce a prompt which will allow you to create your super user
211+
212+
.. code:: shell
213+
214+
Username: admin
215+
Email address: admin@example.com
216+
Password: **********
217+
Password (again): **********
218+
Superuser created successfully.
219+
220+
221+
Login as admin
222+
~~~~~~~~~~~~~~
223+
Now, run the server
224+
225+
.. code:: shell
226+
227+
python3 manage.py runserver
228+
229+
Then visit http://127.0.0.1:8000/admin/
230+
231+
Create and register your first model
232+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
233+
234+
Please follow the guides in https://docs.djangoproject.com/en/4.2/intro/tutorial02/#creating-models
235+
to create and register the model to the Django’s automatically-generated admin site.
236+
237+
How it works
238+
------------
239+
240+
Overall design
241+
~~~~~~~~~~~~~~
242+
243+
.. figure:: https://raw.githubusercontent.com/googleapis/google-cloud-python/main/assets/overview.png
244+
:alt: "Overall Design"
245+
246+
Internals
247+
~~~~~~~~~
248+
249+
.. figure:: https://raw.githubusercontent.com/googleapis/google-cloud-python/main/assets/internals.png
250+
:alt: "Internals"
251+
252+
253+
Executing a query
254+
~~~~~~~~~~~~~~~~~
255+
256+
Here is an example of how to add a row for Model Author, save it and later query it using Django
257+
258+
.. code:: shell
259+
260+
>>> author_kent = Author( first_name="Arthur", last_name="Kent", rating=Decimal("4.1"),)
261+
>>> author_kent.save()
262+
>>> qs1 = Author.objects.all().values("first_name", "last_name")
263+
264+
265+
How to contribute
266+
~~~~~~~~~~~~~~~~~
267+
268+
Contributions to this library are always welcome and highly encouraged.
269+
270+
See `CONTRIBUTING <https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.md>`_ for more information on how to get started.
271+
272+
Please note that this project is released with a Contributor Code of Conduct.
273+
By participating in this project you agree to abide by its terms. See the `Code
274+
of Conduct <https://github.com/googleapis/google-cloud-python/blob/main/CODE_OF_CONDUCT.md>`_ for more information.
275+
276+
277+
Limitations
278+
~~~~~~~~~~~
279+
280+
Spanner has certain limitations of its own. The full set of limitations is documented
281+
`here <https://cloud.google.com/spanner/quotas#schema_limits>`__.
282+
It is recommended that you go through that list.
283+
284+
Django spanner has a set of limitations as well, which you can find
285+
`here <https://github.com/googleapis/google-cloud-python/blob/main/docs/limitations.rst>`__.
286+
287+
Features from spanner that are not supported in Django-spanner are listed
288+
`here <https://github.com/googleapis/google-cloud-python/blob/main/docs/limitations-spanner.rst>`__.

0 commit comments

Comments
 (0)