Merge branch 'postgresql-dialect' into gorm-pilot-support

README.md

@@ -14,10 +14,11 @@ PGAdapter can be used with the following drivers and clients:
 
 ## Frameworks
 PGAdapter can be used with the following frameworks:
-1. `gorm`: Version 1.23.8 and higher have Pilot Support. See [gorm support](docs/gorm.md) for more details.
+1. `Liquibase`: Version 4.12.0 and higher have Pilot Support. See [Liquibase support](docs/liquibase.md)
+   for more details. See also [this directory](samples/java/liquibase) for a sample application using `Liquibase`.
+2. `gorm`: Version 1.23.8 and higher have Pilot Support. See [gorm support](docs/gorm.md) for more details.
    See also [this directory](samples/golang/gorm) for a sample application using `gorm`.
 
-
 ## FAQ
 See [Frequently Asked Questions](docs/faq.md) for answers to frequently asked questions.
 

docs/liquibase.md

@@ -0,0 +1,56 @@
+# PGAdapter - Liquibase Connection Options
+
+PGAdapter has Pilot Support for [Liquibase](https://www.liquibase.org/) version v4.12.0 and higher.
+
+## Limitations
+Pilot Support means that it is possible to use `Liquibase` with Cloud Spanner PostgreSQL databases,
+but with limitations. This means that porting an existing application from PostgreSQL to Cloud Spanner
+will probably require code changes. See [Limitations](../samples/java/liquibase/README.md#limitations)
+in the `Liquibase` sample directory for a full list of limitations.
+
+## Usage
+
+
+### Start PGAdapter
+First start PGAdapter:
+
+```shell
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter
+docker run \
+  -d -p 5432:5432 \
+  -v ${GOOGLE_APPLICATION_CREDENTIALS}:${GOOGLE_APPLICATION_CREDENTIALS}:ro \
+  -e GOOGLE_APPLICATION_CREDENTIALS \
+  gcr.io/cloud-spanner-pg-adapter/pgadapter \
+  -p my-project -i my-instance \
+  -x
+```
+
+### Create databasechangelog and databasechangeloglock Manually
+The `databasechangeloglock` and `databasechangelog` tables **must** be created manually, as the
+DDL script that is automatically generated by Liquibase will try to use the data type
+`timestamp without time zone`, which is not supported by Cloud Spanner. The DDL script to create
+these tables manually can be found in [create_database_change_log.sql](../samples/java/liquibase/create_database_change_log.sql).
+
+### Connect Liquibase to PGAdapter
+Liquibase will by default use DDL transactions when connecting to PostgreSQL databases. This is not
+supported by Cloud Spanner. Instead, PGAdapter can automatically convert DDL transactions into DDL
+batches. This requires the following option to be set in the JDBC connection URL:
+
+```properties
+url: jdbc:postgresql://localhost:5432/liquibase-test?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
+```
+
+See [liquibase.properties](../samples/java/liquibase/liquibase.properties) for an example connection URL.
+
+### Run Liquibase
+Run Liquibase using for example the Maven plugin:
+
+```shell
+mvn liquibase:validate
+```
+
+## Full Sample and Limitations
+[This directory](../samples/java/liquibase) contains a full sample of how to work with `Liquibase` with
+Cloud Spanner and PGAdapter. The sample readme file also lists the [current limitations](../samples/java/liquibase)
+when working with `Liquibase`.

samples/java/hibernate/pom.xml

@@ -24,23 +24,29 @@
     <junixsocket.version>2.5.1</junixsocket.version>
   </properties>
   <dependencies>
+    <!-- [START spanner_hibernate_dependencies] -->
+    <!-- Hibernate for Entity Management -->
     <dependency>
       <groupId>org.hibernate</groupId>
       <artifactId>hibernate-entitymanager</artifactId>
-      <version>${hibernate.version}</version>
+      <version>5.3.20.Final</version>
     </dependency>
 
+    <!-- Hibernate core dependency -->
     <dependency>
       <groupId>org.hibernate</groupId>
       <artifactId>hibernate-core</artifactId>
-      <version>${hibernate.version}</version>
+      <version>5.3.20.Final</version>
     </dependency>
 
+    <!-- The Postgresql JDBC driver dependency -->
     <dependency>
       <groupId>org.postgresql</groupId>
       <artifactId>postgresql</artifactId>
       <version>42.4.3</version>
     </dependency>
+    <!-- [END spanner_hibernate_dependencies] -->
+
     <dependency>
       <groupId>javax.xml.bind</groupId>
       <artifactId>jaxb-api</artifactId>

samples/java/hibernate/src/main/resources/hibernate.properties

@@ -1,5 +1,8 @@
+# [START spanner_hibernate_config]
 hibernate.dialect org.hibernate.dialect.PostgreSQLDialect
 hibernate.connection.driver_class org.postgresql.Driver
+# [END spanner_hibernate_config]
+
 hibernate.connection.url jdbc:postgresql://localhost:5432/test-database
 hibernate.connection.username pratick
 

samples/java/liquibase/README.md

@@ -1,6 +1,6 @@
 # PGAdapter and Liquibase
 
-PGAdapter can be used in combination with Liquibase, but with a number of limitations. This sample
+PGAdapter has Pilot Support for [Liquibase](https://www.liquibase.org/). This sample
 shows the command line arguments and configuration that is needed in order to use Liquibase with
 PGAdapter.
 

samples/java/liquibase/liquibase.properties

@@ -7,4 +7,4 @@ changeLogFile: dbchangelog.xml
 # DDL transactions into DDL batches.
 # See https://github.com/GoogleCloudPlatform/pgadapter/blob/postgresql-dialect/docs/ddl.md for more
 # information.
-url: jdbc:postgresql://localhost:5432/liquibase-test?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction%20-c%20server_version=14.1
+url: jdbc:postgresql://localhost:5432/liquibase-test?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction