ERPNext MariaDB performance tuning

Why ERPNext MariaDB performance tuning starts with the working set

Database tuning should start from the data your site actually touches, not from a generic server size. When a desk page loads slowly, a save stalls or a General Ledger report times out, the cause is often MariaDB working through many small queries that Frappe issues for each document, link field and list view. Memory settings such as the InnoDB buffer pool decide whether those reads come from memory or from disk, so they shape response time directly. The right values depend on the size of the hot tables, the indexes queries use and how many users and background jobs run at the same time. Before changing any setting, measure which tables and indexes are actually read during the slow operation.

This work is needed when a running site slows down as data grows, when a new company or module adds large ledgers, or when a team moves to a bigger server and wants to size memory on evidence. Confirm which ERPNext version you run first. Frappe's supported versions page lists version 15 as supported until the end of 2027 and version 16 until the end of 2029, and version 14 reached end of life on January 31, 2026. Tuning also depends on your version's query patterns, so check the release notes before copying settings from older guides. Your DBA or platform team should confirm MariaDB version compatibility for your bench.

Tuning is one lever among several. A slow page is often caused by a specific query, a report that needs a prepared run, or a background job competing for the same resources. Use query profiling to find the statements responsible, adjust reports to run in the background, and treat database settings as the step that makes the remaining work fast enough to be stable. Changing memory settings without that diagnosis can hide a design problem until the data grows again.

ERPNext MariaDB performance tuning options and when each fits

This table compares the MariaDB and Frappe settings that most affect ERPNext database speed, with the signal that suggests changing each one and the risk of changing it without a baseline. Read each row as a question to answer with your own measurements before editing any value. Exact values come from the MariaDB and Frappe documentation and your own tests, not from this page.

Setting	What it controls	Signal that suggests changing it	Risk without a baseline
InnoDB buffer pool size	How much table and index data MariaDB caches in memory for ERPNext sites	Hit ratio and disk reads stay poor while the server has free RAM, and heavy GL or stock reports read the same pages repeatedly	Starving the OS and Redis or workers of memory, which causes swapping and slower requests
Buffer pool instances	How the buffer pool is split to reduce lock contention under concurrent access	Contention appears on busy multi-worker benches, and the pool is large enough to split	Little benefit on small pools, and more instances can complicate tuning without a measured gain
Connection limits (max connections)	How many simultaneous client sessions MariaDB accepts from web workers, background workers and the scheduler	Connection errors or a rising thread count during peak hours, with workers queuing	Raising the limit lets more queries run at once, which can increase memory use and lock waits
Query cache stance	Whether MariaDB caches query results; it is generally not a recommended setting for write-heavy ERPNext workloads	Confirm in the MariaDB documentation for your version before changing anything	Enabling it on a write-heavy site can add overhead and invalidation cost, so it is usually left alone
Temporary table and sort memory	Memory per session for temp tables and sorts used by reports, grouping and ordering	Reports write temp tables to disk, or sort buffers spill during General Ledger or stock queries	Per-session values multiply by concurrent connections, so large values can exhaust RAM under load
Slow query log	Records queries above a time threshold so you can find the SQL behind slow pages and reports	Users report slow saves or reports and you need the exact statements to fix or index	Logging every query adds I/O and log growth; keep thresholds and retention deliberate
I/O settings (flush and log file size)	How often InnoDB writes changes and how large the redo log is, which affects write latency and crash recovery time	Write latency spikes during bulk imports, reposts or heavy submit activity	Relaxing durability to gain speed can lose recent transactions after a crash, which matters for accounting data
Swap and kernel memory policy	How the operating system uses swap when memory is tight, and whether the database is swapped out	Swap activity rises during peaks or the database shows latency while memory is nominally available	Disabling swap entirely can trigger out-of-memory kills, while heavy swapping makes database latency unpredictable

Sizing the InnoDB buffer pool from the working set

