Skip to content

Commit 9d1fd65

Browse files
authored
docs: remove limitations for new features (#435)
Remove documented limitations for new features that are now supported.
1 parent b446625 commit 9d1fd65

File tree

2 files changed

+25
-28
lines changed

2 files changed

+25
-28
lines changed

README.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11

22
# Liquibase Spanner Extension
33

4-
A Liquibase extension adding support for Google Cloud Spanner. Include this in your
4+
A Liquibase extension adding support for Google Spanner. Include this in your
55
application project to run Liquibase database migration scripts against a Google
6-
Cloud Spanner database.
6+
Spanner database.
77

88
## Performance Recommendations
9-
Executing multiple small DDL statements on Cloud Spanner can take a very long time. This means that
9+
Executing multiple small DDL statements on Spanner can take a very long time. This means that
1010
the standard recommendation to use as small changesets as possible with Liquibase is not always the
11-
best choice when working with Cloud Spanner. Instead, it is recommended to create changesets that
11+
best choice when working with Spanner. Instead, it is recommended to create changesets that
1212
group multiple DDL statements into one DDL batch. Use [SQL change](https://docs.liquibase.com/change-types/community/sql.html)
1313
and batch the DDL using [batch statements](https://cloud.google.com/spanner/docs/jdbc-session-mgmt-commands#batch_statements).
1414

@@ -235,8 +235,8 @@ See the samples directory for specific integrations with other frameworks, such
235235
The following Liquibase [ChangeTypes](https://docs.liquibase.com/change-types/home.html) are supported:<br/>
236236
createTable, dropTable, addColumn, modifyDataType, addNotNullConstraint, dropColumn, createIndex, dropIndex, addForeignKeyConstraint, dropForeignKeyConstraint, dropAllForeignKeyConstraints, addLookupTable, createView, dropView
237237

238-
The following Liquibase [ChangeTypes](https://docs.liquibase.com/change-types/home.html) are not allowed with Cloud Spanner:<br/>
239-
addAutoIncrement, addDefaultValue, addPrimaryKey, addUniqueConstraint, dropUniqueConstraint, createProcedure, dropDefaultValue, dropNotNullConstraint, dropPrimaryKey, dropProcedure, renameColumn, renameSequence, renameTable, renameView, setColumnRemarks, setTableRemarks, alterSequence
238+
The following Liquibase [ChangeTypes](https://docs.liquibase.com/change-types/home.html) are not allowed with Spanner:<br/>
239+
addAutoIncrement, addPrimaryKey, addUniqueConstraint, dropUniqueConstraint, createProcedure, dropNotNullConstraint, dropPrimaryKey, dropProcedure, renameColumn, renameSequence, renameView, setColumnRemarks, setTableRemarks, alterSequence
240240

241241
The following data DML [ChangeTypes](https://docs.liquibase.com/change-types/home.html) are supported:<br/>
242242
insert, update, loadData, loadUpdateData
@@ -274,7 +274,7 @@ delete.
274274

275275
### Unsupported Spanner Features
276276

277-
There are a number of features that Spanner does not have such as sequences and stored procedures. The Liquibase extension will
277+
There are a number of features that Spanner does not have such as stored procedures. The Liquibase extension will
278278
throw an exception during analysis of the changeSet in most cases, but not all. For example, a DELETE without a WHERE clause
279279
will fail in Spanner but not in the Liquibase extension.
280280

@@ -292,7 +292,7 @@ will fail in Spanner but not in the Liquibase extension.
292292
Testing requirements:
293293
* Emulator requires [testcontainers](https://www.testcontainers.org/) and its [requirements](https://www.testcontainers.org/supported_docker_environment/) installed.
294294
* Spanner in GCP requires SPANNER_PROJECT and SPANNER_INSTANCE environment variables set to an active instance
295-
* Spanner in GCP requires application default credentials set or GOOGLE_APPLICATION_CREDENTIALS environent set
295+
* Spanner in GCP requires application default credentials set or GOOGLE_APPLICATION_CREDENTIALS environment set
296296

297297
### Deploying
298298

limitations.md

Lines changed: 17 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Limitations
2-
This library implements as many available features of both Liquibase and Cloud Spanner as possible. However, there
2+
This library implements as many available features of both Liquibase and Spanner as possible. However, there
33
are a number of features that either can't be supported, or that can only be supported through custom SQL changes.
44
These limitations and possible workarounds are listed in this document.
55

6-
## Cloud Spanner features without a corresponding Liquibase change type
7-
The following Cloud Spanner features do not have a corresponding change type in Liquibase and are, therefore,
6+
## Spanner features without a corresponding Liquibase change type
7+
The following Spanner features do not have a corresponding change type in Liquibase and are, therefore,
88
only supported through custom SQL change sets or through automatic modification of the SQL statements that are
99
generated by Liquibase.
1010

@@ -16,30 +16,27 @@ to modify the generated SQL. See the [create-schema.yaml](example/create-schema.
1616
- Commit timestamp columns: Use `ModifySql` to replace the column definition with one that includes the `OPTIONS (allow_commit_timestamp=true)` clause. See [create-schema.yaml](example/create-schema.yaml) for an example.
1717
- Null-filtered indexes: Use `ModifySql` to replace the `CREATE INDEX` statement with `CREATE NULL_FILTERED INDEX`. See [this test file](src/test/resources/create-null-filtered-index-singers-first-name.spanner.yaml) for an example.
1818

19-
## Database features not supported by Cloud Spanner
20-
The following database features are not supported by Cloud Spanner, and trying to create/alter/drop any of them through Liquibase will cause an error.
19+
## Database features not supported by Spanner
20+
The following database features are not supported by Spanner, and trying to create/alter/drop any of them through Liquibase will cause an error.
2121

22-
- Auto increment columns
23-
- Sequences
2422
- Unique constraints: Use `UNIQUE INDEX` instead of `UNIQUE CONSTRAINT`
2523
- Stored procedures
2624
- Table and column remarks
2725

28-
## Liquibase change types with no Cloud Spanner support
29-
The following change types are not supported by Cloud Spanner.
30-
- Add/Drop primary key: Cloud Spanner requires that all tables have a primary key. The primary key must be defined when the table is created, and cannot be dropped or added later.
31-
- Rename table: Cloud Spanner does not support renaming tables. Create a copy instead, and drop the old table.
32-
- Rename column: Cloud Spanner does not support renaming columns. Create a copy instead, and drop the old column.
26+
## Liquibase change types with no Spanner support
27+
The following change types are not supported by Spanner.
28+
- Add/Drop primary key: Spanner requires that all tables have a primary key. The primary key must be defined when the table is created, and cannot be dropped or added later.
29+
- Rename column: Spanner does not support renaming columns. Create a copy instead, and drop the old column.
3330

34-
## Liquibase change types with limited Cloud Spanner support
35-
The following Liquibase change types are implemented for Cloud Spanner but have certain limitations.
31+
## Liquibase change types with limited Spanner support
32+
The following Liquibase change types are implemented for Spanner but have certain limitations.
3633

37-
- AddLookupTable: This feature is implemented and works for most cases. However, if the amount of data to be inserted in the new lookup table exceeds any of the [Cloud Spanner transaction limits](https://cloud.google.com/spanner/docs/dml-tasks#transaction_limits), the change will fail and you should implement it using a custom SQL change.
38-
- Delete: This feature is implemented and works for most cases. However, if the amount of data to be deleted in the new lookup table exceeds any of the [Cloud Spanner transaction limits](https://cloud.google.com/spanner/docs/dml-tasks#transaction_limits), the change will fail and you should implement it using a custom SQL change. Specifying a `WHERE` clause for the `DELETE` statement is required (the clause may be `WHERE TRUE`).
39-
- Load data / Load-update data: These features are implemented and works for most cases. If however the amount of data to be inserted or updated exceeds any of the [Cloud Spanner transaction limits](https://cloud.google.com/spanner/docs/dml-tasks#transaction_limits), the change will fail and you should implement it using a custom SQL change.
40-
- Modify data type: This feature works, but only for the data type changes that are [allowed by Cloud Spanner](https://cloud.google.com/spanner/docs/data-definition-language#description_3).
34+
- AddLookupTable: This feature is implemented and works for most cases. However, if the amount of data to be inserted in the new lookup table exceeds any of the [Spanner transaction limits](https://cloud.google.com/spanner/docs/dml-tasks#transaction_limits), the change will fail and you should implement it using a custom SQL change.
35+
- Delete: This feature is implemented and works for most cases. However, if the amount of data to be deleted in the new lookup table exceeds any of the [Spanner transaction limits](https://cloud.google.com/spanner/docs/dml-tasks#transaction_limits), the change will fail and you should implement it using a custom SQL change. Specifying a `WHERE` clause for the `DELETE` statement is required (the clause may be `WHERE TRUE`).
36+
- Load data / Load-update data: These features are implemented and works for most cases. If however the amount of data to be inserted or updated exceeds any of the [Spanner transaction limits](https://cloud.google.com/spanner/docs/dml-tasks#transaction_limits), the change will fail and you should implement it using a custom SQL change.
37+
- Modify data type: This feature works, but only for the data type changes that are [allowed by Spanner](https://cloud.google.com/spanner/docs/data-definition-language#description_3).
4138

42-
A potential work-around for the transaction limits in Cloud Spanner is to use [Partitioned DML](https://cloud.google.com/spanner/docs/dml-tasks#partitioned-dml) instead of transactional DML. Partitioned DML statements are not bound by the transaction limits, but are also not atomic. The Cloud Spanner JDBC driver that is used by Liquibase supports Partitioned DML by setting the `AUTOCOMMIT_DML_MODE` connection property to `PARTITIONED_NON_ATOMIC`:
39+
A potential work-around for the transaction limits in Spanner is to use [Partitioned DML](https://cloud.google.com/spanner/docs/dml-tasks#partitioned-dml) instead of transactional DML. Partitioned DML statements are not bound by the transaction limits, but are also not atomic. The Spanner JDBC driver that is used by Liquibase supports Partitioned DML by setting the `AUTOCOMMIT_DML_MODE` connection property to `PARTITIONED_NON_ATOMIC`:
4340

4441
```sql
4542
SET AUTOCOMMIT = TRUE;
@@ -53,4 +50,4 @@ SET AUTOCOMMIT_DML_MODE = 'TRANSACTIONAL';
5350

5451
## DDL limits
5552

56-
Cloud Spanner recommends some [best practices for schema updates](https://cloud.google.com/spanner/docs/schema-updates#best-practices) including limiting the frequency of schema updates and to consider the impact of large scale schema changes. One approach it to apply a small number of change sets. Alternatively, use [SQL change](https://docs.liquibase.com/change-types/community/sql.html) and batch the DDL using [batch statements](https://cloud.google.com/spanner/docs/use-oss-jdbc#batch_statements).
53+
Spanner recommends some [best practices for schema updates](https://cloud.google.com/spanner/docs/schema-updates#best-practices) including limiting the frequency of schema updates and to consider the impact of large scale schema changes. One approach it to apply a small number of change sets. Alternatively, use [SQL change](https://docs.liquibase.com/change-types/community/sql.html) and batch the DDL using [batch statements](https://cloud.google.com/spanner/docs/use-oss-jdbc#batch_statements).

0 commit comments

Comments
 (0)