Differences

This shows you the differences between two versions of the page.

--- dev:sqitch [2015/12/29 11:10] – erickson
+++ dev:sqitch [2022/02/10 13:34] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-==== Using Sqitch with Evergreen ====
+===== Using Sqitch with Evergreen =====
 See also[[https://bugs.launchpad.net/evergreen/+bug/1521693|Launchpad Bug 1521693]]
-=== Getting Started ===
+==== Getting Started ====
-== Install Sqitch ==
+=== Install Sqitch ===
 <code>
@@ Line 13: / Line 13: @@
 </code>
-== Install Base Schema ==
+=== Install Base Schema ===
-  - Install the latest working branch from LP 1521693 and use the standard DB install tools.
+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.
-  - Alternatively, you can create a database manually with the working branch checked out like so:
-<code>
+==== Creating an Upgrade Script ====
-$ cd Open-ILS/src/sql/schema
-$ sudo -u postgres psql --set db_name=evergreen -f tools/create_database_extensions.sql
-</code>
-=== Creating an Upgrade Script ===
 For this example, we're cross-porting an existing SQL upgrade script for LP #1319998.
 Full code is tracked in [[http://git.evergreen-ils.org/?p=working/Evergreen.git;a=commitdiff;h=c999d04|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.**
 <code>
@@ Line 36: / Line 32: @@
 </code>
-  * The --requires flag specifies which commit our new commit depends on.  For consistency with existing SQL upgrades, I apply all changes sequentially, so the --requires value points to the previous Sqitch install target.  Or, in other words, the last/bottom target in the sqitch.plan file.
+  * The --requires flag specifies which existing target our new target depends on.  For consistency with existing SQL upgrades, I apply all changes sequentially, so the --requires value points to the previous Sqitch install target.  Or, in other words, the last/bottom target in the sqitch.plan file.
   * -n specifies a Sqitch "commit" message which appears in the Sqitch log output.
@@ Line 50: / Line 46: @@
   * The deploy/ file includes our new change.  The structure of the file is practically identical to our existing upgrade/XXXX.foo.sql files, except they do not include the inline dependency check (evergreen.upgrade_deps_block_check(XXXX)).
   * The revert/ file includes SQL that allows us to roll back the changes in the deploy script.
-    * For example, when deploying a modified function, as is the case with this example, the revert/ file will include the original functoin definition.
+    * For example, when deploying a modified function, as is the case with this example, the revert/ file will include the original (well, previous) function definition.
   * The verify/ file contains SQL to confirm the changes in the deploy/ file were properly deployed.
 For example, see the contents of these 3 files at [[http://git.evergreen-ils.org/?p=working/Evergreen.git;a=commitdiff;h=c999d04|commit c999d04]].
-=== Deploying an Upgrade Script ===
+==== Deploying an Upgrade Script ====
   * Sanity check the status first
@@ Line 90: / Line 86: @@
   - schema.materialized_billing_summary_delete_trigger .. ok
 </code>
+==== 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:
+<code>
+# 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.
+</code>
+The solution is to revert any Sqitch targets that are not shared by both branches.  The offending targets can be completely rolled back using
+<code>
+sqitch revert --to <last-shared-change>
+</code>
+Or they can be virtually rolled back by telling Sqitch to pretend like they were reverted using
+<code>
+sqitch revert --log-only --to <last-shared-change>
+</code>
+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 ===
+  - Deploy sqitch.plan with changes A, B, and C.
+  - Checkout another Git branch with a sqitch.plan file containing changes A, B, D.
+  - 'sqitch deploy' will result in error "Cannot find this change in sqitch.plan" with Name: C
+  - Revert all offending changes:
+<code>
+# roll back the change.
+sqitch revert --to B
+# OR just tell Sqitch to ignore the change.
+sqitch revert --to B --log-only
+</code>
+  - Deploy change D
+<code>
+sqitch deploy
+</code>
+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 [[https://github.com/theory/sqitch/issues/200|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.