# MariaDB

Source: https://www.storeframe.io/docs/infrastructure/stack/mariadb

Auto-tuned MariaDB with Magento-specific InnoDB settings, dynamic scaling by VM size, and nightly off-site backups.

Each StoreFrame environment runs a dedicated MariaDB container. The database configuration is not fixed — most performance-critical settings are calculated from the VM's actual RAM and vCPU count at provision time. You can override any of these through the environment file (`.env`).

![Hub Containers tab showing the mariadb container](https://www.storeframe.io/assets/docs/infrastructure/containerized-stack/hub-containers-tab-showing-mariadb-container.png)

## Version

MariaDB version is pinned per Magento release and tracks the versions Adobe Commerce certifies:

| Magento release | MariaDB version |
| --------------- | --------------- |
| 2.4.9           | 11.4            |
| 2.4.8           | 11.4            |
| 2.4.7           | 10.11           |
| 2.4.6           | 10.11           |
| 2.4.5           | 10.6            |
| 2.4.4           | 10.6            |
| Mage-OS 3.x     | 11.4            |

The default for new environments uses the MariaDB version matching the selected Magento release. You can pin a specific version in `.env`:

```bash
CONTAINERS__MARIADB_VERSION='11.4'
```

## Auto-tuning

The three main dynamic settings are derived from the VM's total RAM at provision time:

### InnoDB buffer pool

```
innodb_buffer_pool_size = floor(RAM × 30%) GB   (minimum 1 GB)
```

On a shared-stack VM (PHP + MariaDB + OpenSearch all on the same host), 30% leaves enough headroom for PHP workers (35%), OpenSearch's JVM heap, Redis, and the OS page cache. If you are running MariaDB on a dedicated database host you can safely increase this to 70–80% of RAM.

`innodb_buffer_pool_instances` is set to the number of vCPUs. Each instance manages a separate segment of the buffer pool, reducing mutex contention under concurrent writes.

### InnoDB log file size

```
innodb_log_file_size = clamp(RAM × 2%, 256 MB, 4 GB)
```

A larger redo log lets InnoDB absorb write bursts without stalling. Magento's catalog import and indexing operations produce sustained write loads — the log file needs to be large enough to buffer a full indexing run without flushing too frequently.

### Temporary table size

```
tmp_table_size = max_heap_table_size = clamp(RAM × 0.8%, 64 MB, 512 MB)
```

Magento's EAV queries and layered navigation frequently sort large intermediate result sets. Keeping temp tables in memory avoids disk I/O for those joins.

## Magento-specific settings

Beyond the dynamic sizing, several fixed settings address known Magento behaviour:

| Setting                                | Value  | Reason                                                                                                       |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `max_connections`                      | 1000   | Magento opens many concurrent short-lived connections                                                        |
| `innodb_flush_log_at_trx_commit`       | 2      | Flush log to OS once per second rather than per-commit; safe for replicated setups, acceptable for single-VM |
| `innodb_thread_concurrency`            | 0      | Let InnoDB manage its own concurrency (recommended for modern hardware)                                      |
| `innodb_io_capacity`                   | 3000   | Tuned for SSD-backed cloud storage                                                                           |
| `innodb_io_capacity_max`               | 6000   | Burst ceiling for I/O-intensive operations                                                                   |
| `innodb_stats_on_metadata`             | 0      | Prevents SHOW TABLE STATUS from triggering stats recalculation                                               |
| `innodb_print_all_deadlocks`           | 1      | Log all deadlocks to the error log for debugging                                                             |
| `table_open_cache`                     | 4000   | Magento's schema has hundreds of tables                                                                      |
| `skip_name_resolve`                    | 1      | Skip reverse DNS lookups on connections; speeds up connection establishment                                  |
| `wait_timeout` / `interactive_timeout` | 7200 s | Matches PHP's `max_execution_time` to prevent connection drops during long operations                        |
| `expire_logs_days`                     | 1      | Binary logs expire after 1 day (binary logging is off by default on single-VM setups)                        |
| `join_buffer_size`                     | 2 MB   | Improves performance on large JOINs common in Magento's EAV queries                                          |

## Network access

MariaDB is not reachable from the internet. Containers reach it by name (`mariadb`) over the environment's private Docker network, and on the VM itself it listens on localhost only.

From the VM host, the `mysql` command connects to the database for you:

```bash
# From the VM host
mysql <database>
```

Replace `<database>` with your environment's database name, which is stored as `MAGENTO_MARIADB__MARIADB_NAME` in `.env`.

For remote access from your local machine, use the Hub terminal or an SSH tunnel through the VM.

## Overriding settings

You can override MariaDB settings with `MAGENTO_MARIADB__` keys in `.env`. For example, to set the buffer pool size yourself:

```bash
MAGENTO_MARIADB__INNODB_BUFFER_POOL_SIZE='8G'
```

If your modules use more memory per request, raise `PHP__PHP_AVG_WORKER_MB` so fewer PHP workers compete with MariaDB for RAM.

```bash
PHP__PHP_AVG_WORKER_MB='384'
```

After editing `.env`, open the environment's **Containers** tab and choose **⋯ → Install** on the MariaDB container (or the PHP container for `PHP__` settings). Restarting a container does not apply changes. Don't put comments on the same line as a value; the platform reads them as part of the value.

Changing `CONTAINERS__MARIADB_VERSION` upgrades the database in place and can't be undone. Take a dump with `sudo framectl db dump` first.

## Backups

Daily SQL dumps are kept on the VM for 7 days, and older dumps stay available inside the off-site backups. See [Backups](/docs/infrastructure/operations/backups).

The backup uses `mysqldump` with `--single-transaction --quick --no-tablespaces` to produce a consistent hot backup without locking tables.

Restore is via `framectl db restore` on the VM host. It needs an argument:

```bash
sudo framectl db restore --list                           # show the dumps on disk
sudo framectl db restore --latest                         # restore the newest dump
sudo framectl db restore backup_08-01-2026_2211.sql.gz    # restore a specific dump
```

For the full backup and restore flow, see [Backups](/docs/infrastructure/operations/backups).

## Checking database status

From the VM host:

```bash
# Interactive shell
mariadb

# Check InnoDB buffer pool hit rate
mysql -e "SHOW GLOBAL STATUS LIKE 'Innodb_buffer_pool_read%';"

# View current connections
mysql -e "SHOW PROCESSLIST;"

# Check slow query log (if enabled)
docker logs mariadb 2>&1 | grep "Query_time" | tail -20
```

## Full-text search

MariaDB's built-in InnoDB full-text search is not used by Magento on StoreFrame — search is handled by OpenSearch. The `innodb_ft_cache_size` setting is tuned to suppress related log warnings that appear even when FTS is not actively used.
