Fix #2051, include a FORCE_DB_VERSION config variable to ask the serv…

…er to downgrade. Plus instructions on how to rollback.

docs/deployment.md

@@ -1,4 +1,3 @@
-
 This document details the process we use to deploy Page Shot to our stage and production environments.
 
 ## Overview of schedule ##
@@ -88,3 +87,27 @@ Softvision will verify production for us, and report any bugs on Wednesday.
 Once we have verified production, update the Page Shot GA account with an annotation including sprint information. Example: "1.0.1 release" Oct. 25th.
 
 Close deployment issue, and give it a `qa:verified` label.
+
+## Database migrations
+
+The database schema version is contained in a table in the database.  You can fetch it via:
+
+```sql
+SELECT value FROM property WHERE key = 'patch';
+```
+
+The desired version is in `server/src/dbschema.js` in the `MAX_DB_LEVEL` variable.
+
+The application server can manage upgrades of the database.  It can also handle downgrades, but only if it knows about how to downgrade the version.  Only the newest version of the application is likely to know how to downgrade to the intended version.
+
+### Rollback
+
+Rollback requires deploying the *newest* version of the application and setting an environmental variable to request it to downgrade.
+
+For instance, if you want to install version 1.0.1, you'd look in [dbschema](https://github.com/mozilla-services/pageshot/blob/1.0.1/server/src/dbschema.js#L7) and see `const MAX_DB_LEVEL = 10;` – but let's say the current database version is 12.  If you look in [server/db-patches](https://github.com/mozilla-services/pageshot/tree/1.0.1/server/db-patches) for version 1.0.1 there's no patch files to make that change.  There *are* [necessary patches in master](https://github.com/mozilla-services/pageshot/tree/master/server/db-patches).
+
+Therefore to deploy an old version *first* you must deploy a recent version and ask it to downgrade the database.  Downgrading can be requested through an environmental variable:
+
+`FORCE_DB_VERSION=10`
+
+This will cause the application to start up, downgrade the database, and immediately exit with a zero exit code.  After that has succeeded then you can install the old version (e.g., 1.0.1 in our example).

server/src/config.js

@@ -122,6 +122,13 @@ var conf = convict({
       default: "",
       env: "RDS_NAME",
       arg: "db-name"
+    },
+    forceDbVersion: {
+      doc: "Force database version (for use in downgrades)",
+      format: "int",
+      default: 0,
+      env: "FORCE_DB_VERSION",
+      arg: "force-db-version"
     }
   },
   gaId: {

server/src/dbschema.js

@@ -6,6 +6,29 @@ const mozlog = require("mozlog")("dbschema");
 
 const MAX_DB_LEVEL = 12;
 
+exports.forceDbVersion = function (version) {
+  mozlog.info("forcing-db-version", {db: db.constr, version});
+  return db.getConnection().then(([conn, done]) => {
+    let dirname = path.join(__dirname, "db-patches");
+    mozlog.info("loading-patches-from", {dirname: dirname});
+    return new Promise((resolve, reject) => {
+      pgpatcher(conn, version, {dir: dirname}, function(err) {
+        if (err) {
+          mozlog.error("error-patching", {
+            msg:`Error patching database to level ${version}!`,
+            err
+          });
+          done();
+          reject(err);
+        } else {
+          mozlog.info("db-level", {msg: `Database is now at level ${version}`});
+          resolve();
+        }
+      });
+    });
+  });
+};
+
 /** Create all the tables */
 exports.createTables = function () {
   mozlog.info("setting-up-tables-on", {db: db.constr});

server/src/server.js

@@ -118,9 +118,21 @@ if (config.useS3) {
   });
 }
 
-
 function initDatabase() {
-  if (config.disableControllerTasks) {
+  let forceDbVersion = config.db.forceDbVersion;
+  if (forceDbVersion) {
+    let hadError = false;
+    dbschema.forceDbVersion(forceDbVersion).then(() => {
+    },
+    (e) => {
+      hadError = true;
+      console.error("Error forcing database version:", forceDbVersion, e);
+    }).then(() => {
+      console.info("Exiting after downgrade");
+      process.exit(hadError ? 2 : 0);
+    });
+    return Promise.resolve();
+  } else if (config.disableControllerTasks) {
     console.info("Note: this server will not perform database initialization");
     return Promise.resolve();
   }