@ai-content-space/loopx 0.2.9 → 0.2.10

package/skills/sql-style/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: sql-style
+description: "Applies loopx SQL and database-change discipline for queries, schemas, indexes, migrations, dialects, and performance-sensitive data access. Not for replacing clarify, spec, implementation planning, code review, or workflow state transitions."
+when_to_use: "sql-style, SQL, database schema, migration, index, query optimization, EXPLAIN, PostgreSQL, MySQL, SQLite, 数据库, 索引"
+license: MIT
+metadata:
+  version: "0.2.10"
+  forked_from: https://github.com/Jeffallan/claude-skills/tree/main/skills/sql-pro
+  maintained_by: loopx
+---
+
+# SQL Style
+
+## Purpose
+
+`sql-style` is the shared loopx SQL/database support lens. It fuses useful upstream `sql-pro` guidance with loopx workflow discipline.
+
+Do not delete or flatten useful SQL/database guidance from other skills just because `sql-style` exists. Instead, make related skills call `sql-style` when SQL, database schema, migration, indexing, or query-performance discipline is relevant.
+
+Use it directly for SQL, schema, index, migration, and database performance work. Use it from `spec`, `exec`, `review`, or `final-review` when work touches persistent data or performance-sensitive data access.
+
+This skill does not replace `spec`. If data ownership, product semantics, migration compatibility, permission boundaries, or rollback decisions are unresolved, route those decisions through `clarify` or `spec`.
+
+## When To Use
+
+- Designing or reviewing database schemas
+- Writing or optimizing SQL queries
+- Adding or changing indexes
+- Writing migrations, backfills, or data cleanup
+- Reviewing ORM-generated SQL or repository data access
+- Investigating slow queries with `EXPLAIN` or query plans
+- Handling dialect-specific behavior in PostgreSQL, MySQL, SQLite, or SQL Server
+
+## Schema And Migration Discipline
+
+- Preserve existing schema conventions unless they are clearly broken.
+- Define primary keys, foreign keys, uniqueness, nullability, and defaults intentionally.
+- Treat nullability as product behavior, not a storage afterthought.
+- Include rollback or forward-fix strategy for migrations that can fail mid-flight.
+- Make repeated migration or backfill runs safe when the deployment process may retry.
+- For large tables, plan lock behavior, batching, indexes, and online migration constraints.
+- Keep application compatibility in mind during rolling deploys.
+- For MySQL tables in Kratos projects, preserve the existing loopx rule: `CREATE TABLE` statements should include table comments, and persisted columns should include column comments where the project convention requires them.
+
+## Query Discipline
+
+- Prefer set-based operations over row-by-row loops.
+- Avoid `SELECT *` in production queries unless the repository has an explicit reason.
+- Filter early and return only required columns.
+- Handle `NULL` explicitly in predicates, joins, ordering, and uniqueness assumptions.
+- Prefer `EXISTS` over `COUNT(*)` for existence checks when only existence matters.
+- Make ordering deterministic for paginated or user-visible results.
+- Use transactions deliberately. State the isolation assumptions when correctness depends on them.
+- Keep query intent readable with names, structure, or short comments for non-obvious logic.
+
+## Index Discipline
+
+- Add indexes for demonstrated access paths, constraints, or clearly required query patterns.
+- Consider column order, selectivity, covering behavior, and write amplification.
+- Avoid redundant indexes unless the dialect or workload justifies them.
+- Verify the intended query uses the index with the project's database tooling when practical.
+- Document why a non-obvious index exists.
+
+## Performance Verification
+
+- Use project-specific performance targets when they exist.
+- If no target exists, state the measured baseline and proposed improvement without inventing an SLO.
+- Analyze execution plans before claiming an optimization works.
+- Test against production-like data volume when data size can change the plan.
+- Record before/after evidence for meaningful optimizations.
+
+Example commands:
+
+```bash
+EXPLAIN ANALYZE <query>;
+go test ./...
+npm test
+pytest
+```
+
+## Dialect Discipline
+
+- Check dialect-specific behavior for upserts, JSON fields, generated columns, partial indexes, expression indexes, collations, time zones, and locking.
+- Do not assume PostgreSQL behavior applies to MySQL or SQLite.
+- Keep ORM abstractions honest by inspecting generated SQL when performance or correctness depends on it.
+
+## Reference Guide
+
+Load detailed guidance from the preserved upstream references when the task needs it:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Query Patterns | `references/query-patterns.md` | JOINs, CTEs, subqueries, recursive queries |
+| Window Functions | `references/window-functions.md` | ROW_NUMBER, RANK, LAG/LEAD, analytics |
+| Optimization | `references/optimization.md` | EXPLAIN plans, indexes, statistics, tuning |
+| Database Design | `references/database-design.md` | Normalization, keys, constraints, schemas |
+| Dialect Differences | `references/dialect-differences.md` | PostgreSQL, MySQL, SQLite, or SQL Server behavior |
+
+## Review Checklist
+
+- Are schema semantics explicit: keys, uniqueness, nullability, defaults?
+- Is migration order safe for rolling deploys and retries?
+- Could repeated runs corrupt data or duplicate work?
+- Do queries avoid unnecessary columns, rows, and row-by-row loops?
+- Are `NULL` and ordering semantics intentional?
+- Are indexes justified by access paths and verified when practical?
+- Are dialect-specific assumptions documented?
+- Is performance evidence fresh before any performance claim?