The InnoDB buffer pool should hold the hot part of the data and indexes that ERPNext reads repeatedly, not the whole database by default. A database of tens of gigabytes may only need a fraction of that in memory if most desk pages, list views and reports touch a narrow set of recent General Ledger, stock and sales rows. Measure that working set under real traffic over a representative period, and make sure the period includes month-end and quarter-end closing, when report and reconciliation queries hit older rows and the pool is tested hardest. A window that only covers quiet weeks will undersize the pool and hide the problem until close week.

Memory has to be divided before the buffer pool is set. Reserve room for the operating system, the Redis instances that Frappe uses for cache and queues, the background workers and scheduler, and the Gunicorn web processes, then give InnoDB what remains with a margin for connections and temporary tables. Multiple sites on one database server change this calculation, because each site adds tables, indexes and query patterns to the same pool, and background jobs for every site compete for the same memory. Confirm the sizing rules, any guidance on buffer pool instances, and the recommended memory per process in the MariaDB documentation for your version and in Frappe's deployment guidance for the ERPNext release you run before you write these values into your configuration, and test the result on a copy of production data.

Tuning by deployment path: bench on Linux, Docker Compose or Frappe Cloud

With a bench installation on Linux, your team owns the MariaDB server, its configuration file and the host memory it shares with Gunicorn, background workers, the scheduler, Redis and any other services. Tuning is a host-level task: you choose settings in the server configuration, restart the database service and verify the result on the host. Because the same machine runs the application tier, memory decisions must account for every process, not only the database.

Configuration file: Database settings go in a MariaDB configuration file under your control, such as a file in the server's configuration directory, so they survive package upgrades.
Buffer pool sizing: The InnoDB buffer pool is set on the host, so size it from the working set of your largest sites and leave memory for workers and the operating system.
Swap behavior: Swap policy is a kernel and host setting, so review it alongside the database settings rather than leaving the defaults untouched.
Change control: Record each change, restart the service in a maintenance window and keep a copy of the previous configuration for rollback.
Monitoring: Watch hit ratio and utilization on the same host where the workers run, since a change that helps the database can starve the application tier.

Before changing anything, confirm the current values on the server and the memory each service uses at peak load.

Reading hit ratio and utilization without chasing false signals

Database dashboards show many numbers that look alarming out of context. The cards below pair each MariaDB signal with the misreading it invites and the check that confirms the actual cause. Set thresholds from your own baselines, measured on your ERPNext sites during normal month-end and peak load, rather than from generic rules of thumb.

Buffer pool hit ratio

The hit ratio shows how often InnoDB reads a page from memory instead of disk. For ERPNext, a healthy-looking average can hide a few expensive General Ledger or stock queries that scan large ranges on every run. The misreading to avoid is treating a high ratio as proof the database is fast. Confirm the cause with the slow query log, which shows the statements that dominate reads, and compare the ratio across quiet and month-end windows.

Buffer pool utilization

Utilization shows how much of the configured buffer pool holds pages. A pool that fills and stays full is expected on a busy site, so a high number alone does not call for a bigger pool. The misreading is resizing on utilization without knowing the working set. Check whether the data and indexes that ERPNext touches daily fit in memory, and whether other services on the same host are competing for RAM before changing innodb_buffer_pool_size.

Connection counts and wait time

Connection counts show how many sessions are open, and wait time shows how long work queues for locks or resources. Frappe workers, the scheduler and web processes all hold connections, so a rising count may just reflect more background jobs. The misreading is raising max_connections to clear errors that actually come from lock waits. Confirm with the lock wait and thread state views during the slow period, and check whether long-running imports or reposts hold locks.

Slow query log output

The slow query log records statements above a configured execution time, which makes it the most direct evidence of where time goes. Each entry needs context, because one repeated query matters more than one rare outlier. The misreading is tuning settings for the slowest single entry while a frequent, moderately slow query drives most load. Group entries by statement pattern, then use Frappe Recorder or EXPLAIN on the top patterns to confirm whether an index or the query itself is the fix.

