From 9eb95b93775cc7a5d111a0f60b7ebf16c95e0973 Mon Sep 17 00:00:00 2001
From: Luke Sneeringer <luke@sneeringer.com>
Date: Fri, 11 Aug 2017 09:51:04 -0700
Subject: [PATCH] Make the Spanner README better. (#3791)

---
 spanner/README.rst | 129 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/spanner/README.rst b/spanner/README.rst
index 1580c27a71a0f..109b9289923ab 100644
--- a/spanner/README.rst
+++ b/spanner/README.rst
@@ -12,3 +12,132 @@ Quick Start
 .. code-block:: console
 
     $ pip install --upgrade google-cloud-spanner
+
+
+Authentication
+--------------
+
+With ``google-cloud-python`` we try to make authentication as painless as
+possible. Check out the `Authentication section`_ in our documentation to
+learn more. You may also find the `authentication document`_ shared by all
+the ``google-cloud-*`` libraries to be helpful.
+
+.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
+.. _authentication document: https://github.com/GoogleCloudPlatform/gcloud-common/tree/master/authentication
+
+
+Using the API
+-------------
+
+Cloud Spanner is the world’s first fully managed relational database service
+to offer both strong consistency and horizontal scalability for
+mission-critical online transaction processing (OLTP) applications. With Cloud
+Spanner you enjoy all the traditional benefits of a relational database; but
+unlike any other relational database service, Cloud Spanner scales
+horizontally to hundreds or thousands of servers to handle the biggest
+transactional workloads. (`About Cloud Spanner`_)
+
+.. _About Cloud Spanner: https://cloud.google.com/spanner/
+
+
+Executing Arbitrary SQL in a Transaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generally, to work with Cloud Spanner, you will want a transaction. The
+preferred mechanism for this is to create a single function, which executes
+as a callback to ``database.run_in_transaction``:
+
+.. code:: python
+
+    # First, define the function that represents a single "unit of work"
+    # that should be run within the transaction.
+    def update_anniversary(transaction, person_id, unix_timestamp):
+        # The query itself is just a string.
+        #
+        # The use of @parameters is recommended rather than doing your
+        # own string interpolation; this provides protections against
+        # SQL injection attacks.
+        query = """UPDATE people
+            SET anniversary = @uxts
+            WHERE id = @person_id"""
+
+        # When executing the SQL statement, the query and parameters are sent
+        # as separate arguments. When using parameters, you must specify
+        # both the parameters themselves and their types.
+        transaction.execute_sql(
+            query=query,
+            params={'person_id': person_id, 'uxts': unix_timestamp},
+            param_types={
+                'person_id': types.INT64_PARAM_TYPE,
+                'uxts': types.INT64_PARAM_TYPE,
+            },
+        )
+
+    # Actually run the `update_anniversary` function in a transaction.
+    database.run_in_transaction(update_anniversary,
+        person_id=42,
+        unix_timestamp=1335020400,
+    )
+
+
+Select records using a Transaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have a transaction object (such as the first argument sent to
+``run_in_transaction``), reading data is easy:
+
+.. code:: python
+
+    # Define a SELECT query.
+    query = """SELECT e.first_name, e.last_name, p.telephone
+        FROM employees as e, phones as p
+        WHERE p.employee_id == e.employee_id"""
+
+    # Execute the query and return results.
+    result = transaction.execute_sql(query)
+    for row in result.rows:
+        print(row)
+
+
+Insert records using a Transaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add one or more records to a table, use ``insert``:
+
+.. code:: python
+
+    transaction.insert(
+        'citizens',
+        columns=['email', 'first_name', 'last_name', 'age'],
+        values=[
+            ['phred@exammple.com', 'Phred', 'Phlyntstone', 32],
+            ['bharney@example.com', 'Bharney', 'Rhubble', 31],
+        ],
+    )
+
+
+Update records using a Transaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Transaction.update`` updates one or more existing records in a table.  Fails
+if any of the records does not already exist.
+
+.. code:: python
+
+    transaction.update(
+        'citizens',
+        columns=['email', 'age'],
+        values=[
+            ['phred@exammple.com', 33],
+            ['bharney@example.com', 32],
+        ],
+    )
+
+
+Learn More
+----------
+
+See the ``google-cloud-python`` API `Cloud Spanner documentation`_ to learn how
+to connect to Cloud Spanner using this Client Library.
+
+.. _Cloud Spanner documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/usage.html