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

# MariaDB

> Deploy MariaDB to Magic Containers

This guide walks you through deploying MariaDB to Magic Containers, either as a standalone container or as part of a [multi-container](/docs/magic-containers/multi-container.md) app alongside your application.

> [!TIP]
>
> Don't have a bunny.net account yet? [Sign up](https://dash.bunny.net/auth/register) and enable Magic Containers to get started.

## Quickstart

**1. Create a new app**

Go to the [bunny.net dashboard](https://dash.bunny.net), select **Magic Containers**, and click **Add App**. Select **Single region deployment**.

> [!WARNING]
>
> Databases should use single region deployment with a single instance. Each pod gets its own dedicated volume with no data replication — this applies both across regions and within the same region. Scaling to multiple pods or regions would result in separate, isolated databases each with their own data.

**2. Add the MariaDB container**

Click **Add Container** and configure the image:

* **Registry**: Docker Hub
* **Image**: `library/mariadb`
* **Tag**: `11`

Magic Containers will automatically detect the required endpoint and environment variables for the image. Configure the environment variables as needed:

* `MARIADB_ROOT_PASSWORD` = a strong root password
* `MARIADB_USER` = `app`
* `MARIADB_PASSWORD` = a strong password
* `MARIADB_DATABASE` = `app`

**3. Add a persistent volume**

In the **Volumes** section of the container settings, add a volume:

* **Name**: `mariadb-data`
* **Mount path**: `/var/lib/mysql`

This ensures your database files persist across restarts and redeployments. Without a volume, all data is lost when the container stops.

See [persistent volumes](/docs/magic-containers/persistent-volumes.md) for more details on volume behavior and pricing.

**4. Deploy**

Review your settings and click **Confirm and Create**.

> [!NOTE]
>
> Always set strong passwords for `MARIADB_ROOT_PASSWORD` and
> `MARIADB_PASSWORD`, even if the database is not exposed externally. Other
> containers in the same pod can access the network, and a password protects
> against accidental or unauthorized access.

## Environment variables

The official MariaDB image supports these environment variables:

| Variable | Description | Default |
| - | - | - |
| `MARIADB_ROOT_PASSWORD` | Root user password (required) | - |
| `MARIADB_USER` | Additional user to create | - |
| `MARIADB_PASSWORD` | Password for the additional user | - |
| `MARIADB_DATABASE` | Default database created on first start | - |

## Connect from your app

In a [multi-container](/docs/magic-containers/multi-container.md) setup, your app and MariaDB share the same localhost network. Connect using `127.0.0.1` and the default port `3306`.

**Connection string**

```
mysql://app:YOUR_PASSWORD@127.0.0.1:3306/app
```

**Node.js**

```javascript theme={null}
import mysql from "mysql2/promise";

const connection = await mysql.createConnection(
  process.env.DATABASE_URL
);

const [rows] = await connection.execute("SELECT NOW()");
```

**Go**

```go theme={null}
import (
	"database/sql"
	"os"

	_ "github.com/go-sql-driver/mysql"
)

db, err := sql.Open("mysql", os.Getenv("DATABASE_URL"))
if err != nil {
	log.Fatal(err)
}
defer db.Close()
```

**Python**

```python theme={null}
import MySQLdb
import os

conn = MySQLdb.connect(
  host="127.0.0.1",
  user="app",
  passwd=os.environ["MARIADB_PASSWORD"],
  db="app",
)
cur = conn.cursor()
cur.execute("SELECT NOW()")
```

**PHP**

```php theme={null}
<?php

$dsn = "mysql:host=127.0.0.1;port=3306;dbname=app";
$pdo = new PDO($dsn, 'app', getenv('MARIADB_PASSWORD'));

$result = $pdo->query('SELECT NOW()')->fetch();
```

> [!WARNING]
>
> Use `127.0.0.1` instead of `localhost` for the database host. Some clients
> (including PHP/PDO) interpret `localhost` as a Unix socket connection, which
> will fail in a container environment. Using `127.0.0.1` forces a TCP
> connection.

## Multi-container example

A typical setup pairs MariaDB with your application. When configuring the app, add two containers:

### App container

* **Image**: your app image (e.g. `ghcr.io/<your-username>/my-app:latest`)
* **Endpoint**: the port your app listens on
* **Environment variables**:
  * `DATABASE_URL` = `mysql://app:YOUR_PASSWORD@127.0.0.1:3306/app`

### MariaDB container

* **Image**: `library/mariadb:11`
* **Volume**: mount path `/var/lib/mysql`
* **Environment variables**:
  * `MARIADB_ROOT_PASSWORD` = a strong root password
  * `MARIADB_USER` = `app`
  * `MARIADB_PASSWORD` = a strong password
  * `MARIADB_DATABASE` = `app`

> [!NOTE]
>
> Both containers share the same localhost network, so your app connects to
> MariaDB at `127.0.0.1:3306`. See [multi-container
> apps](/docs/magic-containers/multi-container.md) for more details.

## External access

To connect to MariaDB from outside Magic Containers (e.g. from your local terminal), add an [Anycast endpoint](/docs/magic-containers/endpoints.md):

1. Go to your app's **Endpoints** tab and click **Add New Endpoint**
2. Select **Anycast** as the type
3. Set **Container Port** to `3306`
4. Set **Exposed Port** to `3306`
5. Click **Add Endpoint**

Then connect using the Anycast IP and the **exposed port**:

```bash theme={null}
mariadb -h <anycast-ip> -P <exposed-port> -u app -p --database app
```

> [!NOTE]
>
> The exposed port and container port may differ. When connecting externally,
> always use the exposed port shown in your endpoint configuration.

> [!WARNING]
>
> Exposing your database to the internet means anyone with the credentials can
> connect. Use a strong password and consider removing the Anycast endpoint when
> external access is no longer needed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.