Skip to content
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

Jump to bottom

docs: update documentation for database-usage #96

Merged
merged 2 commits into from Jun 5, 2020
Merged

docs: update documentation for database-usage #96

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
932bab5
docs: update documentation for database-usage
larkee Jun 4, 2020
3f049e0
Merge branch 'master' into update-database-usage
larkee Jun 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
77 changes: 40 additions & 37 deletions docs/database-usage.rst
View file
Open in desktop
@@ -1,38 +1,39 @@
Database Admin
==============

After creating a :class:`~google.cloud.spanner.instance.Instance`, you can
After creating an :class:`~google.cloud.spanner_v1.instance.Instance`, you can
interact with individual databases for that instance.


List Databases
--------------

To iterate over all existing databases for an instance, use its
:meth:`~google.cloud.spanner.instance.Instance.list_databases` method:
:meth:`~google.cloud.spanner_v1.instance.Instance.list_databases` method:

.. code:: python

for database in instance.list_databases():
# `database` is a `Database` object.

This method yields :class:`~.spanner_admin_database_v1.types.Database`
This method yields :class:`~google.cloud.spanner_v1.database.Database`
objects.


Database Factory
----------------

To create a :class:`~google.cloud.spanner.database.Database` object:
To create a :class:`~google.cloud.spanner_v1.database.Database` object:

.. code:: python

database = instance.database(database_id, ddl_statements)

- ``ddl_statements`` is a list of strings containing DDL for the new database.
- ``ddl_statements`` is a list of strings containing DDL statements for the new database.

You can also use :meth:`Instance.database` to create a local wrapper for
a database that has already been created:
You can also use the :meth:`~google.cloud.spanner_v1.instance.Instance.database` method
on an :class:`~google.cloud.spanner_v1.instance.Instance` object to create a local wrapper
for a database that has already been created:

.. code:: python

Expand All @@ -43,7 +44,7 @@ Create a new Database
---------------------

After creating the database object, use its
:meth:`~google.cloud.spanner.database.Database.create` method to
:meth:`~google.cloud.spanner_v1.database.Database.create` method to
trigger its creation on the server:

.. code:: python
Expand All @@ -52,8 +53,8 @@ trigger its creation on the server:

.. note::

Creating an instance triggers a "long-running operation" and
returns an :class:`~concurrent.futures.Future`-like object. Use
Creating a database triggers a "long-running operation" and
returns a :class:`~concurrent.futures.Future`-like object. Use
the :meth:`~concurrent.futures.Future.result` method to wait for
and inspect the result.

Expand All @@ -62,21 +63,21 @@ Update an existing Database
---------------------------

After creating the database object, you can apply additional DDL statements
via its :meth:`~google.cloud.spanner.database.Database.update_ddl` method:
via its :meth:`~google.cloud.spanner_v1.database.Database.update_ddl` method:

.. code:: python

operation = database.update_ddl(ddl_statements, operation_id)

- ``ddl_statements`` is a list of strings containing DDL to be applied to
the database.
- ``ddl_statements`` is a list of strings containing DDL statements to be
applied to the database.

- ``operation_id`` is a string ID for the long-running operation.

.. note::

Update an instance triggers a "long-running operation" and
returns a :class:`google.cloud.spanner.database.Operation`
Updating a database triggers a "long-running operation" and
returns an :class:`~google.cloud.spanner_v1.database.Operation`
object. See :ref:`check-on-current-database-operation` for polling
to find out if the operation is completed.

Expand All @@ -85,7 +86,7 @@ Drop a Database
---------------

Drop a database using its
:meth:`~google.cloud.spanner.database.Database.drop` method:
:meth:`~google.cloud.spanner_v1.database.Database.drop` method:

.. code:: python

Expand All @@ -97,14 +98,15 @@ Drop a database using its
Check on Current Database Operation
-----------------------------------

