Upgrade¶

This section describe how PQS manages the evolution of its database schema between releases. This is important for operators who need to understand what is involved in upgrading PQS to a new version, and how to troubleshoot any issues that may arise.

Note

The SQL API (not the database schema) is the interface for downstream consumers of PQS. The schema is an implementation detail that will evolve in order to enhance functional and performance characteristics.

When running a new version, PQS automatically applies any missing patches to the schema. This means that new PQS releases seamlessly evolve the schema to the latest required version.

In case automatic schema management is undesirable, see Manual handling of schema upgrades.

Monitoring progress¶

The logging output can be observed to monitor the progress of schema migration:

com.digitalasset.scribe.postgres.document.Main:53 Applying required datastore schema  application=scribe
com.digitalasset.scribe.postgres.document.DocumentPostgres:35 Applying schema  application=scribe
org.flywaydb.core.internal.license.VersionPrinter: Flyway Community Edition 9.22.3 by Redgate  application=scribe
org.flywaydb.core.internal.license.VersionPrinter: See release notes here: https://rd.gt/416ObMi  application=scribe
org.flywaydb.core.internal.license.VersionPrinter:   application=scribe
org.flywaydb.core.FlywayExecutor: Database: jdbc:postgresql://localhost:5432/postgres (PostgreSQL 15.5) application=scribe
org.flywaydb.core.internal.schemahistory.JdbcTableSchemaHistory: Schema history table "public"."flyway_schema_history" does not exist yet  application=scribe
org.flywaydb.core.internal.command.DbValidate: Successfully validated 2 migrations (execution time 00:00.016s) application=scribe
org.flywaydb.core.internal.schemahistory.JdbcTableSchemaHistory: Creating Schema History table "public"."flyway_schema_history" ...  application=scribe
org.flywaydb.core.internal.command.DbMigrate: Current version of schema "public": << Empty Schema >>  application=scribe
org.flywaydb.core.internal.command.DbMigrate: Migrating schema "public" to version "001 - Create initial schema"  application=scribe
org.flywaydb.core.internal.command.DbMigrate: Migrating schema "public" to version "002 - Make initializecontractimplements function idempotent"  application=scribe
org.flywaydb.core.internal.command.DbMigrate: Successfully applied 2 migrations to schema "public", now at version v002 (execution time 00:00.081s)  application=scribe
com.digitalasset.scribe.postgres.document.DocumentPostgres:55 Applying mappings  application=scribe
com.digitalasset.scribe.postgres.document.DocumentPostgres:57 Schema and mappings applied  application=scribe
com.digitalasset.scribe.postgres.document.Main:57 Applied required datastore schema  application=scribe

More detailed logs can be obtained by setting the log level to DEBUG (see Logging).

Manual handling of schema upgrades¶

Some deployment environments require far stricter access control than letting operational processes perform such intrusive database schema operations. PQS allows you to export the required schema to standard output, which can later be reviewed and applied by authorized operators.

The following command displays the latest required schema:

$ ./scribe.jar datastore postgres-document schema show \
    --ledger-host ...

The output contains all SQL statements that are required to bring the schema up to the latest version and clearly demarcates each patch’s contents:

/*********************************************
 * generated by scribe, version: v0.5.8 *
 *********************************************/

-- >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> --
-- db/migration/V001__Create_initial_schema.sql (start) --
-- >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> --
-- ... patch content ...
-- <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< --
-- db/migration/V001__Create_initial_schema.sql (end) --
-- <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< --

... more patches ...

-- DAML<=>PG mappings
do $$ begin
-- ... contracts/exercises partitions initialisation goes here ...
end; $$

The Database Administrator can then review the output and apply the ones that are higher than the current latest entry in the flyway_schema_history table.

Note

The DAML<=>PG mappings section of the above script changes based on the ledger Daml packages in use when invoking the show command, but its contents are idempotent and can be safely re-applied repeatedly.

When PQS’s schema is being managed out-of-band, it is advisable to turn off automatic schema application when launching the pipeline:

$ ./scribe.jar pipeline ledger postgres-document \
    --target-schema-autoapply false ...

Upgrade¶

Monitoring progress¶

Manual handling of schema upgrades¶

On this page