Skip to content

Commit e9ef29b

Browse files
rebelicerebelice
authored
docs: add AI-powered custom SDL check (#941)
* docs: add AI-powered custom SDL check * chore: address comments
1 parent 98dcadd commit e9ef29b

File tree

1 file changed

+294
-66
lines changed

1 file changed

+294
-66
lines changed

‎mintlify/gitops/state-based-workflow/sql-review-ci.mdx‎

Lines changed: 294 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,9 @@ title: SQL Review CI
44

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

7-
<Warning>
8-
**Work in Progress**: SDL SQL Review currently supports basic syntax checks and pre-defined SDL validation rules. Custom SQL Review rules configured in the Bytebase SQL Review Policy feature are not yet supported for SDL workflows, but this capability is actively under development.
9-
</Warning>
10-
117
## What Gets Validated
128

13-
**SDL-specific checks (Current):**
9+
**SDL-specific checks:**
1410
- Schema qualification on all objects
1511
- Table-level constraint placement
1612
- Constraint naming requirements
@@ -19,87 +15,319 @@ SDL validation runs automatically during pull/merge requests to catch syntax and
1915
- Unsupported statement detection
2016
- SQL syntax validation
2117

22-
**Coming Soon:**
23-
- Custom SQL Review Policy rules from Bytebase
24-
- Team-specific naming conventions
25-
- Custom validation rules
18+
**AI-powered validation with your team's standards (Optional):**
19+
- Define standards in natural language (any language)
20+
- Enforce team-specific conventions
21+
- Get context-aware recommendations
22+
- Validate naming conventions and best practices
23+
24+
## AI-Powered Validation with Your Standards
25+
26+
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.
27+
28+
### How It Works
29+
30+
1. **Write Your Standards**: Document your team's SQL conventions in natural language (supports any language)
31+
2. **AI Validates**: Bytebase AI analyzes your schema files against your documented standards
32+
3. **Get Feedback**: Receive specific, actionable feedback on any violations with exact file and line references
33+
34+
### Setup Requirements
35+
36+
<Warning>
37+
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.
38+
</Warning>
39+
40+
**Step 1: Enable AI in Bytebase** (One-time setup)
41+
- Navigate to **Settings** → **General** → **AI Assistant**
42+
- Enable AI and choose your provider (OpenAI, Azure OpenAI, Gemini, or Claude)
43+
- Enter your API credentials and test the connection
44+
45+
**Step 2: Document Your Standards**
46+
- Create `.bytebase/sql-review.md` in your repository
47+
- Write your team's SQL standards in natural language - no special syntax required
48+
49+
**Step 3: Update Your CI/CD Pipeline**
50+
- Add the `--custom-rules` flag pointing to your standards file
51+
- See platform-specific examples in the [CI/CD Integration](#cicd-integration) section
52+
53+
### Example: SQL Review Standards
54+
55+
Create a Markdown file with your SQL review standards. We recommend placing it in `.bytebase/sql-review.md`:
56+
57+
```markdown
58+
# .bytebase/sql-review.md
59+
# SQL Review Standards
60+
61+
## 1. Table Naming Convention
62+
- All table names must be in snake_case
63+
- Table names should be plural nouns (e.g., users, orders, products)
64+
- Avoid abbreviations unless commonly understood
65+
66+
## 2. Column Standards
67+
- Every table must have a created_at timestamp column
68+
- Every table must have an updated_at timestamp column
69+
- Primary key columns should be named 'id'
70+
71+
## 3. Index Requirements
72+
- Foreign key columns must have indexes
73+
- Columns used in WHERE clauses frequently should be indexed
74+
75+
## 4. Comment Requirements
76+
- All tables must have descriptive comments
77+
- Complex columns should have comments explaining their purpose
78+
79+
## 5. Type Consistency
80+
- Use TEXT instead of VARCHAR for string columns
81+
- Use TIMESTAMP for datetime values
82+
- Use BIGINT for auto-incrementing primary keys
83+
```
84+
85+
### AI Validation Output
86+
87+
When AI detects violations, you'll see detailed feedback in your PR/MR:
88+
89+
```
90+
❌ AI-powered validation errors found:
91+
92+
File: schemas/public/tables/users.sql
93+
Rule: Table Naming Convention
94+
Message: Table name 'User' should be plural. Consider renaming to 'users'.
95+
Line: 1
96+
97+
File: schemas/public/tables/products.sql
98+
Rule: Column Standards
99+
Message: Table 'products' is missing required 'created_at' timestamp column.
100+
Line: 1
26101
27-
<Card title="SQL Review Policy" icon="shield-check" href="/sql-review/review-policy">
28-
Learn about SQL Review Policy (migration-based workflow)
29-
</Card>
102+
File: schemas/public/tables/orders.sql
103+
Rule: Index Requirements
104+
Message: Foreign key column 'user_id' should have an index for better query performance.
105+
Line: 5
106+
```
107+
108+
### Best Practices for SQL Review Standards
109+
110+
1. **Be Specific and Actionable**: Clear, specific standards produce better AI analysis
111+
- ✅ "Primary key columns must be named 'id'"
112+
- ❌ "Use good naming conventions"
113+
114+
2. **Organize by Category**: Group related standards for clarity
115+
```markdown
116+
## Naming Conventions
117+
- Tables: plural, snake_case
118+
- Columns: singular, snake_case
119+
120+
## Type Standards
121+
- Timestamps: use TIMESTAMP NOT NULL
122+
- Text fields: use TEXT not VARCHAR
123+
```
124+
125+
3. **Document the "Why"**: Explain the rationale behind each standard
126+
```markdown
127+
## Primary Key Type
128+
Use BIGINT for primary keys (not INTEGER) to prevent ID exhaustion
129+
in high-volume tables and support future growth.
130+
```
131+
132+
4. **Start Small, Iterate**: Begin with a few critical standards and expand based on team needs
133+
134+
5. **Version Control Standards**: Commit `.bytebase/sql-review.md` to your repository alongside schema files for team collaboration
30135

31136
## CI/CD Integration
32137

33-
Enable declarative mode by adding the `--declarative` flag:
138+
Configure SDL validation in your CI/CD pipeline. Choose between:
139+
- **Basic SDL Validation**: Built-in checks for syntax, naming, and structure
140+
- **With Your Team's Standards**: AI validates against your custom standards in `.bytebase/sql-review.md`
34141

35142
<Tabs>
36143
<Tab title="GitHub Actions">
37-
```yaml
38-
# .github/workflows/sql-review.yml
39-
name: SDL Review
40-
on:
41-
pull_request:
42-
paths:
43-
- 'schema/**'
44-
45-
jobs:
46-
sdl-review:
47-
runs-on: ubuntu-latest
48-
steps:
49-
- uses: actions/checkout@v4
50-
51-
- name: SDL Validation
52-
uses: bytebase/sql-review-action@v1
53-
with:
54-
bytebase-url: ${{ secrets.BYTEBASE_URL }}
55-
bytebase-token: ${{ secrets.BYTEBASE_SERVICE_ACCOUNT_TOKEN }}
56-
file-pattern: 'schema/**/*.sql'
57-
declarative: true # Enable SDL mode
58-
```
144+
<Accordion title="Basic SDL Validation">
145+
```yaml
146+
# .github/workflows/sql-review.yml
147+
name: SDL Review
148+
on:
149+
pull_request:
150+
paths:
151+
- 'schema/**'
152+
153+
jobs:
154+
sdl-review:
155+
runs-on: ubuntu-latest
156+
steps:
157+
- uses: actions/checkout@v4
158+
159+
- name: SDL Validation
160+
run: |
161+
docker run --rm \
162+
-v ${{ github.workspace }}:/workspace \
163+
bytebase/bytebase-action \
164+
check \
165+
--url ${{ secrets.BYTEBASE_URL }} \
166+
--service-account ${{ secrets.BYTEBASE_SERVICE_ACCOUNT }} \
167+
--service-account-secret ${{ secrets.BYTEBASE_SERVICE_ACCOUNT_SECRET }} \
168+
--file-pattern "/workspace/schema/**/*.sql" \
169+
--declarative
170+
```
171+
</Accordion>
172+
173+
<Accordion title="With Your Team's Standards" defaultOpen>
174+
**Prerequisites:** AI must be enabled in Bytebase Settings → AI Assistant
175+
176+
```yaml
177+
# .github/workflows/sql-review.yml
178+
name: SDL Review with Team Standards
179+
on:
180+
pull_request:
181+
paths:
182+
- 'schema/**'
183+
- '.bytebase/sql-review.md'
184+
185+
jobs:
186+
sdl-review:
187+
runs-on: ubuntu-latest
188+
steps:
189+
- uses: actions/checkout@v4
190+
191+
- name: SDL Validation with Team Standards
192+
run: |
193+
docker run --rm \
194+
-v ${{ github.workspace }}:/workspace \
195+
bytebase/bytebase-action \
196+
check \
197+
--url ${{ secrets.BYTEBASE_URL }} \
198+
--service-account ${{ secrets.BYTEBASE_SERVICE_ACCOUNT }} \
199+
--service-account-secret ${{ secrets.BYTEBASE_SERVICE_ACCOUNT_SECRET }} \
200+
--file-pattern "/workspace/schema/**/*.sql" \
201+
--declarative \
202+
--custom-rules "$(cat ${{ github.workspace }}/.bytebase/sql-review.md)"
203+
```
204+
</Accordion>
59205
60206
<Card title="GitHub Tutorial" icon="graduation-cap" href="/tutorials/gitops-github-workflow/" horizontal />
61207
</Tab>
62208
63209
<Tab title="GitLab CI">
64-
```yaml
65-
# .gitlab-ci.yml
66-
sdl-review:
67-
image: bytebase/bytebase-action:latest
68-
stage: test
69-
only:
70-
- merge_requests
71-
script:
72-
- |
73-
bytebase-action check \
74-
--url $BYTEBASE_URL \
75-
--service-account $BYTEBASE_SERVICE_ACCOUNT \
76-
--service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
77-
--file-pattern "schema/**/*.sql" \
78-
--declarative
79-
```
210+
<Accordion title="Basic SDL Validation">
211+
```yaml
212+
# .gitlab-ci.yml
213+
sdl-review:
214+
image: bytebase/bytebase-action:latest
215+
stage: test
216+
only:
217+
- merge_requests
218+
script:
219+
- |
220+
bytebase-action check \
221+
--url $BYTEBASE_URL \
222+
--service-account $BYTEBASE_SERVICE_ACCOUNT \
223+
--service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
224+
--file-pattern "schema/**/*.sql" \
225+
--declarative
226+
```
227+
</Accordion>
228+
229+
<Accordion title="With Your Team's Standards" defaultOpen>
230+
**Prerequisites:** AI must be enabled in Bytebase Settings → AI Assistant
231+
232+
```yaml
233+
# .gitlab-ci.yml
234+
sdl-review:
235+
image: bytebase/bytebase-action:latest
236+
stage: test
237+
only:
238+
- merge_requests
239+
script:
240+
- |
241+
bytebase-action check \
242+
--url $BYTEBASE_URL \
243+
--service-account $BYTEBASE_SERVICE_ACCOUNT \
244+
--service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
245+
--file-pattern "schema/**/*.sql" \
246+
--declarative \
247+
--custom-rules "$(cat .bytebase/sql-review.md)"
248+
```
249+
</Accordion>
80250
81251
<Card title="GitLab Tutorial" icon="graduation-cap" href="/tutorials/gitops-gitlab-workflow/" horizontal />
82252
</Tab>
83253
84254
<Tab title="Azure DevOps">
85-
```yaml
86-
# azure-pipelines.yml
87-
jobs:
88-
- job: SDLReview
89-
pool:
90-
vmImage: 'ubuntu-latest'
91-
steps:
92-
- task: Docker@2
93-
inputs:
94-
command: run
95-
arguments: >
96-
bytebase/bytebase-action
97-
check --file-pattern "/workspace/schema/**/*.sql"
98-
--declarative
99-
```
255+
<Accordion title="Basic SDL Validation">
256+
```yaml
257+
# azure-pipelines.yml
258+
jobs:
259+
- job: SDLReview
260+
pool:
261+
vmImage: 'ubuntu-latest'
262+
steps:
263+
- script: |
264+
docker run --rm \
265+
-v $(Build.SourcesDirectory):/workspace \
266+
bytebase/bytebase-action \
267+
check \
268+
--url $(BYTEBASE_URL) \
269+
--service-account $(BYTEBASE_SERVICE_ACCOUNT) \
270+
--service-account-secret $(BYTEBASE_SERVICE_ACCOUNT_SECRET) \
271+
--file-pattern "/workspace/schema/**/*.sql" \
272+
--declarative
273+
displayName: 'SDL Validation'
274+
```
275+
</Accordion>
276+
277+
<Accordion title="With Your Team's Standards" defaultOpen>
278+
**Prerequisites:** AI must be enabled in Bytebase Settings → AI Assistant
279+
280+
```yaml
281+
# azure-pipelines.yml
282+
jobs:
283+
- job: SDLReview
284+
pool:
285+
vmImage: 'ubuntu-latest'
286+
steps:
287+
- script: |
288+
docker run --rm \
289+
-v $(Build.SourcesDirectory):/workspace \
290+
bytebase/bytebase-action \
291+
check \
292+
--url $(BYTEBASE_URL) \
293+
--service-account $(BYTEBASE_SERVICE_ACCOUNT) \
294+
--service-account-secret $(BYTEBASE_SERVICE_ACCOUNT_SECRET) \
295+
--file-pattern "/workspace/schema/**/*.sql" \
296+
--declarative \
297+
--custom-rules "$(cat $(Build.SourcesDirectory)/.bytebase/sql-review.md)"
298+
displayName: 'SDL Validation with Team Standards'
299+
```
300+
</Accordion>
100301
101302
<Card title="Azure Tutorial" icon="graduation-cap" href="/tutorials/gitops-azure-devops-workflow/" horizontal />
102303
</Tab>
304+
305+
<Tab title="Command Line">
306+
<Accordion title="Basic SDL Validation">
307+
```bash
308+
bytebase-action check \
309+
--url https://bytebase.example.com \
310+
--service-account [email protected] \
311+
--service-account-secret "${SERVICE_SECRET}" \
312+
--file-pattern "schema/**/*.sql" \
313+
--declarative
314+
```
315+
</Accordion>
316+
317+
<Accordion title="With Your Team's Standards" defaultOpen>
318+
**Prerequisites:** AI must be enabled in Bytebase Settings → AI Assistant
319+
320+
```bash
321+
bytebase-action check \
322+
--url https://bytebase.example.com \
323+
--service-account [email protected] \
324+
--service-account-secret "${SERVICE_SECRET}" \
325+
--file-pattern "schema/**/*.sql" \
326+
--declarative \
327+
--custom-rules "$(cat .bytebase/sql-review.md)"
328+
```
329+
</Accordion>
330+
</Tab>
103331
</Tabs>
104332

105333
## Common Validation Errors

0 commit comments

Comments
 (0)