It can be helpful to perform actions on your websites immediately prior to or after a database update. To accomplish this, Acquia Cloud Site Factory provides the
db-update hook for your use, allowing you to override the behavior of
drush updatedb. It does this by allowing you to inject custom scripts for execution both before and after the command is run for your websites.
Like several of the other hooks in use by Acquia Cloud Site Factory, you will create a script file and place it in a particular directory, which will be executed at the appropriate time when doing database updates for your websites. To use the hook, complete the following steps:
- Create a script that includes the commands to to run before and after
drush updatedb. You can create more than one script for use with this hook, but the scripts will be executed in alphabetical order. However, a single script can contain both pre- and post-update instructions.
drush updatedbinstruction at the point you wish database updates to be executed.
- Ensure that you have created a directory called
factory-hooksat the root of your code repository.
- In the
factory-hooksdirectory, ensure that you have created a
- In the
/factory-hooks/db-updatedirectory, add the script file(s) that you created for this procedure.
- Examine the files that you created to ensure that they have the executable flag for Acquia Cloud Site Factory to execute them.
If your scripts require additional 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 Acquia Cloud Site Factory user interface to specify arguments to be passed 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 Acquia Cloud Site Factory user interface, perform the following steps:
- Sign in to the Acquia Cloud Site Factory 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 check box.
- Click Update.
Troubleshooting database update hooks
Database updates will be performed normally using
drush updatedb if any of the following conditions are met:
/factory-hooks/db-updatedirectory does not exist, or is not in the right place.
/factory-hooks/db-updatedirectory exists, but contains no files.
/factory-hooks/db-updatedirectory exists and contains files, but none are executable.
If a script in the
db-update directory ends with an error (a non-zero exit code), no additional scripts will be executed in the directory, and the task logs will display errors in
TaskUpdate lines. For information about accessing and reading task logs, see Logging in Acquia Cloud Site Factory.
The following script can be modified 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 below.
# Usage: post-code-deploy 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 nonempty.
# 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 docroot + 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...