# MySQL targets

Connect Buddy CI/CD to MySQL with a reusable target. Run migrations, seed scripts, and maintenance queries from any pipeline.

MySQL targets in Buddy let you store the connection to a MySQL instance once and reuse it across every pipeline that runs migrations, seed scripts, or maintenance queries. The target is consumed by the [MySQL CLI action](/docs/yaml/yaml-actions/mysql-cli.md) and can be referenced by name, by tag, or inline in YAML.

## How to add a MySQL target in Buddy

Navigate to the **Targets** tab where all globally defined connections are listed.

![](/docs/targets/target-add.png 640x369)

Click **New target** and select <u>MySQL</u> from the dropdown menu.

## MySQL connection settings

Required fields:

- **Name** - human-readable target name; the unique ID is generated automatically and can be edited.
- **Scope** - defines which pipelines have [access](/docs/targets/target-scope.md) to the target.
- **Host** - hostname or IP of the MySQL server (e.g. `db.example.com`).
- **Port** - MySQL server port. Default: `3306`.
- **Database** - default database name.
- **Username & Password** - MySQL authentication credentials.

Optional fields:

- **Proxy** - an SSH target used to tunnel traffic to a private MySQL server (useful for RDS, Cloud SQL, or any database behind a bastion).
- **Tags** - labels used to group and match targets.

<Hint type="info">

Fields like `Host`, `Username`, `Password`, and `Database` can use [custom variables](/docs/pipelines/variables.md) defined at the workspace, project, or pipeline level. This keeps secrets out of YAML and lets you switch between environments by overriding the variable set.

</Hint>

## Testing the MySQL connection

Before saving, use **Test connection** to verify the credentials and network access. The test connects from a Buddy runner to the host and port you provided and authenticates with the supplied credentials against the target database. If the test fails, see [Troubleshooting](#troubleshooting-mysql-connection-errors) below.

## Using the MySQL target in YAML pipelines

Reference the target by ID in a [MySQL CLI action](/docs/yaml/yaml-actions/mysql-cli.md):

```yaml
- pipeline: "Apply MySQL migrations"
  trigger_mode: ON_EVERY_PUSH
  actions:
    - action: "Migrate schema"
      type: "MYSQL_CLI"
      target: "mysql-prod"
      execute_commands:
        - "SELECT VERSION();"
      execute_files:
        - "migrations/2026_05_19_add_index.sql"
```

You can also define the target inline if you do not want to manage it in the UI:

```yaml
- action: "Smoke query"
  type: "MYSQL_CLI"
  targets:
    - target: "mysql-prod"
      type: "MYSQL"
      host: "db.example.com"
      port: 3306
      database: "$MYSQL_DB"
      username: "$MYSQL_USER"
      password: "$MYSQL_PASSWORD"
  execute_commands:
    - "SELECT id, email FROM users ORDER BY created_at DESC LIMIT 10;"
```

See the [MySQL CLI YAML reference](/docs/yaml/yaml-actions/mysql-cli.md) for the full field list.

## Troubleshooting MySQL connection errors

Most failures fall into one of the categories below.

- **Access denied for user '...'@'...'** - MySQL grants are bound to a host pattern. The user `app@localhost` will not accept connections from a Buddy runner. Grant access from the runner's IP range or `%`: `GRANT ALL ON db.* TO 'app'@'%' IDENTIFIED BY '...';`.
- **Connection timeout / host unreachable** - the database is not exposed to Buddy runners. Whitelist the [Buddy IP addresses](/docs/troubleshooting/ip-whitelist.md) on your firewall (or AWS Security Group / GCP firewall rule), or route through a [proxy SSH target](/docs/targets/ssh.md#proxy-target).
- **Public Key Retrieval is not allowed** - MySQL 8 uses `caching_sha2_password` by default. Either switch the user to `mysql_native_password`, or use SSL so the password can be exchanged securely.
- **Unknown database** - the named database does not exist on the server. Verify with `mysql -h ... -u ...` from outside Buddy.
- **Too many connections** - the MySQL `max_connections` cap was hit, often by leaked connections from other pipelines. Lower pipeline concurrency or increase the cap.

## See also

- [MySQL CLI action - YAML reference](/docs/yaml/yaml-actions/mysql-cli.md)
- [Other database targets: MSSQL](/docs/targets/mssql.md), [MongoDB](/docs/targets/mongodb.md), [PostgreSQL](/docs/targets/postgresql.md)
- [Targets - REST API](/docs/api/targets.md)
- [Custom variables in pipelines](/docs/pipelines/variables.md)


---
Original source: https://buddy.works/docs/targets/mysql