GitOps 与 SQL 代码审核

NineData 支持将 SQL 代码审核接入企业现有的 GitOps 发版流程。应用代码在 GitLab、云效 Codeup 等代码平台中触发提交、合并请求、发布或流水线任务时，可以在 CI Job 中执行 ninedata check，对指定范围内的 SQL 文件和 MyBatis XML 文件进行审核，并将审核结果输出到代码平台。

功能介绍

在传统发布流程中，应用代码和数据库变更往往由不同系统管理。研发人员可能在提交代码时同时修改 MyBatis XML 文件或 SQL 文件，如果这些 SQL 未经过统一审核，可能在上线后引发慢 SQL、锁等待、全表扫描、语法错误或不符合企业规范等问题。

通过 GitOps 与 SQL 代码审核联动，您可以在代码平台中增加 SQL 审核 Job：

• 代码平台负责配置触发时机，例如提交、合并请求、发布流水线或自定义 Job。
• ninedata check 根据配置的文件匹配规则，从当前代码工作区中提取需要审核的 .sql 文件和 MyBatis XML 文件。
• NineData 基于目标数据源绑定的 SQL 开发规范、语法解析、慢 SQL 规则和索引推荐能力生成审核结果。
• 代码平台展示 NineData 返回的审核结果，提交人或合并人可以根据结果决定是否继续合并或发布。

适用场景

• GitLab Merge Request 或 CI/CD Pipeline 中需要自动审核 SQL。
• 云效 Codeup 代码合并、发布流水线或应用交付流程中需要接入 SQL 质量检查。
• 企业希望在应用发版前展示 SQL 审核结果，辅助提交人、合并人或 DBA 判断本次变更是否可以继续。

前提条件

• 已创建或加入组织，并且该组织已开通数据库 DevOps 企业版，同时请确保您的包年包月订阅未过期。
• 当前账号已切换到目标组织。更多信息，请参见切换到组织。

• 您已将需要审核 SQL 的目标数据库添加为 NineData 数据源。更多信息，请参见创建数据源。
• 目标数据源已配置 SQL 开发规范。更多信息，请参见SQL 开发规范管理。
• 您已准备可调用 NineData OpenAPI 的访问凭证，并已为调用方授予执行 GitOps SQL 审核所需权限。
• 代码平台可以在流水线、Webhook 或自定义脚本中访问 NineData 服务地址。

接入流程

步骤一：确定审核范围

在代码平台中确认需要提交给 NineData 审核的文件范围。当前支持如下文件：

• SQL 文件。
• MyBatis XML 文件，例如 Mapper XML 文件。

对于 Java、Go、Python 等代码文件中内嵌 SQL 的场景，当前版本暂不支持自动解析，相关能力正在排期中。

提示

建议仅提交本次变更涉及的 .sql 或 MyBatis XML 文件，避免每次流水线都重复审核整个代码仓库。

步骤二：在代码平台中配置审核节点

在 GitLab CI/CD、Codeup 流水线或企业自定义发版系统中新增一个 SQL 审核 Job。触发机制由代码平台负责配置，可根据平台能力选择提交、合并请求、发布流水线或自定义事件。

该 Job 通常需要完成如下动作：

1. 在代码平台中准备当前分支、目标分支和变更文件工作区。
2. 配置需要审核的文件匹配规则，例如 sql/**/*.sql 或 src/main/resources/config/mybatis/**/*.xml。
3. 执行 ninedata check。该命令会根据文件匹配规则提取指定文件，解析其中的 SQL，并发起一次 SQL 审核。
4. 将审核结果输出到流水线日志或报告文件中，供提交人、合并人或 DBA 查看。

配置 CI 运行镜像

GitOps 流程通过 CI Job 执行 ninedata check 命令。该命令运行在 NineData 提供的 CI 镜像中，因此需要在 GitLab 或 Codeup 的流水线配置中指定该镜像。CI Runner 启动 Job 时会自动拉取镜像，并在镜像容器内执行审核命令。

NineData GitOps CI 镜像的 Docker Hub 地址为 ninedata/ninedata-cicd，GitLab 示例中使用的镜像为 ninedata/ninedata-cicd:amd。

如果您的 CI Runner 无法自动拉取镜像，或需要提前验证网络连通性，可以在 Runner 所在机器上预先执行如下命令：

docker pull <NineData GitOps CI 镜像地址>

在流水线 YAML 中，镜像和命令的关系如下：

• GitLab：在 Job 中通过 image 指定 CI 镜像，然后在 script 中执行 ninedata check。
• Codeup：在 Job 的 container 字段中指定 CI 镜像，然后在命令执行步骤中执行 ninedata check。

