agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/database/skills/agileflow-database/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: agileflow-database
+version: 1.0.0
+category: agileflow/database
+description: |
+  Use when designing schema, writing migrations, optimizing queries,
+  choosing indexes, or diagnosing database performance. Covers relational
+  (PostgreSQL, MySQL, SQLite) and common NoSQL patterns (MongoDB, Redis).
+  Always migration-safe: reversible, zero-downtime, tested.
+triggers:
+  keywords:
+    - schema design
+    - database
+    - migration
+    - index
+    - query optimization
+    - N+1
+    - foreign key
+    - normalization
+    - join
+    - slow query
+    - EXPLAIN
+    - table design
+    - relationship
+    - one-to-many
+    - many-to-many
+    - transaction
+    - deadlock
+    - partitioning
+  priority: 50
+  exclude:
+    - database administrator (role title)
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/database.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow Database
+
+Schema design, migration discipline, query optimization, and indexing strategy — for relational databases (PostgreSQL, MySQL, SQLite) and common NoSQL patterns (MongoDB, Redis). Every change is reversible and zero-downtime by default.
+
+## When this skill activates
+
+- User needs to design or review a database schema
+- User is writing or reviewing a migration
+- User has a slow query and needs help diagnosing it
+- User asks about indexing strategy — what to index, how to compose indexes
+- User mentions N+1 queries, missing indexes, or EXPLAIN output
+- User needs to model a relationship (one-to-many, many-to-many, hierarchical)
+- User is planning a large table backfill or zero-downtime column change
+- User asks about ACID, transactions, deadlocks, or isolation levels
+
+## Opening discovery flow
+
+**When invoked without clear context, ask one focused question to understand the goal.**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What database work do you need help with?",
+    "header": "Database task",
+    "multiSelect": false,
+    "options": [
+      {"label": "Design a new schema or model a relationship (Recommended starting point)", "description": "Entity identification, normalization, column types, naming conventions, and relationship patterns"},
+      {"label": "Write or review a migration", "description": "Reversible up/down, zero-downtime patterns, lock avoidance, backfill strategy"},
+      {"label": "Optimize a slow query", "description": "Paste the query and EXPLAIN ANALYZE output — I'll diagnose and fix it"},
+      {"label": "Plan an indexing strategy", "description": "Which columns to index, composite index column order, partial indexes, covering indexes"},
+      {"label": "Diagnose a production database problem", "description": "Deadlocks, replication lag, bloat, long-running transactions, connection exhaustion"}
+    ]
+  },
+  {
+    "question": "Which database are you using?",
+    "header": "Database engine",
+    "multiSelect": false,
+    "options": [
+      {"label": "PostgreSQL", "description": "Full feature set: JSONB, GIN/GiST indexes, CTEs, partitioning, LISTEN/NOTIFY"},
+      {"label": "MySQL / MariaDB", "description": "InnoDB engine, JSON columns, generated columns"},
+      {"label": "SQLite", "description": "Embedded, file-based — great for local-first or edge deployments"},
+      {"label": "MongoDB", "description": "Document store — schema validation, aggregation pipeline, Atlas Search"},
+      {"label": "Redis", "description": "Key-value / data structure store — caching, pub/sub, sorted sets"},
+      {"label": "Not sure / multiple", "description": "Tell me your stack and I'll adapt"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+**Route based on answers:**
+
+| Task                      | Next action                                      |
+| ------------------------- | ------------------------------------------------ |
+| Schema design             | Follow `workflows/design-schema.md`              |
+| Migration                 | Follow `workflows/write-migration.md` (inline)   |
+| Slow query / optimization | Follow `workflows/optimize-query.md`             |
+| Indexing strategy         | Load `references/indexing-guide.md`              |
+| Production diagnosis      | Ask for symptoms, error logs, and EXPLAIN output |
+
+## ACID and transaction fundamentals
+
+Every database operation that touches more than one row should be wrapped in a transaction. Know what you're getting:
+
+| Property    | Meaning                                                              |
+| ----------- | -------------------------------------------------------------------- |
+| Atomicity   | All operations in the transaction succeed or all are rolled back     |
+| Consistency | Data moves from one valid state to another — constraints always hold |
+| Isolation   | Concurrent transactions don't see each other's partial writes        |
+| Durability  | Committed transactions survive crashes                               |
+
+### Isolation levels (PostgreSQL)
+
+| Level           | Dirty read | Non-repeatable read | Phantom read | Use when                                    |
+| --------------- | ---------- | ------------------- | ------------ | ------------------------------------------- |
+| Read Committed  | No         | Yes                 | Yes          | Default — fine for most OLTP                |
+| Repeatable Read | No         | No                  | No (PG)      | Reports that must be consistent across rows |
+| Serializable    | No         | No                  | No           | Financial operations, inventory deduction   |
+
+## Normalization vs denormalization decision
+
+**Normalize for writes, denormalize for reads.**
+
+| Situation                                               | Approach                                                 |
+| ------------------------------------------------------- | -------------------------------------------------------- |
+| OLTP: frequent inserts/updates, data integrity critical | Normalize to 3NF                                         |
+| OLAP / reporting: reads dominate, aggregations needed   | Denormalize into a reporting table or materialized view  |
+| Mixed: primary OLTP with some reporting                 | Normalize primary tables, add read-model tables or views |
+| Event-sourced system                                    | Events table normalized; projections denormalized        |
+
+**Signs you've over-normalized:**
+
+- Every read requires 5+ JOINs
+- Query planning time exceeds execution time
+- Application code reconstructs a single object from 8 round-trips
+
+**Signs you've under-normalized:**
+
+- The same value appears in 1,000 rows and you update it in one place — then find 200 rows still have the old value
+- You can't enforce a constraint without an application-level check
+
+## Migration discipline
+
+Every migration must be reversible. Every destructive operation requires a multi-step deployment plan.
+
+### The golden rules
+
+1. **Always write `down`** — even if you think you'll never roll back
+2. **Never lose data in `down`** — rename instead of drop, or restore from backup column
+3. **Test `down` in staging first** — broken rollbacks discovered in production are disasters
+4. **One logical change per migration** — column add, index add, constraint add are separate files
+5. **Never seed production data in migrations** — use seeds or a separate idempotent script
+
+### Zero-downtime patterns
+
+| Change                 | Safe approach                                                               |
+| ---------------------- | --------------------------------------------------------------------------- |
+| Add nullable column    | One migration — always safe                                                 |
+| Add NOT NULL column    | Add nullable → backfill → add default → add constraint (3 migrations)       |
+| Add index              | `CREATE INDEX CONCURRENTLY` — non-blocking in PostgreSQL                    |
+| Rename column          | Add new → backfill → update app → drop old (3 deploys)                      |
+| Remove column          | Stop using in code → deploy → then drop (2 deploys)                         |
+| Change column type     | Add new → trigger/backfill → switch app → drop old                          |
+| Large table backfill   | Batch by PK in chunks of 1,000–10,000, sleep between batches                |
+| Add FK constraint (PG) | Add `NOT VALID` → `VALIDATE CONSTRAINT` separately (avoids full table lock) |
+
+## Query performance principles
+
+### The N+1 problem
+
+N+1 happens when you fetch a list of N records, then issue one query per record to fetch related data. The fix is always eager loading or a JOIN.
+
+```sql
+-- Bad: 1 query for orders + N queries for each order's user
+SELECT * FROM orders;
+-- then for each order: SELECT * FROM users WHERE id = $1
+
+-- Good: one query with a JOIN
+SELECT o.*, u.name, u.email
+FROM orders o
+JOIN users u ON u.id = o.user_id
+WHERE o.status = 'pending';
+```
+
+### Reading EXPLAIN ANALYZE
+
+```sql
+EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 42 AND status = 'pending';
+```
+
+Key nodes to recognize:
+
+| Node             | Meaning                                                             | Action if unexpected              |
+| ---------------- | ------------------------------------------------------------------- | --------------------------------- |
+| Seq Scan         | Full table scan — no index used                                     | Add index if table is large       |
+| Index Scan       | Index used, then row fetched from heap                              | Normal — check rows estimate      |
+| Index Only Scan  | Covering index — no heap fetch needed                               | Best possible                     |
+| Bitmap Heap Scan | Index used for range, rows fetched in batches                       | Normal for range queries          |
+| Hash Join        | In-memory hash of smaller table, probe with larger                  | Fine; bad if hash batches to disk |
+| Nested Loop      | For each outer row, loop inner — fine for small sets, bad for large | Check row estimates               |
+
+**Cost anatomy:** `cost=0.00..432.10 rows=1 width=256`
+
+- First number: startup cost (before first row)
+- Second number: total cost (all rows)
+- Rows: planner estimate — compare to `actual rows` for stale stats
+
+If `actual rows` >> `rows estimate`, run `ANALYZE table_name` to refresh statistics.
+
+## Common schema anti-patterns
+
+| Anti-pattern                       | Problem                                           | Fix                                        |
+| ---------------------------------- | ------------------------------------------------- | ------------------------------------------ |
+| Storing comma-separated IDs        | Can't JOIN, can't enforce FK, hard to query       | Junction table                             |
+| Using FLOAT for money              | Floating-point precision errors                   | DECIMAL(19,4) or integer cents             |
+| Timestamps without timezone        | Ambiguous on DST changes, breaks across regions   | TIMESTAMPTZ, store in UTC                  |
+| VARCHAR(255) everywhere            | Magic number — usually meaningless                | TEXT for arbitrary, or actual max length   |
+| No soft-delete strategy            | Hard deletes break audit trails and FK references | deleted_at TIMESTAMPTZ NULL                |
+| Indexing every column              | Slows writes, bloats storage, confuses planner    | Index only WHERE / JOIN / ORDER BY columns |
+| God table (100+ columns)           | Hard to reason about, locks contend               | Vertical split, 1-to-1 related tables      |
+| Polymorphic FK without constraints | No referential integrity possible                 | STI, CTI, or separate FK per type          |
+
+## Self-improving learnings
+
+`_learnings/database.yaml` records:
+
+- Database engine(s) and version in use
+- ORM or query builder (Prisma, Drizzle, Knex, SQLAlchemy, GORM, ActiveRecord)
+- Migration tool (Flyway, Liquibase, Rails migrations, Alembic, Prisma Migrate)
+- Naming conventions the team uses (if non-standard)
+- Whether the team uses UUID or BIGSERIAL for primary keys
+- Partitioning strategy (if any)
+- Connection pooling setup (PgBouncer, RDS Proxy, Prisma connection limit)
+
+Apply on invocation; update on correction.
+
+## Quality checklist
+
+Before delivering any schema or migration:
+
+- [ ] Every table has a primary key
+- [ ] All foreign keys have corresponding indexes
+- [ ] Timestamps use TIMESTAMPTZ (not TIMESTAMP), stored in UTC
+- [ ] Money values use DECIMAL or integer cents — no FLOAT
+- [ ] Migration has both `up` and `down`
+- [ ] Zero-downtime pattern applied for any destructive change
+- [ ] Large table changes use CONCURRENTLY or batch approach
+- [ ] Constraints named explicitly (easier to reference in errors and rollbacks)
+- [ ] New indexes created CONCURRENTLY in PostgreSQL
+- [ ] EXPLAIN ANALYZE reviewed for any query expected to run at scale
+
+## Integration
+
+- **agileflow-test-writer** — generate tests for migration scripts, data access layers, and repository functions; DB changes without tests are untested contracts
+- **agileflow-story-writer** — acceptance criteria for data-model changes drive schema decisions; always read the AC before designing the schema
+- **agileflow-adr** — document significant schema decisions (UUID vs BIGSERIAL, multi-tenancy strategy, soft-delete vs hard-delete) before implementing
+- **agileflow-migration** — use for zero-downtime schema migrations, large backfills, and framework-level ORM upgrades; database handles design, migration handles execution
+- **agileflow-engineering** — engineering owns the feature; database is the specialist for the storage layer; coordinate so schema and API land together
+- **agileflow-performance** — query optimisation, index analysis, and connection pool tuning overlap between both skills; use database for schema-level fixes, performance for application-level profiling
+- **agileflow-audit** — the query performance and security dimensions of the audit surface DB issues; database fixes what the audit finds
+- **agileflow-refactor** — when a schema has grown organically and needs restructuring (column renames, table splits, normalisation), coordinate with refactor for the application-layer changes
+
+## References
+
+Load these files when you need deeper context:
+
+| File                                | When to load                                                                |
+| ----------------------------------- | --------------------------------------------------------------------------- |
+| `references/schema-design-guide.md` | Full normalization rules, naming conventions, column types, common patterns |
+| `references/indexing-guide.md`      | Index types, composite index ordering, when indexes hurt, maintenance       |
+| `references/migration-guide.md`     | Reversibility rules, zero-downtime patterns, PostgreSQL-specific safety     |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                          | When to follow                                                        |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `workflows/design-schema.md`  | User needs to design a new schema or model entities from requirements |
+| `workflows/optimize-query.md` | User has a slow query and needs diagnosis and a fix                   |

package/content/plugins/database/skills/agileflow-database/references/indexing-guide.md

@@ -0,0 +1,313 @@
+# Indexing Guide
+
+A practical reference for choosing, designing, and maintaining database indexes — primarily PostgreSQL, with notes for MySQL and MongoDB where behavior differs.
+
+---
+
+## When Indexes Help
+
+An index is only worth its write overhead if it meaningfully reduces the rows the planner must examine. Index when:
+
+- A column appears in `WHERE` clauses on large tables
+- A column is used in `JOIN` conditions (foreign keys almost always need indexes)
+- A column drives `ORDER BY` or `GROUP BY` on large result sets
+- A query must enforce `UNIQUE` or `PRIMARY KEY` (indexes are automatic for these)
+- A covering index can eliminate a heap fetch entirely
+
+**Rule of thumb:** if a query returns less than ~5% of rows, an index scan is faster than a sequential scan. Above that, the planner may prefer sequential scan even with an index.
+
+---
+
+## Index Types (PostgreSQL)
+
+| Type    | Operators                                | Use case                                                                                            |
+| ------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| B-tree  | =, <, <=, >, >=, BETWEEN, LIKE 'prefix%' | Default — general purpose, ORDER BY, range queries                                                  |
+| Hash    | = only                                   | Equality lookups only; slightly faster than B-tree for = but not maintained across WAL before PG 10 |
+| GIN     | @>, <@, &&, @@                           | JSONB, arrays, full-text search (tsvector), pg_trgm trigrams                                        |
+| GiST    | Geometric, range, PostGIS                | Geometric queries, PostGIS geography, fuzzy text (pg_trgm)                                          |
+| BRIN    | Range on ordered data                    | Very large append-only tables (time-series, logs) — tiny index, approximate                         |
+| SP-GiST | Partitioned non-balanced trees           | Points, ranges, network addresses                                                                   |
+
+**When to choose GIN over GiST for text search:**
+
+- GIN: faster reads, slower writes, larger index — good for mostly-read data
+- GiST: faster writes, slower reads — good for frequently-updated data
+
+---
+
+## Composite Indexes
+
+Column order in a composite index determines which queries it can serve. The index can serve queries that use a prefix of the column list.
+
+```sql
+-- Index on (user_id, status, created_at)
+CREATE INDEX idx_orders_user_status_created ON orders (user_id, status, created_at);
+```
+
+This index can serve:
+
+- `WHERE user_id = 1`
+- `WHERE user_id = 1 AND status = 'pending'`
+- `WHERE user_id = 1 AND status = 'pending' AND created_at > '2024-01-01'`
+
+This index CANNOT efficiently serve:
+
+- `WHERE status = 'pending'` (leading column missing)
+- `WHERE created_at > '2024-01-01'` (leading columns missing)
+
+### Column Ordering Rules
+
+1. **Equality predicates first** — columns used with `=` before range columns
+2. **Most selective equality column first** — put the column that filters most rows ahead of others
+3. **Range predicates last** — `<`, `>`, `BETWEEN`, `LIKE 'prefix%'`
+4. **ORDER BY columns can follow** — if sort direction matches index direction
+
+```sql
+-- Query: WHERE status = 'active' AND created_at > '2024-01-01' ORDER BY created_at
+
+-- Good: equality first, then range
+CREATE INDEX idx_users_status_created ON users (status, created_at);
+
+-- Bad: range first blocks using the equality column from the index efficiently
+CREATE INDEX idx_users_created_status ON users (created_at, status);
+```
+
+---
+
+## Partial Indexes
+
+A partial index indexes only the rows matching a WHERE condition. Smaller index, faster scans, lower write overhead.
+
+```sql
+-- Index only active users (not soft-deleted)
+CREATE INDEX idx_users_email_active ON users (email) WHERE deleted_at IS NULL;
+
+-- Index only pending orders (status is low-cardinality but subset is small)
+CREATE INDEX idx_orders_pending ON orders (created_at) WHERE status = 'pending';
+
+-- Index only unverified emails (temporary state — small subset)
+CREATE INDEX idx_users_unverified ON users (email) WHERE email_verified_at IS NULL;
+```
+
+The query must include the same WHERE condition for the planner to use the partial index:
+
+```sql
+-- Uses the partial index
+SELECT * FROM users WHERE email = $1 AND deleted_at IS NULL;
+
+-- Does NOT use the partial index (missing the condition)
+SELECT * FROM users WHERE email = $1;
+```
+
+---
+
+## Covering Indexes (Index-Only Scans)
+
+A covering index includes all columns the query needs, eliminating the heap fetch. This is the fastest possible index path: `Index Only Scan`.
+
+```sql
+-- Query: SELECT email, name FROM users WHERE organization_id = $1
+-- Covering index: include both filter and select columns
+CREATE INDEX idx_users_org_covering ON users (organization_id) INCLUDE (email, name);
+```
+
+Use `INCLUDE` (PostgreSQL 11+) for non-key columns — they're in the leaf pages but not the B-tree structure, so they don't participate in ordering but are available for index-only scans.
+
+---
+
+## When Indexes Hurt
+
+Don't index everything. Indexes have costs:
+
+- Every `INSERT`, `UPDATE`, and `DELETE` must update all indexes on the table
+- Indexes consume disk space (sometimes more than the table itself)
+- Too many indexes confuse the query planner — it may choose the wrong one
+- Indexes on low-cardinality columns (boolean, small ENUMs) often aren't used
+
+### Low-cardinality columns
+
+A boolean column with 90% `true` values: the planner knows a sequential scan is cheaper for `WHERE is_active = true` (90% of rows anyway). An index only helps if:
+
+- Combined with other high-cardinality columns in a composite index
+- Used as a partial index condition, not the filter itself
+
+```sql
+-- This standalone index often isn't used
+CREATE INDEX idx_users_is_active ON users (is_active);  -- low cardinality
+
+-- This composite index is useful
+CREATE INDEX idx_orders_status_user ON orders (status, user_id);
+
+-- This partial index is useful
+CREATE INDEX idx_orders_pending_created ON orders (created_at) WHERE status = 'pending';
+```
+
+---
+
+## Non-Blocking Index Creation
+
+Never create an index without CONCURRENTLY on a live table. Standard CREATE INDEX takes an ACCESS SHARE lock that blocks writes.
+
+```sql
+-- Blocks writes during index build — NEVER use on live tables
+CREATE INDEX idx_orders_user_id ON orders (user_id);
+
+-- Non-blocking — takes longer but doesn't block
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+If CONCURRENTLY fails (e.g., transaction issue), it leaves an INVALID index. Clean up:
+
+```sql
+-- Check for invalid indexes
+SELECT indexname, indisvalid FROM pg_indexes
+JOIN pg_class ON pg_class.relname = pg_indexes.indexname
+JOIN pg_index ON pg_index.indexrelid = pg_class.oid
+WHERE indisvalid = false;
+
+-- Drop and recreate
+DROP INDEX CONCURRENTLY idx_orders_user_id;
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+---
+
+## EXPLAIN ANALYZE Reference
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
+```
+
+### Node Types
+
+| Node              | Meaning                                                                                        |
+| ----------------- | ---------------------------------------------------------------------------------------------- |
+| Seq Scan          | Full table scan. Fine for small tables; add an index if table is large and filter is selective |
+| Index Scan        | Index lookup, then heap fetch for each matching row                                            |
+| Index Only Scan   | Covering index — no heap fetch. Best possible for point lookups                                |
+| Bitmap Index Scan | Builds a bitmap of matching pages, then bulk-fetches (efficient for range)                     |
+| Bitmap Heap Scan  | Fetches pages identified by bitmap — paired with Bitmap Index Scan                             |
+| Nested Loop       | Outer loop drives inner — fine for small row counts on outer side                              |
+| Hash Join         | Hashes smaller table in memory, probes with larger — good default                              |
+| Merge Join        | Sorts both inputs, merges — efficient when both inputs already sorted                          |
+| Sort              | Explicit sort node — see if an index could eliminate it                                        |
+| Hash              | Builds an in-memory hash table                                                                 |
+
+### Reading Cost and Rows
+
+```
+->  Index Scan using idx_orders_user_id on orders
+      (cost=0.43..8.45 rows=1 width=128)
+      (actual time=0.032..0.033 rows=1 loops=1)
+```
+
+- `cost=0.43..8.45`: planner's estimated cost (startup..total) in arbitrary units
+- `rows=1`: planner's row estimate
+- `actual time=0.032..0.033`: real execution time in ms (startup..total)
+- `actual rows=1`: real rows returned
+- `loops=1`: how many times this node ran
+
+**Stale statistics warning:** if `actual rows` >> `rows` estimate by 10x or more, run `ANALYZE table_name` to update statistics. The planner makes poor choices with stale stats.
+
+### BUFFERS output
+
+```
+Buffers: shared hit=142 read=18 dirtied=0 written=0
+```
+
+- `hit`: pages found in shared_buffers (fast)
+- `read`: pages read from disk (slow — consider more shared_buffers or caching)
+
+---
+
+## Index Maintenance
+
+### Finding Unused Indexes
+
+```sql
+SELECT
+  schemaname,
+  tablename,
+  indexname,
+  idx_scan AS scans,
+  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size
+FROM pg_stat_user_indexes
+WHERE idx_scan < 50  -- threshold — adjust to your traffic
+  AND indexrelname NOT LIKE '%pkey'
+  AND indexrelname NOT LIKE '%unique'
+ORDER BY pg_relation_size(indexrelid) DESC;
+```
+
+Drop unused indexes after confirming they're truly unused (reset stats after major deployments: `SELECT pg_stat_reset();`).
+
+### Finding Tables Doing Excessive Sequential Scans
+
+```sql
+SELECT
+  relname AS table_name,
+  seq_scan,
+  seq_tup_read,
+  idx_scan,
+  n_live_tup AS row_count,
+  pg_size_pretty(pg_total_relation_size(relid)) AS total_size
+FROM pg_stat_user_tables
+WHERE seq_scan > idx_scan
+  AND n_live_tup > 10000  -- only large tables worth indexing
+ORDER BY seq_tup_read DESC;
+```
+
+### Rebuilding Bloated Indexes
+
+Over time, B-tree indexes accumulate dead tuples (bloat) from updates and deletes. Rebuild without blocking:
+
+```sql
+REINDEX INDEX CONCURRENTLY idx_orders_user_id;
+```
+
+Or recreate with a swap (safer for very large indexes):
+
+```sql
+CREATE INDEX CONCURRENTLY idx_orders_user_id_new ON orders (user_id);
+-- verify new index is valid
+DROP INDEX CONCURRENTLY idx_orders_user_id;
+ALTER INDEX idx_orders_user_id_new RENAME TO idx_orders_user_id;
+```
+
+### Updating Statistics
+
+After bulk data loads or large deletes:
+
+```sql
+ANALYZE orders;          -- update stats for one table
+ANALYZE;                 -- update stats for all tables (runs quickly, non-blocking)
+VACUUM ANALYZE orders;   -- reclaim dead tuples + update stats
+```
+
+---
+
+## MySQL Notes
+
+MySQL (InnoDB) index behavior differs from PostgreSQL in key ways:
+
+- Clustered index: the primary key IS the table in InnoDB — secondary indexes contain the PK value as the row pointer
+- Covering index: use `EXPLAIN` and look for `Using index` in the Extra column
+- No `CONCURRENTLY`: use `pt-online-schema-change` or `gh-ost` for large table index changes
+- FULLTEXT index: MySQL's built-in full-text search — different from PostgreSQL's `tsvector` approach
+- Hash indexes: only in MEMORY engine — InnoDB uses adaptive hash index internally, not user-configurable
+- Foreign key indexes: MySQL requires an index on the FK column; it creates one automatically if missing
+
+---
+
+## Quick Reference
+
+| Scenario                                       | Index to create                                               |
+| ---------------------------------------------- | ------------------------------------------------------------- |
+| `WHERE user_id = $1`                           | `(user_id)`                                                   |
+| `WHERE user_id = $1 AND status = 'active'`     | `(user_id, status)` — equality both, put more selective first |
+| `WHERE status = 'pending' ORDER BY created_at` | `(status, created_at)`                                        |
+| `WHERE deleted_at IS NULL AND email = $1`      | `(email) WHERE deleted_at IS NULL` (partial)                  |
+| `SELECT id, name FROM users WHERE org_id = $1` | `(org_id) INCLUDE (name)` (covering)                          |
+| `WHERE payload @> '{"type": "login"}'` (JSONB) | `USING GIN (payload)`                                         |
+| Full-text: `WHERE to_tsvector(body) @@ query`  | `USING GIN (to_tsvector('english', body))`                    |
+| Unique email                                   | `CREATE UNIQUE INDEX` (or `UNIQUE` constraint — same thing)   |