Deploying Bytebase
Bytebase is an open-source database DevOps platform that provides a web-based collaboration workspace for managing the complete lifecycle of application database schemas. It combines database schema version control, CI/CD automation, SQL review and linting, and advanced security features—making it the go-to solution for development teams, DBAs, and security teams who need to standardize and streamline their database operations.
Built with Go and Vue, Bytebase supports PostgreSQL, MySQL, MariaDB, TiDB, Snowflake, ClickHouse, MongoDB, Redis, Oracle, SQL Server, and many other databases. Whether you’re implementing schema migrations, enforcing SQL standards, managing multi-tenant databases, or maintaining comprehensive audit trails, Bytebase provides the tooling and workflows needed for enterprise-grade database management at scale.
Key Features
- Database CI/CD Pipeline: Automated schema migration workflows with review, linting, and approval processes
- GitOps Integration: Native GitHub and GitLab integration for database-as-code workflows
- SQL Review & Linting: 200+ built-in SQL lint rules to enforce standards and detect anti-patterns
- Multi-Database Support: Support for PostgreSQL, MySQL, MariaDB, Snowflake, ClickHouse, MongoDB, Redis, Oracle, SQL Server, and more
- Data Masking: Advanced column-level data masking with policy-as-code for sensitive data protection
- Access Control: Fine-grained role-based access control (RBAC) with project and workspace-level permissions
- Just-in-Time Database Access: Permission-based database access with approval workflows and temporal access
- Audit Logging: Complete audit trail of all database activities, schema changes, and user actions
- Web SQL Editor: Feature-rich IDE for database development with auto-complete, query history, and syntax highlighting
- Batch Changes: Apply schema changes across multiple databases, environments, or tenants simultaneously
- Rollback Support: 1-click rollback capability with automated snapshots for data recovery
- Schema Sync: Automatic detection and synchronization of schema drift across databases
- Admin Mode: CLI-like experience for direct database management without bastion setup
- API & Terraform: Complete REST API and Terraform provider for infrastructure-as-code integration
- Backup & Recovery: Automated snapshot management for data protection and recovery
- Drift Detection: Automatic detection of unmanaged schema changes across environments
- Multi-Environment Support: Manage development, staging, and production databases with unified policies
- Collaboration Features: Shared SQL editor, comment threads, and team-based review workflows
- Watermarking: Query result watermarking to trace sensitive data access
- Deployment Automation: Scheduled and on-demand database deployments with rollback capabilities
Prerequisites
To deploy Bytebase on Klutch.sh, ensure you have the following:
- An active Klutch.sh account with access to the dashboard at klutch.sh/app
- A GitHub repository (optional, for storing Dockerfile and configuration files)
- Understanding of basic Docker concepts and containerization
- Familiarity with database management concepts
- Access to manage persistent storage volumes for database backups
Important Considerations
Deployment Steps
Create the Dockerfile
Create a
Dockerfilein the root directory of your repository with the following content:FROM bytebase/bytebase:latest# Expose the default Bytebase web UI portEXPOSE 8080# Set the data directory volume mount pointVOLUME ["/var/opt/bytebase"]# Set working directoryWORKDIR /var/opt/bytebase# Health check for container orchestrationHEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \CMD curl -f http://localhost:8080/api/v1/ping || exit 1# Use the default entrypoint from the base imageENTRYPOINT ["/bytebase/bytebase"]# Default command - specify port and data directoryCMD ["--port", "8080", "--data", "/var/opt/bytebase"]This Dockerfile uses the official Bytebase image and configures the necessary ports, volumes, and health checks for production deployment.
Create an Entrypoint Script
Create an
entrypoint.shfile to handle initialization and configuration:#!/bin/bashset -e# Create the data directory if it doesn't existmkdir -p /var/opt/bytebasecd /var/opt/bytebase# Set proper permissionschmod 755 /var/opt/bytebase# Start Bytebase with configured optionsexec /bytebase/bytebase \--port 8080 \--data /var/opt/bytebase \--readonly=${BYTEBASE_READONLY:-false} \--demo=${BYTEBASE_DEMO:-false}Update the Dockerfile’s CMD instruction to use this script if you need custom initialization logic.
Create Environment Configuration File
Create an
.env.examplefile with the following content:# Bytebase Core ConfigurationBYTEBASE_PORT=8080BYTEBASE_DATA_DIR=/var/opt/bytebase# Optional: Readonly Mode# Set to true to run Bytebase in read-only modeBYTEBASE_READONLY=false# Optional: Demo Mode# Set to true to enable demo mode for testingBYTEBASE_DEMO=false# Optional: PostgreSQL Connection (for external metadata database)# By default, Bytebase uses SQLite. Uncomment to use PostgreSQL for metadata# BYTEBASE_EXTERNAL_DB=postgresql://user:password@postgres-host:5432/bytebase# Optional: Backup ConfigurationBYTEBASE_BACKUP_PATH=/var/opt/bytebase/backupsBYTEBASE_LOG_LEVEL=info# SSL/TLS Configuration (optional)# BYTEBASE_SSL_CERT=/var/opt/bytebase/ssl/cert.pem# BYTEBASE_SSL_KEY=/var/opt/bytebase/ssl/key.pem# SMTP Configuration for Notifications (optional)# BYTEBASE_SMTP_HOST=smtp.example.com# BYTEBASE_SMTP_PORT=587# BYTEBASE_SMTP_USERNAME=your-email@example.com# BYTEBASE_SMTP_PASSWORD=your-password# BYTEBASE_SMTP_FROM=noreply@example.com# Authentication Configuration (optional)# OAuth/OIDC Configuration for Single Sign-On# BYTEBASE_OAUTH_GITHUB_CLIENT_ID=your-github-client-id# BYTEBASE_OAUTH_GITHUB_CLIENT_SECRET=your-github-secretThis file defines all the necessary environment variables for configuring Bytebase during deployment.
Create a .gitignore File
Create a
.gitignorefile to exclude sensitive files from version control:# Environment variables.env.env.local.env.*.local# Bytebase data directory (local development only).bytebase/data/# IDE and editor files.vscode/.idea/*.swp*.swo*~# OS files.DS_StoreThumbs.db# Logs*.loglogs/# Build artifactsdist/build/node_modules/Push to GitHub
Initialize a Git repository and push your files to GitHub:
Terminal window git initgit add Dockerfile entrypoint.sh .env.example .gitignoregit commit -m "Initial Bytebase deployment setup"git branch -M maingit remote add origin https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.gitgit push -u origin mainReplace
YOUR_USERNAMEandYOUR_REPOSITORYwith your actual GitHub username and repository name.Deploy on Klutch.sh
- Log in to your Klutch.sh dashboard at klutch.sh/app
- Click Create App and select GitHub as your repository source
- Connect your GitHub account and select the repository you created
- Configure the deployment settings:
- App Name: Enter a name for your Bytebase instance (e.g.,
bytebase-prod) - Branch: Select
main(or your default branch)
- App Name: Enter a name for your Bytebase instance (e.g.,
- Click Deploy and wait for the deployment to complete
Klutch.sh automatically detects the Dockerfile and uses it to build and deploy your Bytebase instance.
Configure Persistent Storage
After deployment, attach a persistent volume for data persistence:
- In the Klutch.sh dashboard, navigate to your deployed Bytebase app
- Go to the Settings or Storage section
- Click Add Persistent Volume
- Configure the volume:
- Mount Path:
/var/opt/bytebase - Size:
50GB(or larger based on your requirements)
- Mount Path:
- Save the configuration and restart the container
This ensures all metadata, audit logs, and configurations persist across deployments and updates.
Configure Network Traffic
Configure your Klutch.sh app to handle HTTP traffic on the standard web port:
- In your app settings, navigate to the Network section
- Set Traffic Type to
HTTP - The internal port should be set to
8080(Bytebase’s default web UI port) - Your Bytebase instance will be accessible at
example-app.klutch.sh
The HTTP configuration allows web browsers to access the Bytebase web interface for managing databases and schemas.
Initial Setup and Configuration
After your Bytebase deployment is live, follow these steps to configure it:
Access the Web UI
Open your browser and navigate to https://example-app.klutch.sh (replace example-app with your actual app name). You’ll see the Bytebase initialization wizard.
Create Admin Account
- The first user automatically becomes the workspace admin
- Set up your admin account with a strong password
- Configure your workspace name and basic settings
Connect Your First Database
- Go to Workspace → Instances to add a database connection
- Click Create Instance and provide:
- Instance Name: A descriptive name (e.g.,
production-postgres) - Engine Type: Select your database type (PostgreSQL, MySQL, MongoDB, etc.)
- Host: The database server address
- Port: The database port (e.g., 5432 for PostgreSQL)
- Database: The database name
- Username: Database user
- Password: Database password
- Instance Name: A descriptive name (e.g.,
- Test the connection and save
Set Up Projects and Environments
- Create a Project to organize your databases (e.g.,
MyApp) - Add Environments like Development, Staging, and Production
- Link databases to appropriate environments
- Configure change policies and approval workflows
Configure Access Control
- Go to Workspace Settings → Members to invite team members
- Assign roles (Owner, DBA, Developer, Viewer) based on responsibilities
- Set project-level permissions for fine-grained access control
Enable Audit Logging
- Go to Workspace Settings → Audit Log
- Review audit entries for all database activities
- Configure retention policies and export settings
Environment Variables
Basic Configuration
# Core Bytebase configurationBYTEBASE_PORT=8080BYTEBASE_DATA_DIR=/var/opt/bytebaseBYTEBASE_READONLY=falseBYTEBASE_DEMO=falseThese variables control the fundamental Bytebase deployment settings, including the web UI port and data storage location.
Production Configuration
For production deployments, use these additional environment variables with Nixpacks:
# Advanced Configuration for Production
# External Database for Metadata Storage# Use PostgreSQL instead of SQLite for metadata in high-availability setupsBYTEBASE_EXTERNAL_DB=postgresql://user:password@postgres-prod:5432/bytebase
# Logging and MonitoringBYTEBASE_LOG_LEVEL=infoBYTEBASE_BACKUP_PATH=/var/opt/bytebase/backupsBYTEBASE_BACKUP_RETENTION_DAYS=30
# SSL/TLS Configuration for Secure ConnectionsBYTEBASE_SSL_CERT=/var/opt/bytebase/ssl/cert.pemBYTEBASE_SSL_KEY=/var/opt/bytebase/ssl/key.pem
# SMTP Configuration for Email NotificationsBYTEBASE_SMTP_HOST=smtp.example.comBYTEBASE_SMTP_PORT=587BYTEBASE_SMTP_USERNAME=notifications@example.comBYTEBASE_SMTP_PASSWORD=your-secure-passwordBYTEBASE_SMTP_FROM=noreply@example.com
# OAuth/OIDC Integration for Single Sign-OnBYTEBASE_OAUTH_GITHUB_CLIENT_ID=your-github-oauth-idBYTEBASE_OAUTH_GITHUB_CLIENT_SECRET=your-github-oauth-secret
# Connection Pooling and PerformanceBYTEBASE_MAX_CONNECTIONS=100BYTEBASE_CONNECTION_TIMEOUT=30s
# Security SettingsBYTEBASE_ENABLE_2FA=trueBYTEBASE_ENFORCE_2FA_FOR_ADMINS=true
# API ConfigurationBYTEBASE_API_TOKEN_EXPIRY=7dTo apply these variables in Klutch.sh:
- Go to your app settings in the Klutch.sh dashboard
- Navigate to Environment Variables section
- Add each variable with its production value
- Click Save and redeploy if necessary
Code Examples
Bash: Automated Database Backup Script
This script backs up all databases registered in Bytebase and stores them locally:
#!/bin/bash
# Bytebase Automated Backup Scriptset -e
# ConfigurationBYTEBASE_HOST="example-app.klutch.sh"BYTEBASE_API_TOKEN="your-api-token"BACKUP_DIR="/var/opt/bytebase/backups"RETENTION_DAYS=30
# Create backup directorymkdir -p "$BACKUP_DIR"
echo "Starting Bytebase database backup..."
# Get all instances from Bytebase APIINSTANCES=$(curl -s -X GET "https://$BYTEBASE_HOST/api/v1/instances" \ -H "Authorization: Bearer $BYTEBASE_API_TOKEN" \ -H "Content-Type: application/json")
# Extract instance names and iterateecho "$INSTANCES" | jq -r '.instances[]?.name' | while read -r instance; do if [ -n "$instance" ]; then echo "Backing up instance: $instance"
TIMESTAMP=$(date +%Y%m%d_%H%M%S) BACKUP_FILE="$BACKUP_DIR/${instance}_backup_${TIMESTAMP}.sql"
# Use Bytebase API to trigger backup curl -s -X POST "https://$BYTEBASE_HOST/api/v1/instances/$instance/backup" \ -H "Authorization: Bearer $BYTEBASE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "backupPath": "'$BACKUP_FILE'", "description": "Automated backup at '$TIMESTAMP'" }'
echo "Backup created: $BACKUP_FILE" fidone
# Clean up old backups (older than retention days)echo "Cleaning up backups older than $RETENTION_DAYS days..."find "$BACKUP_DIR" -name "*.sql" -type f -mtime +$RETENTION_DAYS -delete
echo "Backup process completed successfully!"JavaScript: Bytebase API Client for Schema Changes
This example demonstrates how to interact with Bytebase API to manage schema changes:
// Bytebase API Client for Schema Management
class BytebaseClient { constructor(baseUrl, apiToken) { this.baseUrl = baseUrl; this.apiToken = apiToken; this.headers = { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' }; }
// Get all instances async getInstances() { const response = await fetch(`${this.baseUrl}/api/v1/instances`, { method: 'GET', headers: this.headers }); return response.json(); }
// Create a schema change issue async createSchemaChange(projectId, changePayload) { const response = await fetch(`${this.baseUrl}/api/v1/projects/${projectId}/issues`, { method: 'POST', headers: this.headers, body: JSON.stringify({ title: changePayload.title, description: changePayload.description, type: 'DATABASE_CHANGE', payload: changePayload }) }); return response.json(); }
// List schema changes for a database async getSchemaChanges(projectId) { const response = await fetch(`${this.baseUrl}/api/v1/projects/${projectId}/issues?type=DATABASE_CHANGE`, { method: 'GET', headers: this.headers }); return response.json(); }
// Execute SQL query on a database async executeQuery(instanceId, sql) { const response = await fetch(`${this.baseUrl}/api/v1/instances/${instanceId}/query`, { method: 'POST', headers: this.headers, body: JSON.stringify({ statement: sql, limit: 1000 }) }); return response.json(); }
// Get audit logs async getAuditLogs(filter = {}) { const queryString = new URLSearchParams(filter).toString(); const response = await fetch(`${this.baseUrl}/api/v1/audit-logs?${queryString}`, { method: 'GET', headers: this.headers }); return response.json(); }
// Update database access policy async updateAccessPolicy(projectId, policyPayload) { const response = await fetch(`${this.baseUrl}/api/v1/projects/${projectId}/policies`, { method: 'PUT', headers: this.headers, body: JSON.stringify(policyPayload) }); return response.json(); }}
// Usage exampleconst client = new BytebaseClient('https://example-app.klutch.sh', 'your-api-token');
// Get all database instancesclient.getInstances().then(instances => { console.log('Available Instances:', instances);});
// Create a schema changeclient.createSchemaChange('project-1', { title: 'Add user_preferences column', description: 'Add preferences column to users table', sql: 'ALTER TABLE users ADD COLUMN preferences JSONB DEFAULT \'{}\'::jsonb;'}).then(issue => { console.log('Schema change created:', issue);});cURL: REST API Examples for Common Operations
Execute these cURL commands to interact with Bytebase API:
# Set your Bytebase host and API tokenBYTEBASE_HOST="example-app.klutch.sh"API_TOKEN="your-api-token"
# Get all workspaces (for admin purposes)curl -X GET "https://$BYTEBASE_HOST/api/v1/workspaces" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json"
# List all instancescurl -X GET "https://$BYTEBASE_HOST/api/v1/instances" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json"
# Create a new database instancecurl -X POST "https://$BYTEBASE_HOST/api/v1/instances" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Production PostgreSQL", "engine": "POSTGRES", "host": "postgres.example.com", "port": 5432, "username": "dbuser", "password": "secure-password", "database": "production" }'
# Get all projectscurl -X GET "https://$BYTEBASE_HOST/api/v1/projects" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json"
# Create a projectcurl -X POST "https://$BYTEBASE_HOST/api/v1/projects" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "E-Commerce Platform", "key": "ECP" }'
# Create a schema change issuecurl -X POST "https://$BYTEBASE_HOST/api/v1/projects/project-1/issues" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Add audit_log table", "description": "Create audit_log table for compliance tracking", "type": "DATABASE_CHANGE", "payload": { "databaseId": "db-1", "sql": "CREATE TABLE audit_log (id SERIAL PRIMARY KEY, action VARCHAR(255), user_id INT, timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP);" } }'
# Get audit logscurl -X GET "https://$BYTEBASE_HOST/api/v1/audit-logs?limit=50&offset=0" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json"
# Get schema information for a databasecurl -X GET "https://$BYTEBASE_HOST/api/v1/instances/instance-1/databases" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json"
# Execute a query on a databasecurl -X POST "https://$BYTEBASE_HOST/api/v1/instances/instance-1/query" \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "statement": "SELECT COUNT(*) FROM users;", "limit": 100 }'Best Practices
Schema Management
- Use Change Workflows: Always create schema changes through Bytebase’s issue system rather than executing SQL directly. This ensures audit trails and approval workflows are maintained.
- Enable SQL Review: Configure SQL lint rules to catch anti-patterns before deployment. Use Bytebase’s built-in 200+ rules to enforce consistency.
- Test Changes in Non-Prod: Always deploy schema changes to development and staging environments first. Validate against realistic data volumes.
- Document Changes: Include detailed descriptions in change issues, including rollback procedures and expected impact on application performance.
Access Control and Security
- Implement RBAC: Use role-based access control to limit who can approve, execute, or view schema changes. Assign appropriate roles (Owner, DBA, Developer, Viewer).
- Enable 2FA: Enforce two-factor authentication for all users, especially administrators. Use Bytebase’s 2FA settings to strengthen security.
- Use API Tokens: Create service account API tokens with minimal required permissions for automation and integrations.
- Audit Regularly: Review audit logs frequently to detect unusual database access patterns or unauthorized changes.
Data Security and Compliance
- Enable Data Masking: Configure column-level data masking for sensitive fields (PII, payment data, credentials) in non-production environments.
- Set Up Just-in-Time Access: Use temporary access grants with expiration times for production database access.
- Backup and Recovery: Configure automatic backups and test recovery procedures regularly. Store backups in secure, geographically distributed locations.
- Maintain Audit Trails: Keep audit logs for compliance requirements. Set appropriate retention policies based on regulatory requirements.
Monitoring and Maintenance
- Health Checks: Monitor Bytebase’s health endpoint (
/api/v1/ping) regularly to ensure availability. - Storage Monitoring: Track persistent volume usage and plan capacity accordingly. Clean up old snapshots and backups.
- Update Management: Keep Bytebase updated with the latest security patches and features. Plan updates during maintenance windows.
- Performance Tuning: If using external PostgreSQL for metadata, configure connection pooling and appropriate resource limits.
Integration and Automation
- GitOps Workflow: Enable GitHub/GitLab integration to sync schema changes between repositories and Bytebase.
- Notifications: Configure SMTP for email notifications on schema changes, approvals, and issues.
- API Automation: Use Bytebase API for automated backups, migrations, and reporting.
- Terraform Integration: Use the Bytebase Terraform provider to manage instances, projects, and policies as infrastructure-as-code.
Troubleshooting
Issue: Cannot Connect to Databases
Solution: Verify network connectivity from the Klutch.sh environment to your database servers. Check firewall rules, security groups, and VPC configurations. Ensure the database credentials are correct and the user has sufficient permissions.
Issue: Persistent Storage Data Lost After Restart
Solution: Ensure the persistent volume is properly attached to /var/opt/bytebase before deployment. Check Klutch.sh settings to confirm the volume is mounted and persistent. If data is missing, restore from backups.
Issue: High Memory or CPU Usage
Solution: Monitor resource consumption in the Klutch.sh dashboard. If Bytebase uses excessive resources, consider upgrading the instance size or moving the metadata database to an external PostgreSQL server. Clean up old audit logs and snapshots.
Issue: SSL Certificate Errors
Solution: If using custom SSL certificates, ensure they are properly mounted at /var/opt/bytebase/ssl/. Verify certificate validity and expiration dates. Update SSL configuration through environment variables.
Issue: API Token Expiration
Solution: Rotate API tokens regularly according to your security policy. Store tokens securely and use environment variables to manage sensitive credentials. Monitor token usage and create audit alerts.
Updating Bytebase
To update Bytebase to a newer version:
- Go to your Klutch.sh app dashboard
- Navigate to Deployments or Updates section
- Check for available updates
- Review the changelog for breaking changes or migration steps
- Click Update to deploy the latest version
- Bytebase automatically migrates the metadata database during startup
- Verify the deployment is healthy using the health check endpoint
Always back up your persistent volume before performing updates.
Use Cases
Enterprise Database Management
Deploy Bytebase as the central hub for all database operations across your organization. Enable teams to manage hundreds of databases through a unified platform with consistent policies and audit trails.
DevOps and CI/CD Integration
Integrate Bytebase into your CI/CD pipeline using GitHub/GitLab webhooks. Automatically create schema change issues when database migrations are detected in pull requests, ensuring all changes go through review.
Compliance and Audit Requirements
Use Bytebase’s comprehensive audit logging to maintain compliance with regulations like SOC 2, HIPAA, and GDPR. Track every database access, change, and query for regulatory reporting.
Multi-Tenant SaaS Applications
Manage schema changes across hundreds or thousands of tenant databases simultaneously using batch change functionality. Ensure consistency while maintaining tenant isolation.
Database Migration and Consolidation
Plan and execute large-scale database migrations using Bytebase’s schema sync and drift detection features. Minimize downtime and validate consistency across source and target databases.
SQL Standards Enforcement
Use SQL review and linting rules to enforce organization-wide SQL standards. Catch performance anti-patterns, security issues, and style violations before they reach production.
Data Governance and Masking
Implement fine-grained data masking policies for different user roles. Ensure sensitive data is protected in non-production environments while maintaining utility for development and testing.
Additional Resources
- Official Bytebase Documentation: https://docs.bytebase.com
- GitHub Repository: https://github.com/bytebase/bytebase
- Interactive Demo: https://www.bytebase.com/demo/
- API Reference: https://docs.bytebase.com/integrations/api/overview
- Community Discord: https://discord.gg/huyw7gRsyA
- Supported Databases: https://docs.bytebase.com/introduction/supported-databases
- Bytebase Comparisons: https://www.bytebase.com/blog/
- Terraform Provider: https://registry.terraform.io/providers/bytebase/bytebase/latest/docs
Conclusion
Bytebase empowers organizations to manage database schemas with the same rigor and control as application code through comprehensive CI/CD, GitOps integration, and collaborative workflows. By deploying Bytebase on Klutch.sh, you gain a scalable, maintainable platform for database management that grows with your infrastructure needs.
The combination of Bytebase’s powerful database DevOps capabilities with Klutch.sh’s simplified deployment model makes it straightforward to establish enterprise-grade database governance. Whether you’re managing a single database or hundreds of database instances across multiple environments, Bytebase provides the tooling, security features, and audit capabilities needed for production-grade database operations at scale.
Start with the deployment steps outlined in this guide, configure persistent storage for data durability, and gradually expand to include more databases and teams. Leverage Bytebase’s API for automation, integration with your existing CI/CD pipelines, and comprehensive audit logging for compliance and security.