Skip to content

Commit 5d7b9de

Browse files
olavloiteolavloite
authored
docs: add sample for MyBatis with GoogleSQL (#2026)
1 parent 3e39f70 commit 5d7b9de

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+2721
-101
lines changed

‎.github/workflows/spring-data-mybatis-sample.yaml

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ jobs:
2525
with:
2626
distribution: temurin
2727
java-version: 17
28-
- name: Run tests
28+
- name: Run GoogleSQL sample tests
2929
run: mvn test
30-
working-directory: samples/spring-data-mybatis
30+
working-directory: samples/spring-data-mybatis/googlesql
31+
- name: Run PostgreSQL sample tests
32+
run: mvn test
33+
working-directory: samples/spring-data-mybatis/postgresql

‎samples/spring-data-mybatis/README.md

Lines changed: 7 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,9 @@
1-
# Spring Data MyBatis Sample Application with Cloud Spanner PostgreSQL
1+
# Spring Data MyBatis
22

3-
This sample application shows how to develop portable applications using Spring Data MyBatis in
4-
combination with Cloud Spanner PostgreSQL. This application can be configured to run on either a
5-
[Cloud Spanner PostgreSQL](https://cloud.google.com/spanner/docs/postgresql-interface) database or
6-
an open-source PostgreSQL database. The only change that is needed to switch between the two is
7-
changing the active Spring profile that is used by the application.
3+
This directory contains two sample applications for using Spring Data MyBatis
4+
with the Spanner JDBC driver.
85

9-
The application uses the Cloud Spanner JDBC driver to connect to Cloud Spanner PostgreSQL, and it
10-
uses the PostgreSQL JDBC driver to connect to open-source PostgreSQL. Spring Data MyBatis works with
11-
both drivers and offers a single consistent API to the application developer, regardless of the
12-
actual database or JDBC driver being used.
13-
14-
This sample shows:
15-
16-
1. How to use Spring Data MyBatis with Cloud Spanner PostgreSQL.
17-
2. How to develop a portable application that runs on both Google Cloud Spanner PostgreSQL and
18-
open-source PostgreSQL with the same code base.
19-
3. How to use bit-reversed sequences to automatically generate primary key values for entities.
20-
4. How to use the Spanner Emulator for development in combination with Spring Data.
21-
22-
__NOTE__: This application does __not require PGAdapter__. Instead, it connects to Cloud Spanner
23-
PostgreSQL using the Cloud Spanner JDBC driver.
24-
25-
## Cloud Spanner PostgreSQL
26-
27-
Cloud Spanner PostgreSQL provides language support by expressing Spanner database functionality
28-
through a subset of open-source PostgreSQL language constructs, with extensions added to support
29-
Spanner functionality like interleaved tables and hinting.
30-
31-
The PostgreSQL interface makes the capabilities of Spanner —__fully managed, unlimited scale, strong
32-
consistency, high performance, and up to 99.999% global availability__— accessible using the
33-
PostgreSQL dialect. Unlike other services that manage actual PostgreSQL database instances, Spanner
34-
uses PostgreSQL-compatible syntax to expose its existing scale-out capabilities. This provides
35-
familiarity for developers and portability for applications, but not 100% PostgreSQL compatibility.
36-
The SQL syntax that Spanner supports is semantically equivalent PostgreSQL, meaning schemas
37-
and queries written against the PostgreSQL interface can be easily ported to another PostgreSQL
38-
environment.
39-
40-
This sample showcases this portability with an application that works on both Cloud Spanner PostgreSQL
41-
and open-source PostgreSQL with the same code base.
42-
43-
## MyBatis Spring
44-
[MyBatis Spring](http://mybatis.org/spring/) integrates MyBatis with the popular Java Spring
45-
framework. This allows MyBatis to participate in Spring transactions and to automatically inject
46-
MyBatis mappers into other beans.
47-
48-
## Sample Application
49-
50-
This sample shows how to create a portable application using Spring Data MyBatis and the Cloud Spanner
51-
PostgreSQL dialect. The application works on both Cloud Spanner PostgreSQL and open-source
52-
PostgreSQL. You can switch between the two by changing the active Spring profile:
53-
* Profile `cs` runs the application on Cloud Spanner PostgreSQL.
54-
* Profile `pg` runs the application on open-source PostgreSQL.
55-
56-
The default profile is `cs`. You can change the default profile by modifying the
57-
[application.properties](src/main/resources/application.properties) file.
58-
59-
### Running the Application
60-
61-
1. Choose the database system that you want to use by choosing a profile. The default profile is
62-
`cs`, which runs the application on Cloud Spanner PostgreSQL.
63-
2. The sample by default starts an instance of the Spanner Emulator together with the application and
64-
runs the application against the emulator.
65-
3. Modify the default profile in the [application.properties](src/main/resources/application.properties)
66-
file to run the sample on an open-source PostgreSQL database.
67-
4. Modify either [application-cs.properties](src/main/resources/application-cs.properties) or
68-
[application-pg.properties](src/main/resources/application-pg.properties) to point to an existing
69-
database. If you use Cloud Spanner, the database that the configuration file references must be a
70-
database that uses the PostgreSQL dialect.
71-
5. Run the application with `mvn spring-boot:run`.
72-
73-
### Main Application Components
74-
75-
The main application components are:
76-
* [DatabaseSeeder.java](src/main/java/com/google/cloud/spanner/sample/DatabaseSeeder.java): This
77-
class is responsible for creating the database schema and inserting some initial test data. The
78-
schema is created from the [create_schema.sql](src/main/resources/create_schema.sql) file. The
79-
`DatabaseSeeder` class loads this file into memory and executes it on the active database using
80-
standard JDBC APIs. The class also removes Cloud Spanner-specific extensions to the PostgreSQL
81-
dialect when the application runs on open-source PostgreSQL.
82-
* [JdbcConfiguration.java](src/main/java/com/google/cloud/spanner/sample/JdbcConfiguration.java):
83-
This utility class is used to determine whether the application is running on Cloud Spanner
84-
PostgreSQL or open-source PostgreSQL. This can be used if you have specific features that should
85-
only be executed on one of the two systems.
86-
* [EmulatorInitializer.java](src/main/java/com/google/cloud/spanner/sample/EmulatorInitializer.java):
87-
This ApplicationListener automatically starts the Spanner emulator as a Docker container if the
88-
sample has been configured to run on the emulator.
89-
* [AbstractEntity.java](src/main/java/com/google/cloud/spanner/sample/entities/AbstractEntity.java):
90-
This is the shared base class for all entities in this sample application. It defines a number of
91-
standard attributes, such as the identifier (primary key). The primary key is automatically
92-
generated using a (bit-reversed) sequence. [Bit-reversed sequential values](https://cloud.google.com/spanner/docs/schema-design#bit_reverse_primary_key)
93-
are considered a good choice for primary keys on Cloud Spanner.
94-
* [Application.java](src/main/java/com/google/cloud/spanner/sample/Application.java): The starter
95-
class of the application. It contains a command-line runner that executes a selection of queries
96-
and updates on the database.
97-
* [SingerService](src/main/java/com/google/cloud/spanner/sample/service/SingerService.java) and
98-
[AlbumService](src/main/java/com/google/cloud/spanner/sample/service/SingerService.java) are
99-
standard Spring service beans that contain business logic that can be executed as transactions.
100-
This includes both read/write and read-only transactions.
6+
- [GoogleSQL](googlesql): This sample uses the Spanner GoogleSQL dialect.
7+
- [PostgreSQL](postgresql): This sample uses the Spanner PostgreSQL dialect and the Spanner JDBC
8+
driver. It does not use PGAdapter. The sample application can also be configured to run on open
9+
source PostgreSQL, and shows how a portable application be developed using this setup.

‎samples/spring-data-mybatis/googlesql/README.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Spring Data MyBatis Sample Application with Spanner GoogleSQL
2+
3+
This sample application shows how to develop applications using Spring Data MyBatis in
4+
combination with Spanner GoogleSQL.
5+
6+
This sample shows:
7+
8+
1. How to use Spring Data MyBatis with a Spanner GoogleSQL database.
9+
2. How to use bit-reversed identity columns to automatically generate primary key values for entities.
10+
3. How to set the transaction isolation level that is used by the Spanner JDBC driver.
11+
4. How to use the Spanner Emulator for development in combination with Spring Data.
12+
13+
## MyBatis Spring
14+
[MyBatis Spring](http://mybatis.org/spring/) integrates MyBatis with the popular Java Spring
15+
framework. This allows MyBatis to participate in Spring transactions and to automatically inject
16+
MyBatis mappers into other beans.
17+
18+
### Running the Application
19+
20+
1. The sample by default starts an instance of the Spanner Emulator together with the application and
21+
runs the application against the emulator.
22+
2. To run the sample on a real Spanner database, modify
23+
[application.properties](src/main/resources/application.properties) and set the
24+
`spanner.emulator` property to `false`. Modify the `spanner.project`, `spanner.instance`, and
25+
`spanner.database` properties to point to an existing Spanner database.
26+
The database must use the GoogleSQL dialect.
27+
3. Run the application with `mvn spring-boot:run`.
28+
29+
### Main Application Components
30+
31+
The main application components are:
32+
* [DatabaseSeeder.java](src/main/java/com/google/cloud/spanner/sample/DatabaseSeeder.java): This
33+
class is responsible for creating the database schema and inserting some initial test data. The
34+
schema is created from the [create_schema.sql](src/main/resources/create_schema.sql) file. The
35+
`DatabaseSeeder` class loads this file into memory and executes it on the active database using
36+
standard JDBC APIs.
37+
* [EmulatorInitializer.java](src/main/java/com/google/cloud/spanner/sample/EmulatorInitializer.java):
38+
This ApplicationListener automatically starts the Spanner emulator as a Docker container if the
39+
sample has been configured to run on the emulator. You can disable this with the `spanner.emulator`
40+
property in `application.properties`.
41+
* [AbstractEntity.java](src/main/java/com/google/cloud/spanner/sample/entities/AbstractEntity.java):
42+
This is the shared base class for all entities in this sample application. It defines a number of
43+
standard attributes, such as the identifier (primary key). The primary key is automatically
44+
generated using a (bit-reversed) identity column. [Bit-reversed sequential values](https://cloud.google.com/spanner/docs/schema-design#bit_reverse_primary_key)
45+
are considered a good choice for primary keys in Spanner.
46+
* [Application.java](src/main/java/com/google/cloud/spanner/sample/Application.java): The starter
47+
class of the application. It contains a command-line runner that executes a selection of queries
48+
and updates on the database.
49+
* [SingerService](src/main/java/com/google/cloud/spanner/sample/service/SingerService.java) and
50+
[AlbumService](src/main/java/com/google/cloud/spanner/sample/service/SingerService.java) are
51+
standard Spring service beans that contain business logic that can be executed as transactions.
52+
This includes both read/write and read-only transactions.

‎samples/spring-data-mybatis/googlesql/pom.xml

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<groupId>org.example</groupId>
8+
<artifactId>cloud-spanner-spring-data-mybatis-googlesql-example</artifactId>
9+
<version>1.0-SNAPSHOT</version>
10+
<description>
11+
Sample application showing how to use Spring Data MyBatis with Spanner GoogleSQL.
12+
</description>
13+
<parent>
14+
<groupId>org.springframework.boot</groupId>
15+
<artifactId>spring-boot-starter-parent</artifactId>
16+
<version>3.4.5</version>
17+
<relativePath/>
18+
</parent>
19+
<properties>
20+
<java.version>17</java.version>
21+
<maven.compiler.source>17</maven.compiler.source>
22+
<maven.compiler.target>17</maven.compiler.target>
23+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
24+
</properties>
25+
26+
<dependencyManagement>
27+
<dependencies>
28+
<dependency>
29+
<groupId>org.springframework.data</groupId>
30+
<artifactId>spring-data-bom</artifactId>
31+
<version>2024.1.5</version>
32+
<scope>import</scope>
33+
<type>pom</type>
34+
</dependency>
35+
<dependency>
36+
<groupId>com.google.cloud</groupId>
37+
<artifactId>libraries-bom</artifactId>
38+
<version>26.59.0</version>
39+
<scope>import</scope>
40+
<type>pom</type>
41+
</dependency>
42+
<dependency>
43+
<groupId>org.testcontainers</groupId>
44+
<artifactId>testcontainers-bom</artifactId>
45+
<version>1.21.0</version>
46+
<scope>import</scope>
47+
<type>pom</type>
48+
</dependency>
49+
</dependencies>
50+
</dependencyManagement>
51+
52+
<dependencies>
53+
<dependency>
54+
<groupId>org.mybatis.spring.boot</groupId>
55+
<artifactId>mybatis-spring-boot-starter</artifactId>
56+
<version>3.0.4</version>
57+
</dependency>
58+
<dependency>
59+
<groupId>org.mybatis.dynamic-sql</groupId>
60+
<artifactId>mybatis-dynamic-sql</artifactId>
61+
<version>1.5.2</version>
62+
</dependency>
63+
64+
<!-- Add the Spanner JDBC driver. -->
65+
<!-- TODO: Remove the explicit versions when we have a new BOM release. -->
66+
<dependency>
67+
<groupId>com.google.cloud</groupId>
68+
<artifactId>google-cloud-spanner</artifactId>
69+
<version>6.91.1</version>
70+
</dependency>
71+
<dependency>
72+
<groupId>com.google.cloud</groupId>
73+
<artifactId>google-cloud-spanner-jdbc</artifactId>
74+
<version>2.29.1</version>
75+
<exclusions>
76+
<exclusion>
77+
<groupId>com.google.api.grpc</groupId>
78+
<artifactId>proto-google-cloud-spanner-executor-v1</artifactId>
79+
</exclusion>
80+
</exclusions>
81+
</dependency>
82+
<dependency>
83+
<groupId>org.testcontainers</groupId>
84+
<artifactId>testcontainers</artifactId>
85+
</dependency>
86+
87+
<dependency>
88+
<groupId>com.google.collections</groupId>
89+
<artifactId>google-collections</artifactId>
90+
<version>1.0</version>
91+
</dependency>
92+
93+
<!-- Test dependencies -->
94+
<dependency>
95+
<groupId>com.google.cloud</groupId>
96+
<artifactId>google-cloud-spanner</artifactId>
97+
<version>6.91.1</version>
98+
<type>test-jar</type>
99+
<scope>test</scope>
100+
</dependency>
101+
<dependency>
102+
<groupId>com.google.api</groupId>
103+
<artifactId>gax-grpc</artifactId>
104+
<classifier>testlib</classifier>
105+
<scope>test</scope>
106+
</dependency>
107+
<dependency>
108+
<groupId>junit</groupId>
109+
<artifactId>junit</artifactId>
110+
<version>4.13.2</version>
111+
</dependency>
112+
</dependencies>
113+
114+
<build>
115+
<plugins>
116+
<plugin>
117+
<groupId>com.spotify.fmt</groupId>
118+
<artifactId>fmt-maven-plugin</artifactId>
119+
<version>2.25</version>
120+
<executions>
121+
<execution>
122+
<goals>
123+
<goal>format</goal>
124+
</goals>
125+
</execution>
126+
</executions>
127+
</plugin>
128+
</plugins>
129+
</build>
130+
</project>

0 commit comments

Comments
 (0)