To allow Bytebase to execute operations on behalf the end user, you need to supply Bytebase with the connection info for your database instance.

​

General

​

Connect to the instance on the same host

• If you run Bytebase without Docker and try to connect to a database instance on the same host, then you need to set host as 127.0.0.1

​

Connect to the instance from Bytebase Cloud

To make your Bytebase Cloud instance connect to your databases in your internal network, you need to whitelist the following Bytebase Cloud IPs:

• 34.27.188.162

​

SSH tunnel

To protect their databases, some hosting providers block direct remote access. However, they often enable SSH, which allows users to connect to their servers remotely using an SSH client. If you want to connect to a database on one of these servers from Bytebase, you will need to create an SSH tunnel. This will allow you to connect to the database without compromising security.

1. After filling in the standard database connection information, click SSH Connection > Tunnel + Private Key.
2. Fill in the SSH connection information. The Private Key is used to authenticate the SSH connection. You can also use a password instead.
3. Click Test Connection. If the connection is successful, click Create to create this instance.

​

Extra Connection Parameters

When connecting to a database instance, you may need to specify additional parameters to customize the connection behavior. Bytebase provides a feature that allows users to define extra parameters for the database connection string directly in the UI.

Supported Database Connection Parameters

Below are links to official documentation for configuring connection parameters:

• PostgreSQL: Connection Parameters
• Oracle (Go-ORA): Go-ORA Connection Options
• MySQL (Go SQL Driver): Connection Parameters
• Microsoft SQL Server (Go-MSSQL): Connection Options

Common Connection Parameters

For a full list of supported parameters, refer to the official database documentation links above.

​

External Secret Manager

By default, Bytebase stores the database credentials in an obfuscated format in its own meta store. You can also instruct Bytebase to retrieve the database credential from an external secret manager.

1. User tries to access database from Bytebase.
2. Bytebase calls the external secret manager to exchange the configured key for the database password.
3. Bytebase retrieves the password and connect the database.

​

HashiCorp Vault

Create the secret in Vault like below:

• Secret engine name: secret

• Secret path: bytebase

• Secret key: DB_PASSWORD

• Secret: <<YOUR_PASSOWRD>>

Configure instance to retrieve database password from vault:

• Specify the Vault URL.

• Specify the Vault auth method.

  • For Token, specify the token.
  • For AppRole, specify the auth role id and secret id.

• Specify the secret engine namesecret, secret path bytebase and secret key DB_PASSWORD.

​

Custom endpoint

