Export COMMIT_TIMESTAMP constant. (googleapis#5102)

tseaver · web-flow · commit 7862cd8409cf · 2018-03-23T16:43:10.000-04:00
Magic string value for timestamp columns to be populated on the
backend with the commit timestamp of the corresponding insert / update
operation.

Add a system test which shows using it with a table whose
'commit_ts' column supports it.
diff --git a/spanner/google/cloud/spanner.py b/spanner/google/cloud/spanner.py
@@ -20,6 +20,7 @@
 from google.cloud.spanner_v1 import AbstractSessionPool
 from google.cloud.spanner_v1 import BurstyPool
 from google.cloud.spanner_v1 import Client
+from google.cloud.spanner_v1 import COMMIT_TIMESTAMP
 from google.cloud.spanner_v1 import enums
 from google.cloud.spanner_v1 import FixedSizePool
 from google.cloud.spanner_v1 import KeyRange
@@ -33,6 +34,7 @@
     'AbstractSessionPool',
     'BurstyPool',
     'Client',
+    'COMMIT_TIMESTAMP',
     'enums',
     'FixedSizePool',
     'KeyRange',
diff --git a/spanner/google/cloud/spanner_v1/__init__.py b/spanner/google/cloud/spanner_v1/__init__.py
@@ -28,6 +28,14 @@
 from google.cloud.spanner_v1.pool import FixedSizePool
 
 
+COMMIT_TIMESTAMP = 'spanner.commit_timestamp()'
+"""Placeholder be used to store commit timestamp of a transaction in a column.
+
+This value can only be used for timestamp columns that have set the option 
+``(allow_commit_timestamp=true)`` in the schema.
+"""
+
+
 __all__ = (
     # google.cloud.spanner_v1
     '__version__',
@@ -48,4 +56,7 @@
 
     # google.cloud.spanner_v1.gapic
     'enums',
+
+    # local
+    'COMMIT_TIMESTAMP',
 )
diff --git a/spanner/tests/_fixtures.py b/spanner/tests/_fixtures.py
@@ -48,6 +48,14 @@
     tags ARRAY<STRING(16)> )
     PRIMARY KEY (id);
 CREATE INDEX name ON contacts(first_name, last_name);
+CREATE TABLE users_history (
+     id INT64 NOT NULL,
+     commit_ts TIMESTAMP NOT NULL OPTIONS
+        (allow_commit_timestamp=true),
+     name STRING(MAX) NOT NULL,
+     email STRING(MAX),
+     deleted BOOL NOT NULL )
+     PRIMARY KEY(id, commit_ts DESC);
 """
 
 DDL_STATEMENTS = [stmt.strip() for stmt in DDL.split(';') if stmt.strip()]
diff --git a/spanner/tests/system/test_system.py b/spanner/tests/system/test_system.py
@@ -38,6 +38,7 @@
 from google.cloud.spanner import KeyRange
 from google.cloud.spanner import KeySet
 from google.cloud.spanner import BurstyPool
+from google.cloud.spanner import COMMIT_TIMESTAMP
 
 from test_utils.retry import RetryErrors
 from test_utils.retry import RetryInstanceState
@@ -512,6 +513,34 @@ def test_batch_insert_or_update_then_query(self):
             rows = list(snapshot.execute_sql(self.SQL))
         self._check_rows_data(rows)
 
+    def test_batch_insert_w_commit_timestamp(self):
+        retry = RetryInstanceState(_has_all_ddl)
+        retry(self._db.reload)()
+
+        table = 'users_history'
+        columns = ['id', 'commit_ts', 'name', 'email', 'deleted']
+        user_id = 1234
+        name = 'phred'
+        email = 'phred@example.com'
+        row_data = [
+            [user_id, COMMIT_TIMESTAMP, name, email, False],
+        ]
+
+        with self._db.batch() as batch:
+            batch.delete(table, self.ALL)
+            batch.insert(table, columns, row_data)
+
+        with self._db.snapshot(read_timestamp=batch.committed) as snapshot:
+            rows = list(snapshot.read(table, columns, self.ALL))
+
+        self.assertEqual(len(rows), 1)
+        r_id, commit_ts, r_name, r_email, deleted = rows[0]
+        self.assertEqual(r_id, user_id)
+        self.assertEqual(commit_ts, batch.committed)
+        self.assertEqual(r_name, name)
+        self.assertEqual(r_email, email)
+        self.assertFalse(deleted)
+
     @RetryErrors(exception=exceptions.ServerError)
     def test_transaction_read_and_insert_then_rollback(self):
         retry = RetryInstanceState(_has_all_ddl)
