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: 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:
ParameterDescriptionExampleDatabases
sslmodeSSL connection moderequirePostgreSQL
connect_timeoutConnection timeout10PostgreSQL, MySQL
readTimeoutRead operation timeout30sMySQL, SQL Server
Database Documentation:

​
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:

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

​
Next Steps

Cloud Provider Setup

Configure IAM authentication and cloud-specific features

Production Setup

Best practices for production deployments