SQL Review CI

SDL validation runs automatically during pull/merge requests to catch syntax and convention violations before merge.

What Gets Validated

SDL-specific checks:

Schema qualification on all objects
Table-level constraint placement
Constraint naming requirements
Foreign key type matching
Cross-file integrity validation
Unsupported statement detection
SQL syntax validation

AI-powered validation with your team’s standards (Optional):

Define standards in natural language (any language)
Enforce team-specific conventions
Get context-aware recommendations
Validate naming conventions and best practices

AI-Powered Validation with Your Standards

Enhance SDL validation by teaching AI your team’s SQL standards using natural language. Define your project’s conventions, naming rules, and best practices in any language - AI will validate your schema against them.

How It Works

Write Your Standards: Document your team’s SQL conventions in natural language (supports any language)
AI Validates: Bytebase AI analyzes your schema files against your documented standards
Get Feedback: Receive specific, actionable feedback on any violations with exact file and line references

Setup Requirements

AI must be enabled and configured in your Bytebase instance to use this feature. Without AI setup, your standards file will be ignored during validation.

Step 1: Enable AI in Bytebase (One-time setup)

Navigate to Settings → General → AI Assistant
Enable AI and choose your provider (OpenAI, Azure OpenAI, Gemini, or Claude)
Enter your API credentials and test the connection

Step 2: Document Your Standards

Create .bytebase/sql-review.md in your repository
Write your team’s SQL standards in natural language - no special syntax required

Step 3: Update Your CI/CD Pipeline

Add the --custom-rules flag pointing to your standards file
See platform-specific examples in the CI/CD Integration section

Example: SQL Review Standards

Create a Markdown file with your SQL review standards. We recommend placing it in .bytebase/sql-review.md:

# .bytebase/sql-review.md
# SQL Review Standards

## 1. Table Naming Convention
- All table names must be in snake_case
- Table names should be plural nouns (e.g., users, orders, products)
- Avoid abbreviations unless commonly understood

## 2. Column Standards
- Every table must have a created_at timestamp column
- Every table must have an updated_at timestamp column
- Primary key columns should be named 'id'

## 3. Index Requirements
- Foreign key columns must have indexes
- Columns used in WHERE clauses frequently should be indexed

## 4. Comment Requirements
- All tables must have descriptive comments
- Complex columns should have comments explaining their purpose

## 5. Type Consistency
- Use TEXT instead of VARCHAR for string columns
- Use TIMESTAMP for datetime values
- Use BIGINT for auto-incrementing primary keys

AI Validation Output

When AI detects violations, you’ll see detailed feedback in your PR/MR:

❌ AI-powered validation errors found:

File: schemas/public/tables/users.sql
Rule: Table Naming Convention
Message: Table name 'User' should be plural. Consider renaming to 'users'.
Line: 1

File: schemas/public/tables/products.sql
Rule: Column Standards
Message: Table 'products' is missing required 'created_at' timestamp column.
Line: 1

File: schemas/public/tables/orders.sql
Rule: Index Requirements
Message: Foreign key column 'user_id' should have an index for better query performance.
Line: 5

Best Practices for SQL Review Standards

Be Specific and Actionable: Clear, specific standards produce better AI analysis
- ✅ “Primary key columns must be named ‘id’”
- ❌ “Use good naming conventions”

Organize by Category: Group related standards for clarity

## Naming Conventions
- Tables: plural, snake_case
- Columns: singular, snake_case

## Type Standards
- Timestamps: use TIMESTAMP NOT NULL
- Text fields: use TEXT not VARCHAR

Document the “Why”: Explain the rationale behind each standard

## Primary Key Type
Use BIGINT for primary keys (not INTEGER) to prevent ID exhaustion
in high-volume tables and support future growth.

Start Small, Iterate: Begin with a few critical standards and expand based on team needs
Version Control Standards: Commit .bytebase/sql-review.md to your repository alongside schema files for team collaboration

CI/CD Integration

Configure SDL validation in your CI/CD pipeline. Choose between:

Basic SDL Validation: Built-in checks for syntax, naming, and structure
With Your Team’s Standards: AI validates against your custom standards in .bytebase/sql-review.md

GitHub Actions
GitLab CI
Azure DevOps
Command Line

Basic SDL Validation

# .github/workflows/sql-review.yml
name: SDL Review
on:
  pull_request:
    paths:
      - 'schema/**'

jobs:
  sdl-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: SDL Validation
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace \
            bytebase/bytebase-action \
            check \
            --url ${{ secrets.BYTEBASE_URL }} \
            --service-account ${{ secrets.BYTEBASE_SERVICE_ACCOUNT }} \
            --service-account-secret ${{ secrets.BYTEBASE_SERVICE_ACCOUNT_SECRET }} \
            --file-pattern "/workspace/schema/**/*.sql" \
            --declarative

With Your Team's Standards

Prerequisites: AI must be enabled in Bytebase Settings → AI Assistant

# .github/workflows/sql-review.yml
name: SDL Review with Team Standards
on:
  pull_request:
    paths:
      - 'schema/**'
      - '.bytebase/sql-review.md'

