@zimezone/z-command 1.1.1 → 1.1.2

package/templates/skills/pci-compliance/SKILL.md

@@ -1,466 +0,0 @@
----
-name: pci-compliance
-description: Implement PCI DSS compliance requirements for secure handling of payment card data and payment systems. Use when securing payment processing, achieving PCI compliance, or implementing payment card security measures.
----
-
-# PCI Compliance
-
-Master PCI DSS (Payment Card Industry Data Security Standard) compliance for secure payment processing and handling of cardholder data.
-
-## When to Use This Skill
-
-- Building payment processing systems
-- Handling credit card information
-- Implementing secure payment flows
-- Conducting PCI compliance audits
-- Reducing PCI compliance scope
-- Implementing tokenization and encryption
-- Preparing for PCI DSS assessments
-
-## PCI DSS Requirements (12 Core Requirements)
-
-### Build and Maintain Secure Network
-1. Install and maintain firewall configuration
-2. Don't use vendor-supplied defaults for passwords
-
-### Protect Cardholder Data
-3. Protect stored cardholder data
-4. Encrypt transmission of cardholder data across public networks
-
-### Maintain Vulnerability Management
-5. Protect systems against malware
-6. Develop and maintain secure systems and applications
-
-### Implement Strong Access Control
-7. Restrict access to cardholder data by business need-to-know
-8. Identify and authenticate access to system components
-9. Restrict physical access to cardholder data
-
-### Monitor and Test Networks
-10. Track and monitor all access to network resources and cardholder data
-11. Regularly test security systems and processes
-
-### Maintain Information Security Policy
-12. Maintain a policy that addresses information security
-
-## Compliance Levels
-
-**Level 1**: > 6 million transactions/year (annual ROC required)
-**Level 2**: 1-6 million transactions/year (annual SAQ)
-**Level 3**: 20,000-1 million e-commerce transactions/year
-**Level 4**: < 20,000 e-commerce or < 1 million total transactions
-
-## Data Minimization (Never Store)
-
-```python
-# NEVER STORE THESE
-PROHIBITED_DATA = {
-    'full_track_data': 'Magnetic stripe data',
-    'cvv': 'Card verification code/value',
-    'pin': 'PIN or PIN block'
-}
-
-# CAN STORE (if encrypted)
-ALLOWED_DATA = {
-    'pan': 'Primary Account Number (card number)',
-    'cardholder_name': 'Name on card',
-    'expiration_date': 'Card expiration',
-    'service_code': 'Service code'
-}
-
-class PaymentData:
-    """Safe payment data handling."""
-
-    def __init__(self):
-        self.prohibited_fields = ['cvv', 'cvv2', 'cvc', 'pin']
-
-    def sanitize_log(self, data):
-        """Remove sensitive data from logs."""
-        sanitized = data.copy()
-
-        # Mask PAN
-        if 'card_number' in sanitized:
-            card = sanitized['card_number']
-            sanitized['card_number'] = f"{card[:6]}{'*' * (len(card) - 10)}{card[-4:]}"
-
-        # Remove prohibited data
-        for field in self.prohibited_fields:
-            sanitized.pop(field, None)
-
-        return sanitized
-
-    def validate_no_prohibited_storage(self, data):
-        """Ensure no prohibited data is being stored."""
-        for field in self.prohibited_fields:
-            if field in data:
-                raise SecurityError(f"Attempting to store prohibited field: {field}")
-```
-
-## Tokenization
-
-### Using Payment Processor Tokens
-```python
-import stripe
-
-class TokenizedPayment:
-    """Handle payments using tokens (no card data on server)."""
-
-    @staticmethod
-    def create_payment_method_token(card_details):
-        """Create token from card details (client-side only)."""
-        # THIS SHOULD ONLY BE DONE CLIENT-SIDE WITH STRIPE.JS
-        # NEVER send card details to your server
-
-        """
-        // Frontend JavaScript
-        const stripe = Stripe('pk_...');
-
-        const {token, error} = await stripe.createToken({
-            card: {
-                number: '4242424242424242',
-                exp_month: 12,
-                exp_year: 2024,
-                cvc: '123'
-            }
-        });
-
-        // Send token.id to server (NOT card details)
-        """
-        pass
-
-    @staticmethod
-    def charge_with_token(token_id, amount):
-        """Charge using token (server-side)."""
-        # Your server only sees the token, never the card number
-        stripe.api_key = "sk_..."
-
-        charge = stripe.Charge.create(
-            amount=amount,
-            currency="usd",
-            source=token_id,  # Token instead of card details
-            description="Payment"
-        )
-
-        return charge
-
-    @staticmethod
-    def store_payment_method(customer_id, payment_method_token):
-        """Store payment method as token for future use."""
-        stripe.Customer.modify(
-            customer_id,
-            source=payment_method_token
-        )
-
-        # Store only customer_id and payment_method_id in your database
-        # NEVER store actual card details
-        return {
-            'customer_id': customer_id,
-            'has_payment_method': True
-            # DO NOT store: card number, CVV, etc.
-        }
-```
-
-### Custom Tokenization (Advanced)
-```python
-import secrets
-from cryptography.fernet import Fernet
-
-class TokenVault:
-    """Secure token vault for card data (if you must store it)."""
-
-    def __init__(self, encryption_key):
-        self.cipher = Fernet(encryption_key)
-        self.vault = {}  # In production: use encrypted database
-
-    def tokenize(self, card_data):
-        """Convert card data to token."""
-        # Generate secure random token
-        token = secrets.token_urlsafe(32)
-
-        # Encrypt card data
-        encrypted = self.cipher.encrypt(json.dumps(card_data).encode())
-
-        # Store token -> encrypted data mapping
-        self.vault[token] = encrypted
-
-        return token
-
-    def detokenize(self, token):
-        """Retrieve card data from token."""
-        encrypted = self.vault.get(token)
-        if not encrypted:
-            raise ValueError("Token not found")
-
-        # Decrypt
-        decrypted = self.cipher.decrypt(encrypted)
-        return json.loads(decrypted.decode())
-
-    def delete_token(self, token):
-        """Remove token from vault."""
-        self.vault.pop(token, None)
-```
-
-## Encryption
-
-### Data at Rest
-```python
-from cryptography.hazmat.primitives.ciphers.aead import AESGCM
-import os
-
-class EncryptedStorage:
-    """Encrypt data at rest using AES-256-GCM."""
-
-    def __init__(self, encryption_key):
-        """Initialize with 256-bit key."""
-        self.key = encryption_key  # Must be 32 bytes
-
-    def encrypt(self, plaintext):
-        """Encrypt data."""
-        # Generate random nonce
-        nonce = os.urandom(12)
-
-        # Encrypt
-        aesgcm = AESGCM(self.key)
-        ciphertext = aesgcm.encrypt(nonce, plaintext.encode(), None)
-
-        # Return nonce + ciphertext
-        return nonce + ciphertext
-
-    def decrypt(self, encrypted_data):
-        """Decrypt data."""
-        # Extract nonce and ciphertext
-        nonce = encrypted_data[:12]
-        ciphertext = encrypted_data[12:]
-
-        # Decrypt
-        aesgcm = AESGCM(self.key)
-        plaintext = aesgcm.decrypt(nonce, ciphertext, None)
-
-        return plaintext.decode()
-
-# Usage
-storage = EncryptedStorage(os.urandom(32))
-encrypted_pan = storage.encrypt("4242424242424242")
-# Store encrypted_pan in database
-```
-
-### Data in Transit
-```python
-# Always use TLS 1.2 or higher
-# Flask/Django example
-app.config['SESSION_COOKIE_SECURE'] = True  # HTTPS only
-app.config['SESSION_COOKIE_HTTPONLY'] = True
-app.config['SESSION_COOKIE_SAMESITE'] = 'Strict'
-
-# Enforce HTTPS
-from flask_talisman import Talisman
-Talisman(app, force_https=True)
-```
-
-## Access Control
-
-```python
-from functools import wraps
-from flask import session
-
-def require_pci_access(f):
-    """Decorator to restrict access to cardholder data."""
-    @wraps(f)
-    def decorated_function(*args, **kwargs):
-        user = session.get('user')
-
-        # Check if user has PCI access role
-        if not user or 'pci_access' not in user.get('roles', []):
-            return {'error': 'Unauthorized access to cardholder data'}, 403
-
-        # Log access attempt
-        audit_log(
-            user=user['id'],
-            action='access_cardholder_data',
-            resource=f.__name__
-        )
-
-        return f(*args, **kwargs)
-
-    return decorated_function
-
-@app.route('/api/payment-methods')
-@require_pci_access
-def get_payment_methods():
-    """Retrieve payment methods (restricted access)."""
-    # Only accessible to users with pci_access role
-    pass
-```
-
-## Audit Logging
-
-```python
-import logging
-from datetime import datetime
-
-class PCIAuditLogger:
-    """PCI-compliant audit logging."""
-
-    def __init__(self):
-        self.logger = logging.getLogger('pci_audit')
-        # Configure to write to secure, append-only log
-
-    def log_access(self, user_id, resource, action, result):
-        """Log access to cardholder data."""
-        entry = {
-            'timestamp': datetime.utcnow().isoformat(),
-            'user_id': user_id,
-            'resource': resource,
-            'action': action,
-            'result': result,
-            'ip_address': request.remote_addr
-        }
-
-        self.logger.info(json.dumps(entry))
-
-    def log_authentication(self, user_id, success, method):
-        """Log authentication attempt."""
-        entry = {
-            'timestamp': datetime.utcnow().isoformat(),
-            'user_id': user_id,
-            'event': 'authentication',
-            'success': success,
-            'method': method,
-            'ip_address': request.remote_addr
-        }
-
-        self.logger.info(json.dumps(entry))
-
-# Usage
-audit = PCIAuditLogger()
-audit.log_access(user_id=123, resource='payment_methods', action='read', result='success')
-```
-
-## Security Best Practices
-
-### Input Validation
-```python
-import re
-
-def validate_card_number(card_number):
-    """Validate card number format (Luhn algorithm)."""
-    # Remove spaces and dashes
-    card_number = re.sub(r'[\s-]', '', card_number)
-
-    # Check if all digits
-    if not card_number.isdigit():
-        return False
-
-    # Luhn algorithm
-    def luhn_checksum(card_num):
-        def digits_of(n):
-            return [int(d) for d in str(n)]
-
-        digits = digits_of(card_num)
-        odd_digits = digits[-1::-2]
-        even_digits = digits[-2::-2]
-        checksum = sum(odd_digits)
-        for d in even_digits:
-            checksum += sum(digits_of(d * 2))
-        return checksum % 10
-
-    return luhn_checksum(card_number) == 0
-
-def sanitize_input(user_input):
-    """Sanitize user input to prevent injection."""
-    # Remove special characters
-    # Validate against expected format
-    # Escape for database queries
-    pass
-```
-
-## PCI DSS SAQ (Self-Assessment Questionnaire)
-
-### SAQ A (Least Requirements)
-- E-commerce using hosted payment page
-- No card data on your systems
-- ~20 questions
-
-### SAQ A-EP
-- E-commerce with embedded payment form
-- Uses JavaScript to handle card data
-- ~180 questions
-
-### SAQ D (Most Requirements)
-- Store, process, or transmit card data
-- Full PCI DSS requirements
-- ~300 questions
-
-## Compliance Checklist
-
-```python
-PCI_COMPLIANCE_CHECKLIST = {
-    'network_security': [
-        'Firewall configured and maintained',
-        'No vendor default passwords',
-        'Network segmentation implemented'
-    ],
-    'data_protection': [
-        'No storage of CVV, track data, or PIN',
-        'PAN encrypted when stored',
-        'PAN masked when displayed',
-        'Encryption keys properly managed'
-    ],
-    'vulnerability_management': [
-        'Anti-virus installed and updated',
-        'Secure development practices',
-        'Regular security patches',
-        'Vulnerability scanning performed'
-    ],
-    'access_control': [
-        'Access restricted by role',
-        'Unique IDs for all users',
-        'Multi-factor authentication',
-        'Physical security measures'
-    ],
-    'monitoring': [
-        'Audit logs enabled',
-        'Log review process',
-        'File integrity monitoring',
-        'Regular security testing'
-    ],
-    'policy': [
-        'Security policy documented',
-        'Risk assessment performed',
-        'Security awareness training',
-        'Incident response plan'
-    ]
-}
-```
-
-## Resources
-
-- **references/data-minimization.md**: Never store prohibited data
-- **references/tokenization.md**: Tokenization strategies
-- **references/encryption.md**: Encryption requirements
-- **references/access-control.md**: Role-based access
-- **references/audit-logging.md**: Comprehensive logging
-- **assets/pci-compliance-checklist.md**: Complete checklist
-- **assets/encrypted-storage.py**: Encryption utilities
-- **scripts/audit-payment-system.sh**: Compliance audit script
-
-## Common Violations
-
-1. **Storing CVV**: Never store card verification codes
-2. **Unencrypted PAN**: Card numbers must be encrypted at rest
-3. **Weak Encryption**: Use AES-256 or equivalent
-4. **No Access Controls**: Restrict who can access cardholder data
-5. **Missing Audit Logs**: Must log all access to payment data
-6. **Insecure Transmission**: Always use TLS 1.2+
-7. **Default Passwords**: Change all default credentials
-8. **No Security Testing**: Regular penetration testing required
-
-## Reducing PCI Scope
-
-1. **Use Hosted Payments**: Stripe Checkout, PayPal, etc.
-2. **Tokenization**: Replace card data with tokens
-3. **Network Segmentation**: Isolate cardholder data environment
-4. **Outsource**: Use PCI-compliant payment processors
-5. **No Storage**: Never store full card details
-
-By minimizing systems that touch card data, you reduce compliance burden significantly.

