---
title: "Overriding the Drush updatedb command"
date: "2024-02-14T06:18:38+00:00"
summary: "Learn how to customize Drupal database updates with Site Factory's db-update hook. Inject custom scripts before and after running drush updatedb, and handle errors effectively for seamless site maintenance."
image:
type: "page"
url: "/site-factory/overriding-drush-updatedb-command"
id: "7b137c7e-7136-4259-a657-903ce56cefb7"
---

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](#acsf-dbupdate-failure) 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](/definitions/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](/acquia-cloud-platform/automating-cloud-hooks "Automating with Cloud Hooks") 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](https://docs.acquia.com/site-factory/site-factory-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](/site-factory/login) to the Site Factory Management Console as a user with the [platform admin](/site-factory/manage/users/admin/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](/site-factory/extend/hooks#acsf-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](/site-factory/workflow/deployments/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](/acquia-cloud-platform/monitor-apps/tasks) will display error messages in `TaskUpdate` lines. For information about accessing and reading task logs, see [Viewing tasks](/acquia-cloud-platform/monitor-apps/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

Note

To make the script fail at the first non-zero exit code, add **set -ev** at the start of the script.