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

# MySQL

> Ready-to-run MySQL container template you can run directly or inherit to integrate a relational database into your stack.

## Overview

This template provides a production‑ready MySQL instance as a Monk runnable. You can:

* Run it directly to get a managed MySQL container with sensible defaults
* Inherit it in your own runnable to seamlessly add a relational database to your stack

It exposes MySQL on port 3306, persists data to a host volume, and can optionally create an application user and database on first start.

## What this template manages

* MySQL container (`mysql` image, configurable tag)
* Network service on port 3306
* Persistent volumes for data storage
* Optional initialization of database, user, and passwords

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run MySQL with defaults

```bash theme={null}
monk run mysql/mysql
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `mysql/mysql.yml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:3306` (or the runnable hostname inside Monk networks) using the configured credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  mysql-image-tag: "latest"           # container image tag
  mysql-root-password: "..."          # ROOT password (env: MYSQL_ROOT_PASSWORD)
  mysql-database: "mydb"              # optional app DB to create (env: MYSQL_DATABASE)
  mysql-user: "myuser"                # optional app user (env: MYSQL_USER)
  mysql-password: "..."               # optional app user password (env: MYSQL_PASSWORD)
```

Data is persisted under `${monk-volume-path}/mysql` on the host.

## Use by inheritance (recommended for apps)

Inherit the MySQL runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
db:
  defines: runnable
  inherits: mysql/mysql
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: mysql
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-user:
      value: <- secret("mysql-user")
    database-password:
      value: <- secret("mysql-password")
    database-name:
      value: <- secret("mysql-database")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g mysql-user="appuser"
monk secrets add -g mysql-password="STRONG_USER_PASSWORD"
monk secrets add -g mysql-database="appdb"
monk secrets add -g mysql-root-password="STRONG_ROOT_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `mysql` on TCP port `3306`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence

* Data path: `${monk-volume-path}/mysql:/var/lib/mysql`
* MySQL stores all databases and tables in this directory

## Related templates

* High‑availability setup: see the `mysql-leader-follower/` template in this repository for a leader-follower replication setup.
* Load balancing: see the `mysql-leader-follower-proxysql/` template for leader-follower replication with ProxySQL.

## Troubleshooting

* If you changed `mysql-root-password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside the DB to match.
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f local/mysql/mysql
```