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.
Using the db-update hook
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:
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.
drush updatedbinstruction at the point you want database updates run.
Your script must include the
drush updatedbcommand, because this hook replaces it. If you don’t include the command and you use the
db-updatehook, Site Factory won’t run
drush updatedbon 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-hooksat the root of your code repository, if it doesn’t already exist.
factory-hooksdirectory and your docroot directory are separate directories at the same level in your code repository.
factory-hooksdirectory, create a
db-updatedirectory if it doesn’t already exist.
/factory-hooks/db-updatedirectory, 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
Factory REST API call, or by
signing in to the Site Factory user interface to specify
arguments to pass to the hook.
Providing arguments 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:
In the top menu, click Administration.
In the Code management and deployment section, click Update code.
Scroll to the Site update action section, and then in the Update argument field, enter your arguments, separated by spaces.
Select the Select this check box to confirm that you want to update your public-facing production environment checkbox.
For information on hook arguments, see Hook arguments.
Exiting the update process after errors
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.
Troubleshooting database update hooks
Site Factory will perform database updates using
drush updatedb if any of the following conditions are met:
/factory-hooks/db-updatedirectory doesn’t exist, or isn’t in the right place.
/factory-hooks/db-updatedirectory exists, but has no files.
/factory-hooks/db-updatedirectory 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:
You can change the following script to suit your needs, but the script
must contain the
drush updatedb command.
# 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
# Usage: SCRIPTNAME site env db-role domain custom-arg1 custom-arg2 ...
# Map the script inputs to convenient names.
# Acquia hosting site / environment names
# database role. (Not expected to be needed in most hook scripts.)
# The public domain name of the website.
# Custom argument: we will run entity updates if it is in any way
# The websites' document root can be derived from the site/env:
# 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"
# Run entity updates if the updatedb command didn't fail.
if [ $? -eq 0 -a -n "$update_entities" ] ; then
# Possibly do some preparation here...
To make the script fail at the first non-zero exit code, add set -ev at the start of the script.