Thanks to visit codestin.com
Credit goes to github.com

Skip to content

fix: Update README for alpha release #503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 15, 2020
Merged

fix: Update README for alpha release #503

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
93d8541
fix: Update README for alpha release
c24t Sep 15, 2020
b98acb4
Address comments
c24t Sep 15, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 45 additions & 56 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,50 @@
django-spanner
==============
Cloud Spanner support for Django
================================

ORM plugin for using Cloud Spanner as a database for Django.
ORM plugin for using Cloud Spanner as a `database backend
<https://docs.djangoproject.com/en/2.2/ref/databases/#using-a-3rd-party-database-backend>`__
for Django.

🚨THIS CODE IS STILL UNDER DEVELOPMENT🚨
========================================

Table of contents
-----------------

- `Installing it <#installing-it>`__
- `Using it <#using-it>`__

- `Format <#format>`__
- `Example <#example>`__
Installation
------------

- `Functional tests <#functional-tests>`__
- `Django integration tests <#django-integration-tests>`__
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
<https://github.com/googleapis/python-spanner/#quick-start>`__ for details.

- `django\_test\_suite.sh <#django_test_suitesh>`__
Use the version of ``python-spanner-django`` that corresponds to your version
of Django. For example, ``python-spanner-django`` 2.2.x works with Django
2.2.y. (This is the only supported version at this time.)

- `Environment variables <#environment-variables>`__
- `Example run <#example-run>`__
The minor release number of Django doesn't correspond to the minor release
number of ``python-spanner-django``. Use the latest minor release of each.

- `Parallelization script <#parallelization-script>`__
To install from PyPI:

- `Environment variables <#environment-variables>`__
- `Example run <#example-run>`__
.. code:: shell

- `Limitations <#limitations>`__
- `How it works <#how-it-works>`__
pip3 install django-google-spanner

- `Overall design <#overall-design>`__
- `Internals <#internals>`__

Installing it
-------------
To install from source:

Use the version of django-spanner that corresponds to your version of
Django. For example, django-spanner 2.2.x works with Django 2.2.y. (This
is the only supported version at this time.)
.. code:: shell

The minor release number of Django doesn't correspond to the minor
release number of django-spanner. Use the latest minor release of each.
git clone [email protected]:googleapis/python-spanner-django.git
cd python-spanner-django
pip3 install -e .

.. code:: shell

pip3 install --user .
Useage
------

Using it
--------
After `installattion <#Installation>`__, you'll need to edit your Django
``settings.py`` file:

After `installing it <#installing-it>`__, you'll need to edit your
Django ``settings.py`` file:
- Add ``django_spanner`` as the very first entry in the ``INSTALLED_APPS``
setting

- Add ``django_spanner`` as the very first entry in the
``INSTALLED_APPS`` setting

.. code:: python

Expand Down Expand Up @@ -107,18 +96,19 @@ Limitations
Transaction management isn't supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

django-spanner always works in Django's default transaction behavior,
``autocommit`` mode. Transactions cannot be controlled manually with
calls like ``django.db.transaction.atomic()``.
``python-spanner-django`` 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Spanner doesn't have support for auto-generating primary key values.
Therefore, django-spanner monkey-patches ``AutoField`` to generate a
random UUID4. It generates a default using ``Field``'s ``default``
option which means ``AutoField``\ s will have a value when a model
instance is created. For example:
Therefore, ``python-spanner-django`` monkey-patches ``AutoField`` to generate a
random UUID4. It generates a default using ``Field``'s ``default`` option which
means ``AutoField``\ s will have a value when a model instance is created. For
example:

::

Expand All @@ -136,16 +126,18 @@ were created.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Spanner doesn't support ``ON DELETE CASCADE`` when creating foreign-key
constraints so django-spanner `doesn't support foreign key
constraints <https://github.com/googleapis/python-spanner-django/issues/313>`__.
constraints so ``python-spanner-django`` `doesn't support foreign key
constraints
<https://github.com/googleapis/python-spanner-django/issues/313>`__.

Check constraints aren't supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Spanner doesn't support ``CHECK`` constraints so one isn't created for
```PositiveIntegerField`` <https://docs.djangoproject.com/en/stable/ref/models/fields/#positiveintegerfield>`__
and
```CheckConstraint`` <https://docs.djangoproject.com/en/stable/ref/models/constraints/#checkconstraint>`__
`PositiveIntegerField
<https://docs.djangoproject.com/en/stable/ref/models/fields/#positiveintegerfield>`__
and `CheckConstraint
<https://docs.djangoproject.com/en/stable/ref/models/constraints/#checkconstraint>`__
can't be used.

``DecimalField`` isn't supported
Expand Down Expand Up @@ -185,7 +177,7 @@ Spanner has some limitations on schema changes which you must respect:
- Renaming tables and columns isn't supported.
- A column's type can't be changed.
- A table's primary key can't be altered.
- Migrations aren't atomic since django-spanner doesn't support
- Migrations aren't atomic since ``python-spanner-django`` doesn't support
transactions.

``DurationField`` arithmetic doesn't work with ``DateField`` values (`#253 <https://github.com/googleapis/python-spanner-django/issues/253>`__)
Expand Down Expand Up @@ -247,6 +239,3 @@ Internals

.. figure:: ./assets/internals.png
:alt:

🚨🚨THIS CODE IS STILL UNDER DEVELOPMENT🚨🚨
============================================