> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SQL Review
> Understand automated SQL checks, act on findings, and learn how Bytebase evaluates a change.
**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](/concepts/plan), with approval recorded in its [Issue](/concepts/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](/sql-review/review-policy) for configuration and precedence, and the [rule reference](/sql-review/review-rules) 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](/tutorials/sql-review-gui).
## Understand the result
SQL that exceeds the [SQL size limit](/sql-review/review-policy#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.
| Result | What to do next |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Passed** | The checks that ran found no violations. Continue with the workflow's review or deployment step. |
| **Error** | Read the finding and fix the SQL or ask the policy owner about the requirement. Required checks can block deployment. |
| **Warning** | Assess the finding. Whether it blocks progression depends on the workflow and configured gates. |
| **Pending or running** | Wait for the current check run; it is not yet a pass. |
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.
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](/gitops/migration-based-workflow/sql-review-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.
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.