package/templates/skills/postgresql/SKILL.md

@@ -1,204 +0,0 @@
----
-name: postgresql-table-design
-description: Design a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features
----
-
-# PostgreSQL Table Design 
-
-## Core Rules
-
-- Define a **PRIMARY KEY** for reference tables (users, orders, etc.). Not always needed for time-series/event/log data. When used, prefer `BIGINT GENERATED ALWAYS AS IDENTITY`; use `UUID` only when global uniqueness/opacity is needed.
-- **Normalize first (to 3NF)** to eliminate data redundancy and update anomalies; denormalize **only** for measured, high-ROI reads where join performance is proven problematic. Premature denormalization creates maintenance burden.
-- Add **NOT NULL** everywhere it’s semantically required; use **DEFAULT**s for common values.
-- Create **indexes for access paths you actually query**: PK/unique (auto), **FK columns (manual!)**, frequent filters/sorts, and join keys.
-- Prefer **TIMESTAMPTZ** for event time; **NUMERIC** for money; **TEXT** for strings; **BIGINT** for integer values, **DOUBLE PRECISION** for floats (or `NUMERIC` for exact decimal arithmetic).
-
-## PostgreSQL “Gotchas”
-
-- **Identifiers**: unquoted → lowercased. Avoid quoted/mixed-case names. Convention: use `snake_case` for table/column names.
-- **Unique + NULLs**: UNIQUE allows multiple NULLs. Use `UNIQUE (...) NULLS NOT DISTINCT` (PG15+) to restrict to one NULL.
-- **FK indexes**: PostgreSQL **does not** auto-index FK columns. Add them.
-- **No silent coercions**: length/precision overflows error out (no truncation). Example: inserting 999 into `NUMERIC(2,0)` fails with error, unlike some databases that silently truncate or round.
-- **Sequences/identity have gaps** (normal; don't "fix"). Rollbacks, crashes, and concurrent transactions create gaps in ID sequences (1, 2, 5, 6...). This is expected behavior—don't try to make IDs consecutive.
-- **Heap storage**: no clustered PK by default (unlike SQL Server/MySQL InnoDB); `CLUSTER` is one-off reorganization, not maintained on subsequent inserts. Row order on disk is insertion order unless explicitly clustered.
-- **MVCC**: updates/deletes leave dead tuples; vacuum handles them—design to avoid hot wide-row churn.
-
-## Data Types
-
-- **IDs**: `BIGINT GENERATED ALWAYS AS IDENTITY` preferred (`GENERATED BY DEFAULT` also fine); `UUID` when merging/federating/used in a distributed system or for opaque IDs. Generate with `uuidv7()` (preferred if using PG18+) or `gen_random_uuid()` (if using an older PG version).
-- **Integers**: prefer `BIGINT` unless storage space is critical; `INTEGER` for smaller ranges; avoid `SMALLINT` unless constrained.
-- **Floats**: prefer `DOUBLE PRECISION` over `REAL` unless storage space is critical. Use `NUMERIC` for exact decimal arithmetic.
-- **Strings**: prefer `TEXT`; if length limits needed, use `CHECK (LENGTH(col) <= n)` instead of `VARCHAR(n)`; avoid `CHAR(n)`. Use `BYTEA` for binary data. Large strings/binary (>2KB default threshold) automatically stored in TOAST with compression. TOAST storage: `PLAIN` (no TOAST), `EXTENDED` (compress + out-of-line), `EXTERNAL` (out-of-line, no compress), `MAIN` (compress, keep in-line if possible). Default `EXTENDED` usually optimal. Control with `ALTER TABLE tbl ALTER COLUMN col SET STORAGE strategy` and `ALTER TABLE tbl SET (toast_tuple_target = 4096)` for threshold. Case-insensitive: for locale/accent handling use non-deterministic collations; for plain ASCII use expression indexes on `LOWER(col)` (preferred unless column needs case-insensitive PK/FK/UNIQUE) or `CITEXT`.
-- **Money**: `NUMERIC(p,s)` (never float).
-- **Time**: `TIMESTAMPTZ` for timestamps; `DATE` for date-only; `INTERVAL` for durations. Avoid `TIMESTAMP` (without timezone). Use `now()` for transaction start time, `clock_timestamp()` for current wall-clock time.
-- **Booleans**: `BOOLEAN` with `NOT NULL` constraint unless tri-state values are required.
-- **Enums**: `CREATE TYPE ... AS ENUM` for small, stable sets (e.g. US states, days of week). For business-logic-driven and evolving values (e.g. order statuses) → use TEXT (or INT) + CHECK or lookup table.
-- **Arrays**: `TEXT[]`, `INTEGER[]`, etc. Use for ordered lists where you query elements. Index with **GIN** for containment (`@>`, `<@`) and overlap (`&&`) queries. Access: `arr[1]` (1-indexed), `arr[1:3]` (slicing). Good for tags, categories; avoid for relations—use junction tables instead. Literal syntax: `'{val1,val2}'` or `ARRAY[val1,val2]`.
-- **Range types**: `daterange`, `numrange`, `tstzrange` for intervals. Support overlap (`&&`), containment (`@>`), operators. Index with **GiST**. Good for scheduling, versioning, numeric ranges. Pick a bounds scheme and use it consistently; prefer `[)` (inclusive/exclusive) by default.
-- **Network types**: `INET` for IP addresses, `CIDR` for network ranges, `MACADDR` for MAC addresses. Support network operators (`<<`, `>>`, `&&`).
-- **Geometric types**: `POINT`, `LINE`, `POLYGON`, `CIRCLE` for 2D spatial data. Index with **GiST**. Consider **PostGIS** for advanced spatial features.
-- **Text search**: `TSVECTOR` for full-text search documents, `TSQUERY` for search queries. Index `tsvector` with **GIN**. Always specify language: `to_tsvector('english', col)` and `to_tsquery('english', 'query')`. Never use single-argument versions. This applies to both index expressions and queries.
-- **Domain types**: `CREATE DOMAIN email AS TEXT CHECK (VALUE ~ '^[^@]+@[^@]+$')` for reusable custom types with validation. Enforces constraints across tables.
-- **Composite types**: `CREATE TYPE address AS (street TEXT, city TEXT, zip TEXT)` for structured data within columns. Access with `(col).field` syntax.
-- **JSONB**: preferred over JSON; index with **GIN**. Use only for optional/semi-structured attrs. ONLY use JSON if the original ordering of the contents MUST be preserved.
-- **Vector types**: `vector` type by `pgvector` for vector similarity search for embeddings.
-
-
-### Do not use the following data types
-- DO NOT use `timestamp` (without time zone); DO use `timestamptz` instead.
-- DO NOT use `char(n)` or `varchar(n)`; DO use `text` instead.
-- DO NOT use `money` type; DO use `numeric` instead.
-- DO NOT use `timetz` type; DO use `timestamptz` instead.
-- DO NOT use `timestamptz(0)` or any other precision specification; DO use `timestamptz` instead
-- DO NOT use `serial` type; DO use `generated always as identity` instead.
-
-
-## Table Types
-
-- **Regular**: default; fully durable, logged.
-- **TEMPORARY**: session-scoped, auto-dropped, not logged. Faster for scratch work.
-- **UNLOGGED**: persistent but not crash-safe. Faster writes; good for caches/staging.
-
-## Row-Level Security
-
-Enable with `ALTER TABLE tbl ENABLE ROW LEVEL SECURITY`. Create policies: `CREATE POLICY user_access ON orders FOR SELECT TO app_users USING (user_id = current_user_id())`. Built-in user-based access control at the row level.
-
-## Constraints
-
-- **PK**: implicit UNIQUE + NOT NULL; creates a B-tree index.
-- **FK**: specify `ON DELETE/UPDATE` action (`CASCADE`, `RESTRICT`, `SET NULL`, `SET DEFAULT`). Add explicit index on referencing column—speeds up joins and prevents locking issues on parent deletes/updates. Use `DEFERRABLE INITIALLY DEFERRED` for circular FK dependencies checked at transaction end.
-- **UNIQUE**: creates a B-tree index; allows multiple NULLs unless `NULLS NOT DISTINCT` (PG15+). Standard behavior: `(1, NULL)` and `(1, NULL)` are allowed. With `NULLS NOT DISTINCT`: only one `(1, NULL)` allowed. Prefer `NULLS NOT DISTINCT` unless you specifically need duplicate NULLs.
-- **CHECK**: row-local constraints; NULL values pass the check (three-valued logic). Example: `CHECK (price > 0)` allows NULL prices. Combine with `NOT NULL` to enforce: `price NUMERIC NOT NULL CHECK (price > 0)`.
-- **EXCLUDE**: prevents overlapping values using operators. `EXCLUDE USING gist (room_id WITH =, booking_period WITH &&)` prevents double-booking rooms. Requires appropriate index type (often GiST).
-
-## Indexing
-
-- **B-tree**: default for equality/range queries (`=`, `<`, `>`, `BETWEEN`, `ORDER BY`)
-- **Composite**: order matters—index used if equality on leftmost prefix (`WHERE a = ? AND b > ?` uses index on `(a,b)`, but `WHERE b = ?` does not). Put most selective/frequently filtered columns first.
-- **Covering**: `CREATE INDEX ON tbl (id) INCLUDE (name, email)` - includes non-key columns for index-only scans without visiting table.
-- **Partial**: for hot subsets (`WHERE status = 'active'` → `CREATE INDEX ON tbl (user_id) WHERE status = 'active'`). Any query with `status = 'active'` can use this index.
-- **Expression**: for computed search keys (`CREATE INDEX ON tbl (LOWER(email))`). Expression must match exactly in WHERE clause: `WHERE LOWER(email) = 'user@example.com'`.
-- **GIN**: JSONB containment/existence, arrays (`@>`, `?`), full-text search (`@@`)
-- **GiST**: ranges, geometry, exclusion constraints
-- **BRIN**: very large, naturally ordered data (time-series)—minimal storage overhead. Effective when row order on disk correlates with indexed column (insertion order or after `CLUSTER`).
-
-## Partitioning
-
-- Use for very large tables (>100M rows) where queries consistently filter on partition key (often time/date).
-- Alternate use: use for tables where data maintenance tasks dictates e.g. data pruned or bulk replaced periodically
-- **RANGE**: common for time-series (`PARTITION BY RANGE (created_at)`). Create partitions: `CREATE TABLE logs_2024_01 PARTITION OF logs FOR VALUES FROM ('2024-01-01') TO ('2024-02-01')`. **TimescaleDB** automates time-based or ID-based partitioning with retention policies and compression.
-- **LIST**: for discrete values (`PARTITION BY LIST (region)`). Example: `FOR VALUES IN ('us-east', 'us-west')`.
-- **HASH**: for even distribution when no natural key (`PARTITION BY HASH (user_id)`). Creates N partitions with modulus.
-- **Constraint exclusion**: requires `CHECK` constraints on partitions for query planner to prune. Auto-created for declarative partitioning (PG10+).
-- Prefer declarative partitioning or hypertables. Do NOT use table inheritance.
-- **Limitations**: no global UNIQUE constraints—include partition key in PK/UNIQUE. FKs from partitioned tables not supported; use triggers.
-
-## Special Considerations
-
-### Update-Heavy Tables
-
-- **Separate hot/cold columns**—put frequently updated columns in separate table to minimize bloat.
-- **Use `fillfactor=90`** to leave space for HOT updates that avoid index maintenance.
-- **Avoid updating indexed columns**—prevents beneficial HOT updates.
-- **Partition by update patterns**—separate frequently updated rows in a different partition from stable data.
-
-### Insert-Heavy Workloads
-
-- **Minimize indexes**—only create what you query; every index slows inserts.
-- **Use `COPY` or multi-row `INSERT`** instead of single-row inserts.
-- **UNLOGGED tables** for rebuildable staging data—much faster writes.
-- **Defer index creation** for bulk loads—>drop index, load data, recreate indexes.
-- **Partition by time/hash** to distribute load. **TimescaleDB** automates partitioning and compression of insert-heavy data.
-- **Use a natural key for primary key** such as a (timestamp, device_id) if enforcing global uniqueness is important many insert-heavy tables don't need a primary key at all.
-- If you do need a surrogate key, **Prefer `BIGINT GENERATED ALWAYS AS IDENTITY` over `UUID`**.
-
-### Upsert-Friendly Design
-
-- **Requires UNIQUE index** on conflict target columns—`ON CONFLICT (col1, col2)` needs exact matching unique index (partial indexes don't work).
-- **Use `EXCLUDED.column`** to reference would-be-inserted values; only update columns that actually changed to reduce write overhead.
-- **`DO NOTHING` faster** than `DO UPDATE` when no actual update needed.
-
-### Safe Schema Evolution
-
-- **Transactional DDL**: most DDL operations can run in transactions and be rolled back—`BEGIN; ALTER TABLE...; ROLLBACK;` for safe testing.
-- **Concurrent index creation**: `CREATE INDEX CONCURRENTLY` avoids blocking writes but can't run in transactions.
-- **Volatile defaults cause rewrites**: adding `NOT NULL` columns with volatile defaults (e.g., `now()`, `gen_random_uuid()`) rewrites entire table. Non-volatile defaults are fast.
-- **Drop constraints before columns**: `ALTER TABLE DROP CONSTRAINT` then `DROP COLUMN` to avoid dependency issues.
-- **Function signature changes**: `CREATE OR REPLACE` with different arguments creates overloads, not replacements. DROP old version if no overload desired.
-
-## Generated Columns
-
-- `... GENERATED ALWAYS AS (<expr>) STORED` for computed, indexable fields. PG18+ adds `VIRTUAL` columns (computed on read, not stored).
-
-## Extensions
-
-- **`pgcrypto`**: `crypt()` for password hashing.
-- **`uuid-ossp`**: alternative UUID functions; prefer `pgcrypto` for new projects.
-- **`pg_trgm`**: fuzzy text search with `%` operator, `similarity()` function. Index with GIN for `LIKE '%pattern%'` acceleration.
-- **`citext`**: case-insensitive text type. Prefer expression indexes on `LOWER(col)` unless you need case-insensitive constraints.
-- **`btree_gin`/`btree_gist`**: enable mixed-type indexes (e.g., GIN index on both JSONB and text columns).
-- **`hstore`**: key-value pairs; mostly superseded by JSONB but useful for simple string mappings.
-- **`timescaledb`**: essential for time-series—automated partitioning, retention, compression, continuous aggregates.
-- **`postgis`**: comprehensive geospatial support beyond basic geometric types—essential for location-based applications.
-- **`pgvector`**: vector similarity search for embeddings.
-- **`pgaudit`**: audit logging for all database activity.
-
-## JSONB Guidance
-
-- Prefer `JSONB` with **GIN** index.
-- Default: `CREATE INDEX ON tbl USING GIN (jsonb_col);` → accelerates:
-  - **Containment** `jsonb_col @> '{"k":"v"}'`
-  - **Key existence** `jsonb_col ? 'k'`, **any/all keys** `?\|`, `?&`
-  - **Path containment** on nested docs
-  - **Disjunction** `jsonb_col @> ANY(ARRAY['{"status":"active"}', '{"status":"pending"}'])`
-- Heavy `@>` workloads: consider opclass `jsonb_path_ops` for smaller/faster containment-only indexes:
-  - `CREATE INDEX ON tbl USING GIN (jsonb_col jsonb_path_ops);`
-  - **Trade-off**: loses support for key existence (`?`, `?|`, `?&`) queries—only supports containment (`@>`)
-- Equality/range on a specific scalar field: extract and index with B-tree (generated column or expression):
-  - `ALTER TABLE tbl ADD COLUMN price INT GENERATED ALWAYS AS ((jsonb_col->>'price')::INT) STORED;`
-  - `CREATE INDEX ON tbl (price);`
-  - Prefer queries like `WHERE price BETWEEN 100 AND 500` (uses B-tree) over `WHERE (jsonb_col->>'price')::INT BETWEEN 100 AND 500` without index.
-- Arrays inside JSONB: use GIN + `@>` for containment (e.g., tags). Consider `jsonb_path_ops` if only doing containment.
-- Keep core relations in tables; use JSONB for optional/variable attributes.
-- Use constraints to limit allowed JSONB values in a column e.g. `config JSONB NOT NULL CHECK(jsonb_typeof(config) = 'object')`
-
-
-## Examples
-
-### Users
-
-```sql
-CREATE TABLE users (
-  user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-  email TEXT NOT NULL UNIQUE,
-  name TEXT NOT NULL,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-CREATE UNIQUE INDEX ON users (LOWER(email));
-CREATE INDEX ON users (created_at);
-```
-
-### Orders
-
-```sql
-CREATE TABLE orders (
-  order_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-  user_id BIGINT NOT NULL REFERENCES users(user_id),
-  status TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','PAID','CANCELED')),
-  total NUMERIC(10,2) NOT NULL CHECK (total > 0),
-  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-CREATE INDEX ON orders (user_id);
-CREATE INDEX ON orders (created_at);
-```
-
-### JSONB
-
-```sql
-CREATE TABLE profiles (
-  user_id BIGINT PRIMARY KEY REFERENCES users(user_id),
-  attrs JSONB NOT NULL DEFAULT '{}',
-  theme TEXT GENERATED ALWAYS AS (attrs->>'theme') STORED
-);
-CREATE INDEX profiles_attrs_gin ON profiles USING GIN (attrs);
-```