How to migrate database changes between environments

Michael Riley

Updated March 20, 2026 22:25

Assumptions

This guide assumes:

an active application on Upsun configured to a database
A local repository with the Upsun project as git remote
The Upsun CLI installed locally
An SSH key configured on the project account
admin role granted for the project

Problems Changes to a database in master will be visible to its child environments when they are synchronized, however changes made to a development environment - such as adding an admin user (alan) to a PostgreSQL database - do not run in the opposite direction and will not be available in master. In a Django application, admin user alan is visible from the dev branch.

$ upsun db:sql
psql (11.1 (Debian 11.1-3.pgdg90+1), server 9.6.11)
Type "help" for help.

main=> SELECT * FROM auth_user;
 id |          password         |          last_login           | is_superuser | username | first_name | last_name | email | is_staff | is_active |          date_joined          
----+---------------------------+-------------------------------+--------------+----------+------------+-----------+-------+----------+-----------+-------------------------------
  2 |      <password hash>      | 2019-03-12 15:52:38.379839+00 | t            | chad     |            |           |       | t        | t         | 2019-03-07 16:02:26.583956+00
  6 |      <password hash>      | 2019-03-12 15:48:02+00        | t            | alan     |            |           |       | t        | t         | 2019-03-12 15:47:19+00
(2 rows)

alan is not visible in master, however.

$ upsun db:sql
psql (11.1 (Debian 11.1-3.pgdg90+1), server 9.6.11)
Type "help" for help.

main=> SELECT * FROM auth_user; 
id |          password         |          last_login           | is_superuser | username | first_name | last_name | email | is_staff | is_active |          date_joined          
----+---------------------------+-------------------------------+--------------+----------+------------+-----------+-------+----------+-----------+-------------------------------
 2 |      <password hash>      | 2019-03-11 14:40:56.401026+00 | t            | chad     |            |           |       | t        | t         | 2019-03-07 16:02:26.583956+00
(1 row)

Note: Importing a database into an active environment is a destructive operation. This guide assumes that the only change made between master and dev is the addition of a new admin user in dev. Synchronize dev if there is data in master you do not want to be overwritten.

$ git checkout dev    
$ upsun environment:synchronize

Upsun also strongly recommends that you take a snapshot of the target environment before executing.

$ git checkout master
$ upsun snapshot:create

Migrating changes between environments can be done in two ways:

Restoring a snapshot to the target environment
Manually dumping and importing the database to the target environment

Steps (Restoring a snapshot to the target environment)

Create a snapshot Create a snapshot of the dev environment that contains the database changes

$ git checkout dev   
Switched to branch 'dev'    
$ upsun snapshot:create    
Creating a snapshot of dev   
Waiting for the snapshot to complete...   
Waiting for the activity m3qerwnkyblje (User created a backup of dev):
    Backing up dev
    Backup name is <snapshot name>   
[============================] 14 secs (complete)   
A snapshot of environment dev has been created   
Snapshot name: <snapshot name>

Restore the snapshot from dev to master While still checked out as dev and using the <snapshot name> from above:

$ upsun snapshot:restore --target=master <snapshot name>

Additional information about creating and restoring snapshots can be found in the Upsun documentation and in How to create and restore snapshots using the CLI.

Steps (Manually dump to the target environment)

Dump the database For this example, the relationship database was defined in .upsun/config.yaml with:

relationships:
     database: "postgresqldb:postgresql"

From dev dump the PostgreSQL database according to its relationship name (database). The --relationship tag is useful if there are multiple database relationships present, but if only one is used upsun db:dump will work without it. See the documentation for more information.

$ git checkout dev    
$ upsun db:dump --relationship database    
Creating SQL dump file: <local directory>/<project id>--dev-54ta5gq--postgresqldb--main--dump.sql

Pipe the SQL dump to the target environment

$ git checkout master
$ upsun sql --relationship database -e master < <project id>--dev-54ta5gq--postgresqldb--main--dump.sql

Verify Verify that the new admin user alan is now visible from master.

$ upsun db:sql
psql (11.1 (Debian 11.1-3.pgdg90+1), server 9.6.11)
Type "help" for help.
   
main=> SELECT * FROM auth_user;
id |          password         |          last_login           | is_superuser | username | first_name | last_name | email | is_staff | is_active |          date_joined          
----+---------------------------+-------------------------------+--------------+----------+------------+-----------+-------+----------+-----------+-------------------------------
 2 |      <password hash>      | 2019-03-12 15:52:38.379839+00 | t            | chad     |            |           |       | t        | t         | 2019-03-07 16:02:26.583956+00
 6 |      <password hash>      | 2019-03-12 15:48:02+00        | t            | alan     |            |           |       | t        | t         | 2019-03-12 15:47:19+00
(2 rows)

Conclusion Child environments inherit service visibility from their parents, but to ensure that development changes do not affect a production environment, updates and synchronizations do not occur in the opposite direction. If a change is made in a development environment that is desired on master, the Upsun CLI can be used to migrate those changes by either creating and restoring a snapshot to the target environment or by manually dumping a database and piping the dump file into the target environment.