8000 chore: README updates (#599) · googleapis/python-spanner-django@2c8fb24 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2c8fb24

Browse files
c24tc24t
authored
chore: README updates (#599)
1 parent 5d65e3f commit 2c8fb24

File tree

1 file changed

+60
-46
lines changed

1 file changed

+60
-46
lines changed

‎README.rst

Lines changed: 60 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,35 @@
11
Cloud Spanner support for Django
22
================================
33

4-
ORM plugin for using Cloud Spanner as a `database backend
4+
This package provides a `3rd-party database backend
55
<https://docs.djangoproject.com/en/2.2/ref/databases/#using-a-3rd-party-database-backend>`__
6-
for Django.
6+
for using `Cloud Spanner <https://cloud.google.com/spanner>`__ with the `Django
7+
ORM <https://docs.djangoproject.com/en/2.2/topics/db/>`__. It uses the `Cloud
8+
Spanner Python client library <https://github.com/googleapis/python-spanner>`__
9+
under the hood.
710

8-
How it works
11+
Installation
912
------------
1013

11-
Overall design
12-
~~~~~~~~~~~~~~
14+
To use this library, you'll need a Google Cloud Platform project with the Cloud
15+
Spanner API enabled. For details on enabling the API and authenticating with
16+
GCP, see the `Cloud Spanner Python client library quickstart guide
17+
<https://github.com/googleapis/python-spanner/#quick-start>`__.
1318

14-
.. figure:: ./assets/overview.png
15-
:alt:
19+
Supported versions
20+
~~~~~~~~~~~~~~~~~~
1621

17-
Internals
18-
~~~~~~~~~
22+
At the moment, this library only supports `Django 2.2
23+
<https://docs.djangoproject.com/en/2.2/>`__. It also requires Python version
24+
3.6 or later.
1925

20-
.. figure:: ./assets/internals.png
21-
:alt:
26+
This package follows a common versioning convention for Django plugins: the
27+
major and minor version components of this package should match the installed
28+
version of Django. That is, ``django-google-spanner~=2.2`` works with
29+
``Django~=2.2``.
2230

23-
24-
Installation
25-
------------
26-
27-
Using this library requires a Google Cloud Platform project with the Cloud
28-
Spanner API enabled. See the Spanner Python client `documentation
29-
<https://github.com/googleapis/python-spanner/#quick-start>`__ for details.
30-
31-
The version of ``django-google-spanner`` must correspond to your version
32-
of Django. For example, ``django-google-spanner`` 2.2.x works with Django
33-
2.2.y (Note: this is the only supported version at this time).
34-
35-
The minor release numbers of Django may not correspond to the minor release
36-
numbers of ``django-google-spanner``. Use the latest minor release of each.
31+
Installing the package
32+
~~~~~~~~~~~~~~~~~~~~~~
3733

3834
To install from PyPI:
3935

@@ -51,14 +47,30 @@ To install from source:
5147
pip3 install -e .
5248
5349
50+
Creating a Cloud Spanner instance and database
51+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52+
53+
If you don't already have a Cloud Spanner database, or want to start from
54+
scratch for a new Django application, you can `create a new instance
55+
<https://cloud.google.com/spanner/docs/getting-started/python#create_an_instance>`__
56+
and `database
57+
<https://cloud.google.com/spanner/docs/getting-started/python#create_a_database>`__
58+
using the Google Cloud SDK:
59+
60+
.. code:: shell
61+
62+
gcloud spanner instances create $INSTANCE --config=regional-us-central1 --description="New Django Instance" --nodes=1
63+
gcloud spanner databases create $DB --instance $INSTANCE
64+
65+
5466
Configuring ``settings.py``
5567
~~~~~~~~~~~~~~~~~~~~~~~~~~~
5668

57-
After `installation <#Installation>`__, you'll have to update your Django
58-
``settings.py`` file as follows.
69+
This package provides a Django application named ``django_spanner``. To use the
70+
Cloud Spanner database backend, the application needs to installed and
71+
configured:
5972

60-
- Add ``django_spanner`` as the very first entry in the ``INSTALLED_APPS``
61-
settings:
73+
- Add ``django_spanner`` as the first entry in ``INSTALLED_APPS``:
6274

6375
.. code:: python
6476
@@ -67,34 +79,36 @@ After `installation <#Installation>`__, you'll have to update your Django
6779
...
6880
]
6981
70-
- Edit the ``DATABASES`` settings to point to an EXISTING database, as shown in the following example:
82+
- Edit the ``DATABASES`` setting to point to an existing Cloud Spanner database:
7183

7284
.. code:: python
7385
7486
DATABASES = {
7587
'default': {
7688
'ENGINE': 'django_spanner',
77-
'PROJECT': '<GCP_project_id>',
78-
'INSTANCE': '<instance_id>',
79-
'NAME': '<database_name>',
89+
'PROJECT': '$PROJECT',
90+
'INSTANCE': '$INSTANCE',
91+
'NAME': '$DATABASE',
8092
}
8193
}
8294
83-
- In order to retrieve the Cloud Spanner credentials from a JSON file, the ``credentials_uri`` parameter can also be supplied in the ``OPTIONS`` field:
8495
85-
.. code:: python
96+
How it works
97+
------------
98+
99+
Overall design
100+
~~~~~~~~~~~~~~
101+
102+
.. figure:: ./assets/overview.png
103+
:alt:
104+
105+
Internals
106+
~~~~~~~~~
107+
108+
.. figure:: ./assets/internals.png
109+
:alt:
110+
86111

87-
DATABASES = {
88-
'default': {
89-
'ENGINE': 'django_spanner',
90-
'PROJECT': '<GCP_project_id>',
91-
'INSTANCE': '<instance_id>',
92-
'NAME': '<database_name>',
93-
'OPTIONS': {
94-
'credentials_uri': '<credentials_uri>',
95-
},
96-
},
97-
}
98112

99113
Executing a query
100114
~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)
0