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

# OpenAPI Pipeline Integration

> Submit changed SQL from any CI/CD runner, wait for PawSQL analysis, and convert the result into a build decision.

When no prebuilt connector matches the pipeline, use PawSQL OpenAPI to submit SQL, poll for the analysis result, and apply the quality gate in the runner. This is the recommended pattern for Jenkins, GitHub Actions, GitLab CI, and other pipeline engines.

See [API reference](/api-reference) for the full endpoint definitions.

## Goal

Submit changed SQL from any CI/CD runner, wait for PawSQL analysis, and convert the result into a build decision.

## Prerequisites

Use PawSQL OpenAPI with a configured workspace, review policy, and identity, referring to the API reference for endpoint definitions.

## Pipeline pattern

<Steps>
  <Step title="Detect SQL changes">Compute the changed SQL files from the version-control diff, ignoring removed files.</Step>
  <Step title="Submit the review">Call the OpenAPI to create a review job for the workspace and policy, attaching the SQL and optional context.</Step>
  <Step title="Wait for the result">Poll the job until it reaches a terminal state, respecting the configured timeout.</Step>
  <Step title="Read the decision">Retrieve the gate decision, finding counts, and report link.</Step>
  <Step title="Apply the gate">Map the decision to a build result using the status mapping in [SQL Quality Gates and Feedback](/en/user-guide/cicd/pipeline-gate).</Step>
  <Step title="Handle failure">Apply the configured failure policy on timeout, authentication error, or service unavailability.</Step>
</Steps>

## Example script

<CodeGroup>
  <CodeGroup.Tab title="Bash">
    ```bash theme={null}
    #!/usr/bin/env bash
    set -euo pipefail
    # Locate changed SQL relative to the merge base
    changed=$(git diff --name-only "origin/${BASE_BRANCH:-main}"..HEAD \
      | grep -E '\.sql$' || true)
    if [ -z "$changed" ]; then
      echo "No SQL changes; skipping review."
      exit 0
    fi
    # Submit and poll via PawSQL OpenAPI (see API reference for exact endpoints)
    echo "Reviewing: $changed"
    ```
  </CodeGroup.Tab>
</CodeGroup>

## Practical guidance

* Send database dialect and a version identifier with each review.
* Attach the DDL required by the review policy when the workspace cannot provide it.
* Select only new and modified SQL files, not the whole repository.
* Use a per-run identity with the least privilege required.
* Keep the PawSQL token out of logs and exported environment.
* Make the timeout and failure policy explicit in the pipeline.
* Store the report link and job ID in the build artifacts for traceability.

## Expected Result

The runner produces a build decision based on the PawSQL gate result and stores the report link and job ID.

## Verification

Confirm the pipeline applies the correct status mapping and failure policy on timeout, authentication error, or service unavailability.

## Next step

To turn the review evidence into pass, warning, or block decisions, see [SQL Quality Gates and Feedback](/en/user-guide/cicd/pipeline-gate).