package/skills/sql-style/references/database-design.md

@@ -0,0 +1,402 @@
+# Database Design
+
+## Normalization Levels
+
+```sql
+-- 1NF: Atomic values, no repeating groups
+-- Bad: Non-atomic phone column
+CREATE TABLE customers_bad (
+    customer_id INT PRIMARY KEY,
+    name VARCHAR(100),
+    phones VARCHAR(500)  -- "555-1234,555-5678,555-9012"
+);
+
+-- Good: Atomic values
+CREATE TABLE customers (
+    customer_id SERIAL PRIMARY KEY,
+    name VARCHAR(100) NOT NULL
+);
+
+CREATE TABLE customer_phones (
+    phone_id SERIAL PRIMARY KEY,
+    customer_id INT NOT NULL REFERENCES customers(customer_id),
+    phone_number VARCHAR(20) NOT NULL,
+    phone_type VARCHAR(20) CHECK (phone_type IN ('mobile', 'home', 'work'))
+);
+
+-- 2NF: No partial dependencies (all non-key attributes depend on entire key)
+-- Bad: Partial dependency on composite key
+CREATE TABLE order_items_bad (
+    order_id INT,
+    product_id INT,
+    product_name VARCHAR(100),  -- Depends only on product_id
+    product_price DECIMAL(10,2),  -- Depends only on product_id
+    quantity INT,
+    PRIMARY KEY (order_id, product_id)
+);
+
+-- Good: Separate product attributes
+CREATE TABLE products (
+    product_id SERIAL PRIMARY KEY,
+    product_name VARCHAR(100) NOT NULL,
+    product_price DECIMAL(10,2) NOT NULL CHECK (product_price >= 0)
+);
+
+CREATE TABLE order_items (
+    order_id INT,
+    product_id INT,
+    quantity INT NOT NULL CHECK (quantity > 0),
+    unit_price DECIMAL(10,2) NOT NULL,  -- Snapshot at order time
+    PRIMARY KEY (order_id, product_id),
+    FOREIGN KEY (order_id) REFERENCES orders(order_id),
+    FOREIGN KEY (product_id) REFERENCES products(product_id)
+);
+
+-- 3NF: No transitive dependencies
+-- Bad: City/State depends on ZIP
+CREATE TABLE addresses_bad (
+    address_id INT PRIMARY KEY,
+    street VARCHAR(200),
+    city VARCHAR(100),
+    state VARCHAR(2),
+    zip_code VARCHAR(10)
+);
+
+-- Good: Separate ZIP code reference
+CREATE TABLE zip_codes (
+    zip_code VARCHAR(10) PRIMARY KEY,
+    city VARCHAR(100) NOT NULL,
+    state VARCHAR(2) NOT NULL,
+    county VARCHAR(100)
+);
+
+CREATE TABLE addresses (
+    address_id SERIAL PRIMARY KEY,
+    street VARCHAR(200) NOT NULL,
+    zip_code VARCHAR(10) NOT NULL REFERENCES zip_codes(zip_code)
+);
+```
+
+## Primary and Foreign Keys
+
+```sql
+-- Natural vs Surrogate keys
+-- Natural key (business meaning)
+CREATE TABLE countries (
+    country_code CHAR(2) PRIMARY KEY,  -- ISO 3166-1 alpha-2
+    country_name VARCHAR(100) NOT NULL
+);
+
+-- Surrogate key (technical, no business meaning)
+CREATE TABLE customers (
+    customer_id SERIAL PRIMARY KEY,  -- Auto-incrementing surrogate
+    email VARCHAR(255) NOT NULL UNIQUE,  -- Natural candidate key
+    name VARCHAR(100) NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Composite primary key
+CREATE TABLE student_courses (
+    student_id INT,
+    course_id INT,
+    enrollment_date DATE NOT NULL,
+    grade CHAR(2),
+    PRIMARY KEY (student_id, course_id),
+    FOREIGN KEY (student_id) REFERENCES students(student_id),
+    FOREIGN KEY (course_id) REFERENCES courses(course_id)
+);
+
+-- UUID primary keys (distributed systems, no sequence conflicts)
+CREATE TABLE events (
+    event_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    event_type VARCHAR(50) NOT NULL,
+    event_data JSONB,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Foreign key with cascading actions
+CREATE TABLE orders (
+    order_id SERIAL PRIMARY KEY,
+    customer_id INT NOT NULL,
+    order_date DATE DEFAULT CURRENT_DATE,
+    FOREIGN KEY (customer_id) REFERENCES customers(customer_id)
+        ON DELETE CASCADE  -- Delete orders when customer deleted
+        ON UPDATE CASCADE  -- Update order.customer_id when customers.customer_id changes
+);
+
+CREATE TABLE order_items (
+    order_item_id SERIAL PRIMARY KEY,
+    order_id INT NOT NULL,
+    product_id INT NOT NULL,
+    quantity INT NOT NULL,
+    FOREIGN KEY (order_id) REFERENCES orders(order_id)
+        ON DELETE CASCADE,  -- Delete items when order deleted
+    FOREIGN KEY (product_id) REFERENCES products(product_id)
+        ON DELETE RESTRICT  -- Prevent deleting product if used in orders
+);
+```
+
+## Constraints and Validation
+
+```sql
+-- CHECK constraints
+CREATE TABLE employees (
+    employee_id SERIAL PRIMARY KEY,
+    first_name VARCHAR(50) NOT NULL,
+    last_name VARCHAR(50) NOT NULL,
+    email VARCHAR(255) NOT NULL UNIQUE,
+    salary DECIMAL(12,2) NOT NULL,
+    hire_date DATE NOT NULL,
+    birth_date DATE NOT NULL,
+
+    CONSTRAINT chk_salary_positive CHECK (salary > 0),
+    CONSTRAINT chk_email_format CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}$'),
+    CONSTRAINT chk_hire_after_birth CHECK (hire_date > birth_date + INTERVAL '16 years'),
+    CONSTRAINT chk_hire_not_future CHECK (hire_date <= CURRENT_DATE)
+);
+
+-- Unique constraints (including composite)
+CREATE TABLE user_preferences (
+    user_id INT NOT NULL,
+    preference_key VARCHAR(50) NOT NULL,
+    preference_value TEXT,
+
+    CONSTRAINT uq_user_preference UNIQUE (user_id, preference_key)
+);
+
+-- NOT NULL constraints with defaults
+CREATE TABLE products (
+    product_id SERIAL PRIMARY KEY,
+    name VARCHAR(200) NOT NULL,
+    description TEXT,
+    price DECIMAL(10,2) NOT NULL DEFAULT 0.00,
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Exclusion constraints (PostgreSQL - prevent overlapping ranges)
+CREATE TABLE room_bookings (
+    booking_id SERIAL PRIMARY KEY,
+    room_id INT NOT NULL,
+    booked_during TSTZRANGE NOT NULL,
+
+    EXCLUDE USING GIST (
+        room_id WITH =,
+        booked_during WITH &&
+    )  -- Prevent overlapping bookings for same room
+);
+```
+
+## Indexing Strategy
+
+```sql
+-- Index foreign keys when joins, deletes, cascades, or referential checks make the access path important
+CREATE INDEX idx_orders_customer_id ON orders(customer_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);
+
+-- Composite index for common queries
+CREATE INDEX idx_orders_customer_date ON orders(customer_id, order_date DESC);
+-- Supports:
+-- WHERE customer_id = ? AND order_date > ?
+-- WHERE customer_id = ? ORDER BY order_date DESC
+
+-- Partial index for common filters
+CREATE INDEX idx_active_products ON products(category, price)
+WHERE is_active = true AND deleted_at IS NULL;
+
+-- Unique index for business rules
+CREATE UNIQUE INDEX idx_users_active_email ON users(LOWER(email))
+WHERE deleted_at IS NULL;
+-- Ensures no duplicate emails among active users
+```
+
+## Common Design Patterns
+
+```sql
+-- Polymorphic associations (flexible but harder to enforce integrity)
+CREATE TABLE comments (
+    comment_id SERIAL PRIMARY KEY,
+    commentable_type VARCHAR(50) NOT NULL,  -- 'Post', 'Photo', 'Video'
+    commentable_id INT NOT NULL,
+    content TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    -- Cannot enforce FK without triggers/application logic
+    CHECK (commentable_type IN ('Post', 'Photo', 'Video'))
+);
+
+-- Better: Separate tables with proper FKs
+CREATE TABLE post_comments (
+    comment_id SERIAL PRIMARY KEY,
+    post_id INT NOT NULL REFERENCES posts(post_id),
+    content TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE photo_comments (
+    comment_id SERIAL PRIMARY KEY,
+    photo_id INT NOT NULL REFERENCES photos(photo_id),
+    content TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Many-to-many with attributes (junction/bridge table)
+CREATE TABLE students (
+    student_id SERIAL PRIMARY KEY,
+    name VARCHAR(100) NOT NULL
+);
+
+CREATE TABLE courses (
+    course_id SERIAL PRIMARY KEY,
+    course_name VARCHAR(100) NOT NULL
+);
+
+CREATE TABLE enrollments (
+    enrollment_id SERIAL PRIMARY KEY,
+    student_id INT NOT NULL REFERENCES students(student_id),
+    course_id INT NOT NULL REFERENCES courses(course_id),
+    enrollment_date DATE NOT NULL DEFAULT CURRENT_DATE,
+    grade CHAR(2),
+    status VARCHAR(20) DEFAULT 'active',
+
+    UNIQUE (student_id, course_id),
+    CHECK (status IN ('active', 'completed', 'dropped'))
+);
+
+-- Self-referencing hierarchy
+CREATE TABLE categories (
+    category_id SERIAL PRIMARY KEY,
+    category_name VARCHAR(100) NOT NULL,
+    parent_category_id INT REFERENCES categories(category_id),
+    level INT NOT NULL DEFAULT 0,
+
+    CHECK (category_id != parent_category_id)  -- Prevent self-reference
+);
+
+-- Adjacency list example
+INSERT INTO categories VALUES
+    (1, 'Electronics', NULL, 0),
+    (2, 'Computers', 1, 1),
+    (3, 'Laptops', 2, 2),
+    (4, 'Desktops', 2, 2);
+```
+
+## Temporal/Historical Data
+
+```sql
+-- Slowly Changing Dimension Type 2 (SCD2) - Full history
+CREATE TABLE customer_history (
+    customer_history_id SERIAL PRIMARY KEY,
+    customer_id INT NOT NULL,
+    name VARCHAR(100) NOT NULL,
+    email VARCHAR(255) NOT NULL,
+    address TEXT,
+    valid_from TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    valid_to TIMESTAMP,
+    is_current BOOLEAN NOT NULL DEFAULT true,
+
+    CHECK (valid_to IS NULL OR valid_to > valid_from)
+);
+
+-- Ensure only one current record per customer
+CREATE UNIQUE INDEX idx_customer_current ON customer_history(customer_id)
+WHERE is_current = true;
+
+-- Temporal tables (PostgreSQL system-versioning)
+CREATE TABLE products (
+    product_id SERIAL PRIMARY KEY,
+    name VARCHAR(200) NOT NULL,
+    price DECIMAL(10,2) NOT NULL,
+    sys_period TSTZRANGE NOT NULL DEFAULT tstzrange(CURRENT_TIMESTAMP, NULL)
+);
+
+CREATE TABLE products_history (LIKE products);
+
+CREATE TRIGGER versioning_trigger
+BEFORE INSERT OR UPDATE OR DELETE ON products
+FOR EACH ROW EXECUTE FUNCTION versioning('sys_period', 'products_history', true);
+```
+
+## Soft Deletes
+
+```sql
+-- Soft delete pattern
+CREATE TABLE posts (
+    post_id SERIAL PRIMARY KEY,
+    title VARCHAR(255) NOT NULL,
+    content TEXT NOT NULL,
+    author_id INT NOT NULL REFERENCES users(user_id),
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    deleted_at TIMESTAMP,  -- NULL = active, non-NULL = deleted
+    deleted_by INT REFERENCES users(user_id)
+);
+
+-- Index for filtering active records
+CREATE INDEX idx_posts_active ON posts(created_at DESC)
+WHERE deleted_at IS NULL;
+
+-- View for active posts only
+CREATE VIEW active_posts AS
+SELECT post_id, title, content, author_id, created_at, updated_at
+FROM posts
+WHERE deleted_at IS NULL;
+```
+
+## Audit Trails
+
+```sql
+-- Audit table pattern
+CREATE TABLE audit_log (
+    audit_id BIGSERIAL PRIMARY KEY,
+    table_name VARCHAR(100) NOT NULL,
+    record_id BIGINT NOT NULL,
+    action VARCHAR(10) NOT NULL CHECK (action IN ('INSERT', 'UPDATE', 'DELETE')),
+    old_values JSONB,
+    new_values JSONB,
+    changed_by INT REFERENCES users(user_id),
+    changed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_audit_table_record ON audit_log(table_name, record_id);
+CREATE INDEX idx_audit_timestamp ON audit_log(changed_at DESC);
+
+-- Trigger function for automatic auditing
+CREATE OR REPLACE FUNCTION audit_trigger_func()
+RETURNS TRIGGER AS $$
+BEGIN
+    IF (TG_OP = 'DELETE') THEN
+        INSERT INTO audit_log (table_name, record_id, action, old_values)
+        VALUES (TG_TABLE_NAME, OLD.product_id, 'DELETE', row_to_json(OLD));
+        RETURN OLD;
+    ELSIF (TG_OP = 'UPDATE') THEN
+        INSERT INTO audit_log (table_name, record_id, action, old_values, new_values)
+        VALUES (TG_TABLE_NAME, NEW.product_id, 'UPDATE', row_to_json(OLD), row_to_json(NEW));
+        RETURN NEW;
+    ELSIF (TG_OP = 'INSERT') THEN
+        INSERT INTO audit_log (table_name, record_id, action, new_values)
+        VALUES (TG_TABLE_NAME, NEW.product_id, 'INSERT', row_to_json(NEW));
+        RETURN NEW;
+    END IF;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER products_audit
+AFTER INSERT OR UPDATE OR DELETE ON products
+FOR EACH ROW EXECUTE FUNCTION audit_trigger_func();
+```
+
+## Schema Design Best Practices
+
+1. **Choose appropriate data types**: Use smallest type that fits (INT vs BIGINT, VARCHAR(50) vs TEXT)
+2. **Index foreign keys deliberately**: Add FK indexes for demonstrated joins, deletes, cascades, or referential checks; verify write overhead and plan usage
+3. **Avoid NULLs when possible**: Use NOT NULL with defaults
+4. **Use constraints**: Enforce data integrity at database level
+5. **Normalize to 3NF**: Then denormalize strategically for performance
+6. **Consider soft deletes**: For auditing and data recovery
+7. **Plan for growth**: Use BIGINT for high-volume PKs
+8. **Document schema**: Comment tables and complex constraints
+9. **Version control**: Track schema changes with migrations
+10. **Test with realistic data**: Validate design with production-scale data