Disk I/O and temporary table spill

Disk I/O shows how much data moves to and from storage, and temporary table spill shows when sorts or joins outgrow memory and land on disk. Spilled temporary tables are common in large report queries and can look like a storage problem. The misreading is buying faster disks before confirming that the I/O comes from reports rather than checkpoints or log writes. Check the temporary table counters and the largest queries in the slow log, and review whether the heavy reports belong in prepared report jobs.

Swap activity on the database host

Swap activity shows whether the operating system is paging memory to disk. Even a small amount of swapping under an InnoDB workload can make query latency erratic, while the database metrics still look normal. The misreading is assuming the database caused the stall when the host is short of memory for other processes. Confirm with host-level memory and swap counters alongside the MariaDB settings for swappiness and buffer sizes, and check whether background workers or other services share the same machine.

Swap and memory: why swapping a database hurts more than slow disks

Swapping the MariaDB process is worse than a slow disk because the database expects its buffer pool to stay in RAM. When pages of the InnoDB buffer pool are pushed to swap, every query that touches them waits on the kernel to bring them back, and the stall is felt by every ERPNext site on the host, not only the one running the heavy report. A single runaway reporting job on one bench can therefore slow down general ledger posting for all tenants that share the same MariaDB server. Treat swap activity on the database host as an incident signal, not as normal background noise, and check it alongside the buffer pool hit ratio you are already tracking.

Swappiness and overcommit are host-level kernel settings, so they are shared by MariaDB, Redis, the Frappe workers and anything else on the machine. They interact directly with the buffer pool: if you size innodb_buffer_pool_size close to total RAM and the kernel is then allowed to overcommit or to swap aggressively, the database can be paged out long before memory looks exhausted. Lowering swappiness and setting overcommit deliberately are reasonable steps, but they should be decided together with the buffer pool size and the memory used by the other services on the same host, and the combined budget should be written down.

Keeping a small swap area is a trade-off. Without any swap, the kernel's out-of-memory killer may end the mysqld process outright when a memory spike hits, which means an unclean restart and a recovery cycle for every site. A small swap gives the system room to absorb a short spike, but it can also hide a slow leak or an oversized buffer pool until performance falls apart. Confirm the current Linux kernel guidance on swappiness and overcommit, and the defaults your distribution ships, before you change anything, because these defaults differ between releases and between distributions. Then test the change on a staging host with a representative ERPNext load and record how the server behaves under pressure.

ERPNext MariaDB performance tuning setup in order

This sequence moves ERPNext's database from guesswork to measured tuning, so each MariaDB change is traceable to a baseline, tested on the same work, and reversible if it does not help.

