node package manager
It’s your turn. Help us improve JavaScript. Take the 2017 JavaScript Ecosystem Survey »



A heroku plugin to sync different wordpress environments. Especially to sync databases, ya hear?


  • Heroku cli (
  • MySQL command line client
  • PHP


Installing the plugin is done by running this command:

heroku plugins:install heroku-wp-environment-sync


First you need to create syncfile.json in your project folder. You can create one from a template by running this command:

heroku sync:init

The initialization command will ask you questions and creates a syncfile according to those answers. The syncfile can (and probably have to) be modified by hand afterwards.

Then you need to edit your syncfile.json to correspond the different environments. The search and replaces can be added as many as needed and are defined as followed:

"replaces" : [
        "from" : [
        "to" : "http://localhost"

Every string in the "from" array is changed into the "to" string, so you can funnel multiple urls into one.

You can also use regular expression in the search and replace with the regex -option, like so:

"replaces" : [
        "from" : [
        "to" : "http://localhost",
        "regex" : true

In the syncfile, you need to set the environments that you can sync to as mutable (unless you have specified the --no-mutable-checks -option). Like so:

    "name": "production",
    "app": "production_heroku_app_name"
    "name": "staging",
    "app": "staging_heroku_app_name",
    "mutable": true


To sync your default setup (which, if you created the syncfile using heroku sync:init, is the local), use:

heroku sync:dbsync

If you want to specify the setup, use:

heroku sync:dbsync setup_name

You can also use --to and --from to specify locations, bypassing the setups entirely.

heroku sync:dbsync --from from_environment_name --to to_environment_name

Currently by default, the sync will store a dump to the cache folder which locates in ~/.heroku-wp-environment-sync/cache/. If for some reason you don't want to fetch a fresh dump (for instance, you might have an error in your syncfile search and replaces and after correcting the error you don't need a fresh dump) you can use --use-cache -flag.


To dump a database from an environment in the syncfile, use:

heroku sync:dump environment_name

You can also specify just a app and bypass the syncfile:

heroku sync:dump --app heroku_app_name

Or you can just paste a mysql url, like so:

heroku sync:dump --mysql-url mysql://


To connect to a database, simply type:

heroku sync:connect environment_name

User configurations

User configurations are stored in the ~/.heroku-wp-environment-sync/user_config.json -file. At it's current state, there isn't really that much to configure except the dump caching. The available options are as follows:

    "store_cache" : true
  • store_cache defines if cache are stored. The cache folder is ~/.heroku-wp-environment-sync/cache/.


You can get more information about different commands with the help command. For example:

heroku help sync:dbsync

Also for troubleshooting consider using the --verbose and --more-verbose -flags.


0.3.1 / 4.9.2017

  • Added dump caching for situations where fresh database dump doesn't matter. You can utilize earlier dump by using the --use-cache -flag.
  • Added user configurations for future user specific configurations. For starters, you can modify if the script stores cache.

0.3.0 / 23.8.2017

  • Fixes to bugs conserning initialize and other stuff.
  • More notifications.

0.2.9 / 8.8.2017

  • Made changes to the library structure and refactored a bunch of stuff for the future.
  • Made error reporting more useful and added verbose mode and more-verbose mode for debugging uses.
  • Removed "show-command-outputs" -flag, because of the verbose additions.
  • Added notifications so that if you don't respond to a question in about 1 minute, it will notify you in case you forgot.
  • Added a new feature for cleaning up databases, that creates a home directory (~/.heroku-wp-environment-sync) and a temp database -file in there, that holds the temporary database names for later cleanup. This is useful for example if you exit the process before the cleanup happens, we can clean up the temporary database later.
  • Other bug fixes and changes.