The :meth:`~google.cloud.spanner.database.Database.create` and
:meth:`~google.cloud.spanner.database.Database.update` methods of instance
object trigger long-running operations on the server, and return instances
The :meth:`~google.cloud.spanner_v1.database.Database.create` and
:meth:`~google.cloud.spanner_v1.database.Database.update_ddl` methods of the
:class:`~google.cloud.spanner_v1.database.Database` object trigger
long-running operations on the server, and return operations
conforming to the :class:`~.concurrent.futures.Future` class.

.. code:: python

>>> operation = instance.create()
>>> operation = database.create()
>>> operation.result()


Expand All @@ -116,24 +118,25 @@ Use a Snapshot to Read / Query the Database

A snapshot represents a read-only point-in-time view of the database.

Calling :meth:`~google.cloud.spanner.database.Database.snapshot` with
Calling :meth:`~google.cloud.spanner_v1.database.Database.snapshot` with
no arguments creates a snapshot with strong concurrency:

.. code:: python

with database.snapshot() as snapshot:
do_something_with(snapshot)

See :class:`~google.cloud.spanner.snapshot.Snapshot` for the other options
See :class:`~google.cloud.spanner_v1.snapshot.Snapshot` for the other options
which can be passed.

.. note::

:meth:`~google.cloud.spanner.database.Database.snapshot` returns an
:meth:`~google.cloud.spanner_v1.database.Database.snapshot` returns an
object intended to be used as a Python context manager (i.e., as the
target of a ``with`` statement). Use the instance, and any result
sets returned by its ``read`` or ``execute_sql`` methods, only inside
the block created by the ``with`` statement.
target of a ``with`` statement). Perform all iterations within the
context of the ``with database.snapshot()`` block.



See :doc:`snapshot-usage` for more complete examples of snapshot usage.

Expand All @@ -151,7 +154,7 @@ on the rows of tables in the database.

.. note::

:meth:`~google.cloud.spanner.database.Database.batch` returns an
:meth:`~google.cloud.spanner_v1.database.Database.batch` returns an
object intended to be used as a Python context manager (i.e., as the
target of a ``with`` statement). It applies any changes made inside
the block of its ``with`` statement when exiting the block, unless an
Expand Down Expand Up @@ -187,26 +190,26 @@ transaction as a required argument:

.. note::

:meth:`~google.cloud.spanner.database.Database.run_in_transaction`
:meth:`~google.cloud.spanner_v1.database.Database.run_in_transaction`
commits the transaction automatically if the "unit of work" function
returns without raising an exception.

.. note::

:meth:`~google.cloud.spanner.database.Database.run_in_transaction`
retries the "unit of work" function if the read / query operatoins
or the commit are aborted due to concurrent updates
:meth:`~google.cloud.spanner_v1.database.Database.run_in_transaction`
retries the "unit of work" function if the read / query operations
or the commit are aborted due to concurrent updates.

See :doc:`transaction-usage` for more complete examples of transaction usage.

Configuring a session pool for a database
-----------------------------------------

Under the covers, the ``snapshot``, ``batch``, and ``run_in_transaction``
methods use a pool of :class:`~google.cloud.spanner.session.Session` objects
methods use a pool of :class:`~google.cloud.spanner_v1.session.Session` objects
to manage their communication with the back-end. You can configure
one of the pools manually to control the number of sessions, timeouts, etc.,
and then passing it to the :class:`~google.cloud.spanner.database.Database`
and then pass it to the :class:`~google.cloud.spanner_v1.database.Database`
constructor:

.. code-block:: python
Expand All @@ -221,12 +224,12 @@ constructor:
pool = spanner.FixedSizePool(size=10, default_timeout=5)
database = instance.database(DATABASE_NAME, pool=pool)

Note that creating a database with a pool may presume that its database
already exists, as it may need to pre-create sessions (rather than creating
them on demand, as the default implementation does).
Note that creating a database with a pool will require the database to
already exist if the pool implementation needs to pre-create sessions
(rather than creating them on demand, as the default implementation does).

You can supply your own pool implementation, which must satisfy the
contract laid out in :class:`~google.cloud.spanner.pool.AbstractSessionPool`:
contract laid out in :class:`~google.cloud.spanner_v1.pool.AbstractSessionPool`:

.. code-block:: python

Expand Down