Table of Contents

Using Sqitch with Evergreen

See alsoLaunchpad Bug 1521693

Getting Started

Install Sqitch

# Works on most systems.  See sqitch.org for more.
$ sudo cpan App::Sqitch

Install Base Schema

Install the latest working branch from LP 1521693 using the standard DB install process. The branch is set up to use Sqitch internally. No special considerations are required for the base install.

Creating an Upgrade Script

For this example, we're cross-porting an existing SQL upgrade script for LP #1319998.

Full code is tracked in commit c999d04.

Override Sqitch DB connections parameters the sqitch flags –db-host, –db-name, –db-port, and –db-user. The PGPASSWORD environment variable is also honored.

$ cd Open-ILS/src/sql/schema
$ sqitch add schema.materialized_billing_summary_delete_trigger \
    --requires schema.no_delete_acq_cancel_reasons \
    -n 'Cross porting LP#1319998 schema.materialized_billing_summary_delete_trigger' 

'sqitch add' adds a line to sqitch.plan to track the new install target and creates 3 new files:

deploy/schema.materialized_billing_summary_delete_trigger.sql
revert/schema.materialized_billing_summary_delete_trigger.sql
verify/schema.materialized_billing_summary_delete_trigger.sql

For example, see the contents of these 3 files at commit c999d04.

Deploying an Upgrade Script

$ sqitch status
# On database evergreen
# Project:  evergreen
# Change:   a632d6b112c3770ad8bd3efff80b9f5700212166
# Name:     schema.no_delete_acq_cancel_reasons
# Deployed: 2015-12-29 10:28:02 -0500
# By:       Bill Erickson <berickxx@gmail.com>
# 
Undeployed change:
  * schema.materialized_billing_summary_delete_trigger
$ sqitch deploy
Deploying changes to evergreen
  + schema.materialized_billing_summary_delete_trigger .. ok

* If necessary, revert the change.

$ sqitch revert --to schema.no_delete_acq_cancel_reasons
Revert changes to schema.no_delete_acq_cancel_reasons from evergreen? [Yes] 
  - schema.materialized_billing_summary_delete_trigger .. ok

Resolving Conflicts / Deploying Multiple Plan Files

AKA "Cannot find this change in sqitch.plan"

When deploying changes, Sqitch inspects both the name and position of each target in the sqitch.plan file. A Sqitch install target is a product of its name and which target precedes it. (This is similar to Git commits). I had originally assumed only the name of the change mattered, so this was unexpected.

In an environment where changes are always deployed linearly, like a production database, this has no bearing. However, when using Sqitch on a development database, where changes from different Git branches may be deployed in a single database, this can cause confusion for Sqitch. When the sqitch.plan file does not match the events tracked in the Sqitch database tables, a sqitch deploy may result in an error like this:

# On database evergreen
# Project:  evergreen
# Change:   e29fe26ba146d263e3494cc07960ecf2b26b620d
# Name:     schema.fix_vandelay_stored_procs
# Deployed: 2016-03-30 10:16:33 -0400
# By:       Bill Erickson <foo@example.org>
#
Cannot find this change in sqitch.plan
Make sure you are connected to the proper database for this project.

The solution is to revert any Sqitch targets that are not shared by both branches. The offending targets can be completely rolled back using

sqitch revert --to <last-shared-change>

Or they can be virtually rolled back by telling Sqitch to pretend like they were reverted using

sqitch revert --log-only --to <last-shared-change>

The –log-only option tells Sqitch to update its tracking tables without executing any deploy/verify/revert scripts. This is particularly useful when bouncing between branches where you may not want to revert changes, because it means deleting test data.

Example

  1. Deploy sqitch.plan with changes A, B, and C.
  2. Checkout another Git branch with a sqitch.plan file containing changes A, B, D.
  3. 'sqitch deploy' will result in error "Cannot find this change in sqitch.plan" with Name: C
  4. Revert all offending changes:
# roll back the change.
sqitch revert --to B

# OR just tell Sqitch to ignore the change.
sqitch revert --to B --log-only
  1. Deploy change D
sqitch deploy

The same steps will work when returning to the original branch w/ changes A, B, and C.

The --merge option

Version 1.1.0 of Sqitch will support a –merge option to better handle situations where the plan file does not match the exact order of the events tracked in the Sqitch database. (At time of writing, CPAN installs version 0.9994). In theory, this will make it easier to use a single database for developing across multiple branches.