Introduction: Why Read from a Secondary Database in Frappe?

Reading from a secondary database allows Frappe applications to scale efficiently by separating read-heavy workloads from write operations. In high-traffic ERPNext deployments, dashboards, reports, and API calls often generate a large number of read queries that can overload the primary database.

Frappe Framework v15 supports read replication, enabling applications to execute read queries against a replica (secondary) MariaDB database while all write operations continue on the primary database. This improves performance, reduces latency, and enhances system stability.

What Is a Secondary Database in Frappe?

A secondary database (also called a read replica) is a replicated MariaDB instance that continuously syncs data from the primary database. Frappe can be configured to route read-only queries to this replica automatically.

Key characteristics:

• Primary DB → Handles writes (INSERT, UPDATE, DELETE)
• Secondary DB → Handles reads (SELECT)
• Replication → Managed externally at the database level

When Should You Use a Secondary Database?

Using a secondary database is recommended when:

• ERPNext dashboards are slow due to heavy read load
• APIs and reports generate frequent SELECT queries
• Large user base accesses analytics simultaneously
• You want improved fault tolerance and performance

This setup is commonly used in enterprise-scale ERPNext deployments.

Technical Prerequisites

Before configuring Frappe:

• Frappe Framework Version 15
• MariaDB replication already configured
• Read-only replica database accessible from Frappe server
• Bench environment with access to site_config.json

Frappe does not configure replication—it only consumes it.

How Frappe Handles Database Reads Internally

Frappe uses database routing logic to decide whether a query should hit:

• the primary database, or
• the secondary database

Only safe read-only operations are routed to the replica. Any query inside a transaction or involving writes always uses the primary database.

Step-by-Step: Configure Read from Secondary Database

Step 1: Open site_config.json

Navigate to your site configuration file:

sites/{site_name}/site_config.json

Step 2: Add Secondary Database Configuration

Add the following keys (values shown as examples):

{
"secondary_db_host": "replica-db-host",
"secondary_db_port": 3306,
"secondary_db_name": "site_database_name",
"secondary_db_user": "replica_user",
"secondary_db_password": "replica_password"
}

These settings tell Frappe where the replica database is located.

Step 3: Restart Bench

Apply changes by restarting services:

bench restart

Frappe will now establish connections to both databases.

How Frappe Decides Which Database to Use

Frappe automatically routes queries based on execution context:

This ensures data consistency and avoids replication lag issues.

Example: Read Query Routed to Secondary Database

frappe.get_all(
"Sales Invoice",
fields=["name", "customer", "grand_total"]
)

Since this is a read-only SELECT, Frappe executes it on the secondary database automatically.

No code changes are required.

When Reads Will Always Use the Primary Database

Frappe intentionally avoids using the replica when:

• Query is inside frappe.db.transaction
• Query involves FOR UPDATE
• Query modifies data
• Query depends on immediate consistency

This design prevents stale or inconsistent reads.

Best Practices for Using Secondary Databases

• Use replicas for reports, dashboards, APIs
• Avoid running transactional logic on replicas
• Monitor replication lag at database level
• Keep replica read-only
• Use same database schema as primary

Performance Impact and Benefits

Using a secondary database provides:

• Faster report execution
• Reduced load on primary DB
• Improved system responsiveness
• Better scalability for large ERPNext sites

This setup is especially effective for analytics-heavy ERPNext implementations.

Troubleshooting Common Issues

Reads Still Going to Primary DB

Ensure:

• Query is not inside a transaction
• Secondary DB credentials are correct
• Bench has been restarted

Replica Connection Errors

Check:

• Network connectivity
• Database permissions
• MariaDB replication health

Industry Relevance

Secondary database reads are widely used in:

• Large manufacturing ERP systems
• Multi-branch enterprises
• SaaS ERPNext hosting environments
• High-traffic portals and APIs

Target Audience

• ERPNext System Architects
• Frappe Developers
• DevOps Engineers
• Enterprise ERP Administrators

Related Topics

• Frappe Database Transactions
• Query Optimization in ERPNext
• Scaling ERPNext for Enterprise Use
• MariaDB Replication with ERPNext

Conclusion

Frappe Framework v15 provides native support for reading from a secondary database, enabling ERPNext deployments to scale efficiently without compromising data integrity. By routing read-heavy workloads to a replica database, organizations can achieve better performance, reliability, and user experience.

When combined with proper database replication and expert configuration, this feature becomes a powerful tool for enterprise-grade ERPNext scalability.