Skip to main content
SQL Review is Bytebase’s automated analysis of SQL before execution. It checks statements against supported rules and information about the target database, then returns findings with a severity and explanation. Rules cover syntax, naming, schema design, and potentially risky operations. For example, if a policy requires NOT NULL columns, a nullable employee.nickname produces a finding. The author can correct the SQL and rerun the checks before deployment.

​
SQL Review versus human approval

SQL Review checks SQL rules; human approval assesses context such as rollout timing and application compatibility. UI checks appear on the Plan, with approval recorded in its Issue. GitOps uses CI checks and pull-request review. Passing SQL Review alone neither approves nor deploys a change. SQL Review is one of the automated checks on a UI Plan. Other Plan checks, such as the affected-row estimate, report their own results.

​
Configure SQL Review

A SQL Review policy is a named collection of rules, parameters, and severity levels. A Workspace Admin, Workspace DBA, or member with policy-management permission opens workspace CI/CD → SQL Review, creates a policy, and sets engine-specific rules to Error, Warning, or Disabled. Attach the policy to the intended environments or projects. Bytebase uses the enabled policy on the database’s effective environment, falling back to the project policy. Policies are not merged. Built-in checks also apply unless overridden by a matching configured rule. See the policy guide for configuration and precedence, and the rule reference for engine support.

​
Run SQL Review

Run checks through:
  • UI: create or update the SQL in a Plan and inspect the resulting checks.
  • GitOps: configure a CI job to check migration files and report its findings during pull-request review. Set the job’s failure threshold explicitly.
  • API: an integration can request SQL checks without deploying the SQL.
After editing SQL, read the new results for the intended target.

​
Resolve a finding

  1. Open a draft Plan and inspect the checks under Changes.
  2. Open a finding. Read its rule, severity, statement location, and explanation.
  3. Fix the relevant SQL. For the example above, decide whether the column should be mandatory, then add NOT NULL if appropriate.
  4. Save the updated SQL and wait for the checks to finish again.
For a rule requiring non-null columns, change ADD COLUMN nickname TEXT to ADD COLUMN nickname TEXT NOT NULL DEFAULT '' if nicknames should use an empty string instead of null. For a hands-on exercise using the sample project, follow SQL Review with the GUI.

​
Understand the result

SQL that exceeds the SQL size limit receives a size-limit finding, and the remaining SQL Review rules are skipped. A warning can therefore mean review was incomplete, not that the SQL passed all checks. Read any explanation that says checks were skipped or unavailable; missing evaluation is not a successful review. In the example below, SQL Review passed. Affected rows is a separate Plan check, not another SQL Review rule. The sample checks panel reports SQL review OK and a separate successful affected-row check For stale schema findings or connection failures, ask the instance operator to check metadata sync and connectivity. For unclear rules, contact the policy owner. Differences between Test and Prod can reflect their schemas, engines, or policies. In CI, configure --check-release=FAIL_ON_ERROR to make errors fail the job, or FAIL_ON_WARNING to fail on warnings too. The action’s default SKIP reports findings without using them to fail the job. See SQL Review in CI.

​
Under the hood

Rules draw on different information: the SQL statements, a model of the database schema, or selected live database information. The diagram shows these sources; an individual rule may use only one of them. SQL Review rules use statement analysis, supported schema simulation, or selected live database information to produce findings Bytebase parses SQL with engine-specific support. Some rules inspect statements directly, such as checking whether an UPDATE has a WHERE clause. For supported engines and statements, Bytebase builds an in-memory schema catalog from synchronized metadata and simulates changes in statement order. Later statements can see earlier CREATE TABLE or ALTER TABLE effects, allowing checks on intermediate and final schemas. The catalog contains schema metadata, not rows; simulation does not run the migration on the target. Some rules separately query live information, such as EXPLAIN estimates. Catalog use and simulation support vary by engine and rule. Results depend on supported syntax and available metadata; test application behavior and operational effects before production deployment.