bytebase 使用

1 创建环境

导航到 Environments 菜单， 默认存在 Test 和 Prod 两个环境，你也可以根据实际情况选择创建环境，例如 Staging, Canary 等等。这里我们保留默认的环境即可。

2 添加实例

接下来我们把两个 MySQL 数据库添加到实例中，导航到 Instances 界面，点击 Add Instance 添加数据库实例。

添加 Test 环境的实例，连接参数如下所示。

添加 Prod 环境的实例。

查看当前数据库的状态，可以看到这两个实例当前还没有分配给项目。在操作数据库之前我们需要先把它们关联到项目中。

3 创建项目

Bytebase 中的项目是团队协作的逻辑单元，其中包含了项目相关的数据库，issue，以及用户，类似于 Jira, GitLab 等其他开发工具中的项目概念。导航到 Projects 界面，点击 New Project 新建一个项目。

 

项目名设置为 project-1。

点击 Transfer in DB 将我们先前添加的两个数据库实例转移到项目中。

在项目 project-1 中点击 Databases 可以看到当前该项目中包含的数据库实例。

4 基本查询和变更

Bytebase 的 SQL Editor 为用户提供了一个一体化的界面来对数据库执行交互式操作。

例如可以对数据库进行查询：

Bytebase 能够在我们输入语句的时候智能地进行提示。

 

点击 Schema Diagram 图标还可以展示数据库中各个表中的关系图。

 

点击 Admin Mode 可以打开管理模式。在管理模式下，你不仅可以对数据库进行增删改查，还可以运行 SHOW、SET、GRANT 等数据库管理语句。管理模式通常是提供给 DBA 或者工作区所有者来访问的。

接下来我们按照工单的流程来对表中的字段进行变更。点击 Alert Schema 修改字段。

变更的数据库选择 TestDB 和 ProdDB。

Bytebase 提供了 Schema Editor，我们可以很方便地通过点击编辑来对字段进行修改，在 employee 表中点击 Add column，新增一个字段 phone，类型设置为 VARCHAR(11)。

切换到 Raw SQL，点击 Sync SQL from Scheme Editor 将刚刚编辑的内容直接转换为 SQL 语句。然后点击 Preview issue 进入下一步。

修改一下 issue 的标题，然后点击 Apply to other tasks，最后点击 Create 创建 issue。

默认情况下，变更会自动下发到 Test 环境的数据库实例，我们可以先在 SQL Editor 中查询 TestDB，发现新的字段 phone 已经成功添加了。

接下来点击 Approve 批准变更下发到 Prod 环境。

验证 Prod 环境也成功添加了新字段 phone。

任务运行成功后，可以点击 Resolve issue 关闭工单。

点击 View change 可以看到变更内容。

变更内容如下所示。

 

5 ChatSQL

在最新的 Bytebase 1.14.0 版本中，推出了基于 OpenAI 的 ChatSQL 功能。你可以用自然语言向 ChatSQL 提出问题或者需求，ChatSQL 会自动将这些问题转换为 SQL 语句，并在数据库中执行查询。

要使用 ChatSQL 前提需要有 OpenAI 的密钥，点击 Settings -> Workspace -> General，在 OpenAI API Key 输入框中填入 OpenAI 的密钥。

接下来你就可以在聊天框中向 ChatSQL 提出你的问题。

我向 ChatSQL 问了如下的问题，可以看到不管是简单查询还是多表关联查询，ChatSQL 基本上都可以成功给出正确的 SQL 语句。

 

唯一美中不足的地方就是 ChatSQL 目前并不能完美地支持对话的上下文，例如上面的问题得到了员工数量最多的 department 是 development，紧接着下面的问题我用“这个”来指代上面的 development 部门，但是这里 ChatSQL 并没有将 development 代入到下面的查询语句中。

那我这里把“这个” 换成 development 部门，ChatSQL 就可以给出正确的 SQL 语句了。

接下来我又问了几个问题，ChatSQL 都给出了正确答案。

6  GitOps

“版本控制模式”（Version controlled schema）也称作“数据库即代码”（Database-as-code），它是一种将数据库结构（schema）存储在版本控制系统（VCS，例如 Github）中的实践，其优点是可以跟踪数据库结构的变化，便于审查、协作和回滚。

