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:

1. 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.

2. 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.

3. 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.

4. 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.

5. In the factory-hooks directory, create a db-update directory if it doesn’t already exist.
6. In the /factory-hooks/db-update directory, add the script file(s) you created for this procedure.
7. 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.

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:

1. Sign in to the Site Factory Management Console as a user with the platform admin role.
2. In the top menu, click Administration.
3. In the Code management and deployment section, click Update code.
4. Scroll to the Site update action section, and then in the Update argument field, enter your arguments, separated by spaces.
5. Select the Select this check box to confirm that you want to update your public-facing production environment checkbox.
6. Click Update.

For information on hook arguments, see Hook arguments.

Exiting the update process after errors

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.

Troubleshooting database update hooks

Site Factory will perform database updates using drush updatedb if any of the following conditions are met:

• The /factory-hooks/db-update directory doesn’t exist, or isn’t in the right place.
• The /factory-hooks/db-update directory exists, but has no files.
• The /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.

Example scripts

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.

#!/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

Overriding 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