Database CI/CD and Schema Migration with TiDB and GitHub

Estimated: 30 mins
Database CI/CD and Schema Migration with TiDB and GitHub

A series of articles about Database CI/CD and Schema Migration with TiDB


Overview

In the last article Database CI/CD and Schema Migration with TiDB, you have tried UI workflow in Bytebase.

This tutorial will bring your TiDB schema change to the next level by introducing the GitOps workflow, where you commit the schema change script to the GitHub repository, which will in turn trigger the schema deployment pipeline in Bytebase.

You can use Bytebase free version to finish the tutorial.

Prerequisites

Before you start this tutorial, make sure:

Step 1 - Run Bytebase in Docker and set the External URL generated by ngrok

ngrok is a reverse proxy tunnel, and in our case, we need it for a public network address in order to receive webhooks from VCS. ngrok we used here is for demonstration purposes. For production use, we recommend using Caddy.

ngrok-reverse-proxy

  1. Login to ngrok Dashboard and follow its Getting Started steps to install and configure.

  2. Run ngrok:

    ngrok http 8080

    and obtain the public URL https://b725-103-197-71-76.ap.ngrok.io: terminal-ngrok

  3. Run Bytebase in Docker with the following command:

    docker run --rm --init \
      --name bytebase \
      --publish 8080:8080 \
      --volume ~/.bytebase/data:/var/opt/bytebase \
      bytebase/bytebase:2.14.1
  4. Bytebase is running successfully in Docker, and you can visit it via localhost:8080. Register an admin account and it will be granted the workspace admin role automatically.

  5. Click the gear icon (Settings) on the top right. Click General under Workspace. Paste https://b725-103-197-71-76.ap.ngrok.io as External URL under Network section and click Update.

    external-url

  6. Bytebase is running successfully in Docker, and you can visit it via https://b725-103-197-71-76.ap.ngrok.io.

Step 2 - Find your TiDB in Bytebase

  1. Visit Bytebase Console through the browser via your ngrok URL. Log in using your account created from the previous tutorial. login

  2. If you have followed the last tutorial, you should have a Project TestTiDB and a database demo. home-testtidb-demo

Step 3 - Connect Bytebase with GitHub.com

  1. Click Settings on the top bar, and then click Workspace > Version Control. settings-vc-step1-github

  2. Choose GitHub.com and Click Next.

  3. Follow the instructions within STEP 2 - OAuth application info, and in this tutorial, we will use a GitHub personal account instead of an organization account. The configuration is similar. settings-vc-step2

  4. Go to your GitHub account. Click Settings on the dropdown menu. github-settings

  5. Click Developer Settings at the bottom of the left-side bar. Click OAuth Apps, and click New OAuth App. github-oauth-apps

  6. Fill Application name and then copy the Homepage and Authorization callback URL in Bytebase and fill them in. Click Register application. settings-vc-step2-urls github-new-oauth

  7. After the OAuth application is created successfully. Click Generate a new client secret. Copy Client ID and this newly generated Client Secret, then paste them back into Bytebase. github-client-id-secrets

  8. Click Next. You will be redirected to the confirmation page. Click Confirm and add, and the Git provider is successfully added. github-auth settings-vc-git-provider-added

Step 4 - Enable GitOps workflow with TiDB

  1. Go to project TestTiDB, click Version Control, and choose GitOps Workflow. Click Configure version control. proj-testtidb-gitops
  2. Choose GitHub.com - the provider you just added. It will display all the repositories you can manipulate. Choose tidb-test-bb-local. proj-testtidb-step1-github proj-testtidb-choose-repo
  3. Keep the default setting, and click Finish. proj-testtidb-gitops-enabled

Step 5 - Change schema for TiDB by pushing SQL schema change files to GitHub

  1. In your GitHub repository tidb-test-bb-local, create a folder bytebase, and create an SQL file following the pattern {{ENV_ID}}/{{DB_NAME}}##{{VERSION}}##{{TYPE}}##{{DESCRIPTION}}.sql. It is the default configuration for the file path template setting when you configure the project version control previously. the full file path is bytebase/test/demo##202212302000##ddl##create_t2.sql:
  • test corresponds to {{ENV_ID}}
  • demo corresponds to {{DB_NAME}}
  • 202212302000 corresponds to {{VERSION}}
  • ddl corresponds to {{TYPE}}
  • create_t2 corresponds to {{DESCRIPTION}}

Paste the sql script in it.

CREATE TABLE t2
(
   id BIGINT NOT NULL,
   nickname VARCHAR(255)
);

vscode-demo-create-t2

  1. Commit and push this file.
  2. Go to Bytebase, and go into project TestTiDB. You’ll find there is a new issue [demo] Alter schema created.
  3. Click and go to the issue page, you’ll see:
  • The issue is created via github.com.
  • The issue is completed without manual approval because it applies the schema change to a database from the Test environment. And our Test environment is configured with no manual approval required.
  • The SQL is exactly the one we have committed to the GitHub repository.
  • The Assignee is Bytebase, because it’s automatic. If the github user you use to commit the change has the same email address found in the bytebase member list, we will use that member as the assignee. issue-alter-schema-create-t2
  1. Click the view migration, you could view the migration diff. db-demo-migration-create-t2

  2. Go to GitHub repository, you will see besides your committed SQL, there is a demo##LATEST.sql file. Because you have configured Schema path template before, Bytebase will write back the latest schema to that specified path after completing the schema change. Thus you have access to an update-to-date full schema at any time. github-test-folder github-latest

  3. Let’s create another SQL file demo##202212302040##ddl##add_age.sql to see how that latest schema file will be updated after applying a new schema change. Paste the SQL script in it.

ALTER TABLE t2 ADD age INT;

vscode-add-age-t2 8. After pushing the new SQL file, go back to the Bytebase and you should find the generated issue. issue-alter-schema-add-age 8. Click view migration and compare the diff. db-demo-migration-age 9. Go to GitHub repository and you will find the LATEST SQL has been updated to reflect the latest schema. github-latest-age

Summary and Next

Now you have tried out GitOps workflow, which will store your TiDB schema in GitHub and trigger the change upon committing the change to the repository, to bring your TiDB change workflow to the next level of Database DevOps - Database as Code.

You can check out our GitOps docs to learn more configuration details.

In real world scenario, you might have separate feature and main branches corresponding to your dev and production environment, you can check out GitOps with Feature Branch Workflow to learn the setup. Have a try and look forward to your feedback!

Edit this page on GitHub

Subscribe to Newsletter

By subscribing, you agree with Bytebase's Terms of Service and Privacy Policy.