database upgrade instructions

docs/DEPLOYING_AWS_LAMBDA.md

@@ -172,6 +172,9 @@ Do **NOT** set:
 - `S3_STATIC_PATH`: This will be the s3cmd upload path that corresponds to STATIC_BASE_URL. So if `STATIC_BASE_URL=https://s3.amazon.com/spoke.example.com/static/` then `S3_STATIC_PATH=s3://spoke.example.com/static/` You will also need a ~/.s3cfg file that has the s3 upload credentials. See `package.json`'s postinstall script and more specifically `prod-static-upload`.
 - `"LAMBDA_DEBUG_LOG": "1",`: (ONLY FOR DEBUGGING) This will send more details of requests to the CloudWatch log. However, it will include the full request details, e.g. so do not use this in production.
 
+For large production environments, it might also be a good idea to add `"SUPPRESS_MIGRATIONS": "1"` so that any time you update the schema with a version upgrade,
+you can manually run the migration (see below) rather than it accidentally trigger on multiple lambdas at once.
+
 ## Deploy
 
 To create the AWS Lambda function and the API Gateway to access it, run the following being sure to substitute in the correct values:
@@ -221,14 +224,24 @@ $ AWS_PROFILE=[your_profile_nickname] claudia add-scheduled-event \
 
 ### Migrating the Database
 
-Migrations are created with knex[https://knexjs.org/#Migrations]. You can trigger migration updates with the following command:
+Migrations are created with knex[https://knexjs.org/#Migrations]. 
+
+You can trigger migration updates with the following command:
 
 ```sh
 $ AWS_PROFILE=[your_profile_nickname] claudia test-lambda --event ./deploy/lambda-migrate-database.js
 ```
 
 (Note: the migration will probably take much less than the 5 minutes or whatever your lambda timeout is, however it will look like `test-lambda` is still running/doing something. If you've confirmed on the DB side that the migration completed, it's safe to `Ctrl + c`)
 
+For major  database changes  on large  database instances,  you should
+probably disable  the web  interface so  that web  requests triggering
+database calls are not made.  In AWS, the easiest way to do this is:
+
+1. In the API  Gateway Custom  Domains (see below)  section, add  an 
+   invalid prefix (like `/xxx`) to the domain.
+2. Then in the Lambda AWS Console, you can disable any CloudWatch event triggers
+
 ### Add a Custom Domain
 
 Once Claudia has created an API Gateway we can add a subdomain to access Spoke. Add the custom domain you created the certificate for, selecting that certificate. Add a mapping with a blank path and `spoke`:`latest` for the destination and path.

docs/HOWTO_HEROKU_DEPLOY.md

@@ -67,3 +67,25 @@ git remote add heroku https://git.heroku.com/myspokeapp.git
 git push heroku master
 ```
 You may find that the Customize Log In toggle in auth0 has been disabled, so you will want to turn that back on. You will also want to make sure you are running the latest version of the code for that. See the instructions in Step 11 in the main readme doc. 
+
+### Migrating the Database
+
+For smaller instances with a single dyno, Spoke will automatically
+update the database with schema changes when you update the code.
+Even for smaller instances, it's generally good practice to pause the
+system or at least do so during minimal/zero texting activity.
+
+For large instances (100K-millions of texts and contacts) or extensive
+schema changes,  it's better  to be cautious  during a  migration.  In
+those cases, you should follow the following steps:
+
+1. Pause all of the dynos or disable web requests coming in, in another way.
+
+2. Run (yes it looks a bit redundant)
+
+```
+   heroku run npm run knex migrate:latest
+```
+
+3. Ideally, verify that the migrations have completed on the database.
+   Then re-enable the dynos and web interface.

docs/RELEASE_NOTES.md

@@ -16,7 +16,9 @@ This release includes the following improvements:
 
 Deploy Steps:
 
-- <steps here>
+- For smaller instances (less than 1 million texts/contacts), the migration should complete automatically.
+- For larger instances, it's better to enable the environment variable `SUPPRESS_MIGRATIONS=1`
+  and then follow the relevant steps of your platform to upgrade ( [Heroku](./HOWTO_HEROKU_DEPLOY.md#migrating-the-database), [AWS Lambda](./DEPLOYING_AWS_LAMBDA.md#migrating-the-database) )
 
 Thanks to all the contributors apart of this release including:
 [ibrand](https://github.com/ibrand),