> ## 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.

# AI SQL Review

> [!NOTE]
>
> Available only for:
>
> * **Enterprise** plan

**AI SQL Review** uses the AI model you configured in [AI Assistant](https://docs.bytebase.com/ai-assistant.md) to review the SQL of a database change plan. It adds to [SQL Review Rules](https://docs.bytebase.com/sql-review/review-policy.md): it reads the target database's schema and statistics to look for risks in the change, follows a review policy you can customize in plain language, and posts each finding as an inline comment on the SQL statement in the plan.

It runs beside SQL Review Rules and the other plan checks, and does not read or change them. See [SQL Review](https://docs.bytebase.com/sql-review/overview.md) to compare the two.

What the review checks comes from two places:

* The [default review policy](#default-review-policy), which runs on every review and needs no configuration.
* Your own [AI review policy](#write-an-ai-review-policy), which adds checks you write in plain language, such as a team convention.

## Prerequisites

* The workspace [AI Assistant](https://docs.bytebase.com/ai-assistant.md) setting is enabled. AI SQL Review uses the same provider and model.
* Bytebase has synced the schema of the target databases. The review reads the synced schema, and fails for a database whose schema is not synced.

## Enable AI SQL Review

AI SQL Review has its own switch, which is off by default. Changing it requires the **Workspace Admin** or **Workspace DBA** role.

1. In the workspace sidebar, go to **CI/CD** > **SQL Review**.
2. In the **AI review** section, turn on **Review changes with AI**.
3. Click **Update**.

![Workspace SQL Review page with Review changes with AI turned on and an AI review policy entered below it](https://mintcdn.com/dbx/PVWR7jOhLhaUkwzD/content/docs/sql-review/ai-review/ai-review-settings.webp?fit=max\&auto=format\&n=PVWR7jOhLhaUkwzD\&q=85\&s=699db62444fe1d5863649f8a17e5eb95)

If the section says **AI is off for the workspace, so no AI review runs**, enable [AI Assistant](https://docs.bytebase.com/ai-assistant.md) first. The switch is read-only until you do.

## Default review policy

The default review policy runs on every review. It checks for:

* **Breakage**: a statement that fails on the target database, or breaks a view, function, trigger, or foreign key that depends on what it changes. This includes a constraint that existing rows would break.
* **Operational risk**: a long lock, a table rewrite, or a full scan on a large table.
* **Data loss**: a cascade that deletes rows in tables the statements never name.

It does not report naming, formatting, or style problems unless your policy asks for them.

> [accordion] The default review policy prompt
>
> This is the part of the prompt that says what the model looks for. The full prompt, including how the model works and the format of its answer, is in [`base_prompt.md`](https://github.com/bytebase/bytebase/blob/main/backend/plugin/aireview/base_prompt.md).
>
> ```text theme={null}
> # What to look for
>
> - Breakage: a statement fails on this database or makes later code fail. A
>   view, function, trigger, or foreign key depends on what it changes. Existing
>   rows break a constraint it adds.
> - Operational risk: a long lock, a table rewrite, or a full scan on a large
>   table.
> - Data loss: a cascade that deletes rows in tables the statements never name.
> - Anything the policy below asks for. Check every policy sentence against
>   every statement it applies to.
>
> Do not report naming, formatting, or style problems unless the policy asks for
> them.
>
> # What counts as a finding
>
> - A finding is a defect the author would fix once told: one cause in one
>   statement, which one edit to the statements removes. Do not report remarks,
>   praise, or things that are merely worth knowing.
> - Every finding rests on a fact you have: from the target section, from the
>   statements, or from a tool result.
> - When you cannot get a fact the finding needs, and the schema and the row
>   counts do not settle it, do not raise that finding.
> ```

### Adjust the default review policy

The default review policy has no settings of its own. You change it through your [AI review policy](#write-an-ai-review-policy), in one of two ways. In both, name the check as the list above does.

**Tune a check** when it reports more than you need. Narrow when it applies, or lower the priority it reports at. The review can see each table's row count and size, so a limit on them works:

```text theme={null}
Report a full scan or a table rewrite as operational risk only when the table has more than 1,000,000 rows.
Report a long lock on a table with fewer than 100,000 rows as P2.
```

A finding at a lower priority is still a thread that must be resolved before the automatic rollout. To stop a kind of finding entirely, turn the check off.

**Turn a check off** when you never want it. Say that everything else still applies, so the line does not also switch off your other policy sentences:

```text theme={null}
Do not report operational risk: long locks, table rewrites, or full scans. Report every other problem, and check every other sentence of this policy, as usual.
```

Put either one in the workspace policy to apply it everywhere, or in a project's policy to apply it to that project only. Where the two conflict, the project policy wins. Your policy is an instruction to the model, not a switch, so try it on a plan that has a problem of that kind before you rely on it.

## Write an AI review policy

A policy adds your own checks to the default review policy, in plain language. It is optional: without one, the review still runs the default checks.

```text theme={null}
New tables need created_at and updated_at columns.
```

Policies exist at two levels:

* **Workspace**: in the workspace sidebar, go to **CI/CD** > **SQL Review** and edit **AI review policy**. It applies to every project.
* **Project**: in the project sidebar, go to **CI/CD** > **SQL Review** and edit **Project additional policy**. It is added to the workspace policy and takes precedence where the two conflict.

Each policy can hold up to 64 KiB of text. Both fields appear only while **Review changes with AI** is on. The **Workspace Admin** and **Workspace DBA** roles can edit both policies; the **Project Owner** role can edit the policy of its project.

When your policy states a priority for a problem, the review uses it.

## When a review runs

AI SQL Review covers the database change plans you create in the Bytebase console. A review starts when:

* You create the plan, including as a draft.
* The SQL of the plan changes.
* Someone clicks **Run**, **Rerun**, or **Retry** on the **AI review** row, under **Automated review** in the plan's **Review** section.

![Automated review section of a plan: an AI review row with two P1 findings and a SQL review row that passed, each with Details and Rerun buttons](https://mintcdn.com/dbx/PVWR7jOhLhaUkwzD/content/docs/sql-review/ai-review/ai-review-automated-review.svg?fit=max\&auto=format\&n=PVWR7jOhLhaUkwzD\&q=85\&s=b89134668c3acc609b1ca7993fbf6790)

Marking a draft ready for review does not review the same SQL again.

> [!WARNING]
>
> A review can take several minutes, depending mostly on the model, and the review of each database stops after 10 minutes. When it stops, the whole run fails and posts no new findings. A failed review does not hold the automatic rollout, so click **Retry** before you approve the plan. See [Limitations](#limitations).

AI SQL Review does not cover:

* Plans that create a database.
* [GitOps](https://docs.bytebase.com/gitops/overview.md) changes that come from a release.
* Access grant requests.
* A plan that already has a rollout.

The review runs once for each target database. When the same problem appears on several databases, it is reported as one comment that lists them. If the project sets **CI Data Sampling Size**, the review covers only that many of the target databases; see [Limitations](#limitations). Hover the info icon on the **AI review** row to see which databases it covered.

## Read the findings

Each finding is a comment thread from **AI review**. It appears in two places:

* **On the SQL**: in the plan's **Changes** section, as a comment under the line it refers to. Use the arrows beside the editor to step through the comments.
* **In Activity**: under the entry for the run, such as **AI review reviewed the SQL · 2 new findings**, with the line of SQL it refers to.

![An AI review comment on line 3 of the SQL: a P1 finding that the new employee\_badge table lacks the created\_at and updated\_at columns the policy requires, with the rule, a suggested fix, and Reply and Resolve](https://mintcdn.com/dbx/PVWR7jOhLhaUkwzD/content/docs/sql-review/ai-review/ai-review-comment.svg?fit=max\&auto=format\&n=PVWR7jOhLhaUkwzD\&q=85\&s=7fa9a31ae6566e030ea4b8adb3f1870e)

The **Rule** line quotes what the finding breaks: a sentence of the default review policy, or a sentence of your policy, as in the example above.

| Priority | Meaning |
| - | - |
| **P0** | Likely data loss or an outage. |
| **P1** | Breaks a policy sentence or carries a real operational risk. |
| **P2** | A suggestion, with low rollout risk. Resolve it once read, whether or not you apply it. |

Every open thread holds the automatic rollout, whatever its priority. See [Resolve threads before rollout](#resolve-threads-before-rollout).

When the review runs again:

* A finding it reports again keeps its thread and replies. If it now reports the finding at a higher priority, a resolved thread opens again.
* A finding it no longer reports is resolved automatically.
* If the review cannot run, for example because the AI provider returns an error, the **AI review** row shows the error and a **Retry** button, and earlier findings stay as they were.

> [!WARNING]
>
> A run shows at most **10** open findings. Further new findings are held back, and the **AI review** row does not say how many. To see them, fix the SQL or resolve the findings you have read, then click **Rerun**: resolved threads do not count toward the 10. See [Limitations](#limitations).

## Resolve threads before rollout

Bytebase creates the rollout automatically when all checks pass, every thread is resolved, and the plan is approved. An open thread holds the automatic rollout whoever started it, AI SQL Review or a person, and whatever its priority.

To clear a finding, do one of the following:

* Change the SQL. The review runs again and resolves the findings it no longer reports.
* Click **Resolve** on the thread to accept the risk.

A user who can create the rollout can still choose **Bypass and deploy**, which lists the unresolved threads to acknowledge.

## What AI SQL Review sends to the AI provider

Each review sends the statements as written, the default review policy and your policies, facts about the target database such as its engine and version, and the object definitions and table statistics the model looks up in the synced schema. It reads no rows from your databases. See [What Bytebase sends to the AI provider](https://docs.bytebase.com/ai-assistant.md#what-bytebase-sends-to-the-ai-provider).

## Limitations

* **Findings per run**: a run shows at most 10 open findings, ranked by priority and then by their order in the plan. Open threads from earlier runs count toward the 10 and are always kept; resolved threads do not count. The limit keeps the findings that matter from being lost in a long list of noise. Further new findings are held back, without notice, until you fix or resolve the ones shown and run the review again. We are working to improve this.
* **Sampled databases**: the review calls the model several times for each target database, so a change across many databases costs many model calls. When the project setting **CI Data Sampling Size** is set, the review covers the same databases that plan checks sample: the first that many targets. Without it, the review covers every target database.
* **Review time**: for each database, the model looks up the schema facts it needs and then writes its findings, and Bytebase then merges and summarizes the findings across databases. How long this takes depends on the model and how long it thinks; Bytebase uses the provider's default thinking level. In our tests, a simple change on two databases took 43 seconds to 1 minute 11 seconds with Gemini 3.1 Pro, and more than twice as long with Gemini 3.8 Flash, which thinks for longer before it answers.
* **Time and model calls**: the review of each database stops after 10 minutes or 20 model calls. If the review of any database stops, the whole run fails: it posts no new findings, earlier findings stay as they were, and the **AI review** row shows the error and a **Retry** button. A failed run does not hold the automatic rollout. To get the review through:
  * Click **Retry**. A model does not take the same time on every run.
  * Split a long change into smaller plans, so each review has fewer statements to check.
  * Ask a workspace admin to switch [AI Assistant](https://docs.bytebase.com/ai-assistant.md) to a model that answers faster. The setting applies to every AI feature in the workspace.
* **SQL size**: SQL over 256 KiB is not reviewed.
* **Synced schema only**: the review does not query the database. If the schema changed outside Bytebase, [sync the database](https://docs.bytebase.com/change-database/synchronize-schema.md) before you run the review.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.