MySQL

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.

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:

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, create a separate user:

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.
Google Cloud SQL IAM: an IAM service account for Cloud SQL. See 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.

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.

Extra Parameters

Options that Bytebase passes to the driver as key-value pairs, using the driver’s parameter names 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 has its own TLS settings and Extra Parameters. Set them the same way as for the admin connection.

Introduction

Quick Start

Bytebase Essentials

Install

Connect Databases

Onboarding Guides

Supported versions

Create a user for Bytebase

Connection details

Authentication

Hostname

Port

Username

Password

TLS

SSH tunnel

Extra Parameters

Troubleshooting

Read-only connection

​Supported versions

​Create a user for Bytebase

​Connection details

​Authentication

​Hostname

​Port

​Username

​Password

​TLS

​SSH tunnel

​Extra Parameters

​Troubleshooting

​Read-only connection

Supported versions

Create a user for Bytebase

Connection details

Authentication

Hostname

Port

Username

Password

TLS

SSH tunnel

Extra Parameters

Troubleshooting

Read-only connection