SQL Review CI

​

What Gets Validated

• 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

• 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

​

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

• 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

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

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

​

Example: SQL Review Standards

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

❌ 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
   Copy

   Ask AI

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

   Ask AI

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

• 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/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

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

​

Common Validation Errors

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

-- Change:
id INTEGER PRIMARY KEY

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

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

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

​

Next Steps