Verify backups before any change
Before touching the database, the operations owner confirms that a recent full backup of the ERPNext sites exists and that a restore has been tested on a separate host. Anyone planning a restart should also know how to restore the previous configuration file. The step is done when the team can name the backup file, its timestamp and the host where a restore was last rehearsed. Confirm backup scope with your own runbook, since the Frappe backup command and any database-level dumps may be configured differently in your environment.
Capture a baseline on a copy or quiet window
The team records how the database behaves now, either on a restored copy of production or during a low-traffic window on the live system. They note CPU, memory, disk I/O, active connections and the timings of a fixed set of transactions, such as a sales invoice submit, a stock ledger report and a General Ledger run for a known period. The step is complete when these timings are written down with the date, ERPNext version and data volume, so later results can be compared against the same work.
Enable slow query log and record a representative day
The administrator turns on MariaDB's slow query log with a threshold the team agrees on, and lets it run through a normal working day, including scheduled jobs and month-end or period-close activity if those occur. The log file location and rotation should be checked so it does not fill the disk. The step is done when the team has a log covering peak hours and can group the most frequent and most expensive statements, which usually point to missing indexes or heavy reports rather than to a single setting.
Size buffer pool from measured working set
Using the baseline and the slow query data, the administrator estimates the working set, meaning the data and index pages that are actually read repeatedly, and compares it with the current InnoDB buffer pool size. The buffer pool value is set in the server configuration, and related memory settings are reviewed for the total memory of the host, including what Redis, workers and the web processes need. The step is done when the planned values are documented with the reasoning behind them. Confirm the sizing approach with your DBA or the MariaDB documentation for your version.
Change one setting and restart in a window
The administrator applies a single change from the plan, such as the buffer pool size, and performs the restart during an agreed window while the team watches the service. Changing several settings at once makes it impossible to know which one helped or harmed. The step is complete when MariaDB starts cleanly and the team has confirmed the new value is active by querying the server variables rather than trusting the configuration file alone.
Check error logs and active values after restart
After the restart, the team reads the MariaDB error log for warnings about memory allocation, deprecated options or failed startup checks, and confirms the changed variable with a status query. They also confirm that ERPNext sites load and that background workers reconnect. The step is done when the error log shows no new warnings related to the change and the variable reports the intended value, which proves the change applied rather than being silently ignored.
Rerun the same reports and saves
The team repeats the exact transactions from the baseline in the same order, on the same data, and records new timings alongside the old ones. They look at the slow query log for the same statements and at buffer pool hit and utilization figures over the same period. The step is complete when the comparison shows whether the change improved the chosen transactions, did nothing, or made something worse, and the results are recorded for the next decision.
Keep the previous configuration for rollback
Before each change, the administrator saves a copy of the prior configuration file and notes the exact value it replaced. If the comparison shows regression or the error log shows problems, the team restores that file and restarts under the same controlled window. The step is done when the rollback procedure has been written down, the previous file is stored with the change record, and the team knows which settings are next in the queue. Each later setting follows the same cycle, starting again at the baseline step.

Security and operational risks in database tuning

Database tuning changes how ERPNext behaves under load, and it also changes what an attacker, an operator or a bad restart can do to your data. The cards below cover the access, data exposure, change records, recovery checks, replica effects and alerts that should be settled before any MariaDB value is changed on a running ERPNext.

Privileged access to MariaDB configuration

Anyone who can edit the MariaDB server configuration or restart the service can change durability, memory and authentication settings for every ERPNext site on the server. Limit root and configuration file access to named administrators, keep the Frappe database user scoped to its own schemas, and review who holds shell access to database hosts. Ask your partner or internal team to list every account that can change my.cnf or the systemd unit before the first tuning change.

Slow query log exposure

The slow query log records full SQL text, and ERPNext queries can include customer names, bank details, salary or tax identifiers passed as literal values. Decide whether the slow log is enabled, where it is written, how long it is kept and who can read it. Restrict file permissions, exclude the log from shared support bundles, and rotate it on the same schedule as other production logs.

Change control for each tuned value

Every changed setting, such as innodb_buffer_pool_size, innodb_flush_log_at_trx_commit or max_connections, should have a recorded old value, new value, reason and approver. Keep the configuration in version control so the running state can be compared with the approved state. Without this record, a later slowdown is hard to trace back to a specific change, and rollback becomes guesswork.

Backup and restore testing after restarts

A restart that applies new buffer pool or log file settings is the moment a backup problem is most likely to surface. Confirm that backups complete after each change and that a test restore of a recent ERPNext site opens, migrates cleanly and passes a basic document check. Record the time the restore took, since it sets the realistic recovery window for your team.

Effects on replicas and read routing

If you run a MariaDB replica for heavy reports, a tuned primary can change replication lag, binary log volume and the timing of queries routed to the replica. Test replication after each change to buffer, log or parallelism settings, and confirm that replica credentials and site routing still point where you expect. Changes that look safe on the primary can leave reports reading stale data.

Maintenance windows and configuration drift

Some MariaDB settings take effect only after a restart, and a restart interrupts every site and background job on that database. Schedule a maintenance window, pause scheduled jobs and announce the outage to users in advance. Also compare the MariaDB-related settings on web, worker and scheduler hosts, because a worker pointed at a different server or with different limits can produce failures that appear only under load.

