> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawsql.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> PawSQL 是一个产品：Cloud 是公网部署形态，Engine / Optimizer / Auditor / Advisor / Patroller 是同一产品的组件与交付形态，不是彼此独立的产品。 / PawSQL is a single product: Cloud is the public deployment form, while Engine / Optimizer / Auditor / Advisor / Patroller are components and delivery forms of the same product, not separate products.
> 术语以站内术语表为准：SQL 审核对应英文 SQL Review，查询重写对应 Query Rewrite，索引推荐对应 Index Recommendation；英文内容统一用 Review，不用 Audit。 / Use the site glossary for terminology: 审核 is SQL Review, 重写 is Query Rewrite, 索引推荐 is Index Recommendation; English content uses Review, never Audit.
> 引用能力范围或版本支持时以对应页面为准；标注 unknown、或 status 非 published 的内容表示尚未经产品核实，不应作为事实引用。 / Cite capability scope and version support from the corresponding page; content marked unknown, or with a status other than published, is not yet product-verified and must not be cited as fact.

# SQL Quality Gates and Feedback

> Convert PawSQL review evidence into pass, warning, or block decisions and publish the result to the source platform.

The review policy defines what PawSQL checks. The quality gate defines how those findings affect delivery. Feedback then returns the decision, summary, and secure report link to the developer's current workflow.

## Goal

Convert PawSQL review evidence into pass, warning, or block decisions and publish the result to the source platform.

## Prerequisites

Prepare a review policy that defines what PawSQL checks, including blocking criteria and failure behavior.

## Recommended decisions

| Condition                                    | Default decision | Action                                          |
| -------------------------------------------- | ---------------- | ----------------------------------------------- |
| No SQL changes                               | Skip             | Finish successfully and record the reason       |
| No violations or informational findings only | Pass             | Publish a summary                               |
| Warning-level findings                       | Warn or block    | Apply the team's risk standard                  |
| Critical findings                            | Block            | Require remediation and a new review            |
| SQL parse failure                            | Block            | Correct the dialect, script, or workspace       |
| Required context missing                     | Block            | Add DDL or repair the database connection       |
| PawSQL unavailable                           | Failure policy   | Block, retry within limits, or request approval |

## Configuration workflow

<Steps>
  <Step title="Set the scope">Identify repositories, branches, paths, database types, and delivery stages.</Step>
  <Step title="Choose a validated policy">Use a published ruleset and retain the policy version with every run.</Step>
  <Step title="Define blocking criteria">Use severity, selected rules, parse errors, or approved count thresholds.</Step>
  <Step title="Define failure behavior">Choose fail-closed, fail-open, or manual approval for timeout, authentication failure, and service unavailability.</Step>
  <Step title="Control exceptions">Require a justification, approver, scope, and expiration.</Step>
  <Step title="Publish feedback">Select commit status, review comments, pipeline results, and report links.</Step>
</Steps>

## Feedback fields

| Field          | Purpose                                          |
| -------------- | ------------------------------------------------ |
| Gate decision  | Pass, warning, block, or system error            |
| Job state      | Queued, running, completed, failed, or timed out |
| Finding counts | Summary by severity or rule category             |
| SQL location   | File, statement, and line information            |
| Policy version | Reproduce the original decision                  |
| PawSQL job ID  | Support cross-system tracing                     |
| Report link    | Open complete findings and remediation evidence  |

## Status mapping

| PawSQL outcome             | Repository or pipeline status        |
| -------------------------- | ------------------------------------ |
| Queued or running          | Pending / Running                    |
| Review passes              | Success                              |
| Non-blocking findings only | Success with warnings or Neutral     |
| Blocking criteria met      | Failed                               |
| System failure or timeout  | Error, subject to the failure policy |
| No SQL changes             | Skipped or Success                   |

A new head revision must make the previous decision stale. Only the job for the current revision may satisfy a merge requirement. Repeated runs should update an existing check or bot-owned comment rather than create duplicate feedback.

## Expected Result

Each PawSQL outcome maps to a repository or pipeline status, and feedback publishes the decision, finding counts, policy version, and report link.

<Warning>
  Fail-open requires an alert and an audit record. Every manual exception should identify its approver, justification, scope, and expiration.
</Warning>