It can be helpful to perform actions on your websites before or after a
database update. Site Factory provides the db-update
hook for
you to override the behavior of drush updatedb
. This hook enables you to
inject custom scripts to perform before and after running the
drush updatedb
command for your websites.
Like several of the other hooks in use by Site Factory, you will create a script file and place it in a particular directory. The scripts run in alphabetical order at the appropriate time when doing database updates for your websites.
To use the hook, complete the following steps:
Create a script including the commands to run before and after
drush updatedb
. You can create more than one script for use with this
hook, but the scripts will run in alphabetical order. A single script can
contain both pre-update and post-update instructions.
Place the drush updatedb
instruction at the point you want database
updates run.
Important
Your script must include the drush updatedb
command, because this
hook replaces it. If you don’t include the command and you use the
db-update
hook, Site Factory won’t run
drush updatedb
on your websites.
Be sure to have your script exit with a non-zero exit code in cases where the script encounters an error or any other issue.
Create a directory called factory-hooks
at the root of your code
repository, if it doesn’t already exist.
Note
The factory-hooks
directory and your
docroot directory are
separate directories at the same level in your code repository.
In the factory-hooks
directory, create a db-update
directory if it
doesn’t already exist.
In the /factory-hooks/db-update
directory, add the script file(s)
you created for this procedure.
Examine the files you created to ensure they have the executable flag for Site Factory to execute them.
If your scripts require more arguments, you can provide the
db_update_arguments
argument by either using the /update
Site
Factory REST API call, or by
signing in to the Site Factory user interface to specify
arguments to pass to the hook.
The hook accepts alphanumeric arguments, separated by spaces. To supply
arguments to the db-update
hook from the
Site Factory user interface, perform the following steps:
For information on hook arguments, see Hook arguments.
If a db-update
hook script returns a non-zero exit code,
Site Factory will immediately stop the update process. In
this case, no additional, follow-on db-update
hook scripts will be run,
and the deployment will fail.
For information about how to troubleshoot these errors, see Resolving codebase update errors.
Site Factory will perform database updates using
drush updatedb
if any of the following conditions are met:
/factory-hooks/db-update
directory doesn’t exist, or isn’t
in the right place./factory-hooks/db-update
directory exists, but has no files./factory-hooks/db-update
directory exists and has files,
but none are executable.If a script in the db-update
directory ends with an error (a non-zero exit
code), no more scripts will be run in the directory, and the task
logs will display error messages in
TaskUpdate
lines. For information about accessing and reading task logs,
see Viewing tasks.
The following scripts are available for your use, and include examples that do not use BLT and that require BLT.
You can change the following script to suit your needs, but the script
must contain the drush updatedb
command.
#!/bin/sh
#
# Factory Hook: db-update
#
# The existence of one or more executable files in the
# /factory-hooks/db-update directory will prompt them to be run
# *instead of* the regular database update (drush updatedb) command. So
# that update command will normally be part of the commands executed
# below.
#
# Usage: SCRIPTNAME site env db-role domain custom-arg1 custom-arg2 ...
# Map the script inputs to convenient names.
# Acquia hosting site / environment names
site="$1"
env="$2"
# database role. (Not expected to be needed in most hook scripts.)
db_role="$3"
# The public domain name of the website.
domain="$4"
# Custom argument: we will run entity updates if it is in any way
# nonempty.
update_entities="$5"
# The websites' document root can be derived from the site/env:
docroot="/var/www/html/$site.$env/docroot"
# Acquia recommends the following two practices:
# 1. Hardcode the drush version.
# 2. When running drush, provide the application + url, rather than relying
# on aliases. This can prevent some hard to trace problems.
DRUSH_CMD="drush8 --root=$docroot --uri=https://$domain"
$DRUSH_CMD updatedb
# Run entity updates if the updatedb command didn't fail.
if [ $? -eq 0 -a -n "$update_entities" ] ; then
# Possibly do some preparation here...
$DRUSH_CMD entity-updates
fi
If your application uses BLT, you can change the following script to
suit your needs. The final deploy
command calls drush updatedb
, so a
separate drush updatedb
command isn’t needed.
#!/bin/sh
#
# Factory Hook: db-update
#
# The existence of one or more executable files in the
# /factory-hooks/db-update directory will prompt them to be run
# *instead of* the regular database update (drush updatedb) command. So
# that update command will normally be part of the commands executed
# below.
#
# Usage: SCRIPTNAME site env db-role domain custom-arg
# Map the script inputs to convenient names.
# Acquia hosting site / environment names
site="$1"
env="$2"
# database role. (Not expected to be needed in most hook scripts.)
db_role="$3"
# The public domain name of the website.
domain="$4"
# BLT executable:
blt="/var/www/html/$site.$env/vendor/acquia/blt/blt/bin/blt"
com="$blt deploy:update --define environment=$env --define drush.uri=$domain -v -y"
$com