Skip to content

Latest commit

 

History

History
35 lines (27 loc) · 3.5 KB

schema-migration.md

File metadata and controls

35 lines (27 loc) · 3.5 KB
title: "Schema Migration"

SQL Schema Migration

Teammates uses [Liquibase](https://docs.liquibase.com/start/home.html), a database schema change management solution that enables developers to revise and release database changes to production. The maintainers in charge of releases (Release Leader) will be in charge of generating a Liquibase changelog prior to each release to keep the production databases schema in sync with the code. Therefore this section is just for documentation purposes for contributors.

Liquibase in Teammates

Liquibase is made available using the gradle plugin, providing liquibase functions as tasks. Try gradle tasks | grep "liquibase" to see all the tasks available. In teammates, change logs (more in the next section) are written in XML.

Liquibase connection

Amend the liquibaseDbUrl, liquibaseUsername and liquibasePassword in gradle.properties to allow the Liquibase plugin to connect your database.

Change logs, change sets and change types

A change log is a file that contains a series of change sets (analagous to a transaction) which applies change types (actions). You can refer to this page on liquibase on the types of change types that can be used.

Gradle Activities for Liquibase

Activities in Gradle are a way of specifying different variables provided by gradle to the Liquibase plugin. The argument runList provided by -pRunList=<activity_name> e.g ./gradlew liquibaseSnapshot -PrunList=snapshot is used to specify which activity to be used for the Liquibase command. In this case the liquibaseSnapshot command is run using the snapshot activity.

Here is a brief description of the activities defined for Liquibase

  1. Main: The default activity used by Liquibase commands and is used for running changelogs against a database. This is used by default if a runList is not defined
  2. Snapshot: Used to specify output format and name for snapshots i.e JSON
  3. diffMain: Specify the reference and the target database to generate changelog that contains operations to update reference database to the state of the target database. i.e the reference is the JSON file generated by the snapshot command, this can be replaced with a live database which is used as reference.

Generating/ Updating liquibase change logs

  1. Ensure diff-main activity in build.gradle is pointing to the latest release changelog src/main/resources/db/changelog/db.changelog-<release_number>.xml
  2. Delete the postgres-data folder to clear any old database schemas
  3. Run git checkout <reference_branch> and
  4. Run the server using ./gradlew serverRun to generate tables found on branch
  5. Generate snapshot of database by running ./gradlew liquibaseSnapshot -PrunList=snapshot, the snapshot will be output to liquibase-snapshot.json
  6. Checkout your branch and repeat steps 2 and 4 to generate the tables found on your branch
  7. Run ./gradlew liquibaseDiffChangeLog -PrunList=diffMain to generate changeLog to resolve database schema differences
  8. Manually add a changeSet to tag the database using release_number. The tag should be named <release_number e.g v9.0.0-beta.1 (See the last changeset in v9.0.0 for reference).
  9. Include the new changelog file as the last entry in changelog-root.xml as this is the order which changelogs are executed! (See liquibase include tag)