jobs:
  sdl-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: SDL Validation with Team Standards
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace \
            bytebase/bytebase-action \
            check \
            --url ${{ secrets.BYTEBASE_URL }} \
            --service-account ${{ secrets.BYTEBASE_SERVICE_ACCOUNT }} \
            --service-account-secret ${{ secrets.BYTEBASE_SERVICE_ACCOUNT_SECRET }} \
            --file-pattern "/workspace/schema/**/*.sql" \
            --declarative \
            --custom-rules "$(cat ${{ github.workspace }}/.bytebase/sql-review.md)"

GitHub Tutorial

Basic SDL Validation

# .gitlab-ci.yml
sdl-review:
  image: bytebase/bytebase-action:latest
  stage: test
  only:
    - merge_requests
  script:
    - |
      bytebase-action check \
        --url $BYTEBASE_URL \
        --service-account $BYTEBASE_SERVICE_ACCOUNT \
        --service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
        --file-pattern "schema/**/*.sql" \
        --declarative

With Your Team's Standards

Prerequisites: AI must be enabled in Bytebase Settings → AI Assistant

# .gitlab-ci.yml
sdl-review:
  image: bytebase/bytebase-action:latest
  stage: test
  only:
    - merge_requests
  script:
    - |
      bytebase-action check \
        --url $BYTEBASE_URL \
        --service-account $BYTEBASE_SERVICE_ACCOUNT \
        --service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
        --file-pattern "schema/**/*.sql" \
        --declarative \
        --custom-rules "$(cat .bytebase/sql-review.md)"

GitLab Tutorial

Basic SDL Validation

# azure-pipelines.yml
jobs:
  - job: SDLReview
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - script: |
          docker run --rm \
            -v $(Build.SourcesDirectory):/workspace \
            bytebase/bytebase-action \
            check \
            --url $(BYTEBASE_URL) \
            --service-account $(BYTEBASE_SERVICE_ACCOUNT) \
            --service-account-secret $(BYTEBASE_SERVICE_ACCOUNT_SECRET) \
            --file-pattern "/workspace/schema/**/*.sql" \
            --declarative
        displayName: 'SDL Validation'

With Your Team's Standards

Prerequisites: AI must be enabled in Bytebase Settings → AI Assistant

# azure-pipelines.yml
jobs:
  - job: SDLReview
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - script: |
          docker run --rm \
            -v $(Build.SourcesDirectory):/workspace \
            bytebase/bytebase-action \
            check \
            --url $(BYTEBASE_URL) \
            --service-account $(BYTEBASE_SERVICE_ACCOUNT) \
            --service-account-secret $(BYTEBASE_SERVICE_ACCOUNT_SECRET) \
            --file-pattern "/workspace/schema/**/*.sql" \
            --declarative \
            --custom-rules "$(cat $(Build.SourcesDirectory)/.bytebase/sql-review.md)"
        displayName: 'SDL Validation with Team Standards'

Azure Tutorial

Basic SDL Validation

bytebase-action check \
  --url https://bytebase.example.com \
  --service-account [email protected] \
  --service-account-secret "${SERVICE_SECRET}" \
  --file-pattern "schema/**/*.sql" \
  --declarative

With Your Team's Standards

Prerequisites: AI must be enabled in Bytebase Settings → AI Assistant

bytebase-action check \
  --url https://bytebase.example.com \
  --service-account [email protected] \
  --service-account-secret "${SERVICE_SECRET}" \
  --file-pattern "schema/**/*.sql" \
  --declarative \
  --custom-rules "$(cat .bytebase/sql-review.md)"

Common Validation Errors

Missing schema qualification

Error: Table 'users' must include schema nameFix: Add schema prefix to all objects

-- Change: CREATE TABLE users
-- To: CREATE TABLE public.users

Column-level constraint

Error: PRIMARY KEY must be table-level constraintFix: Move constraint to table level

-- Change:
id INTEGER PRIMARY KEY

-- To:
id INTEGER,
CONSTRAINT users_pkey PRIMARY KEY (id)

Unnamed constraint

Error: All constraints must have explicit namesFix: Add CONSTRAINT keyword with name

-- Change: UNIQUE (email)
-- To: CONSTRAINT users_email_key UNIQUE (email)

Type mismatch in foreign key

Error: Foreign key column 'user_id' (INTEGER) references 'users.id' (BIGINT)Fix: Align column types

-- Ensure both are same type
user_id BIGINT  -- Match users.id type

Database CI/CD

UI-Driven Workflow

GitOps Workflow

Appendix

What Gets Validated

AI-Powered Validation with Your Standards

How It Works

Setup Requirements

Example: SQL Review Standards

AI Validation Output

Best Practices for SQL Review Standards

CI/CD Integration

GitHub Tutorial

GitLab Tutorial

Azure Tutorial

Common Validation Errors

Next Steps

Release

SQL Review Rules

Database CI/CD

UI-Driven Workflow

GitOps Workflow

Appendix

​What Gets Validated

​AI-Powered Validation with Your Standards

​How It Works

​Setup Requirements

​Example: SQL Review Standards

​AI Validation Output

​Best Practices for SQL Review Standards

​CI/CD Integration

GitHub Tutorial

GitLab Tutorial

Azure Tutorial

​Common Validation Errors

​Next Steps

Release

SQL Review Rules

What Gets Validated

AI-Powered Validation with Your Standards

How It Works

Setup Requirements

Example: SQL Review Standards

AI Validation Output

Best Practices for SQL Review Standards

CI/CD Integration

Common Validation Errors

Next Steps