From d70cb28c8a20511558fa47818103afb5e0492918 Mon Sep 17 00:00:00 2001 From: MF2199 <38331387+mf2199@users.noreply.github.com> Date: Tue, 15 Dec 2020 02:22:38 -0500 Subject: [PATCH] Docs: updated `README.rst` file (#563) --- README.rst | 190 ++++++++++++++++++-------------------- docs/api-reference.rst | 2 +- docs/connection-usage.rst | 32 ------- docs/index.rst | 8 -- 4 files changed, 89 insertions(+), 143 deletions(-) delete mode 100644 docs/connection-usage.rst diff --git a/README.rst b/README.rst index dec0d579af..bd9eb1ebed 100644 --- a/README.rst +++ b/README.rst @@ -5,20 +5,35 @@ 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 ------------ -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: @@ -36,15 +51,14 @@ To install from source: pip3 install -e . -Usage ------ +Configuring ``settings.py`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -After `installation <#Installation>`__, you'll need to edit your Django -``settings.py`` file: +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`` - setting - + settings: .. code:: python @@ -53,49 +67,43 @@ After `installation <#Installation>`__, you'll need to edit your Django ... ] -- Edit the ``DATABASES`` setting to point to an EXISTING database - -Format -~~~~~~ +- Edit the ``DATABASES`` settings to point to an EXISTING database, as shown in the following example: -.. code:: python - - DATABASES = { - 'default': { - 'ENGINE': 'django_spanner', - '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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. 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 - } - } + .. code:: python -Execute a query -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + DATABASES = { + 'default': { + 'ENGINE': 'django_spanner', + 'PROJECT': '', + 'INSTANCE': '', + 'NAME': '', + } + } + +- 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 + + DATABASES = { + 'default': { + 'ENGINE': 'django_spanner', + 'PROJECT': '', + 'INSTANCE': '', + 'NAME': '', + 'OPTIONS': { + 'credentials_uri': '', + }, + }, + } + +Executing a query +~~~~~~~~~~~~~~~~~ .. code:: python from google.cloud.spanner_dbapi import connect - connection = connect("instance-id", "database-id") + connection = connect('', '') cursor = connection.cursor() cursor.execute( @@ -107,16 +115,8 @@ Execute a query results = cur.fetchall() -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()``. +Current limitations +------------------- ``AutoField`` generates random IDs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -139,34 +139,34 @@ 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 this is not supported in ``django-google-spanner``. 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'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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Spanner doesn't support these functions. +Spanner does not support these functions. ``Meta.order_with_respect_to`` model option isn't supported ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -177,7 +177,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 +189,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 +205,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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: -Spanner `doesn't support -this `__. + "No matching signature for function TIMESTAMP\_ADD for argument types: + DATE, INTERVAL INT64 DATE\_TIME\_PART." -For example, if ``integer`` is ``IntegerField``: +Computations that yield FLOAT64 values cannot be assigned to INT64 columns +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Spanner does not support this (`#331 +`__) and will +throw an error: :: @@ -233,7 +234,7 @@ For example, if ``integer`` is ``IntegerField``: Addition with null values crash ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For example: +Additions cannot include ``None`` values. For example: :: @@ -241,18 +242,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: 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/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`). diff --git a/docs/index.rst b/docs/index.rst index 58fbbf18bc..5e9fef5773 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,5 @@ .. include:: README.rst -Usage Documentation -------------------- -.. toctree:: - :maxdepth: 1 - :titlesonly: - - connection-usage - API Documentation ----------------- .. toctree::