Using External Database - rtCamp/Frappe-Manager GitHub Wiki

By default, FM uses its global-db service as the central database for all benches. However, you can configure FM to use an external database.

Database User Requirements

Create a user with access from any host (%) since requests will come from Docker containers with dynamic IPs
For Frappe v15 and lower: database username must match database name
For Frappe v16+: you can specify custom username using db_user parameter in site_config.json

Example SQL commands for your external database:

CREATE DATABASE your_database_name;
CREATE USER 'username'@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON your_database_name.* TO 'username'@'%';
FLUSH PRIVILEGES;

Migrating from Internal to External Database

1. Backup Internal Database

First backup your site while it's still using the internal database:

fm shell <sitename>
bench backup

The backup will be stored in ~/frappe/sites/<sitename>/workspace/frappe-bench/sites/<sitename>/private/backups

2. Stop Services

fm shell <sitename>
bench stop

3. Configure External Database

Edit your site's configuration in ~/frappe/sites/<sitename>/workspace/frappe-bench/sites/<sitename>/site_config.json:

⚠️ For Secure Database Connections: If you need to configure TLS/SSL or other advanced database connection settings, refer to Frappe's Remote Database Configuration Documentation.

{
  "db_host": "your-external-db-host",
  "db_port": 3306,
  "db_type": "mariadb",
  "db_name": "your_database_name",
  "db_password": "your_password"
}

4. Start Services

fm shell <sitename>
bench restart

5. Restore Data to External Database

fm shell <sitename>
bench --site <sitename> restore <backup-file>

If you don't want any data then after changing the db

fm shell <sitename>
bench --site <sitename> reset

Important Notes

Ensure your external database server is configured to accept connections from your FM container network
Test the database connection before proceeding with migration
Keep a backup of your data until you've verified the migration was successful