Overriding the drush updatedb command¶

Using the db-update hook¶

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

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, Acquia Cloud 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 Acquia Cloud 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 Acquia Cloud 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 Acquia Cloud Site Factory user interface, perform the following steps:

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 check box.
6. Click Update.

Exiting the update process after errors¶

If a db-update hook script returns a non-zero exit code, Acquia Cloud 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¶

Acquia Cloud 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, and include examples that do not use Acquia BLT and that require Acquia BLT.

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

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