From be06b5974103ab571c37eb4a82a5595915f802c0 Mon Sep 17 00:00:00 2001 From: "STATION\\MF" Date: Sun, 29 Nov 2020 18:55:17 -0500 Subject: [PATCH 1/8] feat: revised `README.rst` --- README.rst | 117 +++++++++++++++++++++++++---------------------------- 1 file changed, 54 insertions(+), 63 deletions(-) diff --git a/README.rst b/README.rst index dec0d579af..ed2e70df53 100644 --- a/README.rst +++ b/README.rst @@ -5,6 +5,21 @@ ORM plugin for using Cloud Spanner as a `database backend `__ for Django. +How it works +------------ + +Overall design +~~~~~~~~~~~~~~ + +.. figure:: ./assets/overview.png + :alt: + +Internals +~~~~~~~~~ + +.. figure:: ./assets/internals.png + :alt: + Installation ------------ @@ -53,39 +68,37 @@ After `installation <#Installation>`__, you'll need to edit your Django ... ] -- Edit the ``DATABASES`` setting to point to an EXISTING database +- Edit the ``DATABASES`` setting to point to an EXISTING database, as shown in the following example. -Format -~~~~~~ +Database configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: python DATABASES = { 'default': { 'ENGINE': 'django_spanner', - 'PROJECT': '', + 'PROJECT': '', 'INSTANCE': '', 'NAME': '', - # Only include this if you need to specify where to retrieve the - # service account JSON for the credentials to connect to Cloud Spanner. - 'OPTIONS': { - 'credentials_uri': '', - }, - }, + } } -Database configurations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In order to retrieve the Cloud Spanner credentials from a JSON file, +``credentials_uri`` parameter can also be supplied in the ``OPTIONS`` field: .. code:: python DATABASES = { 'default': { 'ENGINE': 'django_spanner', - 'PROJECT': 'appdev-soda-spanner-staging', # Or the GCP project-id - 'INSTANCE': 'django-dev1', # Or the Cloud Spanner instance - 'NAME': 'db1', # Or the Cloud Spanner database to use - } + 'PROJECT': '', + 'INSTANCE': '', + 'NAME': '', + 'OPTIONS': { + 'credentials_uri': '', + }, + }, } Execute a query @@ -95,7 +108,7 @@ Execute a query from google.cloud.spanner_dbapi import connect - connection = connect("instance-id", "database-id") + connection = connect('', '') cursor = connection.cursor() cursor.execute( @@ -110,14 +123,6 @@ Execute a query Limitations ----------- -Transaction management isn't supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``django-google-spanner`` always works in ``autocommit`` mode, which is -Django's default behavior even for backends that support manual transaction -management. Transactions cannot be controlled manually with calls like -``django.db.transaction.atomic()``. - ``AutoField`` generates random IDs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,23 +155,23 @@ constraints Check constraints aren't supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Spanner doesn't support ``CHECK`` constraints so one isn't created for +Spanner does not support ``CHECK`` constraints, so one isn't created for `PositiveIntegerField `__ and `CheckConstraint `__ can't be used. -``DecimalField`` isn't supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +No native support for ``DecimalField`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Spanner doesn't support a NUMERIC data type that allows storing high -precision decimal values without the possibility of data loss. +Spanner does not support NUMERIC data types that allow storing high precision +decimal values, so these values are stored as strings instead. ``Variance`` and ``StdDev`` database functions aren't supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Spanner doesn't support these functions. +Spanner does not support these functions. ``Meta.order_with_respect_to`` model option isn't supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -177,7 +182,7 @@ This feature uses a column name that starts with an underscore Random ``QuerySet`` ordering isn't supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Spanner doesn't support it. For example: +Spanner does not support it and will throw an exception. For example: :: @@ -189,13 +194,11 @@ Spanner doesn't support it. For example: Schema migrations ~~~~~~~~~~~~~~~~~ -Spanner has some limitations on schema changes which you must respect: +There are some limitations on schema changes to consider: -- Renaming tables and columns isn't supported. -- A column's type can't be changed. +- No support for renaming tables and columns; +- A column's type can't be changed; - A table's primary key can't be altered. -- Migrations aren't atomic since ``django-google-spanner`` doesn't support - transactions. ``DurationField`` arithmetic doesn't work with ``DateField`` values (`#253 `__) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -207,20 +210,23 @@ the column type: or ``TIMESTAMP_SUB`` - ``DATE`` columns (``DateField``) require ``DATE_ADD`` or ``DATE_SUB`` -Django doesn't provide a way to determine which database function to -use. ``DatabaseOperations.combine_duration_expression()`` arbitrary uses +Django does not provide ways to determine which database function to +use. ``DatabaseOperations.combine_duration_expression()`` arbitrarily uses ``TIMESTAMP_ADD`` and ``TIMESTAMP_SUB``. Therefore, if you use a -``DateField`` in a ``DurationField`` expression, you'll see an error -like: "No matching signature for function TIMESTAMP\_ADD for argument -types: DATE, INTERVAL INT64 DATE\_TIME\_PART." +``DateField`` in a ``DurationField`` expression, you'll likely see an error +such as: + +:: -Computations that yield FLOAT64 values can't be assigned to INT64 columns -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + "No matching signature for function TIMESTAMP\_ADD for argument types: + DATE, INTERVAL INT64 DATE\_TIME\_PART." -Spanner `doesn't support -this `__. +Computations that yield FLOAT64 values cannot be assigned to INT64 columns +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For example, if ``integer`` is ``IntegerField``: +Spanner does not support this (`#331 +`__) and will +throw an error: :: @@ -233,7 +239,7 @@ For example, if ``integer`` is ``IntegerField``: Addition with null values crash ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For example: +Additions cannot include ``None`` values. For example: :: @@ -241,18 +247,3 @@ For example: ... google.api_core.exceptions.InvalidArgument: 400 Operands of + cannot be literal NULL ... - -How it works ------------- - -Overall design -~~~~~~~~~~~~~~ - -.. figure:: ./assets/overview.png - :alt: - -Internals -~~~~~~~~~ - -.. figure:: ./assets/internals.png - :alt: From a6edc4ca34b7a9b1a53b15ba40bd48f81d487437 Mon Sep 17 00:00:00 2001 From: "STATION\\MF" Date: Sun, 29 Nov 2020 19:16:06 -0500 Subject: [PATCH 2/8] chore: some rephrasing --- README.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index ed2e70df53..bee22e6282 100644 --- a/README.rst +++ b/README.rst @@ -144,13 +144,11 @@ these IDs are not monotonically increasing. This means that sorting models by ID isn't guaranteed to return them in the order in which they were created. -``ForeignKey`` constraints aren't created -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``ForeignKey`` constraints aren't created (`#313 `__) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Spanner doesn't support ``ON DELETE CASCADE`` when creating foreign-key -constraints so ``django-google-spanner`` `doesn't support foreign key -constraints -`__. +Spanner does not support ``ON DELETE CASCADE`` when creating foreign-key +constraints, so these are not supported in ``django-google-spanner``. Check constraints aren't supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -165,8 +163,10 @@ can't be used. No native support for ``DecimalField`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Spanner does not support NUMERIC data types that allow storing high precision -decimal values, so these values are stored as strings instead. +Spanner's support for `Decimal `__ +types is limited to +`NUMERIC `__ +precision. Higher-precision values can be stored as strings instead. ``Variance`` and ``StdDev`` database functions aren't supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 74ba9da7c3579922002663df822c7f342a488445 Mon Sep 17 00:00:00 2001 From: "STATION\\MF" Date: Sun, 29 Nov 2020 19:45:20 -0500 Subject: [PATCH 3/8] chore: minor fix --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index bee22e6282..2ce3b3871f 100644 --- a/README.rst +++ b/README.rst @@ -120,8 +120,8 @@ Execute a query results = cur.fetchall() -Limitations ------------ +Current limitations +------------------- ``AutoField`` generates random IDs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From c7e0350cf20666601d60570b6dd3d684e43ec7c7 Mon Sep 17 00:00:00 2001 From: "STATION\\MF" Date: Tue, 1 Dec 2020 23:08:23 -0500 Subject: [PATCH 4/8] cleanup: removal of `connection-usage.rst` --- docs/connection-usage.rst | 32 -------------------------------- 1 file changed, 32 deletions(-) delete mode 100644 docs/connection-usage.rst diff --git a/docs/connection-usage.rst b/docs/connection-usage.rst deleted file mode 100644 index 9049e3e2b2..0000000000 --- a/docs/connection-usage.rst +++ /dev/null @@ -1,32 +0,0 @@ -DB API Connection -================= - -.. _spanner-client: - - -Creating a Connection ---------------------- - -To use the API, the :class:`~google.cloud.spanner_django.connection.Connection` -class defines a high-level interface which handles connection to a Spanner -databse: - -.. code:: python - - from google.cloud.spanner import connection - conn = connection.Connection() - -Configuration -------------- - -- For an overview of authentication in ``google.cloud-python``, - see `Authentication - `_. - -- In addition to any authentication configuration, you can also set the - :envvar:`GCLOUD_PROJECT` environment variable for the Google Cloud Console - project you'd like to interact with. If your code is running in Google App - Engine or Google Compute Engine the project will be detected automatically. - (Setting this environment variable is not required, you may instead pass the - ``project`` explicitly when constructing a - :class:`~google.cloud.spanner_django.connection.Connection`). From 3ea4e4e017f1f214167b9be48995e1b30402cf74 Mon Sep 17 00:00:00 2001 From: "STATION\\MF" Date: Tue, 1 Dec 2020 23:31:14 -0500 Subject: [PATCH 5/8] docs: updates to `README.rst` --- README.rst | 86 ++++++++++++++++++++++++++---------------------------- 1 file changed, 42 insertions(+), 44 deletions(-) diff --git a/README.rst b/README.rst index 2ce3b3871f..a242e493a5 100644 --- a/README.rst +++ b/README.rst @@ -24,16 +24,16 @@ Internals Installation ------------ -To use this library you'll need a Google Cloud Platform project with the Cloud -Spanner API enabled. See the `Cloud Spanner Python client docs +Using this library requires a Google Cloud Platform project with the Cloud +Spanner API enabled. See the Spanner' Python Client `documentation `__ for details. -Use the version of ``django-google-spanner`` that corresponds to your version +The version of ``django-google-spanner`` must correspond to your version of Django. For example, ``django-google-spanner`` 2.2.x works with Django -2.2.y. (This is the only supported version at this time.) +2.2.y (Note: this is the only supported version at this time). -The minor release number of Django doesn't correspond to the minor release -number of ``django-google-spanner``. Use the latest minor release of each. +The minor release numbers of Django may not correspond to the minor release +numbers of ``django-google-spanner``. Use the latest minor release of each. To install from PyPI: @@ -42,7 +42,7 @@ To install from PyPI: pip3 install django-google-spanner -To install from source: +To install from the source: .. code:: shell @@ -54,12 +54,14 @@ To install from source: Usage ----- -After `installation <#Installation>`__, you'll need to edit your Django -``settings.py`` file: +Configuring ``settings.py`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Add ``django_spanner`` as the very first entry in the ``INSTALLED_APPS`` - setting +After `installation <#Installation>`__, you'll have to update your Django +``settings.py`` file as follows. +- Add ``django_spanner`` as the very first entry in the ``INSTALLED_APPS`` + settings: .. code:: python @@ -68,41 +70,37 @@ After `installation <#Installation>`__, you'll need to edit your Django ... ] -- Edit the ``DATABASES`` setting to point to an EXISTING database, as shown in the following example. - -Database configurations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: python - - DATABASES = { - 'default': { - 'ENGINE': 'django_spanner', - 'PROJECT': '', - 'INSTANCE': '', - 'NAME': '', - } - } - -In order to retrieve the Cloud Spanner credentials from a JSON file, -``credentials_uri`` parameter can also be supplied in the ``OPTIONS`` field: +- Edit the ``DATABASES`` settings to point to an EXISTING database, as shown in the following example: -.. code:: python + .. code:: python - DATABASES = { - 'default': { - 'ENGINE': 'django_spanner', - 'PROJECT': '', - 'INSTANCE': '', - 'NAME': '', - 'OPTIONS': { - 'credentials_uri': '', - }, - }, - } - -Execute a query -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + DATABASES = { + 'default': { + 'ENGINE': 'django_spanner', + 'PROJECT': '', + 'INSTANCE': '', + 'NAME': '', + } + } + +- In order to retrieve the Cloud Spanner credentials from a JSON file, ``credentials_uri`` parameter can also be supplied in the ``OPTIONS`` field: + + .. code:: python + + DATABASES = { + 'default': { + 'ENGINE': 'django_spanner', + 'PROJECT': '', + 'INSTANCE': '', + 'NAME': '', + 'OPTIONS': { + 'credentials_uri': '', + }, + }, + } + +Executing a query +~~~~~~~~~~~~~~~~~ .. code:: python From ccf9672b8ce7fc6685815da5ae454de20524c30a Mon Sep 17 00:00:00 2001 From: "STATION\\MF" Date: Tue, 1 Dec 2020 23:47:17 -0500 Subject: [PATCH 6/8] fix: updating broken reference --- docs/api-reference.rst | 2 +- docs/django-spanner-usage.rst | 4 ++++ docs/index.rst | 2 +- 3 files changed, 6 insertions(+), 2 deletions(-) create mode 100644 docs/django-spanner-usage.rst diff --git a/docs/api-reference.rst b/docs/api-reference.rst index 7da735f86f..847846a55e 100644 --- a/docs/api-reference.rst +++ b/docs/api-reference.rst @@ -1,6 +1,6 @@ API Reference ============= -The following classes and methods constitute the Spanner DB API connection. +The following classes and methods constitute the Django Spanner API. [this page is under construction] diff --git a/docs/django-spanner-usage.rst b/docs/django-spanner-usage.rst new file mode 100644 index 0000000000..a7dd8a9335 --- /dev/null +++ b/docs/django-spanner-usage.rst @@ -0,0 +1,4 @@ +Usage +===== + +[this page is under construction] \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 58fbbf18bc..e78cd6e7e1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Usage Documentation :maxdepth: 1 :titlesonly: - connection-usage + django-spanner-usage API Documentation ----------------- From 7cf8b5520cd953e8575e0d9db08e62e27fe9a3a6 Mon Sep 17 00:00:00 2001 From: "STATION\\MF" Date: Mon, 7 Dec 2020 18:00:09 -0500 Subject: [PATCH 7/8] fix: docs --- README.rst | 13 +++++-------- docs/django-spanner-usage.rst | 4 ---- 2 files changed, 5 insertions(+), 12 deletions(-) delete mode 100644 docs/django-spanner-usage.rst diff --git a/README.rst b/README.rst index a242e493a5..bd9eb1ebed 100644 --- a/README.rst +++ b/README.rst @@ -25,7 +25,7 @@ Installation ------------ Using this library requires a Google Cloud Platform project with the Cloud -Spanner API enabled. See the Spanner' Python Client `documentation +Spanner API enabled. See the Spanner Python client `documentation `__ for details. The version of ``django-google-spanner`` must correspond to your version @@ -42,7 +42,7 @@ To install from PyPI: pip3 install django-google-spanner -To install from the source: +To install from source: .. code:: shell @@ -51,9 +51,6 @@ To install from the source: pip3 install -e . -Usage ------ - Configuring ``settings.py`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -83,7 +80,7 @@ After `installation <#Installation>`__, you'll have to update your Django } } -- In order to retrieve the Cloud Spanner credentials from a JSON file, ``credentials_uri`` parameter can also be supplied in the ``OPTIONS`` field: +- In order to retrieve the Cloud Spanner credentials from a JSON file, the ``credentials_uri`` parameter can also be supplied in the ``OPTIONS`` field: .. code:: python @@ -146,12 +143,12 @@ were created. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Spanner does not support ``ON DELETE CASCADE`` when creating foreign-key -constraints, so these are not supported in ``django-google-spanner``. +constraints, so this is not supported in ``django-google-spanner``. Check constraints aren't supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Spanner does not support ``CHECK`` constraints, so one isn't created for +Spanner does not support ``CHECK`` constraints so one isn't created for `PositiveIntegerField `__ and `CheckConstraint diff --git a/docs/django-spanner-usage.rst b/docs/django-spanner-usage.rst deleted file mode 100644 index a7dd8a9335..0000000000 --- a/docs/django-spanner-usage.rst +++ /dev/null @@ -1,4 +0,0 @@ -Usage -===== - -[this page is under construction] \ No newline at end of file From c825e0d71bbca9f011249d9eb20b2b36745ed55a Mon Sep 17 00:00:00 2001 From: "STATION\\MF" Date: Mon, 7 Dec 2020 18:00:30 -0500 Subject: [PATCH 8/8] docs: cleanup --- docs/index.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index e78cd6e7e1..5e9fef5773 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,5 @@ .. include:: README.rst -Usage Documentation -------------------- -.. toctree:: - :maxdepth: 1 - :titlesonly: - - django-spanner-usage - API Documentation ----------------- .. toctree::