Memory pressure and connection alerts

Set alerts on buffer pool and host memory use, swap activity, active connection counts against max_connections, and aborted connections. Connection saturation often shows first as slow page loads and worker timeouts rather than as database errors, so alerts on the database alone can miss it. Agree the thresholds with the team that owns the host and review them after each tuning change.

Questions teams ask before tuning ERPNext's database

How much does MariaDB tuning for ERPNext cost and what drives the price?

Tuning is priced from the written scope, so no figure can be given here. The main cost drivers are the number of sites sharing one database server, the data volume, how many heavy reports run during business hours, and whether ERPNext runs on Frappe Cloud or on infrastructure you control. A quote should separate the one-time work (baseline capture, configuration changes, verification and a runbook) from any recurring work such as monitoring reviews or retainer support. Ask the partner to state which of the server metrics and slow-query data they expect you to export, because that data is what most of the effort depends on.

How long does a first ERPNext database tuning cycle usually take?

The duration depends on how much baseline data already exists and how many change windows you can use. A cycle usually has four parts: capturing a baseline, changing settings in small steps, measuring the effect on real pages and reports, and documenting the result. Each change needs a quiet period long enough to see its effect under normal load, so the calendar time is often set by your release and maintenance calendar more than by the work itself. Ask for the schedule in writing, with the number of change windows assumed and the acceptance measures agreed before work begins.

What must our team provide before a database tuning engagement starts?

Your team needs to provide the following before work starts:

Read access to the database server metrics, the MariaDB configuration files and the bench or Docker setup for each site
A representative period of normal traffic, including month-end or quarter-end runs if those are your heavy periods
Agreed maintenance windows for restarts and configuration changes, with a rollback plan
Recent backup evidence showing that a restore has been tested, not just that backups run

Without the traffic sample, tuning decisions rest on guesses about the working set. Confirm with your partner exactly which accounts and tools they need access through, since that affects your security review.

Can an internal engineer tune ERPNext's MariaDB alone using the MariaDB documentation?

A capable database engineer can make progress with the MariaDB documentation, but ERPNext adds Frappe-specific behavior that generic guidance does not cover, such as how background workers, the scheduler and report queries share the same database. The main risk is changing a global setting that helps one site and hurts another. Internal teams usually succeed when they have someone who owns the database, a test copy of production data, a way to replay representative load and time for careful measurement. If those conditions are missing, a short external review of your settings and baseline is often a lower-risk first step.

When should we profile slow queries or add a read replica instead of tuning settings?

Tune settings first when the server is consistently short of memory, disk or connections across many pages. Profile queries first when one or two pages or saves are slow even though server metrics look healthy, because the fix is usually an index or a changed query rather than a configuration value. A read replica becomes the better step when heavy reports compete with transactional work on the primary database and vertical scaling is no longer enough. Ask your partner to show the evidence that points to each path, since the three options often overlap in the same incident.

What does Frappe Cloud support or a support plan change for database tuning?

On Frappe Cloud, the hosting provider manages the infrastructure, so the scope of tuning is narrower and depends on what that platform exposes to you. Frappe's supported versions policy states that customers must be on a listed version and subscribed to a matching Frappe Cloud support plan to receive warranty coverage from Frappe. Confirm with Frappe what changes to database settings are possible on your hosting tier and what support covers them. Self-hosted ERPNext gives you full control of MariaDB settings but also full responsibility for backups, upgrades and monitoring.

Which ERPNext version should we be on before tuning the database?

Tune against a version that is still supported, because query behavior and database access patterns change between releases. Frappe's supported versions page lists version 14 as end of life from January 31, 2026, with version 15 planned to be supported until the end of 2027 and version 16 until the end of 2029. Frequent minor releases on both supported lines also change query plans and fixes. Ask the partner to record the exact ERPNext and Frappe versions in the baseline so that later measurements can be compared fairly.

