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

1. Write Your Standards: Document your team’s SQL conventions in natural language (supports any language)
2. AI Validates: Bytebase AI analyzes your schema files against your documented standards
3. 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

1. Be Specific and Actionable: Clear, specific standards produce better AI analysis

   • ✅ “Primary key columns must be named ‘id’”
   • ❌ “Use good naming conventions”

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

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

4. Start Small, Iterate: Begin with a few critical standards and expand based on team needs

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

Use a compatible bytebase-action image. For Bytebase Cloud, use bytebase/bytebase-action:cloud. For self-hosted Bytebase, replace :cloud with your Bytebase server version, for example :3.14.0.

GitHub Actions

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:cloud \
            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:cloud \
            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

GitLab CI

Basic SDL Validation

# .gitlab-ci.yml
sdl-review:
  image: bytebase/bytebase-action:cloud
  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:cloud
  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

Azure DevOps

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:cloud \
            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:cloud \
            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

Command Line

Basic SDL Validation

bytebase-action check \
  --url https://bytebase.example.com \
  --service-account [e-mail] \
  --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 [e-mail] \
  --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 name

Fix: 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 constraint

Fix: 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 names

Fix: 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

---

Next Steps

Release

Deploy SDL changes after validation approval

SQL Review Rules

Explore all available SQL review rules