Database maintenance - CDCgov/prime-simplereport Wiki


This page helps guide through maintaining your local database.

Restart & Clean

When there are DB schema changes the backend may throw an error and fail to start.

Restarting the docker way:

  1. run cd backend
  2. Bring down the service by running docker-compose down
  3. Wipe the db by running docker system prune && docker images prune && docker volume prune
  4. Restart the service docker-compose up --build

Restarting the SQL way:

  1. run db-setup/
  2. restart the spring app gradle bootRun --args=''


The application uses the Liquibase plugin for Gradle to perform certain database management tasks.

To roll the database back to its state at a prior date:

docker compose run --rm backend gradle liquibaseRollbackToDate -PliquibaseCommandValue=${date}


$ ./gradlew liquibaseRollbackToDate -PliquibaseCommandValue=${date}

To roll back a certain number of migrations:

docker compose run --rm backend gradle liquibaseRollbackCount -PliquibaseCommandValue=${n}


$ ./gradlew liquibaseRollbackCount -PliquibaseCommandValue=${n}

To roll back to a certain tag:

docker compose run --rm backend gradle liquibaseRollback -PliquibaseCommandValue=${TAG}


$ ./gradlew liquibaseUpdateToTag -PliquibaseCommandValue=${TAG}

If you are required to roll back a non-local database, you may generate the required SQL to execute elsewhere. Use liquibaseRollbackToDateSQL or liquibaseRollbackCountSQL in the manner described above to write the rollback SQL to stdout.

Rollback gotchas

Our changelog contains a some migrations that make the use of get_census_dob_group(...) these migrations are not able to be rolled backward because they need specify the schema and thus be rewritten to ${database.defaultSchemaName}.get_census_dob_group(...), rewriting the changelog will required us to manually recompute the checksum inside the databasechangelog table for the affected migrations per every environment and will require some downtime.

To get around this issue we decided to only test the last 20 rollbacks, that way we we don't hit the problematic migrations. As you can see here

We don't see a case where we will ever rollback to the problematic migrations, thus this compromise is acceptable.

Local database manipulation

Using Intellij

Using the database tool in intellij, you can view and modify entries in your database. The database tool window can be opened by clicking by clicking Database on the right panel of intellij or by going to View > Tool Window > Database


To add your database, go to + > Data Source > Postgres. Set the jdbc url to jdbc:postgresql://localhost:5432/simple_report and password to api123. In the schema tab ensure the correct schema is selected. Typically you can just set the Schema Pattern to simple_report:simple_report. The connection may now be tested and if valid, you may apply the configuration.

To access the data you may go to [email protected] > simple_report > tables and double click the table you wish to view. To access data via query you can open the query console and run any query. For example, to get all test_events you can use this query select * from simple_report.test_event;


Using other tools

To view tables/entries in your local database, team members currently use Postico and DataGrip. We recommend you use something similar to view/work with your local data.

To connect to the Postgres server, use the following credentials

  • username: simple_report_app
  • password: api123
  • port: 5432
  • database: simple_report