Overview

Connect Bytebase to your databases - from basic setup to cloud-native authentication

Learn how to connect Bytebase to your database instances and configure basic connection settings.

Quick Start

AWS Databases

RDS, Aurora with IAM auth

GCP Databases

Cloud SQL, Spanner with service accounts

Azure Databases

Azure SQL with managed identity

Basic Connection

Before configuring connection parameters, ensure network connectivity:

Network Requirements:

• Verify network routing between Bytebase and your database instance (e.g., VPN, private networks)
• Configure firewall rules to allow Bytebase to connect to your database port
• For cloud databases, add Bytebase to security groups or IP allowlists
• Bytebase Cloud users: Whitelist required IPs

Connection Parameters:

1. Host: Database server address

   • Docker (standard): Use host.docker.internal for localhost databases
   • Docker (—network host): Use 127.0.0.1 for localhost databases

2. Port: Database port number (e.g., 5432 for PostgreSQL, 3306 for MySQL)

3. Username & Password: Database credentials with appropriate permissions

Additional parameters vary by database type - see the database-specific guides below.

Advanced Connection Options

Read-Only Connections

Configure separate read-only connections for enhanced security and performance. Read-only connections are used for:

• SQL Editor queries with data source restrictions
• Export Center operations

Setup:

1. Create a read-only database user or configure a read-replica
2. In Bytebase, click + next to Connection Info
3. Enter the read-only connection details
4. Save the configuration

SSH Tunnel

Use SSH tunneling to connect through a bastion host when your database is behind a firewall or in a private network.

Setup:

1. Enter your database connection details
2. Enable SSH Connection and select Tunnel + Private Key
3. Configure SSH settings:
   • SSH Host: Bastion host address
   • SSH Port: SSH port (typically 22)
   • SSH User: Username for SSH authentication
   • Private Key or Password: SSH credentials
4. Test and save the connection

Connection Parameters

Customize connection behavior with database-specific parameters:

Parameter	Description	Example	Databases
sslmode	SSL connection mode	require	PostgreSQL
connect_timeout	Connection timeout	10	PostgreSQL, MySQL
readTimeout	Read operation timeout	30s	MySQL, SQL Server

Database Documentation:

• PostgreSQL Parameters
• MySQL Parameters
• SQL Server Parameters

Secret Manager Integration

Never store database passwords in Bytebase. Use your existing secret manager for automatic rotation, compliance, and centralized control.

Key benefits:

• Meet SOC2/HIPAA compliance requirements
• Automatic password rotation without downtime
• Complete audit trail of credential access
• Centralized management across all systems

Supported integrations:

• AWS Secrets Manager - For AWS deployments
• GCP Secret Manager - For GCP deployments
• HashiCorp Vault - Enterprise secret management
• Custom API Endpoint - Custom integrations

HashiCorp Vault

Requires Vault KV v2 engine

Vault Setup:

1. Create secret in Vault:
   • Engine: secret
   • Path: bytebase
   • Key: DB_PASSWORD

Bytebase Configuration:

1. Enter Vault URL
2. Choose authentication: Token or AppRole
3. Specify secret location

Custom API Endpoint

