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

# Integration Model and Core Concepts

> Learn how events, SQL change sets, workspaces, review policies, and quality gates fit together.

A PawSQL integration begins with a repository change and ends with a traceable SQL quality decision. The following objects form the contract between the source platform, the pipeline, and PawSQL.

## Core Concepts

| Concept                   | Purpose                                                                         |
| ------------------------- | ------------------------------------------------------------------------------- |
| Trigger event             | A push, pull request, merge request, or manual pipeline run                     |
| SQL change set            | SQL files and statements added or modified by the change                        |
| Integration configuration | Maps repositories and branches to PawSQL projects                               |
| Workspace                 | Supplies the database engine, version, schema, indexes, and optional statistics |
| Review policy             | Selects rules, parameters, and severities                                       |
| Review job                | Stores input SQL, findings, recommendations, and processing state               |
| Quality gate              | Converts review evidence into pass, warn, or block                              |
| External run identity     | Links the PawSQL job to a commit, review, or pipeline execution                 |

## Prerequisites

No special prerequisites.

## Steps

Understand how the trigger event, SQL change set, integration configuration, workspace, review policy, review job, quality gate, and external run identity form the contract between the source platform, the pipeline, and PawSQL.

## Review scope

| Mode            | Best for                                  | Consideration                           |
| --------------- | ----------------------------------------- | --------------------------------------- |
| Incremental     | Routine pull requests                     | Requires a reliable comparison baseline |
| Full repository | Initial onboarding or scheduled baselines | More complete but slower                |
| Selected paths  | Centralized migration directories         | Keep path rules under change control    |
| Selected files  | Manual verification and diagnostics       | Should not replace the automated gate   |

## Idempotency and freshness

Treat repeated delivery of the same repository event as one logical run. Use the platform event ID when available. A new head commit must invalidate the previous decision, and only the latest commit may satisfy a merge requirement.

<Note>
  A passing review means the SQL satisfies the active policy. It does not execute the SQL or replace business validation, change approval, or database release controls.
</Note>

## Expected Result

You can map any repository change to a traceable SQL quality decision through the objects described on this page.

## Verification

Confirm each concept on this page maps to your platform, pipeline, and PawSQL configuration.

## Related documents

<CardGroup cols={2}>
  <Card title="Prerequisites and Security" href="/en/user-guide/cicd/prerequisites" />

  <Card title="SQL Quality Gates and Feedback" href="/en/user-guide/cicd/pipeline-gate" />

  <Card title="Workspaces" href="/en/user-guide/workspaces" />
</CardGroup>