配置 GitLab 流水线 YAML

在 GitLab 项目根目录中维护 .gitlab-ci.yml 和 ninedata-review.yml 两个文件。两个文件需要位于同一个根目录下，.gitlab-ci.yml 只需要引用同级的 ninedata-review.yml：

include:
  - local: ninedata-review.yml

在 ninedata-review.yml 中配置完整的 SQL 审核 Job：

sql-review:
  stage: test
  image:
    name: ninedata/ninedata-cicd:amd
    pull_policy: always
  variables:
    CREATOR: $GITLAB_USER_LOGIN
    NINEDATA_URL: "<NineData 服务地址>"
    CUR_BRANCH: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
    TARGET_BRANCH: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
    ACCESS_KEY: "<NineData OpenAPI AccessKey>"
    ACCESS_SECRET: "<NineData OpenAPI AccessSecret>"
    DATASOURCE_ID: "<目标数据源 ID>"
    DATABASE_NAME: "<目标数据库名>"
    EVENT_SOURCE: $CI_PIPELINE_SOURCE
  script:
    - pwd
    - |
      ninedata check \
        --url="$NINEDATA_URL" \
        --creator="$CREATOR" \
        --cur-branch="$CUR_BRANCH" \
        --trg-branch="$TARGET_BRANCH" \
        --access-key="$ACCESS_KEY" \
        --access-secret="$ACCESS_SECRET" \
        --file-patterns="src/main/resources/config/mybatis/console/mapper/*.xml" \
        --file-patterns="migration/*.sql" \
        --datasource="$DATASOURCE_ID" \
        --db="$DATABASE_NAME" \
        --event="$EVENT_SOURCE"
  artifacts:
    reports:
      codequality: ninedata_review_result.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - changes:
        - "migration/*.sql"
        - "src/main/resources/config/mybatis/console/mapper/*.xml"

需要替换或确认的参数如下。

参数	是否需要替换	说明
image.name	通常不需要	NineData GitOps CI 镜像地址。默认使用 Docker Hub 上的 ninedata/ninedata-cicd。若企业使用私有镜像仓库或镜像加速地址，请替换为实际镜像地址。
NINEDATA_URL	需要	NineData 服务地址，需要与 OpenAPI 凭证所属环境一致。
ACCESS_KEY、ACCESS_SECRET	需要	NineData OpenAPI 访问凭证。建议在 GitLab CI/CD Variables 中维护真实凭证，并在 ninedata-review.yml 中引用变量，避免明文提交到代码仓库。
DATASOURCE_ID	需要	目标数据源 ID。可在 NineData 数据源详情或相关 OpenAPI 查询结果中获取。
DATABASE_NAME	需要	需要审核 SQL 所属的数据库名称。
--file-patterns	需要	需要提交给 NineData 审核的文件范围。按仓库目录结构配置，当前支持 .sql 文件和 MyBatis XML 文件。
rules.changes	需要	GitLab 触发 SQL 审核 Job 的文件变更范围，建议与 --file-patterns 保持一致。
CREATOR	通常不需要	提交人，默认使用 GitLab 内置变量 $GITLAB_USER_LOGIN。
CUR_BRANCH、TARGET_BRANCH	通常不需要	当前分支和目标分支，默认使用 GitLab Merge Request 内置变量。
EVENT_SOURCE	通常不需要	流水线触发来源，默认使用 $CI_PIPELINE_SOURCE。
artifacts.reports.codequality	通常不需要	GitLab Code Quality 报告文件路径，默认使用 ninedata_review_result.json。

Codeup 流水线 YAML 示例：

sources:
  repo_0:
    type: codeup
    name: <Codeup 仓库名称>
    endpoint: <Codeup 仓库地址>
    branch: dev
    triggerEvents:
      - mergeRequestOpenedOrUpdate
    branchFilter: .*
    pathFilter: src/main/resources/config/mybatis/**/*.xml
defaultWorkspace: repo_0
stages:
  stage_0:
    name: SQL 审核
    jobs:
      job_0:
        name: Ninedata_CI
        runsOn:
          group: public/cn-hangzhou
          labels: linux,amd64
          container: <NineData GitOps CI 镜像地址>
        steps:
          step_0:
            name: 执行命令
            step: Command
            with:
              ifGivenShell: false
              run: |-
                ninedata check --url="$NINEDATA_URL" \
                  --creator="$BUILD_EXECUTOR" \
                  --cur-branch="$CI_COMMIT_REF_NAME" \
                  --trg-branch="$CI_COMMIT_TARGET_REF_NAME" \
                  --access-key="$NINEDATA_ACCESS_KEY" \
                  --access-secret="$NINEDATA_ACCESS_SECRET" \
                  --file-patterns="src/main/resources/config/mybatis/**/*.xml" \
                  --file-patterns="migration/*.sql" \
                  --db="$NINEDATA_DATABASE" \
                  --event="merge-request-event" \
                  --datasource="$NINEDATA_DATASOURCE_ID"
          step_1:
            name: 审核报告
            step: UnitTestReport
            with:
              reportPath: ./report/ninedata_review_result.html
              reporter: Java-JUnit
              failOnError: false

