Skip to content

Commit a6ed382

Browse files
olavloiteolavloite
authored
docs: add samples for Spanner-specific features (#492)
* docs: add samples for Spanner-specific features * docs: more samples * docs: add more samples * test: add tests for samples * chore: fix linting error * docs: document samples * docs: link to README
1 parent 93579c8 commit a6ed382

14 files changed

+915
-0
lines changed

‎.github/workflows/test_suite.yml

+16
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,22 @@ jobs:
5353
- name: Run mockserver tests
5454
run: nox -s mockserver
5555

56+
samples:
57+
runs-on: ubuntu-latest
58+
59+
steps:
60+
- name: Checkout code
61+
uses: actions/checkout@v4
62+
- name: Setup Python
63+
uses: actions/setup-python@v5
64+
with:
65+
python-version: 3.12
66+
- name: Install nox
67+
run: python -m pip install nox
68+
- name: Run samples
69+
run: nox -s _all_samples
70+
working-directory: samples
71+
5672
compliance_tests_13:
5773
runs-on: ubuntu-latest
5874

‎README.rst

+7
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,13 @@ Next install the package from the package ``setup.py`` file:
5858

5959
During setup the dialect will be registered with entry points.
6060

61+
Samples
62+
-------------
63+
64+
The `samples directory <https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/README.md>`__
65+
contains multiple examples for how to configure and use common Spanner features.
66+
67+
6168
A Minimal App
6269
-------------
6370

‎samples/README.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Spanner SQLAlchemy Samples
2+
3+
This folder contains samples for how to use common Spanner features with SQLAlchemy. The samples use
4+
a shared [data model](model.py) and can be executed as a standalone application. The samples
5+
automatically start the [Spanner Emulator](https://cloud.google.com/spanner/docs/emulator) in a
6+
Docker container when they are executed. You must therefore have Docker installed on your system to
7+
run a sample.
8+
9+
You can run a sample with `nox`:
10+
11+
```shell
12+
nox -s hello_world
13+
```
14+
15+
Change `hello_world` to run any of the other sample names. The runnable samples all end with
16+
`_sample.py`. Omit the `_sample.py` part of the file name to run the sample.
17+
18+
19+
20+
| Sample name | Description |
21+
|-----------------------|-----------------------------------------------------------------------------|
22+
| bit_reversed_sequence | Use a bit-reversed sequence for primary key generation. |
23+
| date_and_timestamp | Map Spanner DATE and TIMESTAMP columns to SQLAlchemy. |
24+
| default_column_value | Create and use a Spanner DEFAULT column constraint in SQLAlchemy. |
25+
| generated_column | Create and use a Spanner generated column in SQLAlchemy. |
26+
| hello_world | Shows how to connect to Spanner with SQLAlchemy and execute a simple query. |
27+
| insert_data | Insert multiple rows to Spanner with SQLAlchemy. |
28+
| interleaved_table | Create and use an interleaved table (INTERLEAVE IN PARENT) with SQLAlchemy. |
29+
| transaction | Execute a read/write transaction on Spanner with SQLAlchemy. |
30+

‎samples/bit_reversed_sequence_sample.py

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Copyright 2024 Google LLC All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import datetime
16+
import uuid
17+
18+
from sqlalchemy import create_engine
19+
from sqlalchemy.orm import Session
20+
21+
from sample_helper import run_sample
22+
from model import Singer, Concert, Venue, TicketSale
23+
24+
25+
# Shows how to use a bit-reversed sequence for primary key generation.
26+
#
27+
# The TicketSale model uses a bit-reversed sequence for automatic primary key
28+
# generation:
29+
#
30+
# id: Mapped[int] = mapped_column(
31+
# BigInteger,
32+
# Sequence("ticket_sale_id"),
33+
# server_default=TextClause("GET_NEXT_SEQUENCE_VALUE(SEQUENCE ticket_sale_id)"),
34+
# primary_key=True,
35+
# )
36+
#
37+
# This leads to the following table definition:
38+
#
39+
# CREATE TABLE ticket_sales (
40+
# id INT64 NOT NULL DEFAULT (GET_NEXT_SEQUENCE_VALUE(SEQUENCE ticket_sale_id)),
41+
# ...
42+
# ) PRIMARY KEY (id)
43+
def bit_reversed_sequence_sample():
44+
engine = create_engine(
45+
"spanner:///projects/sample-project/"
46+
"instances/sample-instance/"
47+
"databases/sample-database",
48+
echo=True,
49+
)
50+
with Session(engine) as session:
51+
singer = Singer(id=str(uuid.uuid4()), first_name="John", last_name="Doe")
52+
venue = Venue(code="CH", name="Concert Hall", active=True)
53+
concert = Concert(
54+
venue=venue,
55+
start_time=datetime.datetime(2024, 11, 7, 19, 30, 0),
56+
singer=singer,
57+
title="John Doe - Live in Concert Hall",
58+
)
59+
# TicketSale automatically generates a primary key value using a
60+
# bit-reversed sequence. We therefore do not need to specify a primary
61+
# key value when we create an instance of TicketSale.
62+
ticket_sale = TicketSale(
63+
concert=concert, customer_name="Alice Doe", seats=["A010", "A011", "A012"]
64+
)
65+
session.add_all([singer, venue, concert, ticket_sale])
66+
session.commit()
67+
68+
69+
if __name__ == "__main__":
70+
run_sample(bit_reversed_sequence_sample)

‎samples/date_and_timestamp_sample.py

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Copyright 2024 Google LLC All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import datetime
16+
import uuid
17+
18+
from sqlalchemy import create_engine
19+
from sqlalchemy.orm import Session
20+
21+
from sample_helper import run_sample
22+
from model import Singer, Concert, Venue
23+
24+
25+
# Shows how to map and use the DATE and TIMESTAMP data types in Spanner.
26+
def date_and_timestamp_sample():
27+
engine = create_engine(
28+
"spanner:///projects/sample-project/"
29+
"instances/sample-instance/"
30+
"databases/sample-database",
31+
echo=True,
32+
)
33+
with Session(engine) as session:
34+
# Singer has a property birthdate, which is mapped to a DATE column.
35+
# Use the datetime.date type for this.
36+
singer = Singer(
37+
id=str(uuid.uuid4()),
38+
first_name="John",
39+
last_name="Doe",
40+
birthdate=datetime.date(1979, 10, 14),
41+
)
42+
venue = Venue(code="CH", name="Concert Hall", active=True)
43+
# Concert has a property `start_time`, which is mapped to a TIMESTAMP
44+
# column. Use the datetime.datetime type for this.
45+
concert = Concert(
46+
venue=venue,
47+
start_time=datetime.datetime(2024, 11, 7, 19, 30, 0),
48+
singer=singer,
49+
title="John Doe - Live in Concert Hall",
50+
)
51+
session.add_all([singer, venue, concert])
52+
session.commit()
53+
54+
# Use AUTOCOMMIT for sessions that only read. This is more
55+
# efficient than using a read/write transaction to only read.
56+
session.connection(execution_options={"isolation_level": "AUTOCOMMIT"})
57+
print(
58+
f"{singer.full_name}, born on {singer.birthdate}, has planned "
59+
f"a concert that starts on {concert.start_time} in {venue.name}."
60+
)
61+
62+
63+
if __name__ == "__main__":
64+
run_sample(date_and_timestamp_sample)

‎samples/default_column_value_sample.py

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Copyright 2024 Google LLC All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import datetime
16+
import uuid
17+
18+
from sqlalchemy import create_engine
19+
from sqlalchemy.orm import Session
20+
21+
from sample_helper import run_sample
22+
from model import Singer, Album, Track
23+
24+
25+
# Shows how to use a default column with SQLAlchemy and Spanner.
26+
def default_column_value_sample():
27+
engine = create_engine(
28+
"spanner:///projects/sample-project/"
29+
"instances/sample-instance/"
30+
"databases/sample-database",
31+
echo=True,
32+
)
33+
with Session(engine) as session:
34+
# The Track model has a `recorded_at` property that is set to
35+
# CURRENT_TIMESTAMP if no other value is supplied.
36+
singer = Singer(id=str(uuid.uuid4()), first_name="John", last_name="Doe")
37+
album = Album(id=str(uuid.uuid4()), title="My album", singer=singer)
38+
39+
# This track will use the default CURRENT_TIMESTAMP for the recorded_at
40+
# property.
41+
track1 = Track(
42+
id=str(uuid.uuid4()),
43+
track_number=1,
44+
title="My track 1",
45+
album=album,
46+
)
47+
track2 = Track(
48+
id=str(uuid.uuid4()),
49+
track_number=2,
50+
title="My track 2",
51+
recorded_at=datetime.datetime(2024, 11, 7, 10, 0, 0),
52+
album=album,
53+
)
54+
session.add_all([singer, album, track1, track2])
55+
session.commit()
56+
print(f"Track 1 was recorded at: " f"{track1.recorded_at}")
57+
print(f"Track 2 was recorded at: " f"{track2.recorded_at}")
58+
59+
60+
if __name__ == "__main__":
61+
run_sample(default_column_value_sample)

‎samples/generated_column_sample.py

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Copyright 2024 Google LLC All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import uuid
16+
17+
from sqlalchemy import create_engine
18+
from sqlalchemy.orm import Session
19+
20+
from sample_helper import run_sample
21+
from model import Singer
22+
23+
24+
# Shows how to use a generated column with SQLAlchemy and Spanner.
25+
def generated_column_sample():
26+
engine = create_engine(
27+
"spanner:///projects/sample-project/"
28+
"instances/sample-instance/"
29+
"databases/sample-database",
30+
echo=True,
31+
)
32+
with Session(engine) as session:
33+
# The Singer model has a `full_name` property that is generated by the
34+
# database.
35+
singer = Singer(id=str(uuid.uuid4()), first_name="John", last_name="Doe")
36+
session.add(singer)
37+
session.commit()
38+
print(
39+
f"The database generated a full name for the singer: " f"{singer.full_name}"
40+
)
41+
42+
# Updating the first name or last name of the singer will also update
43+
# the generated full name property.
44+
singer.last_name = "Jones"
45+
session.commit()
46+
print(f"Updated full name for singer: " f"{singer.full_name}")
47+
48+
49+
if __name__ == "__main__":
50+
run_sample(generated_column_sample)

‎samples/hello_world_sample.py

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Copyright 2024 Google LLC All rights reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from sqlalchemy import create_engine, select, text
16+
from sample_helper import run_sample
17+
18+
19+
def quickstart():
20+
engine = create_engine(
21+
"spanner:///projects/sample-project/"
22+
"instances/sample-instance/"
23+
"databases/sample-database"
24+
)
25+
with engine.connect().execution_options(isolation_level="AUTOCOMMIT") as connection:
26+
results = connection.execute(select(text("'Hello World!'"))).fetchall()
27+
print("\nMessage from Spanner: ", results[0][0], "\n")
28+
29+
30+
if __name__ == "__main__":
31+
run_sample(quickstart)

0 commit comments

Comments
 (0)