feat: support fine-grained permissions database roles in connect

README.rst

@@ -252,6 +252,13 @@ Connection API represents a wrap-around for Python Spanner API, written in accor
    result = cursor.fetchall()
 
 
+If using [fine-grained access controls](https://cloud.google.com/spanner/docs/access-with-fgac) you can pass a ``database_role`` argument to connect as that role:
+
+.. code:: python
+
+   connection = connect("instance-id", "database-id", database_role='your-role')
+
+
 Aborted Transactions Retry Mechanism
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

google/cloud/spanner_dbapi/connection.py

@@ -720,6 +720,7 @@ def connect(
     user_agent=None,
     client=None,
     route_to_leader_enabled=True,
+    database_role=None,
     **kwargs,
 ):
     """Creates a connection to a Google Cloud Spanner database.
@@ -763,6 +764,10 @@ def connect(
         disable leader aware routing. Disabling leader aware routing would
         route all requests in RW/PDML transactions to the closest region.
 
+    :type database_role: str
+    :param database_role: (Optional) The database role to connect as when using
+        fine-grained access controls.
+
     **kwargs: Initial value for connection variables.
 
 
@@ -797,7 +802,9 @@ def connect(
     instance = client.instance(instance_id)
     database = None
     if database_id:
-        database = instance.database(database_id, pool=pool)
+        database = instance.database(
+            database_id, pool=pool, database_role=database_role
+        )
     conn = Connection(instance, database)
     if pool is not None:
         conn._own_pool = False

tests/unit/spanner_dbapi/test_connect.py

@@ -59,7 +59,9 @@ def test_w_implicit(self, mock_client):
         )
 
         self.assertIs(connection.database, database)
-        instance.database.assert_called_once_with(DATABASE, pool=None)
+        instance.database.assert_called_once_with(
+            DATABASE, pool=None, database_role=None
+        )
         # Datbase constructs its own pool
         self.assertIsNotNone(connection.database._pool)
         self.assertTrue(connection.instance._client.route_to_leader_enabled)
@@ -75,13 +77,15 @@ def test_w_explicit(self, mock_client):
         client = mock_client.return_value
         instance = client.instance.return_value
         database = instance.database.return_value
+        role = "some_role"
 
         connection = connect(
             INSTANCE,
             DATABASE,
             PROJECT,
             credentials,
             pool=pool,
+            database_role=role,
             user_agent=USER_AGENT,
             route_to_leader_enabled=False,
         )
@@ -102,7 +106,9 @@ def test_w_explicit(self, mock_client):
         client.instance.assert_called_once_with(INSTANCE)
 
         self.assertIs(connection.database, database)
-        instance.database.assert_called_once_with(DATABASE, pool=pool)
+        instance.database.assert_called_once_with(
+            DATABASE, pool=pool, database_role=role
+        )
 
     def test_w_credential_file_path(self, mock_client):
         from google.cloud.spanner_dbapi import connect

tests/unit/spanner_dbapi/test_connection.py

@@ -815,6 +815,13 @@ def test_custom_client_connection(self):
         connection = connect("test-instance", "test-database", client=client)
         self.assertTrue(connection.instance._client == client)
 
+    def test_custom_database_role(self):
+        from google.cloud.spanner_dbapi import connect
+
+        role = "some_role"
+        connection = connect("test-instance", "test-database", database_role=role)
+        self.assertEqual(connection.database.database_role, role)
+
     def test_invalid_custom_client_connection(self):
         from google.cloud.spanner_dbapi import connect
 
@@ -858,8 +865,9 @@ def database(
         database_id="database_id",
         pool=None,
         database_dialect=DatabaseDialect.GOOGLE_STANDARD_SQL,
+        database_role=None,
     ):
-        return _Database(database_id, pool, database_dialect)
+        return _Database(database_id, pool, database_dialect, database_role)
 
 
 class _Database(object):
@@ -868,7 +876,9 @@ def __init__(
         database_id="database_id",
         pool=None,
         database_dialect=DatabaseDialect.GOOGLE_STANDARD_SQL,
+        database_role=None,
     ):
         self.name = database_id
         self.pool = pool
         self.database_dialect = database_dialect
+        self.database_role = database_role