Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

chore: remove design documents from repository (#17916)

zchpeter7ce145ff7985
diff --git a/BYT-7917-Design-Complete.md b/BYT-7917-Design-Complete.md
deleted file mode 100644
index 38e5b55c91..0000000000
--- a/BYT-7917-Design-Complete.md
+++ /dev/null
@@ -1,756 +0,0 @@
-# BYT-7917: Complete Solution - Table Require PK False Positive Fix
-
-**Design Version**: Complete Solution with Local State Tracking
-**Date**: 2025-10-27
-**Status**: Ready for Implementation
-
----
-
-## 1. Executive Summary
-
-### Problem
-The `table.require-pk` advisor across all 6 database engines currently validates each statement independently, causing false positives when a primary key is added in a subsequent statement within the same migration script.
-
-**Example:**
-```sql
-CREATE TABLE employees (id INT, name VARCHAR(100)); -- ❌ False positive warning
-ALTER TABLE employees ADD PRIMARY KEY (id); -- PK added here
-```
-
-### Solution Overview
-Implement **two-phase validation with local state tracking**:
-1. **Phase 1 (Collection)**: Track PK-affecting operations and maintain local PK state for newly created tables
-2. **Phase 2 (Validation)**: Validate against `catalog.Final` state to determine actual violations
-
-### Affected Engines
-1. PostgreSQL (pgantlr) - New ANTLR-based implementation
-2. MySQL - Existing two-phase implementation
-3. TiDB - Existing two-phase implementation
-4. MSSQL - Needs catalog support
-5. Oracle - Needs catalog support
-6. Snowflake - Needs catalog support
-
----
-
-## 2. Technical Background
-
-### Current Architecture
-
-All engines follow a similar pattern but with different parsers:
-- **PostgreSQL (pgantlr)**: ANTLR Listener pattern
-- **MySQL**: ANTLR Listener pattern
-- **TiDB**: AST Visitor pattern (TiDB parser)
-- **MSSQL, Oracle, Snowflake**: ANTLR Listener pattern
-
-### The Core Problem
-
-When processing multi-statement scripts, advisors validate each statement as it's encountered:
-
-```sql
--- Statement 1
-CREATE TABLE t(id INT, name TEXT);
--- ❌ Advisor sees no PK, reports violation immediately
-
--- Statement 2
-ALTER TABLE t ADD PRIMARY KEY (id);
--- ✅ Now table has PK, but too late - already reported
-```
-
-### Why This Is Complex
-
-For newly created tables, `catalog.Origin` doesn't contain them (Origin represents database state BEFORE the script). We cannot rely solely on catalog queries.
-
-**Example Challenge:**
-```sql
-Line 1: CREATE TABLE t(id INT PRIMARY KEY);
-Line 2: ALTER TABLE t DROP CONSTRAINT t_pkey;
-```
-
-When processing Line 2, checking `catalog.Origin` for constraint information returns nothing because table `t` doesn't exist yet.
-
----
-
-## 3. Detailed Design
-
-### 3.1 Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ AST/Parse Tree │
-└────────────────────┬────────────────────────────────────┘
- │
- ▼
- ┌───────────────────────┐
- │ Phase 1: Collection │
- │ ───────────────── │
- │ Walk all statements │
- │ Track PK operations │
- │ Build local PK state │
- └───────────┬───────────┘
- │
- │ affectedTables map
- │ localPKColumns map
- │
- ▼
- ┌───────────────────────┐
- │ Phase 2: Validation │
- │ ────────────────── │
- │ For each affected │
- │ table, check │
- │ catalog.Final state │
- └───────────┬───────────┘
- │
- ▼
- ┌───────────────────────┐
- │ Generate Advice │
- │ with accurate line │
- │ numbers │
- └───────────────────────┘
-```
-
-### 3.2 Data Structures
-
-```go
-// PostgreSQL (pgantlr) Example
-type tableRequirePKChecker struct {
- *parser.BasePostgreSQLParserListener
-
- adviceList []*storepb.Advice
- level storepb.Advice_Status
- title string
- statementsText string
- catalog *catalog.Finder
-
- // NEW: Track affected tables
- affectedTables map[string]*affectedTable // key: "schema.table"
-
- // NEW: Local PK tracking for newly created tables
- localPKColumns map[string][]string // key: "schema.table", value: PK columns
-
- // NEW: Cache Origin lookups
- originTableCache map[string]bool // key: "schema.table", value: exists?
-}
-
-type affectedTable struct {
- schemaName string
- tableName string
- lastLine int // Line of last PK-affecting operation
- lastStmt string // Statement text for error message
- isNewTable bool // Created in this script?
-}
-```
-
-### 3.3 Algorithm Flow
-
-#### Phase 1: Collection
-
-```
-For each statement in script:
-
- If CREATE TABLE:
- Extract PK columns from:
- - Column-level: id INT PRIMARY KEY
- - Table-level: PRIMARY KEY (id)
- - Composite: PRIMARY KEY (id1, id2)
-
- Store in localPKColumns[table] = [columns]
- Record as affected (isNewTable=true)
-
- Else if ALTER TABLE DROP CONSTRAINT:
- Determine if constraint is PK:
- - If table is new: Check localPKColumns
- - If table exists: Query catalog.Origin.FindIndex()
-
- If constraint is PK:
- Remove from localPKColumns
- Record as affected with current line number
-
- Else if ALTER TABLE DROP COLUMN:
- Determine if column is in PK:
- - If table is new: Check localPKColumns
- - If table exists: Query catalog.Origin.FindPrimaryKey()
-
- If column in PK:
- Remove from localPKColumns (for composite PKs)
- Record as affected with current line number
-
- Else if ALTER TABLE ADD PRIMARY KEY:
- Extract PK columns
- Update localPKColumns[table]
- (Do NOT record as affected - this ADDS PK)
-```
-
-#### Phase 2: Validation
-
-```
-For each affected table:
-
- hasPK = catalog.Final.HasPrimaryKey(schemaName, tableName)
-
- If NOT hasPK:
- Generate advice:
- - Table name
- - Line number: affectedTable.lastLine
- - Statement text: affectedTable.lastStmt
- - Error: "Table requires PRIMARY KEY"
-```
-
-### 3.4 Helper Functions
-
-#### 3.4.1 Table Key Generation
-```go
-func tableKey(schema, table string) string {
- return fmt.Sprintf("%s.%s", normalizeSchemaName(schema), table)
-}
-```
-
-#### 3.4.2 Origin Existence Check (with caching)
-```go
-func (c *tableRequirePKChecker) existsInOrigin(schema, table string) bool {
- key := tableKey(schema, table)
-
- // Check cache
- if exists, cached := c.originTableCache[key]; cached {
- return exists
- }
-
- // Query catalog
- originTable := c.catalog.Origin.FindTable(&catalog.TableFind{
- SchemaName: normalizeSchemaName(schema),
- TableName: table,
- })
-
- exists := originTable != nil
- c.originTableCache[key] = exists
- return exists
-}
-```
-
-#### 3.4.3 Extract PK Columns from CREATE TABLE
-```go
-// PostgreSQL ANTLR example
-func extractPKColumns(ctx *parser.CreatestmtContext) []string {
- var pkColumns []string
-
- if ctx.Opttableelementlist() == nil {
- return pkColumns
- }
-
- allElements := ctx.Opttableelementlist().Tableelementlist().AllTableelement()
-
- for _, elem := range allElements {
- // Column-level: id INT PRIMARY KEY
- if elem.ColumnDef() != nil {
- columnDef := elem.ColumnDef()
- if hasColumnLevelPK(columnDef) {
- columnName := extractColumnName(columnDef)
- pkColumns = append(pkColumns, columnName)
- }
- }
-
- // Table-level: PRIMARY KEY (id, name)
- if elem.Tableconstraint() != nil {
- constraint := elem.Tableconstraint()
- if isPrimaryKeyConstraint(constraint) {
- cols := extractConstraintColumns(constraint)
- pkColumns = append(pkColumns, cols...)
- }
- }
- }
-
- return pkColumns
-}
-```
-
-#### 3.4.4 Check if DROP CONSTRAINT Affects PK
-```go
-func (c *tableRequirePKChecker) isDropPKConstraint(
- schemaName, tableName, constraintName string,
-) bool {
- key := tableKey(schemaName, tableName)
-
- // Case 1: New table - check local tracking
- if affected, exists := c.affectedTables[key]; exists && affected.isNewTable {
- // For new tables, we conservatively assume any DROP CONSTRAINT
- // might affect PK. Actual validation happens in Phase 2.
- return true
- }
-
- // Case 2: Existing table - query catalog.Origin
- _, index := c.catalog.Origin.FindIndex(&catalog.IndexFind{
- SchemaName: schemaName,
- TableName: tableName,
- IndexName: constraintName,
- })
-
- return index != nil && index.Primary()
-}
-```
-
-#### 3.4.5 Check if DROP COLUMN Affects PK
-```go
-func (c *tableRequirePKChecker) isDropPKColumn(
- schemaName, tableName, columnName string,
-) bool {
- key := tableKey(schemaName, tableName)
-
- // Case 1: New table - check local tracking
- if pkColumns, exists := c.localPKColumns[key]; exists {
- for _, col := range pkColumns {
- if col == columnName {
- return true
- }
- }
- return false
- }
-
- // Case 2: Existing table - query catalog.Origin
- pk := c.catalog.Origin.FindPrimaryKey(&catalog.PrimaryKeyFind{
- SchemaName: schemaName,
- TableName: tableName,
- })
-
- if pk != nil {
- for _, col := range pk.ExpressionList() {
- if col == columnName {
- return true
- }
- }
- }
-
- return false
-}
-```
-
----
-
-## 4. Implementation by Engine
-
-### 4.1 PostgreSQL (pgantlr) - Complex Refactor
-
-**Current State**: Per-statement validation, marked "WIP - needs debugging"
-
-**File**: `backend/plugin/advisor/pgantlr/advisor_table_require_pk.go`
-
-**Changes Required**:
-1. Add data structures to `tableRequirePKChecker`
-2. Refactor `EnterCreatestmt()` to track instead of validate
-3. Refactor `EnterAltertablestmt()` to track PK-affecting operations
-4. Add `validateFinalState()` method
-5. Modify `Check()` to call validation after AST walk
-6. Add helper functions for PK extraction and checking
-
-**Complexity**: High (structural changes required)
-
-**Test File**: `backend/plugin/advisor/pgantlr/test/table_require_pk.yaml`
-
-### 4.2 MySQL - Simple Modification
-
-**Current State**: Already has two-phase structure with local tracking
-
-**File**: `backend/plugin/advisor/mysql/rule_table_require_pk.go`
-
-**Changes Required**:
-1. Modify `generateAdviceList()` method (lines 227-240)
-2. Add catalog.Final validation alongside local state check
-
-**Before:**
-```go
-func (r *TableRequirePKRule) generateAdviceList() {
- tableList := r.getTableList()
- for _, tableName := range tableList {
- if len(r.tables[tableName]) == 0 { // Only checks local state
- r.AddAdvice(...)
- }
- }
-}
-```
-
-**After:**
-```go
-func (r *TableRequirePKRule) generateAdviceList() {
- for tableName := range r.tables {
- // Check BOTH local state AND catalog.Final
- hasPKLocal := len(r.tables[tableName]) > 0
- hasPKFinal := r.catalog.Final.HasPrimaryKey(&catalog.PrimaryKeyFind{
- TableName: tableName,
- })
-
- // Only report if BOTH checks fail
- if !hasPKLocal && !hasPKFinal {
- r.AddAdvice(...)
- }
- }
-}
-```
-
-**Complexity**: Low (single method modification)
-
-**Test File**: `backend/plugin/advisor/mysql/test/table_require_pk.yaml`
-
-### 4.3 TiDB - Same Pattern as MySQL
-
-**Current State**: Already has two-phase structure with local tracking
-
-**File**: `backend/plugin/advisor/tidb/advisor_table_require_pk.go`
-
-**Changes Required**: Same as MySQL (modify validation logic)
-
-**Complexity**: Low
-
-**Test File**: `backend/plugin/advisor/tidb/test/table_require_pk.yaml`
-
-### 4.4 MSSQL - Add Catalog Support
-
-**Current State**: No catalog access, only local tracking
-
-**File**: `backend/plugin/advisor/mssql/rule_table_require_pk.go`
-
-**Changes Required**:
-1. Add `catalog` field to `TableRequirePkRule` struct (line 68)
-2. Pass `checkCtx.Catalog` in `NewTableRequirePkRule()` (line 42)
-3. Modify `generateFinalAdvice()` to use catalog.Final
-
-**Before:**
-```go
-func NewTableRequirePkRule(level storepb.Advice_Status, title string) *TableRequirePkRule {
- return &TableRequirePkRule{
- BaseRule: BaseRule{...},
- // No catalog
- }
-}
-```
-
-**After:**
-```go
-func NewTableRequirePkRule(
- level storepb.Advice_Status,
- title string,
- catalog *catalog.Finder, // NEW
-) *TableRequirePkRule {
- return &TableRequirePkRule{
- BaseRule: BaseRule{...},
- catalog: catalog, // NEW
- }
-}
-
-// In Check():
-rule := NewTableRequirePkRule(level, string(checkCtx.Rule.Type), checkCtx.Catalog)
-```
-
-**Complexity**: Medium (requires plumbing catalog through)
-
-**Test File**: `backend/plugin/advisor/mssql/test/table_require_pk.yaml`
-
-### 4.5 Oracle - Same Pattern as MSSQL
-
-**File**: `backend/plugin/advisor/oracle/rule_table_require_pk.go`
-
-**Changes**: Add catalog support, modify final validation
-
-**Complexity**: Medium
-
-**Test File**: `backend/plugin/advisor/oracle/test/table_require_pk.yaml`
-
-### 4.6 Snowflake - Same Pattern as MSSQL
-
-**File**: `backend/plugin/advisor/snowflake/rule_table_require_pk.go`
-
-**Changes**: Add catalog support, modify final validation
-
-**Complexity**: Medium
-
-**Test File**: `backend/plugin/advisor/snowflake/test/table_require_pk.yaml`
-
----
-
-## 5. Test Cases
-
-### Required Test Cases (All Engines)
-
-```yaml
-# Test 1: BYT-7917 - CREATE without PK, ADD PK (should PASS)
-- statement: |-
- CREATE TABLE employees(id INT, name VARCHAR(100));
- ALTER TABLE employees ADD PRIMARY KEY (id);
- changeType: 1
- # Expected: No violation
-
-# Test 2: CREATE with PK, DROP PK constraint (should FAIL)
-- statement: |-
- CREATE TABLE book(id INT PRIMARY KEY, title TEXT);
- ALTER TABLE book DROP CONSTRAINT book_pkey;
- changeType: 1
- want:
- - status: 2
- code: 601
- title: table.require-pk
- content: 'Table "public"."book" requires PRIMARY KEY'
- startposition:
- line: 2 # Line of DROP CONSTRAINT
-
-# Test 3: CREATE with PK, DROP column in PK (should FAIL)
-- statement: |-
- CREATE TABLE author(id INT PRIMARY KEY, name TEXT);
- ALTER TABLE author DROP COLUMN id;
- changeType: 1
- want:
- - status: 2
- code: 601
- startposition:
- line: 2 # Line of DROP COLUMN
-
-# Test 4: CREATE without PK, ADD PK, DROP PK (should FAIL)
-- statement: |-
- CREATE TABLE product(id INT, name TEXT);
- ALTER TABLE product ADD PRIMARY KEY (id);
- ALTER TABLE product DROP CONSTRAINT product_pkey;
- changeType: 1
- want:
- - status: 2
- code: 601
- startposition:
- line: 3 # Line of DROP CONSTRAINT
-
-# Test 5: CREATE without PK, ADD PK, DROP PK column (should FAIL)
-- statement: |-
- CREATE TABLE customer(id INT, email TEXT);
- ALTER TABLE customer ADD PRIMARY KEY (id);
- ALTER TABLE customer DROP COLUMN id;
- changeType: 1
- want:
- - status: 2
- code: 601
- startposition:
- line: 3 # Line of DROP COLUMN
-
-# Test 6: Composite PK - CREATE, DROP one column (should FAIL)
-- statement: |-
- CREATE TABLE enrollment(
- student_id INT,
- course_id INT,
- PRIMARY KEY (student_id, course_id)
- );
- ALTER TABLE enrollment DROP COLUMN student_id;
- changeType: 1
- want:
- - status: 2
- code: 601
- startposition:
- line: 6 # Line of DROP COLUMN
-
-# Test 7: Existing table (in catalog.Origin), DROP non-PK column (should PASS)
-- statement: ALTER TABLE "tech_book" DROP COLUMN non_pk_column;
- changeType: 1
- # Expected: No violation (tech_book has PK, dropping non-PK column)
-
-# Test 8: Existing table (in catalog.Origin), DROP PK constraint (should FAIL)
-- statement: ALTER TABLE "tech_book" DROP CONSTRAINT "old_pk";
- changeType: 1
- want:
- - status: 2
- code: 601
-```
-
-### Test Coverage Matrix
-
-| Scenario | CREATE in Script? | Has PK Initially? | Operation | Expected Result |
-|----------|------------------|-------------------|-----------|-----------------|
-| BYT-7917 | Yes | No | ADD PK | PASS ✅ |
-| Edge 1 | Yes | Yes | DROP PK | FAIL ❌ |
-| Edge 2 | Yes | Yes | DROP PK col | FAIL ❌ |
-| Edge 3 | Yes | No | ADD then DROP PK | FAIL ❌ |
-| Edge 4 | Yes | No | ADD PK, DROP col | FAIL ❌ |
-| Edge 5 | Yes | Yes (composite) | DROP 1 col | FAIL ❌ |
-| Edge 6 | No (in Origin) | Yes | DROP non-PK col | PASS ✅ |
-| Edge 7 | No (in Origin) | Yes | DROP PK | FAIL ❌ |
-
----
-
-## 6. Implementation Checklist
-
-### Phase 1: Setup
-- [ ] Rebase from `origin/main`
-- [ ] Resolve any conflicts
-- [ ] Update `backend/plugin/advisor/catalog/state.go` with `HasPrimaryKey()` helper (if not present)
-
-### Phase 2: PostgreSQL (pgantlr)
-- [ ] Read and understand current "WIP" implementation
-- [ ] Add 8 test cases to `test/table_require_pk.yaml`
-- [ ] Add data structures to `tableRequirePKChecker`
-- [ ] Implement helper functions
-- [ ] Refactor `EnterCreatestmt()`
-- [ ] Refactor `EnterAltertablestmt()`
-- [ ] Add `validateFinalState()` method
-- [ ] Update `Check()` function
-- [ ] Run tests: `go test -v -count=1 github.com/bytebase/bytebase/backend/plugin/advisor/pgantlr -run TestPostgreSQLANTLRRules`
-- [ ] Debug and fix failures
-- [ ] Uncomment `advisor.SchemaRuleTableRequirePK` in `pgantlr_test.go`
-
-### Phase 3: MySQL
-- [ ] Add 8 test cases
-- [ ] Modify `generateAdviceList()` method
-- [ ] Run tests: `go test -v -count=1 github.com/bytebase/bytebase/backend/plugin/advisor/mysql`
-- [ ] Fix any failures
-
-### Phase 4: TiDB
-- [ ] Add 8 test cases
-- [ ] Modify `generateAdviceList()` method
-- [ ] Run tests: `go test -v -count=1 github.com/bytebase/bytebase/backend/plugin/advisor/tidb`
-- [ ] Fix any failures
-
-### Phase 5: MSSQL
-- [ ] Add 8 test cases (adapt syntax for T-SQL)
-- [ ] Add catalog support
-- [ ] Modify `generateFinalAdvice()` method
-- [ ] Run tests
-- [ ] Fix failures
-
-### Phase 6: Oracle
-- [ ] Add 8 test cases (adapt syntax for PL/SQL)
-- [ ] Add catalog support
-- [ ] Modify final validation
-- [ ] Run tests
-- [ ] Fix failures
-
-### Phase 7: Snowflake
-- [ ] Add 8 test cases (adapt syntax for Snowflake SQL)
-- [ ] Add catalog support
-- [ ] Modify final validation
-- [ ] Run tests
-- [ ] Fix failures
-
-### Phase 8: Final Validation
-- [ ] Run all advisor tests: `go test -v -count=1 github.com/bytebase/bytebase/backend/plugin/advisor/...`
-- [ ] Run linting: `golangci-lint run --allow-parallel-runners`
-- [ ] Fix linting issues (run multiple times until clean)
-- [ ] Build project: `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
-- [ ] Manual smoke test (if possible)
-
----
-
-## 7. Complexity Analysis
-
-### Code Changes by Engine
-
-| Engine | Current Lines | Estimated New Lines | Net Change | Complexity |
-|--------|--------------|---------------------|------------|------------|
-| PostgreSQL (pgantlr) | 204 | ~300 | +96 | High |
-| MySQL | 279 | ~290 | +11 | Low |
-| TiDB | 240 | ~250 | +10 | Low |
-| MSSQL | 198 | ~230 | +32 | Medium |
-| Oracle | 175 | ~207 | +32 | Medium |
-| Snowflake | 217 | ~249 | +32 | Medium |
-| **Total** | **1,313** | **~1,526** | **+213** | - |
-
-### Performance Characteristics
-
-- **Time Complexity**: O(n) where n = number of statements
- - Each statement processed once
- - Catalog lookups cached
-- **Space Complexity**: O(t) where t = number of affected tables
- - Typically small (< 10 tables per script)
-- **Catalog Query Impact**: Minimal
- - Origin lookups cached per table
- - Final state queried once per affected table
-
----
-
-## 8. Risk Assessment
-
-### Low Risk
-- ✅ Self-contained changes (no external API modifications)
-- ✅ Comprehensive test coverage
-- ✅ Reuses existing catalog infrastructure
-- ✅ No breaking changes to rule configuration
-
-### Medium Risk
-- ⚠️ PostgreSQL pgantlr has existing "WIP" issues to debug
-- ⚠️ Need to handle edge cases (composite PKs, constraint names)
-- ⚠️ Catalog.Final must accurately reflect post-script state
-
-### Mitigation Strategies
-1. **Incremental Rollout**: Fix engines one by one, test thoroughly
-2. **Comprehensive Testing**: 8+ test cases per engine covering edge cases
-3. **Code Review**: Focus on PK extraction and tracking logic
-4. **Fallback**: Keep old implementation as reference during development
-
----
-
-## 9. Timeline Estimate
-
-| Task | Estimated Time | Priority |
-|------|---------------|----------|
-| Setup & Rebase | 30 min | High |
-| PostgreSQL (pgantlr) | 4-5 hours | Critical |
-| MySQL | 1.5 hours | High |
-| TiDB | 1.5 hours | High |
-| MSSQL | 2 hours | Medium |
-| Oracle | 2 hours | Medium |
-| Snowflake | 2 hours | Medium |
-| Testing & Polish | 1.5 hours | High |
-| **Total** | **15-17 hours** | - |
-
----
-
-## 10. Success Criteria
-
-### Functional Requirements
-- ✅ BYT-7917 scenario (CREATE without PK, ADD PK) passes for all engines
-- ✅ All edge cases handled correctly (8 test scenarios)
-- ✅ Existing test cases continue to pass
-- ✅ Line numbers point to exact PK-affecting statement
-
-### Non-Functional Requirements
-- ✅ No performance degradation
-- ✅ Code passes `golangci-lint` without errors
-- ✅ No breaking changes to rule configuration
-- ✅ Consistent behavior across all 6 engines
-
-### Deliverables
-1. Updated implementations for all 6 engines
-2. 8+ test cases per engine (48+ total new tests)
-3. All tests passing
-4. Linting clean
-5. Project builds successfully
-6. PostgreSQL pgantlr version enabled (migration unblocked)
-
----
-
-## 11. Future Enhancements
-
-### Potential Improvements
-1. **More Granular Line Numbers**: Point to exact constraint definition, not just statement
-2. **Better Error Messages**: Include column names in composite PK violations
-3. **Transaction Boundaries**: Consider rollback scenarios
-4. **Performance Optimization**: Batch catalog queries if needed
-
-### Not In Scope
-- ❌ Validating PK column types (separate rule)
-- ❌ Suggesting which column should be PK
-- ❌ Handling temporary tables differently
-- ❌ Cross-database PK consistency checks
-
----
-
-## 12. References
-
-### Related Issues
-- BYT-7917: Table require PK false positive when PK added in subsequent statement
-
-### Related Files
-- `backend/plugin/advisor/catalog/state.go` - Catalog infrastructure
-- `backend/plugin/advisor/pgantlr/advisor_table_require_pk.go` - PostgreSQL impl
-- `backend/plugin/advisor/mysql/rule_table_require_pk.go` - MySQL impl
-- `backend/plugin/advisor/tidb/advisor_table_require_pk.go` - TiDB impl
-- `backend/plugin/advisor/mssql/rule_table_require_pk.go` - MSSQL impl
-- `backend/plugin/advisor/oracle/rule_table_require_pk.go` - Oracle impl
-- `backend/plugin/advisor/snowflake/rule_table_require_pk.go` - Snowflake impl
-
-### Documentation
-- Google Style Guide: https://google.github.io/styleguide/go/
-- Bytebase Development SOP: `CLAUDE.md`
-
----
-
-**Document End**
diff --git a/BYT-7917-Design-Simple.md b/BYT-7917-Design-Simple.md
deleted file mode 100644
index dff179b4c1..0000000000
--- a/BYT-7917-Design-Simple.md
+++ /dev/null
@@ -1,860 +0,0 @@
-# BYT-7917: Simple Solution - Table Require PK False Positive Fix
-
-**Design Version**: Simple Solution without Local State Tracking
-**Date**: 2025-10-27
-**Status**: Alternative Approach - Faster Implementation with Known Limitations
-
----
-
-## 1. Executive Summary
-
-### Problem
-The `table.require-pk` advisor across all 6 database engines currently validates each statement independently, causing false positives when a primary key is added in a subsequent statement within the same migration script.
-
-**Example:**
-```sql
-CREATE TABLE employees (id INT, name VARCHAR(100)); -- ❌ False positive warning
-ALTER TABLE employees ADD PRIMARY KEY (id); -- PK added here
-```
-
-### Solution Overview
-Implement **simplified validation without local state tracking**:
-- Collect all table names mentioned in the script
-- After processing all statements, validate each table against `catalog.Final`
-- Report violations with the line number where the table was **LAST mentioned** (improved accuracy!)
-
-### Key Assumption
-**User Behavior Pattern**: In a typical migration script, users commonly:
-- ✅ CREATE TABLE without PK → ADD PRIMARY KEY later (common pattern)
-- ❌ CREATE TABLE with PK → DROP PRIMARY KEY later (rare in single script)
-
-This solution optimizes for the common case and accepts trade-offs for rare edge cases.
-
-### Affected Engines
-All 6 engines: PostgreSQL (pgantlr), MySQL, TiDB, MSSQL, Oracle, Snowflake
-
----
-
-## 2. Design Philosophy
-
-### Simplicity Over Perfection
-
-**Principle**: "Perfect is the enemy of good"
-
-This design prioritizes:
-1. **Fast Implementation**: Minimal code changes, no complex state tracking
-2. **Solving the Common Case**: Fix BYT-7917 (the reported issue)
-3. **Maintainability**: Simple logic, easy to understand
-4. **Acceptable Trade-offs**: Known limitations documented clearly
-
-### What We're Optimizing For
-
-```sql
--- COMMON CASE (90%+ of scripts): This will work correctly
-CREATE TABLE users(id INT, name TEXT); -- Line 1
-CREATE TABLE orders(id INT, user_id INT); -- Line 2
-ALTER TABLE users ADD PRIMARY KEY (id); -- Line 3
-ALTER TABLE orders ADD PRIMARY KEY (id); -- Line 4
--- Result: ✅ No violations, correct!
-```
-
-### What We're Trading Off
-
-```sql
--- RARE CASE (<10% of scripts): Line number will be incorrect
-CREATE TABLE temp(id INT PRIMARY KEY); -- Line 1 (creates with PK)
-ALTER TABLE temp DROP CONSTRAINT temp_pkey; -- Line 2 (drops PK)
--- Result: ❌ Violation reported at Line 1 (should be Line 2)
--- But still correctly identifies violation exists!
-```
-
----
-
-## 3. Technical Design
-
-### 3.1 Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ AST/Parse Tree │
-└────────────────────┬────────────────────────────────────┘
- │
- ▼
- ┌───────────────────────────┐
- │ Single Pass: Collection │
- │ ──────────────────────── │
- │ Walk all statements │
- │ Collect table names │
- │ Track LAST mention line │
- │ (No PK state tracking) │
- └───────────┬───────────────┘
- │
- │ tableMentions map[table]line
- │
- ▼
- ┌───────────────────────────┐
- │ Final Validation │
- │ ──────────────────────── │
- │ For each mentioned table: │
- │ Check catalog.Final state │
- │ Report using LAST line │
- └───────────┬───────────────┘
- │
- ▼
- ┌───────────────────────────┐
- │ Generate Advice │
- │ (May have approximate │
- │ line numbers) │
- └───────────────────────────┘
-```
-
-### 3.2 Data Structures
-
-```go
-// Simplified structure - NO local PK tracking
-type tableRequirePKChecker struct {
- *parser.BasePostgreSQLParserListener
-
- adviceList []*storepb.Advice
- level storepb.Advice_Status
- title string
- statementsText string
- catalog *catalog.Finder
-
- // ONLY track table mentions - no PK state
- tableMentions map[string]int // key: "schema.table", value: LAST line number
-}
-```
-
-**Comparison with Complete Solution:**
-
-| Feature | Complete Solution | Simple Solution |
-|---------|------------------|-----------------|
-| affectedTables | ✅ Yes | ❌ No |
-| localPKColumns | ✅ Yes | ❌ No |
-| originTableCache | ✅ Yes | ❌ No |
-| tableMentions | ❌ No | ✅ Yes |
-
-**Lines of Code Reduction**: ~60% less code per engine
-
-### 3.3 Algorithm Flow
-
-#### Single Pass: Collection
-
-```
-For each statement in script:
-
- If CREATE TABLE:
- Extract table name
- Record: tableMentions[table] = line_number (ALWAYS update)
- (Do NOT extract or track PK columns)
-
- Else if ALTER TABLE:
- Extract table name
- Record: tableMentions[table] = line_number (ALWAYS update - last occurrence)
-
- Else if DROP TABLE:
- Extract table name
- Remove from tableMentions (table no longer exists)
-```
-
-#### Final Validation
-
-```
-For each table in tableMentions:
-
- hasPK = catalog.Final.HasPrimaryKey(schemaName, tableName)
-
- If NOT hasPK:
- Generate advice:
- - Table name
- - Line number: tableMentions[table] (LAST mention)
- - Error: "Table requires PRIMARY KEY"
-```
-
-### 3.4 Why Last Occurrence vs First Occurrence?
-
-**Key Design Decision**: Track the LAST mention of each table, not the first.
-
-#### Rationale
-
-When a table violates the PK requirement, the last statement mentioning that table is temporally closer to the root cause than the first statement.
-
-#### Comparison Scenarios
-
-| Scenario | First Occurrence | Last Occurrence | Winner |
-|----------|-----------------|-----------------|---------|
-| CREATE without PK | Line 1 (CREATE) ✅ | Line 1 (CREATE) ✅ | Tie |
-| CREATE + ADD PK | No violation | No violation | Tie |
-| CREATE with PK + DROP PK | Line 1 (CREATE) ❌ | Line 2 (DROP) ✅ | **Last** |
-| CREATE + ADD PK + DROP PK | Line 1 (CREATE) ❌ | Line 3 (DROP) ✅ | **Last** |
-| Existing table + operations | First ALTER ⚠️ | Last ALTER ✅ | **Last** |
-
-#### Example: DROP PK Scenario
-
-```sql
-Line 1: CREATE TABLE book(id INT PRIMARY KEY);
-Line 2: ALTER TABLE book DROP CONSTRAINT book_pkey;
-```
-
-**First Occurrence**: Reports Line 1 (CREATE) ❌
-- Misleading: CREATE actually HAD a primary key
-- Developer sees "Line 1" and gets confused
-
-**Last Occurrence**: Reports Line 2 (DROP) ✅
-- Accurate: DROP operation removed the PK
-- Developer immediately sees the problem statement
-
-#### Accuracy Improvement
-
-| Metric | First Occurrence | Last Occurrence | Improvement |
-|--------|-----------------|-----------------|-------------|
-| Line Accuracy | ~70% | ~80-85% | +10-15% |
-| Implementation Cost | None | None | No trade-off! |
-
-**Conclusion**: Last occurrence provides strictly better results with zero additional cost.
-
-### 3.5 Key Differences from Complete Solution
-
-| Aspect | Complete Solution | Simple Solution |
-|--------|------------------|-----------------|
-| **PK Extraction** | Extract columns from CREATE TABLE | Skip extraction |
-| **Operation Tracking** | Track DROP CONSTRAINT, DROP COLUMN | Skip tracking |
-| **Origin Queries** | Query catalog.Origin for existing tables | Skip queries |
-| **Line Accuracy** | Point to exact violating statement | Point to LAST mention |
-| **Complexity** | O(n × m) operations | O(n) operations |
-| **Code Lines** | +213 lines total | +60 lines total |
-
----
-
-## 4. Implementation by Engine
-
-### 4.1 PostgreSQL (pgantlr)
-
-**File**: `backend/plugin/advisor/pgantlr/advisor_table_require_pk.go`
-
-**Current Lines**: 204 | **New Lines**: ~230 | **Net**: +26
-
-**Changes**:
-
-1. **Remove** complex tracking from `EnterCreatestmt()`:
-```go
-// Before (validates immediately)
-func (c *tableRequirePKChecker) EnterCreatestmt(ctx *parser.CreatestmtContext) {
- // ... extract table name ...
- // ... check if has PK ...
- if !hasPK {
- c.addMissingPKAdvice(schemaName, tableName, ctx) // ❌ Immediate violation
- }
-}
-
-// After (just record - ALWAYS update for last occurrence)
-func (c *tableRequirePKChecker) EnterCreatestmt(ctx *parser.CreatestmtContext) {
- // ... extract table name ...
- key := tableKey(schemaName, tableName)
- c.tableMentions[key] = ctx.GetStart().GetLine() // Always update
-}
-```
-
-2. **Simplify** `EnterAltertablestmt()`:
-```go
-// Before (complex checking)
-func (c *tableRequirePKChecker) EnterAltertablestmt(ctx *parser.AltertablestmtContext) {
- // ... 50+ lines of checking DROP CONSTRAINT, DROP COLUMN, etc ...
- // ... querying catalog.Origin ...
-}
-
-// After (just record - ALWAYS update for last occurrence)
-func (c *tableRequirePKChecker) EnterAltertablestmt(ctx *parser.AltertablestmtContext) {
- // ... extract table name ...
- key := tableKey(schemaName, tableName)
- c.tableMentions[key] = ctx.GetStart().GetLine() // Always update
-}
-```
-
-3. **Add** simple validation:
-```go
-func (c *tableRequirePKChecker) validateFinalState() {
- for tableKey, lineNumber := range c.tableMentions {
- // Parse table key to extract schema and table name
- schemaName, tableName := parseTableKey(tableKey)
-
- // Check catalog.Final
- hasPK := c.catalog.Final.HasPrimaryKey(&catalog.PrimaryKeyFind{
- SchemaName: schemaName,
- TableName: tableName,
- })
-
- if !hasPK {
- c.adviceList = append(c.adviceList, &storepb.Advice{
- Status: c.level,
- Code: advisor.TableNoPK.Int32(),
- Title: c.title,
- Content: fmt.Sprintf("Table %q.%q requires PRIMARY KEY", schemaName, tableName),
- StartPosition: &storepb.Position{
- Line: int32(lineNumber),
- },
- })
- }
- }
-}
-```
-
-### 4.2 MySQL
-
-**File**: `backend/plugin/advisor/mysql/rule_table_require_pk.go`
-
-**Current Lines**: 279 | **New Lines**: ~285 | **Net**: +6
-
-**Changes**: Simplify `generateAdviceList()` to only check catalog.Final:
-
-```go
-// Before (checks local state)
-func (r *TableRequirePKRule) generateAdviceList() {
- for tableName := range r.tables {
- if len(r.tables[tableName]) == 0 { // Check local tracking
- r.AddAdvice(...)
- }
- }
-}
-
-// After (checks catalog.Final only)
-func (r *TableRequirePKRule) generateAdviceList() {
- for tableName := range r.tables {
- hasPK := r.catalog.Final.HasPrimaryKey(&catalog.PrimaryKeyFind{
- TableName: tableName,
- })
- if !hasPK {
- r.AddAdvice(...)
- }
- }
-}
-```
-
-**Note**: Can keep existing tracking infrastructure but only use catalog.Final for validation.
-
-### 4.3 TiDB, MSSQL, Oracle, Snowflake
-
-**Same Pattern**:
-- Keep existing collection logic
-- Replace validation logic with catalog.Final check
-- Minimal code changes per engine
-
----
-
-## 5. Test Cases
-
-### 5.1 Test Cases That Will Work Correctly
-
-```yaml
-# Test 1: BYT-7917 - PRIMARY GOAL ✅
-- statement: |-
- CREATE TABLE employees(id INT, name VARCHAR(100));
- ALTER TABLE employees ADD PRIMARY KEY (id);
- changeType: 1
- # Expected: No violation ✅
- # Reason: catalog.Final has PK
-
-# Test 2: CREATE without PK, never add PK ✅
-- statement: CREATE TABLE bad_table(id INT);
- changeType: 1
- want:
- - status: 2
- code: 601
- startposition:
- line: 1
- # Expected: Violation at line 1 ✅
- # Reason: catalog.Final has no PK
-
-# Test 3: CREATE with PK, keep PK ✅
-- statement: CREATE TABLE good_table(id INT PRIMARY KEY);
- changeType: 1
- # Expected: No violation ✅
- # Reason: catalog.Final has PK
-
-# Test 4: Multiple tables, mixed scenarios ✅
-- statement: |-
- CREATE TABLE t1(id INT); -- Line 1
- CREATE TABLE t2(id INT PRIMARY KEY); -- Line 2
- ALTER TABLE t1 ADD PRIMARY KEY (id); -- Line 3
- changeType: 1
- # Expected: No violations ✅
- # Reason: Both t1 and t2 have PK in catalog.Final
-```
-
-### 5.2 Test Cases with Improved Line Number Accuracy (Last Occurrence)
-
-```yaml
-# Test 5: CREATE with PK, DROP PK ✅ IMPROVED
-- statement: |-
- CREATE TABLE book(id INT PRIMARY KEY); -- Line 1
- ALTER TABLE book DROP CONSTRAINT book_pkey; -- Line 2
- changeType: 1
- want:
- - status: 2
- code: 601
- startposition:
- line: 2 # ✅ Reports Line 2 (last mention - the DROP operation)
- # Expected: Violation ✅ (correct detection)
- # Line Number: ✅ ACCURATE with last occurrence (points to DROP!)
-
-# Test 6: CREATE with PK, DROP PK column ✅ IMPROVED
-- statement: |-
- CREATE TABLE author(id INT PRIMARY KEY); -- Line 1
- ALTER TABLE author DROP COLUMN id; -- Line 2
- changeType: 1
- want:
- - status: 2
- code: 601
- startposition:
- line: 2 # ✅ Reports Line 2 (last mention - the DROP)
-
-# Test 7: CREATE without PK, ADD PK, DROP PK ✅ IMPROVED
-- statement: |-
- CREATE TABLE product(id INT); -- Line 1
- ALTER TABLE product ADD PRIMARY KEY (id); -- Line 2
- ALTER TABLE product DROP CONSTRAINT pkey; -- Line 3
- changeType: 1
- want:
- - status: 2
- code: 601
- startposition:
- line: 3 # ✅ Reports Line 3 (last mention - the final DROP)
-```
-
-### 5.3 Test Coverage Summary
-
-| Test Scenario | Violation Detected? | Line Number Accurate? |
-|---------------|--------------------|-----------------------|
-| CREATE no PK, ADD PK | ✅ Correct (no violation) | ✅ N/A |
-| CREATE no PK, no ADD | ✅ Correct (violation) | ✅ Yes |
-| CREATE with PK, keep | ✅ Correct (no violation) | ✅ N/A |
-| CREATE with PK, DROP | ✅ Correct (violation) | ✅ **YES** (points to DROP) |
-| CREATE with PK, DROP col | ✅ Correct (violation) | ✅ **YES** (points to DROP) |
-| CREATE no PK, ADD, DROP | ✅ Correct (violation) | ✅ **YES** (points to final DROP) |
-
-**Accuracy**: 100% violation detection, **80-85% line number accuracy** (improved with last occurrence!)
-
----
-
-## 6. Known Limitations
-
-### 6.1 Line Number Accuracy with Last Occurrence
-
-**Status**: **Significantly Improved!** By tracking last occurrence instead of first, line number accuracy increased from ~70% to 80-85%.
-
-**Remaining Edge Cases**:
-When a table has multiple ALTER TABLE statements AFTER the problematic operation, the line number may point to a non-PK-affecting statement:
-
-**Example**:
-```sql
-Line 1: CREATE TABLE t(id INT PRIMARY KEY);
-Line 2: ALTER TABLE t ADD COLUMN name TEXT;
-Line 3: ALTER TABLE t DROP CONSTRAINT t_pkey; -- Real problem here
-Line 4: ALTER TABLE t ADD COLUMN email TEXT; -- Last mention
-```
-**Reported**: "Line 4: Table t requires PRIMARY KEY"
-**Should Report**: "Line 3: Table t requires PRIMARY KEY"
-
-**Impact**:
-- ✅ Violation is correctly detected
-- ✅ Line 4 is temporally close to problem (better than Line 1!)
-- ⚠️ Developer may need to review nearby statements
-
-**Frequency**: Estimated <5% of real-world migration scripts (very rare)
-
-### 6.2 Cannot Distinguish PK-Affecting Operations
-
-**Limitation**: Treats all ALTER TABLE statements equally, cannot identify which specific operation removes PK.
-
-**Impact**:
-- Cannot provide detailed guidance like "Dropping constraint X removes PRIMARY KEY"
-- Error messages are generic
-
-**Comparison**:
-
-| Solution | Error Message Quality |
-|----------|----------------------|
-| Complete | "Line 5: Dropping constraint 'user_pkey' removes PRIMARY KEY from table 'users'" |
-| Simple | "Line 1: Table 'users' requires PRIMARY KEY" |
-
-### 6.3 No Composite PK Column Tracking
-
-**Limitation**: Cannot detect when only some columns of a composite PK are dropped.
-
-**Example**:
-```sql
-CREATE TABLE t(a INT, b INT, PRIMARY KEY (a, b));
-ALTER TABLE t DROP COLUMN a; -- Breaks composite PK
-```
-
-**Impact**:
-- ✅ Still detects violation (catalog.Final has no PK)
-- ⚠️ Line number may point to CREATE TABLE
-
-### 6.4 No Origin vs. New Table Distinction
-
-**Limitation**: Treats tables created in script same as tables existing in database.
-
-**Impact**: Minimal (catalog.Final handles both cases)
-
----
-
-## 7. Trade-off Analysis
-
-### 7.1 What We Gain
-
-| Benefit | Quantification |
-|---------|----------------|
-| **Development Speed** | 60% faster (10 hours vs 15-17 hours) |
-| **Code Complexity** | 60% less code (+60 lines vs +213 lines) |
-| **Maintenance Burden** | Low (simple logic, easy to debug) |
-| **Testing Effort** | 40% less (fewer edge cases to test) |
-| **Bug Risk** | Lower (less code = fewer bugs) |
-
-### 7.2 What We Lose
-
-| Trade-off | Impact Level | Frequency |
-|-----------|-------------|-----------|
-| **Line Number Accuracy** | Medium | Low (10-15% of scripts) |
-| **Detailed Error Messages** | Low | Medium (would be nice-to-have) |
-| **Composite PK Tracking** | Low | Low (rare edge case) |
-
-### 7.3 Decision Matrix
-
-**Choose Simple Solution If**:
-- ✅ Fast delivery is priority
-- ✅ BYT-7917 is the primary pain point
-- ✅ Team accepts line number trade-off for rare cases
-- ✅ Maintenance simplicity is valued
-
-**Choose Complete Solution If**:
-- ✅ Perfect line number accuracy is required
-- ✅ Detailed error messages are important
-- ✅ Edge cases must be handled perfectly
-- ✅ Development time is not constrained
-
----
-
-## 8. Implementation Complexity
-
-### 8.1 Code Changes by Engine
-
-| Engine | Current | Simple Solution | Complete Solution | Savings |
-|--------|---------|----------------|-------------------|---------|
-| PostgreSQL | 204 | ~230 (+26) | ~300 (+96) | 70 lines |
-| MySQL | 279 | ~285 (+6) | ~290 (+11) | 5 lines |
-| TiDB | 240 | ~245 (+5) | ~250 (+10) | 5 lines |
-| MSSQL | 198 | ~215 (+17) | ~230 (+32) | 15 lines |
-| Oracle | 175 | ~190 (+15) | ~207 (+32) | 17 lines |
-| Snowflake | 217 | ~228 (+11) | ~249 (+32) | 21 lines |
-| **Total** | 1,313 | **~1,393 (+80)** | **~1,526 (+213)** | **133 lines** |
-
-**Code Reduction**: 62% fewer new lines (80 vs 213)
-
-### 8.2 Testing Complexity
-
-| Aspect | Simple Solution | Complete Solution |
-|--------|----------------|-------------------|
-| New Test Cases | 4-5 per engine | 8+ per engine |
-| Edge Cases | Minimal | Extensive |
-| Debugging Time | Low | Medium-High |
-| Test Maintenance | Low | Medium |
-
----
-
-## 9. Implementation Steps
-
-### Phase 1: Setup (15 min)
-```bash
-git fetch origin main
-git rebase origin/main
-```
-
-### Phase 2: PostgreSQL (1.5 hours)
-1. Add `tableMentions map[string]int` to checker struct
-2. Modify `EnterCreatestmt()` - just record table name + line
-3. Modify `EnterAltertablestmt()` - just record if not exists
-4. Add `validateFinalState()` method
-5. Update `Check()` to call validation
-6. Add 4-5 test cases
-7. Run tests and debug
-
-### Phase 3: Other Engines (4-5 hours total)
-- MySQL: 45 min
-- TiDB: 45 min
-- MSSQL: 1 hour
-- Oracle: 1 hour
-- Snowflake: 1 hour
-
-### Phase 4: Testing & Polish (1 hour)
-- Run all tests
-- Linting
-- Build
-- Smoke test
-
-**Total Time**: 7-8 hours (vs 15-17 hours for complete solution)
-
----
-
-## 10. Migration Path
-
-### 10.1 Immediate: Deploy Simple Solution
-
-**Timeline**: Week 1
-- Fix BYT-7917 (primary issue)
-- Minimal risk, fast delivery
-- Acceptable trade-offs documented
-
-### 10.2 Future: Upgrade to Complete Solution (Optional)
-
-**Timeline**: Quarter 2-3 (if needed)
-
-**Decision Criteria**:
-- User complaints about line number inaccuracy reach threshold (e.g., >5 reports/month)
-- Product requirement changes (need perfect accuracy)
-- Engineering resources available for refactor
-
-**Migration Strategy**:
-1. Simple solution provides working baseline
-2. Complete solution can be implemented incrementally
-3. No breaking changes needed (rule config stays same)
-4. Test cases from simple solution still apply
-
----
-
-## 11. Recommendations
-
-### 11.1 For Immediate Implementation
-
-**Recommendation**: ✅ **Start with Simple Solution**
-
-**Reasoning**:
-1. Solves BYT-7917 (the actual reported issue)
-2. 60% faster delivery (7-8 hours vs 15-17 hours)
-3. Lower risk (less code, simpler logic)
-4. Acceptable trade-offs for rare edge cases
-5. Can upgrade later if needed
-
-### 11.2 User Communication
-
-**Documentation Update**:
-```markdown
-## table.require-pk Advisor Behavior
-
-**Primary Check**: Validates that all tables have a PRIMARY KEY after executing the migration script.
-
-**Note**: In rare cases where a table is created WITH a primary key but then the
-primary key is dropped in the same script, the error message may point to the
-CREATE TABLE statement rather than the DROP operation. The violation is still
-correctly detected.
-
-Example:
-```sql
-CREATE TABLE t(id INT PRIMARY KEY); -- Error reported here
-ALTER TABLE t DROP CONSTRAINT t_pkey; -- Actual problem here
-```
-
-If you encounter this, review your script to identify which operation removes the primary key.
-```
-
-### 11.3 Future Work
-
-**Phase 2 Enhancements** (if needed):
-1. Track PK-affecting operations for accurate line numbers
-2. Provide detailed error messages with operation context
-3. Handle composite PK column drops granularly
-4. Add "did you mean" suggestions
-
-**Estimated Effort**: Additional 8-10 hours to upgrade from simple to complete
-
----
-
-## 12. Success Criteria
-
-### Must Have (Simple Solution)
-- ✅ BYT-7917 scenario passes (no false positive)
-- ✅ Violations correctly detected for all cases
-- ✅ All existing tests continue to pass
-- ✅ Project builds successfully
-- ✅ No performance degradation
-
-### Nice to Have (Future Enhancement)
-- ⚠️ Line numbers accurate for all scenarios
-- ⚠️ Detailed error messages with operation context
-- ⚠️ Composite PK handling
-
-### Won't Have (Out of Scope)
-- ❌ PK column type validation
-- ❌ PK column suggestions
-- ❌ Cross-table PK consistency
-
----
-
-## 13. Risk Assessment
-
-### Low Risk
-- ✅ Simple logic, easy to understand
-- ✅ Minimal code changes
-- ✅ Fast to implement and test
-- ✅ Easy to rollback if issues
-
-### Medium Risk
-- ⚠️ User confusion if line number points to wrong statement
-- ⚠️ May need documentation updates
-
-### Mitigation
-1. Clear documentation of line number limitation
-2. Comprehensive test coverage
-3. Monitor user feedback post-deployment
-4. Plan for potential upgrade to complete solution
-
----
-
-## 14. Conclusion
-
-The **Simple Solution** provides a pragmatic approach to fixing BYT-7917:
-
-**Pros**:
-- ✅ 60% faster implementation
-- ✅ 62% less code to maintain
-- ✅ Solves the reported issue completely
-- ✅ Lower risk, simpler logic
-- ✅ Can upgrade later if needed
-
-**Cons**:
-- ⚠️ Line numbers may be inaccurate for edge cases (~10-15% of scripts)
-- ⚠️ Less detailed error messages
-
-**Recommendation**: Implement simple solution first, monitor feedback, upgrade if needed.
-
-**Expected Outcome**:
-- BYT-7917 resolved
-- Fast delivery
-- Happy users (most won't encounter edge cases)
-- Option to enhance later
-
----
-
-## 15. Appendix: Code Examples
-
-### A. PostgreSQL Simple Implementation
-
-```go
-type tableRequirePKChecker struct {
- *parser.BasePostgreSQLParserListener
- adviceList []*storepb.Advice
- level storepb.Advice_Status
- title string
- statementsText string
- catalog *catalog.Finder
- tableMentions map[string]int // "schema.table" -> first line
-}
-
-func (c *tableRequirePKChecker) EnterCreatestmt(ctx *parser.CreatestmtContext) {
- if !isTopLevel(ctx.GetParent()) {
- return
- }
-
- var tableName, schemaName string
- allQualifiedNames := ctx.AllQualified_name()
- if len(allQualifiedNames) > 0 {
- tableName = extractTableName(allQualifiedNames[0])
- schemaName = extractSchemaName(allQualifiedNames[0])
- if schemaName == "" {
- schemaName = "public"
- }
- }
-
- key := fmt.Sprintf("%s.%s", schemaName, tableName)
- if _, exists := c.tableMentions[key]; !exists {
- c.tableMentions[key] = ctx.GetStart().GetLine()
- }
-}
-
-func (c *tableRequirePKChecker) EnterAltertablestmt(ctx *parser.AltertablestmtContext) {
- if !isTopLevel(ctx.GetParent()) {
- return
- }
-
- var tableName, schemaName string
- if ctx.Relation_expr() != nil && ctx.Relation_expr().Qualified_name() != nil {
- tableName = extractTableName(ctx.Relation_expr().Qualified_name())
- schemaName = extractSchemaName(ctx.Relation_expr().Qualified_name())
- if schemaName == "" {
- schemaName = "public"
- }
- }
-
- key := fmt.Sprintf("%s.%s", schemaName, tableName)
- if _, exists := c.tableMentions[key]; !exists {
- c.tableMentions[key] = ctx.GetStart().GetLine()
- }
-}
-
-func (c *tableRequirePKChecker) validateFinalState() {
- for tableKey, lineNumber := range c.tableMentions {
- parts := strings.Split(tableKey, ".")
- schemaName := parts[0]
- tableName := parts[1]
-
- hasPK := c.catalog.Final.HasPrimaryKey(&catalog.PrimaryKeyFind{
- SchemaName: schemaName,
- TableName: tableName,
- })
-
- if !hasPK {
- c.adviceList = append(c.adviceList, &storepb.Advice{
- Status: c.level,
- Code: advisor.TableNoPK.Int32(),
- Title: c.title,
- Content: fmt.Sprintf("Table %q.%q requires PRIMARY KEY", schemaName, tableName),
- StartPosition: &storepb.Position{
- Line: int32(lineNumber),
- },
- })
- }
- }
-}
-```
-
-### B. MySQL Simple Implementation
-
-```go
-func (r *TableRequirePKRule) generateAdviceList() {
- for tableName := range r.tables {
- // Simple check: only validate against catalog.Final
- hasPK := r.catalog.Final.HasPrimaryKey(&catalog.PrimaryKeyFind{
- TableName: tableName,
- })
-
- if !hasPK {
- r.AddAdvice(&storepb.Advice{
- Status: r.level,
- Code: advisor.TableNoPK.Int32(),
- Title: r.title,
- Content: fmt.Sprintf("Table `%s` requires PRIMARY KEY", tableName),
- StartPosition: common.ConvertANTLRLineToPosition(r.line[tableName]),
- })
- }
- }
-}
-```
-
----
-
-## 16. References
-
-### Related Documents
-- `BYT-7917-Design-Complete.md` - Complete solution with full state tracking
-- `CLAUDE.md` - Development SOP
-
-### Related Issues
-- BYT-7917: Table require PK false positive
-
-### Related Files
-- All `*table_require_pk.go` files across 6 engine directories
-
----
-
-**Document End**