Skip to content

Commit 66469bf

Browse files
vi3k6i5vi3k6i5
authored
docs: Add limitations docs on spanner features not supported by spanner-django library. (#758)
* chore: release 2.2.1b4 Release-As: 2.2.1b4 * docs: Add spanner django limitations from spanner perspective * docs: refactored table layout for workarounds in spanner limitations files * refactor: remove double occurance of work workaround in spanner limitations file
1 parent dd7ed22 commit 66469bf

File tree

2 files changed

+116
-1
lines changed

2 files changed

+116
-1
lines changed

‎README.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -246,4 +246,7 @@ Spanner has certain limitations of its own. The full set of limitations is docum
246246
It is recommended that you go through that list.
247247

248248
Django spanner has a set of limitations as well, which you can find
249-
`here <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations.rst>`__.
249+
`here <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations.rst>`__.
250+
251+
Features from spanner that are not supported in Django-spanner are listed
252+
`here <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations-spanner.rst>`__.

‎docs/limitations-spanner.rst

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
Limitations from Spanner perspective
2+
------------------------------------
3+
4+
Below is a List of Limitations for features that are supported in Spanner but
5+
are not supported in the Django Spanner library. Some features have been
6+
disabled because of compatibility issues using the Django feature toggle.
7+
8+
Query Hints
9+
~~~~~~~~~~~
10+
Django automatically manages query generation and thus does not expose methods
11+
to add query hints directly. While libraries can add support for this feature
12+
and manage the query generation part, we have not added this because of the
13+
added complexity. The workaround to use this feature is by using Raw Queries
14+
directly, and adding Query hints there.
15+
16+
Mutations
17+
~~~~~~~~~
18+
Mutations are not a concept that is understood by Django so it does not support
19+
it inherently. The workaround is to use python-spanner objects and run Mutations using that.
20+
21+
Batch DDL
22+
~~~~~~~~~
23+
Migrations (creation and updation) of tables in Django are sequential operations.
24+
Django doesn't inherently support doing batch DDL operations. However, customers
25+
can use python-spanner objects to run batch DDL for unmanaged tables in Django.
26+
27+
Stale Reads
28+
~~~~~~~~~~~
29+
Stale Reads are not a concept that is understood by Django so it does not support
30+
it inherently. The workaround is to use python-spanner objects and run read operations on snapshots.
31+
32+
Interleaving
33+
~~~~~~~~~~~~
34+
Interleaving is not a concept that is understood by Django so it does not support
35+
it inherently. The workaround is to use Unmanaged tables and python-spanner objects
36+
to create and manage interleaved tables.
37+
38+
39+
Partitioned DML
40+
~~~~~~~~~~~~~~~
41+
Partitioned DML is not a concept that is understood by Django so it does not support
42+
it inherently. The workaround is to use python-spanner objects to perform partitioned
43+
DML operations.
44+
45+
Session Labeling
46+
~~~~~~~~~~~~~~~~
47+
Django does not support session pools for databases directly and does not have the
48+
concept of session labeling itself. The workaround is to use python-spanner objects
49+
to create and manage sessions along with Session labels.
50+
51+
Request Priority
52+
~~~~~~~~~~~~~~~~
53+
Request Priority for database calls is not a concept that is understood by Django so
54+
it does not support it inherently. The workaround is to use python-spanner objects
55+
and use request priority as part of the db calls.
56+
57+
Tagging
58+
~~~~~~~
59+
Tagging for database calls is not a concept that is understood by Django so it does not
60+
support it inherently. The workaround is to use python-spanner objects and use the
61+
tagging feature via that.
62+
63+
Configurable Leader Option
64+
~~~~~~~~~~~~~~~~~~~~~~~~~~
65+
Configuring Leader Option for database calls is not a concept that is understood by
66+
Django so it does not support it inherently. The workaround is to use python-spanner
67+
objects while creating the database.
68+
69+
Backups / Cross region Backups
70+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71+
Backups for databases are not managed by Django so it does not support it inherently.
72+
In general, none of the Spanner ORMs / drivers are expected to support backup management.
73+
The workaround is to use python-spanner objects and use backup features via that.
74+
75+
Custom Instance Config
76+
~~~~~~~~~~~~~~~~~~~~~~
77+
Instances for spanner are not managed by Django so it does not support it inherently.
78+
The workaround is to use python-spanner objects and use Instance config features via that.
79+
80+
Workaround
81+
----------
82+
83+
.. list-table::
84+
:widths: 33 67
85+
:header-rows: 1
86+
87+
* - Features
88+
- Is a workaround available?
89+
* - Query Hints
90+
- Raw Queries can be used for Query hints `Link <https://stackoverflow.com/a/28350704/3027854>`__.
91+
* - Mutations
92+
- Python-spanner database objects can be used to run Mutation queries. `Link <https://cloud.google.com/spanner/docs/modify-mutation-api#python>`__.
93+
* - Batch DDL
94+
- Using unmanaged tables in Django. `Link <https://docs.djangoproject.com/en/4.0/ref/models/options/#managed>`__ and Directly using Python spanner objects to execute batch DDL statements. `Link <https://cloud.google.com/spanner/docs/getting-started/python#create_a_database>`__.
95+
* - Stale Reads
96+
- Python-spanner database objects can be used to perform stale reads. `Link <https://cloud.google.com/spanner/docs/reads#python>`__.
97+
* - Interleaving
98+
- Using unmanaged tables in Django. `Link <https://docs.djangoproject.com/en/4.0/ref/models/options/#managed>`__ and Directly using Python spanner objects to create interleaved tables. `Link <https://cloud.google.com/spanner/docs/getting-started/python#create_a_database>`__.
99+
* - Partitioned DML
100+
- Python-spanner database objects can be used to perform Partitioned DML. `Link <https://cloud.google.com/spanner/docs/dml-partitioned#python>`__.
101+
* - Session Labeling
102+
- Python-spanner connection objects can be used to perform Session creation and labeling . `Link <https://cloud.google.com/spanner/docs/sessions#python>`__.
103+
* - Request Priority
104+
- Python-spanner connection objects can be used to make backend calls with request priority. `Link <https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions>`__.
105+
* - Tagging
106+
- Python-spanner connection objects can be used to make backend calls with request tags. `Link <https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions>`__.
107+
* - Configurable Leader Option
108+
- Python-spanner database objects can be used to set or update leader options. `Link <https://cloud.google.com/spanner/docs/modifying-leader-region#python>`__.
109+
* - Cross region backup
110+
- Python-spanner library can be used to perform db backups across regions. `Link <https://cloud.google.com/spanner/docs/backup>`__.
111+
* - Custom Instance Config
112+
- Python-spanner library can be used to manage instances. `Link <https://googleapis.dev/python/spanner/latest/instance-api.html>`__.

0 commit comments

Comments
 (0)