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)

​
Deleting Instances

​
Archive Instance

To temporarily remove an instance from active use while preserving its configuration:
  1. Navigate to the instance page
  2. Click Archive to move the instance to archived status
  3. Archived instances remain accessible from Settings > Archived
Before archiving an instance, ensure all its databases are unassigned from projects. Databases actively assigned to projects cannot be archived.

​
Hard Delete Instance

To permanently remove an instance and all its associated metadata from Bytebase:
  1. Archive the instance first:
    • Go to the instance page
    • Click Archive this instance (requires all databases to be unassigned from projects) on the bottom of the page
  2. Permanently delete the archived instance:
    • Navigate to Settings > Archived
    • Select the archived instance
    • Click Hard-Delete to permanently remove the instance