Endpoint Format: {{http://example.com/secrets/mydbkey}}

Expected Response:

{
  "payload": {
    "data": "base64_encoded_password"
  }
}

Instance Management

Configure instance-level settings to optimize how Bytebase interacts with your databases.

Sync Interval

Manually trigger schema metadata sync at any time:

• Database level: Sync an individual database’s schema metadata
• Instance level: Sync all databases and detect newly added or removed databases

Bytebase automatically syncs schema metadata when changes are made through Bytebase. For external changes, set an automatic sync interval to keep metadata current for SQL review, data masking, and drift detection. We recommend 24 hours for most use cases—shorter intervals can overload your database server and Bytebase service.

Maximum Connections

Control the number of concurrent connections Bytebase can establish to your database. Finding the right balance is important:

• Too high: May overwhelm your database server
• Too low: May cause task queuing and execution delays

Consider these factors when setting the limit:

• Team size and concurrent SQL Editor usage
• Available database connection capacity
• Parallel operations (migrations, backups, syncs)

Database-Specific Guides

Configure connection settings for specific database types:

PostgreSQL

If the connecting instance is managed by the cloud provider, then SUPERUSER is not available and you should create the role via that provider’s admin console. The created role will have provider specific restricted semi-SUPERUSER privileges:

• In AWS RDS, the roll is rds_superuser.

• In Google Cloud SQL, the role is cloudsqlsuperuser.

You should grant Bytebase privileges with that semi-SUPERUSER role, e.g.:

-- For AWS RDS
GRANT rds_superuser TO bytebase

-- For Google Cloud SQL
GRANT cloudsqlsuperuser TO bytebase

Besides, you may need to grant Bytebase privileges with GRANT role_name TO bytebase; for all existing roles. Otherwise, Bytebase may not access existing databases or tables.

To prevent blocking operations for a long time, consider setting a lock_timeout on the Bytebase user.

Oracle

For managing Oracle database, Bytebase provides two manage modes: Manage based on database and Manage based on schema. You can choose the manage mode when adding an instance or in the instance detail page.

Manage based on database

In this mode, Bytebase will manage the database as a whole.

• For normal Oracle instance, we treat the Oracle database as a Bytebase database.
• For CDB instance, we treat the CDB and all PDBs as Bytebase databases.
• For PDB instance, we treat the PDB as a Bytebase database.

Manage based on schema

In this mode, Bytebase will manage the schema as a whole.

• For any Oracle database, we treat the Oracle schema as a Bytebase database.

MongoDB

Go to Atlas MongoDB Security > Network Access and add IP allowing access from Anywhere.

Go to Atlas MongoDB Deployment > Database, and click Connect.

Click Connect to your application.

Find this string cluster0.8bxxxbz.mongodb.net. Go back to Bytebase, put the string into Host or Socket, and leave Port empty.

Choose mongodb+srv:// as Connection String Schema.

Snowflake

To find the Account Locator, go to your Snowflake account, you can find it in the URL, or from the locator field (but lower case).

If the account is located in the AWS US West (Oregon) region, then it would be something like xy12345, otherwise, the format will be <<account_locator>>.<<cloud_region_id>>.<<cloud>> such as xy12345.us-east-2.aws. See official doc.

ClickHouse

If you use ClickHouse Cloud. Go to your ClickHouse Cloud account, and click View connection string. Also make sure to whitelist the IP where Bytebase connects from.

Databricks

In Environment, select your database. Then fill Host or Socket, Warehouse ID and Token.

• Host or Socket. Copy it from the URL of your Databricks account.

  

• Warehouse ID. Go to SQL Warehouses and click your warehouse (that is, your database), copy the ID in Overview section.

  

• Token. Go to your avatar on the upper-right of Databricks to find Settings. Click Developer and then Access tokens, where you Generate new token and copy it to paste under Token in Bytebase.

  

Click Test Connection to verify.

Spanner

For connecting to Google Cloud Spanner, you need to provide the following info:

1. Google cloud project ID.

2. Google cloud Spanner instance ID.

3. Google cloud service account credentials.

   

Specify Google Cloud Project ID and Spanner Instance ID

From the Spanner database detail page, you can get the project ID and the instance ID from the URL.

For example, the project ID and instance ID are spanner-test-3717002 and spanner-bb1 respectively for the above database.

Create a Google Cloud Service Account as the Credential

1. Go to Google Cloud console.
2. Click APIs & Services and then Credentials. You might have to click Menu on the top left first.
3. Click Create Credentials and then Service account.
4. For Service account name, enter a name for the service account.
5. Click Create and Continue.
6. For Select a role, select Cloud Spanner Database Admin for the service account.
7. Click Done.
8. Click the created service account.
9. At the top, click Keys and then Add Key and then Create new key. Make sure the key type is set to JSON and click Create.
10. You’ll get a message that the service account’s private key JSON file was downloaded to your computer. Make a note of the file name and where your browser saves it. You’ll need it later.

Upload the JSON file to the Credentials input.

Next Steps

Cloud Provider Setup

Configure IAM authentication and cloud-specific features

Production Setup

Best practices for production deployments