Limits to confirm in your environment

Tuning MariaDB for ERPNext depends on constraints that sit outside the database: the versions you run, the hosting plan you bought, the memory and disk on the host, and the support terms behind your site. Confirm these before you agree on a change plan, because each one can rule out a setting or change who is responsible when something breaks.

MariaDB version and supported keys

The configuration keys that matter for Frappe depend on the MariaDB release your ERPNext version is built and tested against. Ask your vendor or DBA which MariaDB major version the bench or Docker images ship with, and confirm that each setting you plan to change exists and behaves as documented in that release. A key that is valid in one major version may be renamed, deprecated or ignored in another, so write the exact version into the change ticket next to each setting.

Server-level change permission

Buffer pool sizing, swap behavior and some MariaDB options live in the server configuration, not in ERPNext's site configuration. On Frappe Cloud and other managed plans, you may not have shell or root access to change them at all. Ask whether your plan permits server-level changes, who applies them, whether a restart is needed, and how a rollback works if a change degrades performance.

ERPNext support window

The support window determines how long your tuning baseline stays valid before you must upgrade. Version 15 is planned for support until the end of 2027, and version 16 until the end of 2029. Version 14 has already reached end of life. Confirm which version you run, when it leaves support, and whether a database engine change or Frappe upgrade is expected in that window, so that tuning work is not repeated after an upgrade changes query patterns.

Warranty and Frappe Cloud support plan

Frappe's supported versions policy ties warranty coverage to running a listed version and holding a matching Frappe Cloud support plan. If you tune MariaDB outside what Frappe supports, or on a plan without the matching subscription, you may lose the warranty path for database problems. Ask your vendor to confirm in writing which settings fall inside supported configuration, and whether your current plan covers the version you run.

Host memory and disk capacity

Buffer pool sizing depends on how much RAM the host has after the operating system, Redis, background workers, the scheduler and web workers take their share. Disk speed and free space also limit how much data the database can cache and how fast backups run. Ask for the total RAM, the memory used by each Frappe service at peak, the storage type and IOPS, and the current size of the largest site database, so the buffer pool is set from measured numbers.

Query problems versus server tuning

Server settings cannot fix a report that scans an unindexed table or a save that runs hundreds of redundant queries. Before you expect tuning to solve a slow page, ask your team or DBA to show the top queries by total time, and whether the slow path is a missing index, a heavy report or a background job competing for the same resources. If the query pattern is the cause, the fix belongs in ERPNext code, indexes or report design, and tuning only changes the ceiling.

How DeployOpen scopes and delivers ERPNext database tuning

DeployOpen plans, implements, tests and documents ERPNext inside your own infrastructure, including the MariaDB settings that shape how Frappe performs. Work starts from a written scope, and the tuning changes are measured, recorded and handed over so your team can run them after the engagement ends.

How we scope

Engagements are fixed-scope, with the sites, database servers and workloads covered written down before work starts.
We review your current MariaDB version, Frappe bench layout and hosting model to confirm which settings apply to your setup.
The written scope names the monitoring data you need to provide, such as hit ratio and utilization history from the current server.

How we build

We size the InnoDB buffer pool against the measured working set of your largest sites, not against a fixed default.
Each change to the server configuration is applied in a staging copy first, with a rollback step recorded before production work begins.
We check swap behavior, connection limits and temporary table settings together, since they interact with the buffer pool under load.

How we hand over

You receive the final configuration files, the reasoning for each value and the monitoring queries used to confirm the results.
The handover includes a short runbook that lists which metrics to watch, the thresholds that should prompt review and who acts on them.
Your team walks through the changes with us so the people who will run the database can explain each setting later.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after the initial tuning work is complete.
A retainer can cover periodic review of hit ratio and utilization trends as your data grows and ERPNext versions change.
Support requests for performance issues follow the response terms agreed in the written contract, which you can review before signing.