Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions spanner/postgresql/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Cloud Spanner PostgreSQL-Dialect Samples

Python samples demonstrating PostgreSQL-dialect Spanner queries, DML `RETURNING` clauses, and `last_statement=True` transaction optimizations.

## Setup

1. Create and activate a Python 3.13+ virtual environment:

```sh
python3 -m venv env
source env/bin/activate
```

2. Install dependencies:

```sh
pip install -r requirements.txt
```

## Running Tests

Run unit tests offline:

```sh
pip install -r requirements-test.txt
pytest tests
```
21 changes: 21 additions & 0 deletions spanner/postgresql/noxfile_config.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

TEST_CONFIG_OVERRIDE = {
"ignored_versions": ["2.7", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12"],
"enforce_type_hints": True,
"gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
"pip_version_override": None,
"envs": {},
}
30 changes: 30 additions & 0 deletions spanner/postgresql/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Local samples only. This package isn't published: install it from this
# directory with `pip install -e .`, never by name from PyPI.
[build-system]
requires = ["setuptools>=64"]
build-backend = "setuptools.build_meta"

[project]
name = "spanner-postgresql-samples"
version = "0.0.0"
requires-python = ">=3.13"
dependencies = [
"google-api-core==2.44.0",
"google-cloud-spanner==3.72.0",
]
# PyPI rejects uploads with this classifier.
classifiers = ["Private :: Do Not Upload"]
2 changes: 2 additions & 0 deletions spanner/postgresql/requirements-test.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
-e .
pytest==9.2.0
2 changes: 2 additions & 0 deletions spanner/postgresql/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
google-api-core==2.44.0
google-cloud-spanner==3.72.0
13 changes: 13 additions & 0 deletions spanner/postgresql/src/spanner_postgresql/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# [START spanner_postgresql_dml_last_statement]
import sys

from google.api_core import exceptions
from google.cloud import spanner
from google.cloud import spanner_v1
from google.cloud.spanner_v1 import param_types


def update_postgresql_dml_last_statement(
project_id: str, instance_id: str, database_id: str
) -> None:
"""Executes the final PostgreSQL DML statement with last_statement=True.

Setting last_statement=True commits the transaction inline with the final
DML request, avoiding a separate Commit RPC round trip.

Args:
project_id: The Google Cloud project ID.
instance_id: The Spanner instance ID.
database_id: The PostgreSQL-dialect Spanner database ID.
"""
client = spanner.Client(project=project_id)
database = client.instance(instance_id).database(database_id)
updated_count = 0

def update_singers(transaction: spanner_v1.Transaction) -> None:
nonlocal updated_count
row_count = transaction.execute_update(
"UPDATE Singers SET LastName = $1 WHERE SingerId = $2",
params={"p1": "Doe", "p2": 54214},
param_types={"p1": param_types.STRING, "p2": param_types.INT64},
last_statement=True,
)
updated_count = int(row_count)

try:
database.run_in_transaction(update_singers)
except exceptions.NotFound as err:
print(
f"error: PostgreSQL database '{database_id}' on instance "
f"'{instance_id}' was not found: {err.message}",
file=sys.stderr,
)
except exceptions.GoogleAPICallError as err:
print(
f"error: PostgreSQL DML last_statement update failed on database "
f"'{database_id}' in instance '{instance_id}': {err.message}",
file=sys.stderr,
)
else:
print(f"Resource ID: {database_id}")
print(f"Updated Rows: {updated_count}")


# [END spanner_postgresql_dml_last_statement]


if __name__ == "__main__":
import argparse
import os

parser = argparse.ArgumentParser(
description="Execute a PostgreSQL-dialect DML update with last_statement=True."
)
parser.add_argument(
"--project-id",
default=os.environ.get("GOOGLE_CLOUD_PROJECT", "example-project-id"),
help="Google Cloud project ID (default: $GOOGLE_CLOUD_PROJECT)",
)
parser.add_argument(
"--instance-id",
default=os.environ.get("SPANNER_INSTANCE_ID", "example-instance"),
help="Spanner instance ID (default: $SPANNER_INSTANCE_ID)",
)
parser.add_argument(
"--database-id",
default=os.environ.get("SPANNER_DATABASE_ID", "example-pg-db"),
help="PostgreSQL-dialect Spanner database ID (default: $SPANNER_DATABASE_ID)",
)
args = parser.parse_args()

update_postgresql_dml_last_statement(
project_id=args.project_id,
instance_id=args.instance_id,
database_id=args.database_id,
)
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# [START spanner_postgresql_drop_sequence]
import sys

from google.api_core import exceptions
from google.cloud import spanner_admin_database_v1


def drop_postgresql_sequence(
project_id: str, instance_id: str, database_id: str
) -> None:
"""Detaches a column DEFAULT and drops a PostgreSQL sequence via DDL.

Args:
project_id: The Google Cloud project ID.
instance_id: The Spanner instance ID.
database_id: The PostgreSQL-dialect Spanner database ID with Seq.
"""
client = spanner_admin_database_v1.DatabaseAdminClient()
database_path = client.database_path(project_id, instance_id, database_id)
sequence_name = "Seq"
request = spanner_admin_database_v1.UpdateDatabaseDdlRequest(
database=database_path,
statements=[
"ALTER TABLE Customers ALTER COLUMN CustomerId DROP DEFAULT",
f"DROP SEQUENCE {sequence_name}",
],
)

try:
operation = client.update_database_ddl(request=request)
print(
f"Waiting for PostgreSQL sequence '{sequence_name}' drop on "
f"'{database_id}'..."
)
operation.result(timeout=300)
except exceptions.FailedPrecondition as err:
print(
f"error: sequence '{sequence_name}' is still referenced or missing "
f"on database '{database_id}' in instance '{instance_id}': {err.message}",
file=sys.stderr,
)
except TimeoutError as err:
print(
f"error: timed out waiting to drop PostgreSQL sequence "
f"'{sequence_name}' on database '{database_id}' in instance "
f"'{instance_id}'; the operation may still be running: {err}",
file=sys.stderr,
)
except exceptions.GoogleAPICallError as err:
print(
f"error: failed to drop PostgreSQL sequence '{sequence_name}' on "
f"database '{database_id}' in instance '{instance_id}': {err.message}",
file=sys.stderr,
)
else:
print(f"Resource ID: {database_id}")
print(f"Dropped Sequence: {sequence_name}")


# [END spanner_postgresql_drop_sequence]


if __name__ == "__main__":
import argparse
import os

parser = argparse.ArgumentParser(
description="Detach column default and drop a PostgreSQL sequence."
)
parser.add_argument(
"--project-id",
default=os.environ.get("GOOGLE_CLOUD_PROJECT", "example-project-id"),
help="Google Cloud project ID (default: $GOOGLE_CLOUD_PROJECT)",
)
parser.add_argument(
"--instance-id",
default=os.environ.get("SPANNER_INSTANCE_ID", "example-instance"),
help="Spanner instance ID (default: $SPANNER_INSTANCE_ID)",
)
parser.add_argument(
"--database-id",
default=os.environ.get("SPANNER_PG_DATABASE_ID", "example-db"),
help="Spanner database ID",
)
args = parser.parse_args()

drop_postgresql_sequence(
project_id=args.project_id,
instance_id=args.instance_id,
database_id=args.database_id,
)
13 changes: 13 additions & 0 deletions spanner/postgresql/tests/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
38 changes: 38 additions & 0 deletions spanner/postgresql/tests/conftest.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Shared live-test configuration for Cloud Spanner PostgreSQL-Dialect Samples."""

import os

import pytest

LIVE_PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT", "")
LIVE_INSTANCE_ID = os.environ.get("SPANNER_INSTANCE_ID", "")
LIVE_DATABASE_ID = os.environ.get(
"SPANNER_PG_DATABASE_ID", os.environ.get("SPANNER_DATABASE_ID", "")
)

if os.environ.get("RUN_INTEGRATION_TESTS") == "true" and (
not LIVE_PROJECT_ID or not LIVE_INSTANCE_ID or not LIVE_DATABASE_ID
):
raise RuntimeError(
"Set GOOGLE_CLOUD_PROJECT, SPANNER_INSTANCE_ID, and "
"SPANNER_PG_DATABASE_ID when RUN_INTEGRATION_TESTS=true."
)

live_only = pytest.mark.skipif(
os.environ.get("RUN_INTEGRATION_TESTS") != "true",
reason="Set RUN_INTEGRATION_TESTS=true to run integration tests.",
)
Loading