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

# MySQL

> Connect Bytebase to MySQL, including verified TLS and client certificates.

To add a MySQL database, go to **Instances**, click **Connect instance**, and choose **MySQL**.

Bytebase lists every database on the server except `information_schema`, `mysql`, `performance_schema`, and `sys` as a Bytebase database. See [Database](/concepts/database).

## Supported versions

Bytebase supports MySQL 5.7 and later, including Amazon Aurora MySQL. It connects through a built-in driver, so there is nothing to install.

## Create a user for Bytebase

Connect as an administrator and create a dedicated user for Bytebase. The examples name it `bytebase`.

For MySQL 8.0 and 5.7:

```sql theme={null}
CREATE USER bytebase@'%' IDENTIFIED BY '<password>';
GRANT ALTER, ALTER ROUTINE, CREATE, CREATE ROUTINE, CREATE VIEW,
  DELETE, DROP, EVENT, EXECUTE, INDEX, INSERT, PROCESS, REFERENCES,
  SELECT, SHOW DATABASES, SHOW VIEW, TRIGGER, UPDATE, USAGE,
  RELOAD, LOCK TABLES, REPLICATION CLIENT, REPLICATION SLAVE
  /*!80000 , SET_USER_ID */
  ON *.* TO bytebase@'%';
```

MySQL 8.4 removed `SET_USER_ID`, and naming it there is a syntax error. For MySQL 8.4 and later, replace the `/*!80000 , SET_USER_ID */` line with `, SET_ANY_DEFINER, ALLOW_NONEXISTENT_DEFINER`.

On Amazon RDS for MySQL, run the statement as the master user. Before version 8.0.36, the master user doesn't have `SET_USER_ID`, so leave that line out.

For a [read-only connection](#read-only-connection), create a separate user:

```sql theme={null}
CREATE USER bytebase_readonly@'%' IDENTIFIED BY '<password>';
GRANT SELECT, SHOW DATABASES, SHOW VIEW, USAGE ON *.* TO bytebase_readonly@'%';
```

## Connection details

### Authentication

How Bytebase signs in:

* **Plain Password**: the **Username** and **Password** below.
* **AWS RDS IAM**: an IAM authentication token for Amazon RDS or Aurora. See [AWS](/get-started/connect/aws).
* **Google Cloud SQL IAM**: an IAM service account for Cloud SQL. See [GCP](/get-started/connect/gcp).

### Hostname

The host name or IP address of the MySQL server, such as `db.example.com`. With **Verify server certificate** on, it must be one of the names in the server's certificate.

### Port

The server port. MySQL's default is `3306`.

### Username

The MySQL account Bytebase connects as.

### Password

The account's password. You can also read it from a [secret manager](/get-started/connect/overview#secret-manager-integration).

### TLS

**TLS mode** decides whether Bytebase encrypts the connection:

* **Disabled**: the connection is unencrypted, even when the server offers TLS.
* **TLS**: Bytebase encrypts the connection.
* **Mutual TLS**: the same as **TLS**, and Bytebase also presents a client certificate. Use it for accounts created with `REQUIRE X509`, `REQUIRE SUBJECT`, or `REQUIRE ISSUER`.

Under **Server identity**, turn on **Verify server certificate** so that Bytebase checks the server's certificate and confirms that **Hostname** is one of the names in it. **CA certificate source** sets which certificate authority (CA) the check trusts:

* **System trust**: the CAs that the machine running Bytebase already trusts.
* **Paste PEM**: a CA certificate you paste in PEM format, for a private CA or a self-signed certificate.
* **File path**: a CA certificate file on the Bytebase server. Not available in Bytebase Cloud.

The certificates that MySQL generates on its own at first start have no Subject Alternative Names, so verification always fails against them. To verify the server, install a certificate that names the server's host, set through `ssl_ca`, `ssl_cert`, and `ssl_key`. With verification off, the connection is encrypted, but Bytebase doesn't check which server it reached. Use that only for testing.

For **Mutual TLS**, set **Client identity source** to **Paste PEM** or **File path**, and provide the client certificate and its private key.

### SSH tunnel

Connects through a bastion host. See [SSH Tunnel](/get-started/connect/overview#ssh-tunnel).

### Extra Parameters

Options that Bytebase passes to the driver as key-value pairs, using the [driver's parameter names](https://github.com/go-sql-driver/mysql#parameters) such as `timeout` and `readTimeout`. The driver sends any name it doesn't recognize to MySQL as a session variable, so a server-wide setting such as `connect_timeout` fails. With **TLS mode** set to **Disabled**, the `tls` parameter controls encryption, so `tls` with the value `skip-verify` encrypts the connection without verifying the server. Bytebase refuses `allowAllFiles`, which would let the server read any file on the Bytebase server.

## Troubleshooting

**Test Connection** shows the error from the server or the driver:

| Error | Cause | Fix |
| - | - | - |
| `SSL cert failed to verify: x509: certificate is not valid for any names, but wanted to match …` | The server's certificate has no Subject Alternative Names, such as a certificate MySQL generated on its own. | Install a certificate that names the server's host. For a test server only, turn off **Verify server certificate**. |
| `SSL cert failed to verify: x509: certificate signed by unknown authority` | Verification is on, and the CA from **CA certificate source** didn't sign the server's certificate. | Paste the CA that signed the server's certificate, or point to it. |
| `SSL cert failed to verify: x509: certificate is valid for …, not …` | **Hostname** isn't one of the names in the server's certificate. | Use a name from the certificate, or have the certificate reissued. |
| `Error 3159 (HY000): Connections using insecure transport are prohibited while --require_secure_transport=ON.` | The server requires TLS, and **TLS mode** is **Disabled**. | Set **TLS mode** to **TLS**. |
| `Error 1045 (28000): Access denied for user '…'@'…' (using password: YES)` | The password is wrong, or the account requires a client certificate and **TLS mode** isn't **Mutual TLS**. | Check the password. For an account created with `REQUIRE X509`, set **TLS mode** to **Mutual TLS**. |
| `ssl_cert and ssl_key must be both set or unset` | Only one of the client certificate and its private key is set. | Provide both. |
| `failed to read CA certificate file` | **File path** points to a file the Bytebase server can't read. | Check the path on the Bytebase server. |
| `Error 1229 (HY000): Variable '…' is a GLOBAL variable and should be set with SET GLOBAL` | **Extra Parameters** holds a name the driver doesn't recognize, which it sends to MySQL as a session variable. | Use the driver's parameter instead, such as `timeout` rather than `connect_timeout`. |
| `connection parameter "allowAllFiles" is not allowed for security reasons` | **Extra Parameters** includes `allowAllFiles`. | Remove it. |

## Read-only connection

A [read-only connection](/get-started/connect/overview#read-only-connections) has its own TLS settings and **Extra Parameters**. Set them the same way as for the admin connection.


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