Configuring settings and databases

Configuration Overview

All configuration files are located in ~/.mage-db-sync/config

---

Settings Configuration

Location

config/settings.json

Required Parameters

General Settings

• localDomainExtension - Domain extension for your local development environment (e.g., .development)
• elasticsearchPort - Port number for ElasticSearch on your local environment (e.g., 9200)
• databaseLocation - Full path to the database download folder

Admin Configuration

• adminUsername - Default admin username for Magento backend
• adminPassword - Default admin password for Magento backend
• adminEmailAddress - Default admin email address

Optional Parameters

SSH Settings

• keyLocation - Full path to your SSH private key (auto-detected if empty)
• passphrase - SSH key passphrase (if applicable)

Example Configuration

{
  "general": {
    "localDomainExtension": ".development",
    "elasticsearchPort": "9200",
    "databaseLocation": "/Users/{username}/Databases"
  },
  "ssh": {
    "keyLocation": "{full path to SSH key folder}",
    "passphrase": "{optional passphrase for SSH}"
  },
  "magentoBackend": {
    "adminUsername": "admin",
    "adminPassword": "Password1!",
    "adminEmailAddress": "[email protected]"
  }
}

---

Database Configuration

Location

• config/databases/production.json
• config/databases/staging.json

Required Parameters

• username - SSH username for server access
• server - Server hostname or IP address
• domainFolder - Domain folder path on the server
• port - SSH port number

Optional Parameters

• password - SSH password (if required)
• localProjectFolder - Path to local Magento root directory
• externalProjectFolder - Full path to external Magento root (overrides domainFolder)
• externalPhpPath - Custom PHP path on server (use when user PHP version differs from server)
• localProjectUrl - Custom local development URL (defaults to: {project folder name}{localDomainExtension})
• wordpress - Set to true to synchronize WordPress database (default: false)
• commandsFolder - Directory containing custom commands (searches for magerun2.txt or database.txt)
• sshKeyName - Custom SSH key name (searches in ~/.ssh/)
• stagingUsername - Reference to staging environment username

Example Configuration

{
  "databases": {
    "production-username-1-placeholder": {
      "username": "example1",
      "password": "",
      "server": "example1.io",
      "domainFolder": "example1.io",
      "port": "2222",
      "localProjectFolder": "",
      "externalProjectFolder": "",
      "externalPhpPath": "",
      "localProjectUrl": "example1.development",
      "wordpress": false,
      "commandsFolder": "commands/example-project",
      "stagingUsername": "staging-username-1-placeholder",
      "sshKeyName": "id_ed25519"
    },
    "production-username-2-placeholder": {
      "username": "example2",
      "password": "",
      "server": "example2.io",
      "domainFolder": "example2.io",
      "port": "2222",
      "localProjectFolder": "",
      "externalProjectFolder": "",
      "externalPhpPath": "",
      "localProjectUrl": "example2.development",
      "wordpress": false,
      "commandsFolder": "commands/example-project",
      "stagingUsername": "staging-username-2-placeholder",
      "sshKeyName": "id_ed25519"
    }
  }
}

---

Project Commands (Optional)

When a project is configured with a commandsFolder, mage-db-sync will search for custom command files relative to the config/databases folder.

Supported Command Files

database.txt

SQL queries to execute during database configuration.

Important: Use double quotes as shown in the example.

UPDATE core_config_data SET `value` = "http://github.com/jellesiderius/mage-db-sync" WHERE `path` = "web/unsecure/base_url";
UPDATE core_config_data SET `value` = "https://github.com/jellesiderius/mage-db-sync" WHERE `path` = "web/secure/base_url";

magerun2.txt

Magerun2 commands to execute during configuration.

magerun2 sys:cron:run sitemap_generate;
magerun2 sys:cron:run consumers_runner;

---

Quick Reference

File Structure

~/.mage-db-sync/
└── config/
    ├── settings.json
    └── databases/
        ├── production.json
        ├── staging.json
        └── commands/
            └── example-project/
                ├── database.txt
                └── magerun2.txt

Configuration Priority

1. Project-specific settings override global settings
2. externalProjectFolder overrides domainFolder
3. localProjectUrl overrides auto-generated URL
4. sshKeyName overrides global keyLocation