Manage Databases with Terraform
This tutorial is part of the Manage Bytebase with Terraform series:
- Part 1: Manage Databases with Terraform (This one) - Set up instances and environments
- Part 2: Manage Projects with Terraform - Organize databases into projects
- Part 3: Manage Bytebase Settings with Terraform - Configure workspace settings, approval flows, and risk management
- Part 4: Configure Database Access with Terraform (Coming next) - Set up access controls and permissions
📚 Complete examples: GitHub - Bytebase Terraform Provider
Learn how to automate database infrastructure management by combining Bytebase with Terraform using the Terraform Bytebase Provider.
What You’ll Learn
In this tutorial, you’ll discover how to:
- Set up Bytebase and Terraform for database infrastructure management
- Configure environments using two different approaches (settings vs. individual resources)
- Create and manage database instances across multiple environments
- Implement proper dependency management for reliable deployments
Why Use Terraform with Bytebase?
While Bytebase provides an intuitive GUI for database management, Terraform brings several key advantages for larger deployments:
- Scale Efficiently: Manage hundreds of database instances without repetitive manual work
- Reduce Errors: Infrastructure as code eliminates human mistakes in configuration
- Version Control: Track and review all infrastructure changes through Git workflows
- Consistency: Ensure identical configurations across environments
Bytebase Terraform Provider handles control plane configuration such as settings, policies, access controls. It does not handle data plane operations such as database creation, schema migrations, DML execution, query.
Prerequisites
Before starting this tutorial, ensure you have:
- Docker: Install Docker to run Bytebase and MySQL instances
- Terraform: We’ll install this in the next section
- Basic CLI Knowledge: Familiarity with terminal/command line operations
Setup
Install Terraform
For macOS (using Homebrew):
For other platforms: Follow the official Terraform installation guide.
Start Services
-
Start Bytebase:
-
Start MySQL instances for Test and Prod environments:
-
Set up Bytebase admin account:
Navigate to Bytebase (usually
http://localhost:8080
) and register an admin account withWorkspace Admin
role.
Initial Bytebase Setup (GUI)
Before automating with Terraform, let’s set up a basic instance through the GUI to understand the manual process:
-
Add a database instance:
- Login as admin, click Instances on the left sidebar, click + Add Instance
- Configure for
Test
environment with credentialsroot
/testpwd1
-
Create a project and database:
- Click Projects on the left sidebar, click + New Project, create project
Test
- Navigate to project, click Database > Databases on the left sidebar, click + New DB
- Create database
demo
- Click Projects on the left sidebar, click + New Project, create project
This manual process works fine for a few instances, but imagine doing this for dozens or hundreds of database instances across multiple environments!
Add Instances via Terraform
You’ve added an instance for the Test
environment in Bytebase by clicking. What if you need to add hundreds of instances. In this section, you’ll witness the process simplification Terraform brings.
Step 1 - Create a Terraform file
-
Create a new folder
learn-terraform-bytebase
and create a blank filemain.tf
in it. -
Go to https://registry.terraform.io/providers/bytebase/bytebase/latest/docs. Click Use Provider, copy and paste the whole code block in the gray box into
main.tf
. Pay attention to the version. -
Copy the following provider part and paste it in
main.tf
.
Step 2 - Add a Terraform account
-
Go to IAM & Admin > Users & Groups, click + Add User.
-
Choose
Service Account
as the Type, fill in the Email withtf@service.bytebase.com
, chooseWorkspace DBA
as Roles, and click Confirm. -
Copy the Service Key for later use.
Step 3 - Query to list all resources
-
Paste the Service Key, Service Account Email, and URL into
main.tf
. -
Paste the following queries after the provider block and save the file. What it does is to list all existing environments and instances and print those out in the terminal.
-
Run
terraform init
,terraform plan
andterraform apply
one by one in the terminal. You’ll see the output like this:As we have two default environments in our Bytebase. Pay attention to
resource_id
, they aretest
andprod
.As we can see, it’s the instance we just added. Follow
"title" = "MySQL test"
, you’ll find"resource_id" = "mysql-test"
.
Step 4 - Configure Environments
Before creating instances, let’s properly configure the environments. There are two approaches to achieve this - you typically only need one of them.
Step 4a - Configure Environment Settings (Recommended)
This approach uses environment settings and is usually sufficient for most use cases.
-
Remove the
#List all environment
and#List all instances
blocks, and add the following environment configuration:
Step 4b - Create Environments via Individual Resources (Alternative)
Alternatively, you can create environments using individual bytebase_environment
resources. This approach provides more granular control but requires careful dependency management.
Important: When using multiple bytebase_environment
resources, you must use depends_on
between environments. This ensures Terraform updates them in the correct order, as the Bytebase API only supports updating one environment list at a time.
-
Add the following environment resources after the settings configuration:
Step 5 - Add Database Instances
Finally, let’s add the database instances that will be associated with our environments. The configuration depends on which approach you chose in Step 4:
If you used Step 4a (Environment Settings)
If you used Step 4b (Individual Environment Resources)
Key Points:
- Step 4a approach: Instances depend on
bytebase_setting.environments
and use environment references like"environments/${local.environment_id_test}"
- Step 4b approach: Instances depend on individual environment resources and use direct references like
bytebase_environment.test.name
- Both approaches create the same end result - database instances properly linked to their environments
-
Run
terraform plan
andterraform apply
one by one in the terminal. You will see this in the terminal. -
Go back to Bytebase, and click Environments. There is nothing changed with these two environments.
-
Click Instances on the left sidebar, and you will see the two instances we just added.
-
Click into one instance, scroll down and click Test Connection. It should be successful.
Summary and Next
Now you have learned how to use Terraform to manage your MySQL database environments and instances in Bytebase, for PostgreSQL, you can futher declare database roles. Please check more example usage in GitHub.
Next in the Series
Continue to the next tutorial: Manage Projects with Terraform where you’ll learn how to organize your databases into projects for better management.
If you encounter any problems while trying, welcome to our discord channel.