MySQL targets

View as Markdown

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 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.

Image loading...

Click New target and select MySQL 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 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.

Info

Fields like Host, Username, Password, and Database can use custom variables 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.

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 below.

Using the MySQL target in YAML pipelines

Reference the target by ID in a MySQL CLI action:

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 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 on your firewall (or AWS Security Group / GCP firewall rule), or route through a proxy SSH 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.