thanh-kit 2.5.0 → 2.5.2

package/templates/skills/databases/stacks/postgres.md

@@ -0,0 +1,235 @@
+# PostgreSQL Rules
+
+Guidelines for designing schemas specific to PostgreSQL.
+
+---
+
+## Data Types
+
+| Use case | Type | Notes |
+|----------|------|-------|
+| Primary key | `BIGSERIAL` | Auto-increment BIGINT |
+| Primary key (small) | `SERIAL` | Auto-increment INT |
+| Foreign key | Match with PK type | |
+| Money/Price | `NUMERIC(18,2)` | Precise |
+| Boolean | `BOOLEAN` | TRUE/FALSE/NULL |
+| Short text | `VARCHAR(n)` or `TEXT` | TEXT has no limit |
+| JSON | `JSONB` | **Queryable**, prefer over JSON |
+| Timestamp | `TIMESTAMPTZ` | **Always use with timezone** |
+| Date | `DATE` | |
+| UUID | `UUID` | Native type |
+| Array | `TEXT[]`, `INT[]` | |
+| IP Address | `INET` | |
+
+### TIMESTAMPTZ vs TIMESTAMP
+**IMPORTANT**: Always use `TIMESTAMPTZ` to avoid timezone issues.
+
+---
+
+## Comments (NO metadata tables needed)
+
+PostgreSQL supports `COMMENT ON`:
+
+### Table comment
+```sql
+COMMENT ON TABLE orders IS 'Table storing customer orders';
+```
+
+### Column comments
+```sql
+COMMENT ON COLUMN orders.id IS 'Primary key, auto increment';
+COMMENT ON COLUMN orders.order_number IS 'Unique order code, format: ORD-YYYYMMDD-XXXXX';
+COMMENT ON COLUMN orders.status IS 'Status: pending|confirmed|shipped|cancelled';
+```
+
+### Query comments
+```sql
+-- Table comment
+SELECT obj_description('orders'::regclass);
+
+-- Column comments
+SELECT
+    c.column_name,
+    pgd.description
+FROM information_schema.columns c
+LEFT JOIN pg_catalog.pg_statio_all_tables st
+    ON c.table_schema = st.schemaname AND c.table_name = st.relname
+LEFT JOIN pg_catalog.pg_description pgd
+    ON pgd.objoid = st.relid AND pgd.objsubid = c.ordinal_position
+WHERE c.table_name = 'orders';
+```
+
+---
+
+## Index Types
+
+### B-Tree (default)
+```sql
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+### Partial Index (very useful)
+```sql
+-- Only index non-deleted records
+CREATE INDEX idx_orders_active ON orders(user_id, status)
+    WHERE deleted_at IS NULL;
+
+-- Only index pending orders
+CREATE INDEX idx_orders_pending ON orders(created_at)
+    WHERE status = 'pending';
+```
+
+### GIN (for JSONB, Arrays, Full-text)
+```sql
+CREATE INDEX idx_orders_metadata ON orders USING GIN(metadata);
+CREATE INDEX idx_products_tags ON products USING GIN(tags);
+
+-- Full-text search
+CREATE INDEX idx_products_search ON products
+    USING GIN(to_tsvector('english', name || ' ' || description));
+```
+
+### BRIN (for large tables with ordered data)
+```sql
+CREATE INDEX idx_logs_created ON logs USING BRIN(created_at);
+```
+
+---
+
+## Sequences (Auto Increment)
+
+```sql
+-- SERIAL/BIGSERIAL auto-creates sequence
+CREATE TABLE users (id BIGSERIAL PRIMARY KEY);
+
+-- Identity columns (PostgreSQL 10+)
+CREATE TABLE users (
+    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY
+);
+
+-- Custom sequence
+CREATE SEQUENCE order_number_seq START 1000;
+```
+
+---
+
+## Auto update timestamp (requires trigger)
+
+PostgreSQL **does not have** `ON UPDATE CURRENT_TIMESTAMP`. Need to create trigger:
+
+```sql
+-- Function
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Apply to table
+CREATE TRIGGER trg_orders_updated_at
+    BEFORE UPDATE ON orders
+    FOR EACH ROW
+    EXECUTE FUNCTION update_updated_at_column();
+```
+
+---
+
+## ENUM Type
+
+```sql
+-- Create enum type
+CREATE TYPE order_status AS ENUM (
+    'pending', 'confirmed', 'shipped', 'cancelled', 'completed'
+);
+
+-- Use in table
+CREATE TABLE orders (
+    status order_status NOT NULL DEFAULT 'pending'
+);
+
+-- Add new value
+ALTER TYPE order_status ADD VALUE 'refunded' AFTER 'completed';
+```
+
+**Note:** Cannot remove values from ENUM.
+
+---
+
+## Partitioning
+
+### Range partitioning
+```sql
+CREATE TABLE fact_orders (
+    id BIGSERIAL,
+    order_date DATE NOT NULL,
+    ...
+) PARTITION BY RANGE (order_date);
+
+CREATE TABLE fact_orders_2024 PARTITION OF fact_orders
+    FOR VALUES FROM ('2024-01-01') TO ('2025-01-01');
+
+CREATE TABLE fact_orders_default PARTITION OF fact_orders DEFAULT;
+```
+
+### Hash partitioning
+```sql
+CREATE TABLE logs PARTITION BY HASH (user_id);
+CREATE TABLE logs_0 PARTITION OF logs FOR VALUES WITH (MODULUS 4, REMAINDER 0);
+CREATE TABLE logs_1 PARTITION OF logs FOR VALUES WITH (MODULUS 4, REMAINDER 1);
+```
+
+---
+
+## Example DDL
+
+```sql
+-- Create enum
+CREATE TYPE order_status AS ENUM ('pending', 'confirmed', 'shipped', 'cancelled');
+
+-- Create table
+CREATE TABLE orders (
+    id BIGSERIAL PRIMARY KEY,
+    order_number VARCHAR(50) NOT NULL,
+    user_id BIGINT NOT NULL,
+    status order_status NOT NULL DEFAULT 'pending',
+    subtotal NUMERIC(18,2) NOT NULL DEFAULT 0,
+    discount_amount NUMERIC(18,2) NOT NULL DEFAULT 0,
+    total_amount NUMERIC(18,2) NOT NULL DEFAULT 0,
+    metadata JSONB DEFAULT '{}',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT uk_orders_number UNIQUE (order_number),
+    CONSTRAINT fk_orders_user FOREIGN KEY (user_id) REFERENCES users(id)
+);
+
+-- Indexes
+CREATE INDEX idx_orders_user ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+CREATE INDEX idx_orders_metadata ON orders USING GIN(metadata);
+
+-- Comments
+COMMENT ON TABLE orders IS 'Table storing order information';
+COMMENT ON COLUMN orders.order_number IS 'Unique order code';
+COMMENT ON COLUMN orders.status IS 'Order status';
+
+-- Trigger for updated_at
+CREATE TRIGGER trg_orders_updated_at
+    BEFORE UPDATE ON orders
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+```
+
+---
+
+## Checklist
+
+- [ ] Use `TIMESTAMPTZ` instead of `TIMESTAMP`
+- [ ] Use `JSONB` instead of `JSON`
+- [ ] `COMMENT ON` for tables and columns
+- [ ] Trigger for `updated_at`
+- [ ] Partial indexes for soft delete / filtered queries
+- [ ] GIN index for JSONB columns

package/templates/skills/databases/stacks/sqlite.md

@@ -0,0 +1,244 @@
+# SQLite Rules
+
+Guidelines for designing schemas specific to SQLite.
+
+---
+
+## Data Types
+
+SQLite has **dynamic typing**, with only 5 storage classes:
+
+| Storage Class | Use case | Notes |
+|---------------|----------|-------|
+| `INTEGER` | PK, FK, counts, booleans | |
+| `REAL` | Floats, decimals | |
+| `TEXT` | Strings, dates, JSON, enums | |
+| `BLOB` | Binary data | |
+| `NULL` | Null values | |
+
+### Type affinity
+SQLite does not strictly enforce types. Type declaration is just a "hint":
+```sql
+-- All of these will be stored
+CREATE TABLE test (price REAL);
+INSERT INTO test VALUES (100);      -- Stored as INTEGER
+INSERT INTO test VALUES (99.99);    -- Stored as REAL
+INSERT INTO test VALUES ('free');   -- Stored as TEXT (!)
+```
+
+### Date/Time
+SQLite **does not have** DATE/TIME type. Store as TEXT with ISO format:
+```sql
+created_at TEXT DEFAULT (datetime('now'))
+-- Format: YYYY-MM-DD HH:MM:SS
+```
+
+---
+
+## Metadata Tables (REQUIRED)
+
+SQLite **does not support comments** on tables and columns. Need to create metadata tables:
+
+### Create metadata tables
+
+```sql
+CREATE TABLE IF NOT EXISTS metadata_tables (
+    table_name TEXT PRIMARY KEY,
+    description TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS metadata_columns (
+    table_name TEXT NOT NULL,
+    column_name TEXT NOT NULL,
+    description TEXT NOT NULL,
+    data_type TEXT,
+    is_nullable INTEGER DEFAULT 1,  -- 0=NOT NULL, 1=NULL
+    default_value TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (table_name, column_name),
+    FOREIGN KEY (table_name) REFERENCES metadata_tables(table_name) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_metadata_columns_table ON metadata_columns(table_name);
+```
+
+### Insert metadata after creating table
+
+```sql
+-- Table metadata
+INSERT INTO metadata_tables (table_name, description)
+VALUES ('orders', 'Table storing customer order information');
+
+-- Column metadata
+INSERT INTO metadata_columns (table_name, column_name, description, data_type, is_nullable)
+VALUES
+    ('orders', 'id', 'Primary key, auto increment', 'INTEGER', 0),
+    ('orders', 'order_number', 'Unique order code', 'TEXT', 0),
+    ('orders', 'user_id', 'FK to users.id', 'INTEGER', 0),
+    ('orders', 'status', 'pending|confirmed|shipped|cancelled', 'TEXT', 0),
+    ('orders', 'total_amount', 'Total value', 'REAL', 0);
+```
+
+### Query metadata
+
+```sql
+-- View schema with descriptions
+SELECT
+    t.table_name,
+    t.description AS table_description,
+    c.column_name,
+    c.description AS column_description,
+    c.data_type
+FROM metadata_tables t
+LEFT JOIN metadata_columns c ON t.table_name = c.table_name
+ORDER BY t.table_name, c.column_name;
+```
+
+---
+
+## Auto Increment
+
+```sql
+-- Option 1: INTEGER PRIMARY KEY (recommended)
+-- SQLite auto-increments INTEGER PRIMARY KEY automatically
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY,
+    name TEXT
+);
+
+-- Option 2: AUTOINCREMENT keyword
+-- Ensures deleted IDs are not reused (slower)
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT
+);
+```
+
+---
+
+## Foreign Keys
+
+**IMPORTANT**: FK is disabled by default in SQLite!
+
+```sql
+-- Enable FK for each connection
+PRAGMA foreign_keys = ON;
+
+-- Create table with FK
+CREATE TABLE order_items (
+    id INTEGER PRIMARY KEY,
+    order_id INTEGER NOT NULL,
+    product_id INTEGER NOT NULL,
+    FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
+    FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE RESTRICT
+);
+
+-- Create index for FK
+CREATE INDEX idx_order_items_order ON order_items(order_id);
+CREATE INDEX idx_order_items_product ON order_items(product_id);
+```
+
+---
+
+## ENUM substitute
+
+SQLite does not have ENUM. Use CHECK constraint:
+
+```sql
+CREATE TABLE orders (
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'confirmed', 'shipped', 'cancelled'))
+);
+```
+
+---
+
+## Index Types
+
+SQLite only supports B-Tree indexes:
+
+```sql
+-- Standard index
+CREATE INDEX idx_orders_status ON orders(status);
+
+-- Composite index
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+
+-- Unique index
+CREATE UNIQUE INDEX idx_orders_number ON orders(order_number);
+
+-- Partial index (SQLite 3.8.0+)
+CREATE INDEX idx_orders_active ON orders(user_id)
+    WHERE deleted_at IS NULL;
+```
+
+---
+
+## Limitations
+
+| Feature | Status | Workaround |
+|---------|--------|------------|
+| `ALTER COLUMN` | ❌ Not supported | Recreate table |
+| `DROP COLUMN` | ✅ SQLite 3.35+ | Recreate table (older) |
+| Comments | ❌ Not supported | Metadata tables |
+| ENUM | ❌ Not supported | CHECK constraint |
+| Stored procedures | ❌ Not supported | App logic |
+| Concurrent writes | ⚠️ Limited | Single writer |
+
+---
+
+## Example DDL
+
+```sql
+-- Enable foreign keys
+PRAGMA foreign_keys = ON;
+
+-- Create table
+CREATE TABLE orders (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    order_number TEXT NOT NULL,
+    user_id INTEGER NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'confirmed', 'shipped', 'cancelled')),
+    subtotal REAL NOT NULL DEFAULT 0,
+    discount_amount REAL NOT NULL DEFAULT 0,
+    total_amount REAL NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at TEXT,
+
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+);
+
+-- Indexes
+CREATE UNIQUE INDEX idx_orders_number ON orders(order_number);
+CREATE INDEX idx_orders_user ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_updated ON orders(updated_at);
+
+-- Metadata
+INSERT INTO metadata_tables (table_name, description)
+VALUES ('orders', 'Table storing order information');
+
+INSERT INTO metadata_columns (table_name, column_name, description, data_type, is_nullable)
+VALUES
+    ('orders', 'id', 'Primary key', 'INTEGER', 0),
+    ('orders', 'order_number', 'Unique order code', 'TEXT', 0),
+    ('orders', 'user_id', 'FK to users.id', 'INTEGER', 0),
+    ('orders', 'status', 'pending|confirmed|shipped|cancelled', 'TEXT', 0),
+    ('orders', 'total_amount', 'Total payment', 'REAL', 0);
+```
+
+---
+
+## Checklist
+
+- [ ] `PRAGMA foreign_keys = ON` at start of each connection
+- [ ] Metadata tables created
+- [ ] INSERT metadata after each CREATE TABLE
+- [ ] Use `TEXT` for dates (ISO format: YYYY-MM-DD HH:MM:SS)
+- [ ] CHECK constraint instead of ENUM
+- [ ] Index for FK columns
+- [ ] Update metadata when ALTER/DROP table

package/templates/skills/databases/transactional.md

@@ -0,0 +1,176 @@
+# Transactional (OLTP) Rules
+
+> **Note:** Core naming conventions, workflow, and checklist are in `SKILL.md` or `db-design.md` (always loaded).
+
+Guidelines for designing schemas for day-to-day business operations.
+
+---
+
+## Normalization Principles
+
+### Prefer 3NF (Third Normal Form)
+
+- Each table represents one clear entity/relationship
+- No repeating information that can be referenced (use FK)
+- Clear separation:
+  - `orders` (header) vs `order_items` (line items)
+  - `products` vs `product_variants`, `product_prices`
+
+### Foreign Key Constraints
+
+Use FK with appropriate ON DELETE / ON UPDATE:
+
+```sql
+-- Cascade: delete order → delete order_items
+FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE
+
+-- Restrict: cannot delete user if orders exist
+FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+
+-- Set null: delete category → product.category_id = NULL
+FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE SET NULL
+```
+
+---
+
+## Indexing Rules
+
+### 1. Primary Key
+- Usually `BIGINT` auto-increment or UUID
+- Format: `PRIMARY KEY (id)`
+
+### 2. Foreign Key Indexes
+**IMPORTANT**: Create indexes for ALL foreign keys for efficient JOINs:
+```sql
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+CREATE INDEX idx_order_items_product_id ON order_items(product_id);
+```
+
+### 3. Frequently Filtered Columns
+Index columns commonly used in WHERE:
+- `status`, `created_at`, `updated_at`
+- Code/reference columns: `order_number`, `sku`
+
+### 4. Composite Indexes
+Based on actual query patterns:
+```sql
+-- Query: WHERE user_id = ? AND status = ? ORDER BY created_at DESC
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+
+-- Query: WHERE store_id = ? AND created_at BETWEEN ...
+CREATE INDEX idx_orders_store_created ON orders(store_id, created_at);
+```
+
+**Composite index rules:**
+- Put columns with **high selectivity** (fewer duplicate values) first
+- Avoid duplicate/redundant indexes
+- Index should cover WHERE + ORDER BY of query
+
+### 5. Unique Constraints
+```sql
+UNIQUE (order_number)
+UNIQUE (sku)
+UNIQUE (user_id, email)  -- compound unique
+```
+
+---
+
+## Soft Delete Pattern
+
+When you need to keep deleted data instead of permanently deleting:
+
+```sql
+-- Add deleted_at column
+deleted_at TIMESTAMP NULL
+
+-- Partial index for non-deleted records (PostgreSQL)
+CREATE INDEX idx_orders_active ON orders(user_id, status)
+    WHERE deleted_at IS NULL;
+
+-- Query only active records
+SELECT * FROM orders WHERE deleted_at IS NULL;
+```
+
+---
+
+## Anti-patterns to Avoid
+
+### Missing FK Index
+```sql
+-- ❌ BAD: FK without index → slow JOINs
+FOREIGN KEY (user_id) REFERENCES users(id)
+-- Forgot CREATE INDEX
+```
+
+### Over-indexing
+```sql
+-- ❌ BAD: Indexing each column separately
+CREATE INDEX idx_a ON orders(user_id);
+CREATE INDEX idx_b ON orders(status);
+CREATE INDEX idx_c ON orders(created_at);
+
+-- ✅ GOOD: Composite index based on query pattern
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+### Using TEXT instead of ENUM
+```sql
+-- ❌ BAD: Cannot validate values
+status TEXT
+
+-- ✅ GOOD: Use ENUM or CHECK
+status ENUM('pending', 'confirmed', 'shipped', 'cancelled')
+-- or
+status VARCHAR(32) CHECK (status IN ('pending', 'confirmed', 'shipped'))
+```
+
+### Missing Audit Columns
+```sql
+-- ❌ BAD
+CREATE TABLE products (id INT, name VARCHAR(255));
+
+-- ✅ GOOD
+CREATE TABLE products (
+    id INT,
+    name VARCHAR(255),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## Example DDL
+
+```sql
+CREATE TABLE orders (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    order_number VARCHAR(50) NOT NULL,
+    user_id BIGINT NOT NULL,
+    status VARCHAR(32) NOT NULL DEFAULT 'pending',
+    subtotal DECIMAL(18,2) NOT NULL DEFAULT 0,
+    discount_amount DECIMAL(18,2) NOT NULL DEFAULT 0,
+    total_amount DECIMAL(18,2) NOT NULL DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+    UNIQUE (order_number),
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
+);
+
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
+```
+
+---
+
+## Checklist
+
+- [ ] Audit columns: `created_at`, `updated_at`
+- [ ] All FKs have indexes
+- [ ] Unique constraints for business keys (`order_number`, `sku`, `email`)
+- [ ] ENUM or CHECK for status/type columns
+- [ ] Composite index based on main query patterns
+- [ ] Soft delete if needed: `deleted_at` + partial index