> ## Documentation Index
> Fetch the complete documentation index at: https://doc.trycapsule.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL / MariaDB

> Connect and back up MySQL and MariaDB databases with Capsule.

## Required tools

Capsule uses `mysqldump` to create backups and `mysql` to restore them.

<Tabs>
  <Tab title="Debian / Ubuntu">
    ```bash theme={null}
    sudo apt-get install mysql-client
    ```

    For MariaDB:

    ```bash theme={null}
    sudo apt-get install mariadb-client
    ```
  </Tab>

  <Tab title="RHEL / CentOS / Amazon Linux">
    ```bash theme={null}
    sudo dnf install mysql
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    brew install mysql-client && brew link --force mysql-client
    ```
  </Tab>
</Tabs>

Verify:

```bash theme={null}
capsule doctor
```

***

## Connection details

| Field         | Example                   |
| ------------- | ------------------------- |
| Host          | `localhost` or `10.0.0.5` |
| Port          | `3306`                    |
| Database name | `myapp_production`        |
| Username      | `myapp_user`              |
| Password      | your database password    |

***

## Authentication

How Capsule passes your password to `mysqldump` depends on whether the connection is Docker-based or native:

* **Native** (MySQL running directly on the server): Capsule writes a temporary MySQL options file (mode `0600`, readable only by the process that created it) containing your password, passes it to `mysqldump` via `--defaults-file`, and deletes it immediately after the backup completes. This mirrors how Capsule handles PostgreSQL passwords via a temporary `.pgpass` file.
* **Docker**: `docker exec` can't read a config file sitting on the host filesystem, so Capsule instead injects the password as the `MYSQL_PWD` environment variable directly into the container process.

Either way, the password never ends up in the process list (`ps aux`) and is not left on disk after the backup finishes.

***

## Dump flags

Capsule runs `mysqldump` with no extra consistency flags, which means it takes table locks while dumping — on a busy production database, this can briefly block writes during the backup window. If your tables are InnoDB and you need a lock-free, consistent snapshot, run backups during a low-traffic window until this is configurable.

***

## Docker

If MySQL runs in a Docker container, enter the container name in the Docker field when adding the connection. Capsule will exec into the container to run `mysqldump`, so no host-side MySQL tools are needed.

See [Docker containers](/databases/docker) for details.

***

## Troubleshooting

**`Access denied for user`**

* Confirm the username and password are correct
* Make sure the user has `SELECT`, `LOCK TABLES`, `SHOW VIEW`, `EVENT`, and `TRIGGER` privileges on the target database

**`mysqldump: command not found`**

Install MySQL client tools and run `capsule doctor` to confirm.

**MariaDB**

MariaDB is fully supported. The `mysqldump` binary shipped with MariaDB works identically for Capsule's purposes.