This tutorial is part of the Bytebase Terraform Provider series:

​
What You’ll Learn

In this tutorial, you’ll use Terraform to manage Bytebase environments programmatically. You’ll learn how to:
  • Define environments (Test, Prod) with different protection levels
  • Configure automatic vs manual deployment policies
  • Set up data access restrictions for production
  • Manage everything as Infrastructure as Code (IaC)

​
Prerequisites

Before starting this tutorial, ensure you have:

​
Step 1 - Setup

​
Install Terraform

Follow the official Terraform installation guide.

​
Start Bytebase

  1. Run Bytebase in Docker: 
    docker run --rm --init \
  --name bytebase \
  --publish 8080:8080 --pull always \
  --volume ~/.bytebase/data:/var/opt/bytebase \
  bytebase/bytebase:latest
  2. Access Bytebase at http://localhost:8080.
  3. Register an admin account with Workspace Admin role. register-admin
  4. Follow the guide to configure, you’ll need the built-in sample data for this tutorial. use-built-in-sample
  5. (Optional) After logging into Bytebase, activate official or trial license. Some features require the Enterprise Plan. subscription

​
Explore Current Environments

Navigate to Environments in Bytebase. You’ll see two default environments Test and Prod. We’ll manage these environments using Terraform next. env-default

​
Step 2 - Configure Terraform Provider

​
Set up Provider

  1. Create a new folder learn-terraform-bytebase and navigate to it.
  2. Create 0-provider.tf, visit Terraform Bytebase Provider, click USE PROVIDER and copy the configuration. tf-use-provider
    0-provider.tf
    terraform {
   required_providers {
      bytebase = {
         source  = "registry.terraform.io/bytebase/bytebase"
         version = "3.8.6"  # Check for latest version
      }
   }
}

provider "bytebase" {
   service_account = "tf@service.bytebase.com"
   service_key     = "<Your service key>"      # We'll get this next
   url             = "http://localhost:8080"    # Your Bytebase URL
}

​
Create Service Account

  1. In Bytebase, go to IAM & Admin > Users & Groups.
  2. Click + Add User and create a service account:
    • Type: Service Account
    • Email: tf@service.bytebase.com
    • Roles: Workspace Admin
  3. Copy the generated Service Key.

​
Initialize Terraform

  1. Update 0-provider.tf with your service account key.
  2. Initialize Terraform:
terraform init
You should see: “Terraform has been successfully initialized!”

​
Step 3 - Inspect Current Environments

Before making changes, let’s see what environments exist.
Terraform data sourcebytebase_environment
Sample file1-0-list-env.tf
Create 1-0-list-env.tf:
1-0-list-env.tf
# Read current environment settings from Bytebase
data "bytebase_setting" "environments" {
   name = "settings/ENVIRONMENT"
}

# Display all environments
output "all_environments" {
   value = data.bytebase_setting.environments
}
Run these commands: 
terraform plan
terraform apply
You’ll see the existing test and prod environments.

​
Step 4 - Define Environment Configuration

Terraform resourcebytebase_setting
Sample file1-1-env-setting.tf
Create 1-1-env-setting.tf:
1-1-env-setting.tf
# Define environments as Infrastructure as Code
resource "bytebase_setting" "environments" {
   name = "settings/ENVIRONMENT"

   environment_setting {
      # Test environment - for development
      environment {
         id        = "test"
         title     = "Test"
         protected = false
      }

      # Production environment - needs protection
      environment {
         id        = "prod"
         title     = "Prod"
         ## Bytebase will attach a shield icon 🛡️ besides the environment name.
         protected = true
      }
   }
}

​
Step 5 - Configure Environment Policies

Let’s add rollout and data protection policies, you may find more details in Environment Settings.

​
Rollout Policy

Terraform resourcebytebase_policy
Sample file1-2-env-policy-rollout.tf
Create 1-2-env-policy-rollout.tf:
1-2-env-policy-rollout.tf
# Test environment - automatic deployment
resource "bytebase_policy" "rollout_policy_test" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[0].name
   type       = "ROLLOUT_POLICY"

   rollout_policy {
      automatic = true  # Deploy changes automatically
      roles = [
         "roles/workspaceAdmin",
         "roles/projectOwner",
         "roles/LAST_APPROVER",
         "roles/CREATOR"
      ]
   }
}

# Production - manual deployment required
resource "bytebase_policy" "rollout_policy_prod" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[1].name
   type       = "ROLLOUT_POLICY"

   rollout_policy {
      automatic = false  # Require manual deployment
      roles = [
         "roles/workspaceAdmin",
         "roles/projectOwner",
         "roles/LAST_APPROVER",
         "roles/CREATOR"
      ]
   }
}
  • roles is the list of roles that are allowed to click the button to deploy the changes manually. Even automatic rollout is enabled, manual approval is still needed while there is any automatic check failure.

​
Data Protection Policy

Terraform resourcebytebase_policy
Sample file1-3-env-policy-data.tf
Create 1-3-env-policy-data.tf:
1-3-env-policy-data.tf
# Prevent copying data in SQL Editor from production
resource "bytebase_policy" "disable_copy_data_policy_prod" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[1].name
   type       = "DISABLE_COPY_DATA"

   disable_copy_data_policy {
      enable = true  # Block data copy
   }
}

# Restrict SQL execution in SQL Editor from production
resource "bytebase_policy" "data_source_query_policy_prod" {
   depends_on = [bytebase_setting.environments]
   parent     = bytebase_setting.environments.environment_setting[0].environment[1].name
   type       = "DATA_SOURCE_QUERY"

   data_source_query_policy {
      restriction  = "RESTRICTION_UNSPECIFIED"
      disallow_ddl = true  # No schema changes via SQL Editor
      disallow_dml = true  # No data changes via SQL Editor
   }
}
  • Here data protection policy is only applied to the Prod environment. Which means in Test environment, by default, users may execute DDL and DML statements or copy data directly in SQL Editor.
  • restriction controls access to the data source:
    • RESTRICTION_UNSPECIFIED: Admin data source is allowed.
    • DISALLOW: Admin data source is completely disallowed.
    • FALLBACK: Prefer the read-only data source; use admin only if read-only is not configured.

​
Step 6 - Apply Configuration

Apply all configurations: 
terraform plan
terraform apply
Verify in Bytebase:
  1. Go to Environments.
  2. Check that Prod shows a shield icon (protected).
  3. Click each environment to see the configured policies.

​
Summary and Next Steps

You’ve successfully configured Bytebase environments using Terraform! Your setup now includes:
  • Test environment: Unprotected with automatic deployment for fast development
  • Prod environment: Protected with manual deployment and data restrictions for safety

Part 2: Manage Databases with Terraform