GitLab 接入示例

在 GitLab 中，您可以通过 Merge Request Pipeline、Branch Pipeline 或自定义 Job 接入 NineData SQL 代码审核。

1. 在 GitLab 项目根目录中创建 ninedata-review.yml，配置 SQL 审核 Job、镜像、审核参数和触发规则。
2. 确保 .gitlab-ci.yml 与 ninedata-review.yml 处于同一个项目根目录，并在 .gitlab-ci.yml 中通过 include 引用同级的 ninedata-review.yml。
3. 将 ninedata-review.yml 中的 NineData 服务地址、OpenAPI 访问凭证、目标数据源 ID、目标数据库和文件匹配规则替换为实际值。
4. 根据 GitLab 支持的触发条件配置 Job 触发时机，例如 Merge Request 或自定义 Pipeline。
5. 在 Job 脚本中执行 ninedata check，提取指定 .sql 文件和 MyBatis XML 文件并完成审核。
6. 在 Job 日志、报告文件或 Merge Request 页面展示审核结果。当前 GitOps 审核结果仅用于展示，NineData 不会在代码平台侧硬性阻塞合并或发布；提交人、合并人可以根据结果人工判断是否继续，企业也可以按自身 CI 策略配置阻塞规则。

Codeup 接入示例

在云效 Codeup 中，您可以在代码合并检查、流水线任务或应用发布流程中接入 NineData SQL 代码审核。

1. 在云效流水线中新增 SQL 审核任务。
2. 配置任务变量，保存 NineData 服务地址、访问凭证、目标数据源 ID、目标数据库等信息。
3. 根据 Codeup 支持的监听条件和过滤条件配置触发时机，例如提交、合并请求更新或指定路径变更。
4. 在任务脚本中执行 ninedata check，提取指定 .sql 文件和 MyBatis XML 文件并完成审核。
5. 在流水线日志、单元测试报告或 Codeup CI 节点中展示审核结果。当前 GitOps 审核结果仅用于展示，NineData 不会在代码平台侧硬性阻塞合并或发布；提交人、合并人可以根据结果人工判断是否继续，企业也可以按自身 CI 策略配置阻塞规则。

查看审核结果

GitOps SQL 审核不会在 NineData 控制台中创建持久化的 SQL 代码审核任务。审核完成后，您可以在代码平台查看结果：

• 流水线 Job 日志：查看 ninedata check 的执行日志、命中的规则和错误信息。
• 报告文件：查看流水线生成的 HTML 报告，例如 report/ninedata_review_result.html。
• 合并请求或 CI 节点页面：根据 GitLab、Codeup 或其他代码平台的展示能力查看审核结论。

结果处理建议

审核结果	建议处理方式
审核通过	在代码平台展示通过结果，后续流程可继续执行。
审核不通过	在代码平台展示问题 SQL、命中规则和优化建议。提交人或合并人可以根据结果人工阻塞合并或发布，企业也可以在 CI 中自行配置阻塞规则。
调用失败	检查 NineData 服务地址、访问凭证、网络连通性、目标数据源和数据库配置是否正确。

注意事项

• 不要在代码仓库中明文保存 NineData 访问凭证。建议使用 GitLab CI/CD Variables、Codeup 流水线变量或企业密钥管理服务保存。
• 建议将 SQL 审核 Job 放在应用部署或生产合并之前，便于提交人、合并人及时查看审核结果。
• 当前仅支持 .sql 文件和 MyBatis XML 文件。代码文件中内嵌 SQL 的场景暂不支持自动解析。
• GitOps 平台负责触发时机、分支信息、工作区和结果展示；NineData 负责根据文件匹配配置提取指定文件、解析 SQL 并返回审核结果。
• GitOps SQL 审核当前不会在 NineData 控制台中创建持久化任务。如需留档，请使用代码平台的流水线日志或报告归档能力。
• 如果同一应用涉及多个数据库，请按数据库分别执行审核，避免审核结果和目标数据源不匹配。