Skip to content
Permalink
Browse files
docs: update documentation for database-usage (#96)
The PR fixes the following:
- links to other documentation
- confusing wording
- incorrect references to instance instead of database
- incorrect grammar
  • Loading branch information
larkee committed Jun 5, 2020
1 parent 16a812f commit 44e398c3aa9c1af661fecf2beed481484dd05713
Showing with 40 additions and 37 deletions.
  1. +40 −37 docs/database-usage.rst
@@ -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
@@ -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
@@ -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.

@@ -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.

@@ -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
@@ -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()
@@ -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.

@@ -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
@@ -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
@@ -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

0 comments on commit 44e398c

Please sign in to comment.