Bytebase 作为 CNCF Landscape 中首个数据库 CI/CD 解决方案，GitOps 功能在其中扮演着极为重要的角色。接下来将会介绍通过 Bytebase GitOps 的方式完成数据库的变更，当 SQL 文件在 Github 中被更新时，会自动在 Bytebase 上创建工单进行数据库变更。当变更完成后，Bytebase 还会将最新的数据库 Schema 记录到 Github 中。

6.1 添加 Github Provider

点击 Settings -> Integration -> GitOps -> Github.com，配置 Bytebase GitOps 与 Github 进行集成。

然后会出现 OAuth Apps 的注册信息。其中最重要的参数就是 Authorization callback URL，这是 GitHub 在 OAuth 流程中用于回调 Bytebase 的 URI。

登录 Github 页面，转到 Settings -> Developer settings > OAuth Apps，点击 Register a new application。

 

使用 Bytebase 设置向导中提供的信息填写表格。

保存好 Client ID 和 Client Secret。

将 Application ID（Client ID） 和 Secret（Client Secret）填写到 Bytebase 设置向导的相应字段中。

确认并添加。

6.2 在项目中启用 GitOps 工作流

首先准备好一个 Github 仓库用于存放 SQL 文件。

在 project-1 项目中点击 GitOps，选择 GitOps workflow，单击 Configure GitOps 进入下一步。

 选择在 6.1 小节中添加的 Github Provider。

• Repository：设置连接到 Bytebase 项目的 Github 仓库。
• Base directory：设置为 bytebase/project-1，Bytebase 只会观察该目录及其所有子目录下的文件变化，稍后我们会将 project-1 项目相关的 SQL 变更文件放到该目录中。
• File path template：保持默认，该模板的支持以下占位符：
  • 必需的占位符：
    • {{DB_NAME}}：数据库名称。
    • {{VERSION}}：版本，一种常见的做法是使用类似 YYYYMMDDHHMMSS 的时间戳或者 v1, v2 作为版本名称。
    • {{TYPE}} ：变更的类型，可以是 ddl 或者 dml。
  • 可选的占位符：
    • {{ENV_ID}} ：小写的环境标识符，例如 Test 环境对应的是 test。
    • {{DESCRIPTION}} ：描述信息。
• Schema path template：保持默认，在每次变更后，Bytebase 会将最新的 Schema 写到该路径。
   

6.3 提交 SQL 变更代码

在 project-1 目录下的 test 和 prod 目录下各自创建 一个 SQL 文件 employee##v1##ddl##create_table.sql，文件内容相同，添加一张名为 timecards 表。

 SQL 语句如下。

CREATE TABLE timecards (
  `timecard_id` INT AUTO_INCREMENT PRIMARY KEY,
  `emp_no` INT NOT NULL,
  `date` DATE NOT NULL,
  `start_time` TIME NOT NULL,
  `end_time` TIME NOT NULL,
  `hours_worked` DECIMAL(5, 2) NOT NULL,
  FOREIGN KEY (`emp_no`) REFERENCES `employee` (`emp_no`) 
);

将代码推送到 Github 上。

git add .
git commit -m "add new table"
git push

提交代码后，回到 project-1 项目首页，可以看到捕获到了 Push 事件。

点击 Github 的 commit id 可以跳转到 Github 上对应的 commit。

Bytebase 会自动为我们创建工单，点击 issue 跳转到工单页面。默认情况下，Test 环境会自动下发变更，点击 Approve 下发变更到 Prod 环境。

等待 Prod 环境的变更执行成功。

点击 View change，可以看到变更内容，如图所示。

此时，返回到 GitHub 仓库可以看到 Bytebase 已经将最新版本的数据库 schema 写回到 Github 中了。

7 总结

 在本文中，我们首先向读者展示了 Bytebase 的安装部署过程，以及其查询和更改的基本功能。接着，我们体验了 Bytebase 1.14.0 最新版本所带来的 ChatSQL 功能，该功能基于 OpenAI，能够根据我们的问题或需求生成相应的 SQL 语句。最后，我们实践了 Bytebase 的 GitOps 功能，通过结合版本控制系统，可以跟踪数据库结构的变化，方便我们对数据库变更进行审查、协作和回滚操作。