Manage Databases in Bytebase with Terraform
This tutorial will guide you to use Terraform Bytebase Provider to manage your databases via Terraform.
Terraform is an infrastructure as code tool that lets you build, change, and version infrastructure safely and efficiently. This includes low-level components like compute instances, storage, and networking; and high-level components like DNS entries and SaaS features.
Bytebase is an open-source database DevOps tool, it's the GitLab for managing databases throughout the application development lifecycle. It offers a web-based workspace for Developers and DBAs to collaborate and manage the database change safely and efficiently.
Why Terraform? Although Bytebase provides a GUI for you to manage databases, if you have tens or hundreds of database instances for different environments, instead of repetitive and error-prone manual work, Terraform would definitely save your efforts and prevent mistakes.
Before you start the tutorial, make sure:
- Have Docker installed.
Install Terraform
Follow Terraform installation Guide, we use the mac version in this tutorial.
- Install the HashiCorp tap, a repository of all our Homebrew packages.
- Install Terraform with hashicorp/tap/terraform.
- Verify the installation by typing.
Run Bytebase
In this section, you’ll start Bytebase and follow its onboard guide.
-
Make sure your docker daemon is running, and then start the Bytebase docker container by typing the following command in the terminal.
-
Type the following commands one by one in the terminal to start two MySQL instances, and they will be mapped to
Test
andProd
environments later.
- Register admin account
DBA
. This account will be grantedWorkspace Admin
role. https://www.bytebase.com/docs/concepts/roles-and-permissions
Add an Instance in Bytebase from GUI
In this section, you'll follow the onboard guide to add an instance in Bytebase.
-
Follow the onboard guide or click Add instance on home page.
-
Create an instance for
Test
Environment with the following configuration. Fill username/password asroot
/testpwd1
-
Follow the onboard guide or click New Project on Projects page. Create a project
Test
with keyTEST
and click Create. -
Follow the onboard guide or click New DB on the project
Test
page. -
Create a database
demo
, and click Create. This will take you to the issue page, an issue is created. Since it’s forTest
environment, it will execute without approval from you. Click Resolve issue, and the issue will be done.
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. -
Follow the document and go to Example Usage. Copy the following provider part and paste it in
main.tf
.
Step 2 - Add a Terraform account
-
Click Settings on the top navigation bar, and click Workspace > Members.
-
Turn on Create as service account, fill email with prefix
tf
, and click + Add. -
Scroll down, and you can see the newly added account there. Click Copy Service Key.
Step 3 - Query to list all resources
-
Paste the Service Key, Service Account Email, and URL into
main.tf
.The file now should look like this: -
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:
As we have two default environments in our Bytebase. Pay attention to resource_id
, they are test
and prod
.
As we can see, it’s the instance we just added. Follow "title" = "MySQL Test"
, you'll find "resource_id" = "instance-e14ae248"
.
Step 4 - Add instances via Terraform
Now you have listed all environments and instances you have in Bytebase. Then how to create/update?
- Remove the
#List all environment
and#List all environment
blocks, and add the following:
What it does is first to define some variables, and then add four resources:
- two environments –
Test
andProd
- two instances -
MySQL Test TF
andMySQL Prod TF
-
Run
terraform init
,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.
If you go back to the previous query output
You can see that the resource_id
happens to be the same as in the local variables:
Combined with the terminal warning message above:
What happened is that the two existing environments match with the ones terraform declare by resource_id, so the Bytebase provider will attempt to update the environment.
- Click Instances. You’ll see there are two instances added.
Why it's different from the environments? If you go back to query output for our existing instance which is added from GUI.
And there are the resource_id
s defined in the local variables:
The resource_id
generated by UI operation instance-e14ae248
can’t match the one defined in terraform, and it’s not possible to adjust to make them match. So for the instances, it adds them instead of updating.
Step 5 - Test if the instances added by Terraform are working
-
Click Projects on the top navigation bar, and then click New Project. Create a new project called
TestTF
. -
Click TestTF on the left side bar, and click New DB.
-
Fill out the form as follows and click Create.
- Name: demotf
- Environment: Test
- Instance: MySQL Test TF
-
You’ll be redirected to the issue page, and click Resolve issue.
-
Click Instances on the top navigation bar, then select
MySQL Test TF
. You’ll seedemotf
.
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.
If you encounter any problems while trying, welcome to our discord channel.