If you have a custom external secret manager, you can supply its API endpoint by enclosing it with the mustache {{ }}, e.g {{http://example.com/secrets/mydbkey}}

Sample request

Usually mydbkey is unique for each database and used for exchanging the password for that database.

curl "http://example.com/secrets/mydbkey"

Expected response

Bytebase expects the following JSON response from the external secret manager. The payload.data is the base64-encoded contents of the database password.

{
  "payload": {
    "data": "xxx"
  }
}

​

AWS

While creating an RDS or Aurora instance, you can choose to enable IAM authentication.

​

IAM Authentication

​

Create IAM policy

1. Go to IAM > Policies and click Create policy.

2. Select RDS IAM Authentication for service.

3. Select connect permission and specific as Resources. Check Any in this account.

   Any in this account will mark the resource as arn:aws:rds-db:*:<<your-db-id>>:dbuser:*/*, which contains 3 *:

   • 1st *: any regions
   • 2nd *: any databases
   • 3rd *: any database users

   This will allow the RDS connect on behalf of all database users in all databases in your account. If you want to limit the connection to specific databases, please follow this doc.

4. Name it rds-connect and create this policy.

​

Create IAM user

1. Go to IAM > Users can click Create user. Name it rds-connector.

2. Choose Attach policy directly and select the rds-connect policy. Click Next and then click Create user.

3. On the user detail page, click Create access key.

4. Choose Application running outside AWS and click Next.

5. Then you get the access key and the secret access key.

​

Use IAM Auth in Bytebase

1. Start Bytebase with AWS IAM credentials by passing the AWS environment variables:

   Copy

   Ask AI

     docker run --init \
     -e AWS_ACCESS_KEY_ID=<<your-access-key>> \
     -e AWS_SECRET_ACCESS_KEY=<<your-secret-access-key>> \
     -e AWS_REGION=<<your-aws-region>> \
     --name bytebase \
     --publish 8080:8080 --pull always \
     bytebase/bytebase:3.8.0
   

2. Go to RDS instance detail page, you’ll find the endpoint and port.

3. Configure instance connection using AWS RDS IAM, create the bytebase user with AWSAuthenticationPlugin and grant permission.

   Copy

   Ask AI

       CREATE USER bytebase@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
   
       ALTER USER 'bytebase'@'%' REQUIRE SSL;
   
       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@'%';
   

4. Use the instance endpoint, port and the username bytebase to connect the instance.

​

Secrets Manager

​

Create an IAM user to access the Secrets Manager

Visit IAM to create a new IAM user. Name it bytebase-external-secret.

Attach SecretsManagerReadWrite permission.

After creating the IAM user, create an Access Key to be used by Bytebase later.

Select Third-party service as the use case.

Optionally set the description tag and in the Retrieve access keys screen, record Access key and Secret access key. They will be passed as environment variables when starting Bytebase.

​

Create secret

Visit AWS Secrets Manager to store a new secret. Select Other type of secret, and add a key/value pair. The key is DB_PASSWORD and the value is your database user password.

Next to the Configure secret, use bytebase as the Secret name

Skip rotation, review and create the secret.

​

Use secret in Bytebase

Restart Bytebase with the following environment variables

• AWS_REGION=us-east-1
• AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are the ones you previously created on the IAM user:

AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=xxx AWS_SECRET_ACCESS_KEY=yyy ./bytebase <<other options>>

docker run --init \
  -e AWS_REGION=us-east-1 AWS_ACCESS_KEY_ID=xxx AWS_SECRET_ACCESS_KEY=yyy \
  --name bytebase \
  <<other options>>

Go to instance setting, specify bytebase as the Secret name and DB_PASSWORD as the Secret key. These two correspond to the value you created in the AWS Secrets Manager.

​

GCP

​

IAM Authentication

​

Create a service account

1. Visit Service accounts to create a new service account bytebase.

2. Grant Cloud SQL Admin permission to the service account.

3. After the service account is created, you may view the email for the service account bytebase@<<you-project-name>>.iam.gserviceaccount.com. Go to KEYS.

4. Click ADD KEY and then Create new key.

5. Choose JSON as the key type and click CREATE. Keep the downloaded private key file. This will be passed as environment variables when starting Bytebase.

6. Go to Cloud SQL database instance detail page, and make sure cloudsql_iam_authentication is enabled.

7. Go to Users tab, and click ADD USER ACCOUNT.

8. Select Cloud IAM and copy/paste the service account email bytebase@<<your-project-name>>.iam.gserviceaccount.com.

9. Then you can get the Cloud SQL IAM user: bytebase.

​

Use IAM Auth in Bytebase

1. Start Bytebase with Google IAM credentials by passing GOOGLE_APPLICATION_CREDENTIALS as an environment variable:

   Copy

   Ask AI

     docker run --init \
     -e GOOGLE_APPLICATION_CREDENTIALS=<<your-json-file>> \
     --name bytebase \
     --publish 8080:8080 --pull always \
     --volume ~/.bytebase/data:/var/opt/bytebase \
     bytebase/bytebase:3.8.0
   

2. Go to SQL overview page, you’ll find the Connection name, use it as the host. Choose Google Cloud SQL IAM along with your user bytebase to connect to the database.
   

​

Secret Manager

​

Create a service account to access the Secret Manager

Visit Service accounts to create a new service account.

Grant Secret Manager Secret Accessor permission to the service account.

After the service account is created, visit its KEYS page and add a new key.

Choose JSON as the key type and create. Keep the downloaded private key file. This will be passed as environment variables when starting Bytebase.

​

Create secret

Visit GCP Secret Manager to create a new secret.

After creation, note the fully qualified secret name.

​

Use secret in Bytebase

Restart Bytebase by specifying GOOGLE_APPLICATION_CREDENTIALS=private key file as an environment variable. The private key file is the JSON file downloaded before for the service account.

docker run --init \
  -e GOOGLE_APPLICATION_CREDENTIALS=/var/opt/bytebase/key.json \
  --name bytebase \
  --volume ~/.bytebase/data:/var/opt/bytebase \
  <<other options>>

Go to instance setting, specify the fully qualified name such as projects/228712144016/secrets/DB_PASSWORD as the Secret full name.

​

Azure

​

Entra Managed Identity

Bytebase supports connect to Azure SQL through Azure IAM by using default Azure credential and client secret credential. This section introduces how to use system-assigned managed identity to connect to Azure SQL. For more information about the credential chain in default Azure credential, please refer to default azure credential overview.

​

Create a VM with enabled system-assigned managed identity

1. Enable system assigned managed identity while creating a VM.

2. Deploy the Bytebase on the VM in Docker:

   Copy

   Ask AI

     docker run --init \
     --network=host \
     --name bytebase \
     --pull always \
     --volume ~/.bytebase/data:/var/opt/bytebase \
     bytebase/bytebase:3.8.0
   

​

Enable Microsoft Entra Authentication in Azure SQL

1. Go to the Azure SQL panel, and set the Microsoft Entra Admin for Azure SQL managed instance, don’t forget to click Save button. Once you set the Microsoft Entra Admin, the Microsoft Entra authentication is enabled. Check the Microsoft guide if you use Azure SQL on VM.

​

Create a contained database user

1. Connect to the Azure SQL database using the Microsoft Entra Admin account.

2. For each databases desired to be managed by Bytebase, running the following SQL command inside the database to a contained database user:

   Copy

   Ask AI

      CREATE USER [<Microsoft_Entra_principal_name>] FROM EXTERNAL PROVIDER;
      ALTER ROLE db_owner ADD MEMBER [<Microsoft_Entra_principal_name>];
   

​

Connect to Azure SQL Database in Bytebase

1. Using Azure IAM default credential to connect to Azure SQL database:

In this way, Bytebase can only connect to one specific Azure SQL database. To manage multiple Azure SQL databases in one instance inside Bytebase, considering set the VM principal as the Azure SQL Managed Instance Microsoft Entra Admin.

​

Database-Specific Configuration

-- For AWS RDS
GRANT rds_superuser TO bytebase

-- For Google Cloud SQL
GRANT cloudsqlsuperuser TO bytebase

-- For AWS RDS
GRANT rds_superuser TO bytebase

-- For Google Cloud SQL
GRANT cloudsqlsuperuser TO bytebase