@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/postgres/references/connection-pooling.md

@@ -0,0 +1,142 @@
+# Postgres — Connection Pooling
+
+## Why connection pooling is necessary
+
+Postgres spawns one process per connection, each consuming ~5–10 MB of RAM. At 200+ direct connections:
+- Memory pressure becomes significant.
+- Context-switching overhead increases.
+- Connection setup latency adds up (especially from serverless functions).
+
+**Rule**: almost every Postgres deployment in production needs a connection pooler in front.
+
+## PgBouncer — the standard choice
+
+PgBouncer is a lightweight, battle-tested TCP proxy for Postgres.
+
+### Pooling modes
+
+| Mode | How it works | Use for |
+| --- | --- | --- |
+| **Transaction** (recommended) | A server connection is held only for the duration of a transaction | Stateless apps, serverless, most OLTP |
+| **Session** | One server connection per client session until it disconnects | Apps that use session-level features (`SET`, `LISTEN`, advisory locks) |
+| **Statement** | Returns connection after each statement | Only for apps that don't use multi-statement transactions — rare |
+
+**Transaction mode caveat**: prepared statements are session-level in Postgres and break under transaction pooling. Use `pgbouncer_prepared_statements = 1` (PgBouncer 1.21+) or disable prepared statements in your client.
+
+### Typical PgBouncer configuration (`pgbouncer.ini`)
+
+```ini
+[databases]
+mydb = host=127.0.0.1 port=5432 dbname=mydb
+
+[pgbouncer]
+listen_addr = 0.0.0.0
+listen_port = 6432
+auth_type = scram-sha-256
+auth_file = /etc/pgbouncer/userlist.txt
+pool_mode = transaction
+max_client_conn = 1000        ; max connections from apps to PgBouncer
+default_pool_size = 20        ; max actual Postgres connections per database/user pair
+reserve_pool_size = 5         ; extra connections for spikes
+reserve_pool_timeout = 3
+server_idle_timeout = 600
+log_connections = 0           ; disable in production (log noise)
+```
+
+### Pool sizing formula
+
+```
+default_pool_size ≈ (num_postgres_cpu_cores × 2) + num_spindle_disks
+```
+
+For a 4-core managed Postgres: target ~10–15 server connections. App instances × client threads → PgBouncer → bounded Postgres connections.
+
+## Application-level connection pools
+
+Even with PgBouncer, application clients should pool connections to PgBouncer (not open/close on each request).
+
+### Node.js — `pg` / `node-postgres`
+
+```ts
+import { Pool } from 'pg';
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 10,            // max connections from this app instance to PgBouncer
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 5000,
+});
+// Use pool.query() directly or pool.connect() for transactions
+```
+
+### Python — SQLAlchemy
+
+```python
+engine = create_engine(
+    DATABASE_URL,
+    pool_size=10,
+    max_overflow=5,
+    pool_pre_ping=True,       # test connection health before use
+    pool_recycle=3600,        # recycle connections every hour
+)
+```
+
+### Prisma (Node.js)
+
+```
+# .env
+DATABASE_URL="postgresql://user:pass@pgbouncer-host:6432/mydb?pgbouncer=true"
+```
+
+The `?pgbouncer=true` flag disables prepared statements, which is required for transaction pooling.
+
+## Serverless / edge environments
+
+Serverless functions open and close connections per invocation — disastrous for direct Postgres connections.
+
+Options:
+1. **PgBouncer in transaction mode** — each function call uses a pool connection only during its transaction.
+2. **Supabase Transaction Pooler** — managed PgBouncer built into Supabase (port 6543).
+3. **Neon serverless driver** — uses HTTP instead of TCP; no persistent connection overhead.
+
+```ts
+// Neon serverless (HTTP-based, no connection overhead)
+import { neon } from '@neondatabase/serverless';
+const sql = neon(process.env.DATABASE_URL);
+const orders = await sql`SELECT * FROM orders WHERE user_id = ${userId}`;
+```
+
+## Monitoring connections
+
+```sql
+-- Current connection breakdown
+SELECT state, count(*) FROM pg_stat_activity GROUP BY state ORDER BY count DESC;
+
+-- Waiting connections (lock or connection wait)
+SELECT pid, state, wait_event_type, wait_event, query
+FROM pg_stat_activity
+WHERE wait_event IS NOT NULL;
+
+-- Max connections setting
+SHOW max_connections;
+
+-- Current utilization rate
+SELECT count(*) * 100.0 / current_setting('max_connections')::int AS pct_used
+FROM pg_stat_activity;
+```
+
+Alert when `pct_used > 80%` — before you hit the limit.
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| No pooler in serverless | Add PgBouncer or use HTTP driver |
+| `max_connections` set too high on Postgres | Lower it and pool instead |
+| Prepared statements in transaction pool mode | Disable at driver level |
+| App pool size > PgBouncer pool size | App waits; PgBouncer has no server connections left |
+| No `pool_pre_ping` / health check | Stale connections fail silently |
+
+## Sources
+- PgBouncer documentation: https://www.pgbouncer.org/config.html
+- PostgreSQL max_connections: https://www.postgresql.org/docs/current/runtime-config-connection.html
+- Prisma PgBouncer guide: https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/databases/postgresql#pgbouncer

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/postgres/references/migrations.md

@@ -0,0 +1,126 @@
+# Postgres — Database Migrations
+
+## Core principles
+
+- Migrations must be **idempotent** where possible — safe to run more than once.
+- Migrations must be **reversible** — always write a down migration.
+- Every migration runs inside a transaction (unless it contains commands that can't be transactional, like `CREATE INDEX CONCURRENTLY`).
+- Test on a staging environment with a recent production data dump before production.
+
+## Migration table (simple self-managed setup)
+
+```sql
+CREATE TABLE IF NOT EXISTS _migrations (
+  id      SERIAL PRIMARY KEY,
+  name    TEXT NOT NULL UNIQUE,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+```
+
+## Zero-downtime migration pattern (additive-first)
+
+Never make breaking schema changes in the same deploy as the application code that depends on them. Expand, then contract.
+
+### Phase 1: Expand (add without breaking)
+```sql
+-- Add new nullable column — safe, no lock, app can read NULL for old rows
+ALTER TABLE orders ADD COLUMN notes TEXT;
+
+-- Add new index concurrently — no write lock
+CREATE INDEX CONCURRENTLY idx_orders_notes ON orders (notes) WHERE notes IS NOT NULL;
+```
+
+### Phase 2: Backfill (populate data)
+```sql
+-- Backfill in batches — never in one big UPDATE that locks the table
+DO $$
+DECLARE batch_size INT := 1000;
+        last_id BIGINT := 0;
+BEGIN
+  LOOP
+    UPDATE orders SET notes = '' WHERE id > last_id AND notes IS NULL
+    RETURNING id INTO last_id;
+    EXIT WHEN NOT FOUND;
+    PERFORM pg_sleep(0.01);  -- brief pause between batches
+  END LOOP;
+END $$;
+```
+
+### Phase 3: Constrain (enforce, after app deploys)
+```sql
+-- Add NOT NULL only after backfill is complete and app always sets notes
+-- Use VALIDATE CONSTRAINT to avoid a long table lock
+ALTER TABLE orders ADD CONSTRAINT orders_notes_not_null CHECK (notes IS NOT NULL) NOT VALID;
+ALTER TABLE orders VALIDATE CONSTRAINT orders_notes_not_null;
+-- Later, replace with actual NOT NULL (requires table rewrite — schedule maintenance)
+ALTER TABLE orders ALTER COLUMN notes SET NOT NULL;
+```
+
+## Safe vs unsafe DDL
+
+| Operation | Safe online? | Notes |
+| --- | --- | --- |
+| Add nullable column | ✅ | Instant in Postgres 11+ |
+| Add NOT NULL column with DEFAULT | ✅ Postgres 11+ | Older versions rewrite table |
+| Drop column | ✅ | Marks column invisible; no immediate rewrite |
+| Add index | ❌ (blocks writes) | Use `CREATE INDEX CONCURRENTLY` |
+| Add UNIQUE constraint | ❌ | Create unique index concurrently first, then `ADD CONSTRAINT ... USING INDEX` |
+| Rename column | ⚠️ | Breaking change — requires multi-phase deploy |
+| Change column type | ❌ | Usually needs table rewrite; use additive approach |
+| Drop table | ❌ | Irreversible without backup; ensure app no longer references it |
+
+## CREATE INDEX CONCURRENTLY
+
+The only way to add an index without blocking writes:
+
+```sql
+-- Run outside a transaction block (psql \c or separate connection)
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+Caveats:
+- Cannot run inside a transaction.
+- Takes longer than regular `CREATE INDEX`.
+- If it fails, leaves an `INVALID` index — drop it and retry:
+  ```sql
+  DROP INDEX CONCURRENTLY idx_orders_user_id;
+  ```
+
+## Renaming — multi-phase deploy
+
+Never rename a column in a single deploy. The app will break.
+
+```
+Phase 1: Add new column, dual-write in app to both old and new.
+Phase 2: Backfill new column from old.
+Phase 3: Deploy app to read from new column only.
+Phase 4: Remove old column.
+```
+
+## Migration tools
+
+| Tool | Language | Notes |
+| --- | --- | --- |
+| **Flyway** | Java / CLI | SQL-based, version numbered, popular in enterprise |
+| **Liquibase** | Java / CLI | XML/YAML/SQL, rollback built in |
+| **golang-migrate** | Go / CLI | Simple, SQL-based, widely used in Go projects |
+| **Alembic** | Python | SQLAlchemy-integrated, autogenerate support |
+| **Prisma Migrate** | Node.js | Generates SQL from schema diff, dev-friendly |
+| **Drizzle** | Node.js | TypeScript-first, explicit SQL migrations |
+
+For any tool: always store migration files in version control and review them in PRs.
+
+## Production checklist before running a migration
+
+- [ ] Tested on staging with production data size.
+- [ ] Estimated lock duration checked (`EXPLAIN` or timing on staging).
+- [ ] `CREATE INDEX CONCURRENTLY` used for any new indexes.
+- [ ] Down migration written and tested.
+- [ ] Monitoring dashboard open during migration.
+- [ ] Rollback plan documented.
+- [ ] Maintenance window scheduled if migration is non-online.
+
+## Sources
+- ALTER TABLE: https://www.postgresql.org/docs/current/sql-altertable.html
+- CREATE INDEX CONCURRENTLY: https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY
+- Zero-downtime schema changes: https://www.postgresql.org/docs/current/ddl-alter.html

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/postgres/references/performance-ops.md

@@ -0,0 +1,117 @@
+# Postgres — Performance and Operations
+
+## EXPLAIN workflow
+
+Always baseline with `EXPLAIN (ANALYZE, BUFFERS)` before and after any change.
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT * FROM orders WHERE user_id = 42 ORDER BY created_at DESC LIMIT 20;
+```
+
+Key things to read:
+- **Actual vs estimated rows**: large mismatch → run `ANALYZE` on the table.
+- **`Buffers: shared hit / read`**: high `read` → data not cached, I/O bound.
+- **`Seq Scan`** on a large table with a filter → likely missing index.
+- **`Hash Join` vs `Nested Loop`**: nested loop is fast with small inner set; hash join is better for large sets.
+- **`Sort` + `Limit`**: if sorting before limiting, consider an index with matching sort order.
+
+## pg_stat_statements
+
+Tracks cumulative stats for every query shape. Use to find top queries by total time.
+
+```sql
+-- Enable once per cluster
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+-- Top 10 queries by total execution time
+SELECT query, calls, total_exec_time::int, mean_exec_time::int, rows
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC
+LIMIT 10;
+
+-- Reset stats after tuning
+SELECT pg_stat_statements_reset();
+```
+
+## ANALYZE — keeping planner stats fresh
+
+Postgres uses per-column statistics (histograms, MCVs) to estimate row counts. Stale stats = bad plans.
+
+```sql
+ANALYZE orders;              -- single table
+ANALYZE VERBOSE orders;      -- with output
+ANALYZE;                     -- whole database
+```
+
+- `autovacuum` runs `ANALYZE` automatically when ~10% of rows change. For bulk loads, run manually.
+- Increase `default_statistics_target` (default 100) for columns with skewed distribution:
+  ```sql
+  ALTER TABLE orders ALTER COLUMN status SET STATISTICS 500;
+  ANALYZE orders;
+  ```
+
+## VACUUM and autovacuum
+
+Postgres uses MVCC — dead tuples accumulate from UPDATEs and DELETEs. VACUUM reclaims them.
+
+```sql
+VACUUM orders;               -- reclaim dead tuples (non-blocking)
+VACUUM ANALYZE orders;       -- reclaim + refresh stats
+VACUUM FULL orders;          -- rewrite table, reclaims disk — needs exclusive lock, use cautiously
+```
+
+Signs of autovacuum not keeping up:
+```sql
+-- Tables with high dead tuple counts
+SELECT relname, n_dead_tup, n_live_tup, last_autovacuum
+FROM pg_stat_user_tables
+ORDER BY n_dead_tup DESC;
+```
+
+Tuning autovacuum for hot tables:
+```sql
+ALTER TABLE orders SET (
+  autovacuum_vacuum_scale_factor = 0.01,   -- default 0.2 — trigger earlier
+  autovacuum_analyze_scale_factor = 0.005
+);
+```
+
+## Connection pooling
+
+Postgres spawns one process per connection. At ~200+ connections, overhead is significant.
+- Use **PgBouncer** (transaction pooling) to multiplex app connections.
+- Size pool to available CPU cores × 2–4. Monitor `pg_stat_activity`.
+
+```sql
+-- Active connections breakdown
+SELECT state, count(*) FROM pg_stat_activity GROUP BY state;
+
+-- Long-running queries
+SELECT pid, now() - query_start AS duration, query, state
+FROM pg_stat_activity
+WHERE state != 'idle' AND query_start < now() - interval '30 seconds';
+```
+
+## Lock monitoring
+
+```sql
+-- Blocked queries and what is blocking them
+SELECT blocked.pid, blocked.query, blocking.pid AS blocking_pid, blocking.query AS blocking_query
+FROM pg_stat_activity blocked
+JOIN pg_stat_activity blocking ON blocking.pid = ANY(pg_blocking_pids(blocked.pid))
+WHERE cardinality(pg_blocking_pids(blocked.pid)) > 0;
+```
+
+## Key production guardrails
+
+- Never run `VACUUM FULL` on a busy production table — takes an exclusive lock.
+- Use `CREATE INDEX CONCURRENTLY` to avoid write blocks.
+- Set `statement_timeout` and `lock_timeout` to prevent runaway queries from starving the system.
+- Avoid long-open transactions — they block autovacuum and cause bloat.
+
+## Sources
+- EXPLAIN: https://www.postgresql.org/docs/current/using-explain.html
+- pg_stat_statements: https://www.postgresql.org/docs/current/pgstatstatements.html
+- ANALYZE: https://www.postgresql.org/docs/current/sql-analyze.html
+- VACUUM / autovacuum: https://www.postgresql.org/docs/current/routine-vacuuming.html

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/postgres/references/schema-indexing.md

@@ -0,0 +1,79 @@
+# Postgres — Schema Design and Indexing
+
+## Schema design
+
+- Declare `NOT NULL` on every column that should never be null; reduces planner uncertainty and storage overhead.
+- Use `CHECK` constraints for domain rules (`amount > 0`, `status IN (...)`) — they are enforced transactionally and inform the planner.
+- Use `FOREIGN KEY` constraints for referential integrity; add indexes on FK columns to prevent sequential scans during cascades and joins.
+- Prefer `BIGINT` generated identity columns or UUIDs (v7 for sortability) as primary keys. Avoid random UUIDs as clustered keys on write-heavy tables — they fragment B-tree pages.
+- Use `TEXT` over `VARCHAR(n)` unless you need the length constraint enforced at the DB layer.
+- Prefer `TIMESTAMPTZ` over `TIMESTAMP` for all time columns.
+
+## Index types and when to use them
+
+| Type | When to use |
+| --- | --- |
+| **B-tree** (default) | Equality, range, `ORDER BY`, `LIKE 'prefix%'` |
+| **GIN** | JSONB containment (`@>`), full-text search, array overlap (`&&`) |
+| **GiST** | Geometric types, range type overlap, nearest-neighbor search |
+| **BRIN** | Append-mostly tables (time-series, logs) with high physical correlation |
+| **Hash** | Pure equality lookups only (`=`), smaller than B-tree |
+
+## Multicolumn (composite) indexes
+
+- Column order matters: place equality predicates first, then range/sort columns.
+- The planner can use a composite index for any leading prefix of its columns.
+- Example: `(status, created_at)` supports `WHERE status = 'open' ORDER BY created_at` but NOT `WHERE created_at > ...` alone without a full scan.
+
+```sql
+CREATE INDEX idx_orders_status_created ON orders (status, created_at DESC);
+```
+
+## Partial indexes
+
+- Index only the rows that queries actually need — dramatically smaller, faster to update.
+- Use when a hot query always includes a constant predicate.
+
+```sql
+-- Only index unpaid invoices, avoiding index bloat from millions of paid rows
+CREATE INDEX idx_invoices_unpaid ON invoices (due_date) WHERE paid = false;
+```
+
+## Covering indexes (INCLUDE)
+
+- Add non-predicate columns to the index to allow index-only scans (no heap fetch).
+- Put predicate columns in the key; put projection-only columns in `INCLUDE`.
+
+```sql
+CREATE INDEX idx_orders_user_covering ON orders (user_id, status)
+INCLUDE (total_amount, created_at);
+```
+
+## BRIN for append-mostly tables
+
+- Works by storing min/max per block range. Tiny index size, fast sequential insans.
+- Best when table rows are physically written in correlation with the indexed column (e.g., `created_at` on an append-only event table).
+- Useless for randomly ordered data.
+
+```sql
+CREATE INDEX idx_events_created_brin ON events USING BRIN (created_at);
+```
+
+## Index maintenance rules
+
+- Run `ANALYZE` after large data loads to refresh planner statistics.
+- Detect unused indexes:
+  ```sql
+  SELECT schemaname, relname, indexrelname, idx_scan
+  FROM pg_stat_user_indexes
+  WHERE idx_scan = 0;
+  ```
+- Drop unused indexes — they slow writes and increase vacuum cost.
+- Use `CREATE INDEX CONCURRENTLY` in production to avoid table locks.
+
+## Sources
+- PostgreSQL docs: Indexes — https://www.postgresql.org/docs/current/indexes.html
+- Multicolumn: https://www.postgresql.org/docs/current/indexes-multicolumn.html
+- Partial: https://www.postgresql.org/docs/current/indexes-partial.html
+- Covering (INCLUDE): https://www.postgresql.org/docs/current/sql-createindex.html
+- BRIN: https://www.postgresql.org/docs/current/brin.html

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/redis/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: redis
+description: Redis data modeling, caching strategy, throughput/latency optimization, and operational safety.
+---
+
+# Redis
+
+## Optimization workflow
+
+1. Define key schema and TTL policy first.
+2. Reduce round-trips with pipelining and batching.
+3. Tune memory footprint by data structure choice.
+4. Diagnose latency with server + system context.
+5. Validate hot-key and cluster-slot distribution for scale.
+
+## Indexing-style patterns in Redis
+
+- Redis is key-based; design key schema as your primary access index.
+- Use sorted sets and secondary lookup structures for query-like access.
+- Use `SCAN`-family commands for incremental traversal; avoid `KEYS` in production.
+
+## Pagination techniques
+
+- For ordered feeds/leaderboards, paginate with sorted set score/member boundaries.
+- For keyspace traversal, cursor-based `SCAN` pagination only.
+
+## Performance guardrails
+
+- Keep value payloads bounded; avoid giant hot keys.
+- Monitor expiry storms and eviction behavior.
+- Use realistic load tests for pipeline and memory tuning.
+
+## References
+
+- `references/cache-patterns.md`
+- `references/operations.md`

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/redis/references/cache-patterns.md

@@ -0,0 +1,154 @@
+# Redis — Cache and Throughput Patterns
+
+## Choosing the right data structure
+
+This is the most important Redis decision. Using the wrong type causes unnecessary memory use and complexity.
+
+| Use case | Data structure | Key pattern |
+| --- | --- | --- |
+| Single value / counter | `String` | `user:{id}:session` |
+| Object with fields | `Hash` | `user:{id}` |
+| Ordered leaderboard / timeline | `Sorted Set` (ZSET) | `leaderboard:global` |
+| Unique membership / deduplication | `Set` | `online_users` |
+| Message queue / feed | `List` (LPUSH/RPOP) or `Stream` | `queue:emails` |
+| Feature flags per user | `Hash` or `Bitmap` | `flags:{user_id}` |
+| Rate limiting | `String` + `INCR` + `EXPIRE` | `rate:{user_id}:{window}` |
+| Time-series / event log | `Stream` | `events:{service}` |
+| Pub/Sub fan-out | `Pub/Sub` channel | `channel:notifications` |
+
+**Never** store serialized JSON in a `String` if you only need individual fields — use `Hash` and `HGET`/`HSET` to avoid deserializing the whole blob.
+
+## Key naming conventions
+
+Consistent naming prevents key collisions and makes `SCAN`-based debugging possible.
+
+```
+<namespace>:<entity>:<id>[:<field>]
+
+user:42:session        → session token for user 42
+product:99:views       → view counter for product 99
+rate:192.168.1.1:1706  → rate limit bucket for IP + minute window
+leaderboard:global     → global ZSET leaderboard
+queue:emails           → email send queue (List)
+```
+
+Rules:
+- Use `:` as separator, not `.` or `/`.
+- Keep keys short — key names count toward memory.
+- Avoid dynamic segments that produce unbounded key space without TTL.
+
+## TTL strategy
+
+Always set TTLs on cache keys. Omitting TTL = memory leak.
+
+```redis
+SET user:42:session "token" EX 3600         # expires in 1 hour
+SETEX user:42:profile 300 "{...}"           # 5 minutes
+EXPIRE user:42:temp 60                       # set TTL on existing key
+
+# Atomic set + expire (preferred over SETEX)
+SET key value EX 300 NX                     # set only if not exists + TTL
+```
+
+Check TTL on a key:
+```redis
+TTL user:42:session     # -1 = no TTL (danger!), -2 = key gone, N = seconds left
+```
+
+## Pipelining — batch commands to reduce round-trips
+
+Each Redis command is a network round-trip. Pipeline batches commands into a single trip.
+
+```ts
+// Node.js (ioredis) example
+const pipeline = redis.pipeline();
+pipeline.get('user:1:session');
+pipeline.incr('user:1:views');
+pipeline.expire('user:1:views', 3600);
+const results = await pipeline.exec();
+```
+
+Use pipelining for any hot path that issues 3+ Redis commands in sequence.
+
+## SCAN instead of KEYS in production
+
+`KEYS pattern` blocks the Redis event loop for its entire duration — it will freeze Redis under load.
+
+```redis
+# NEVER in production
+KEYS user:*
+
+# CORRECT: iterative cursor scan
+SCAN 0 MATCH user:* COUNT 100
+# Use returned cursor until it returns 0
+```
+
+In code:
+```ts
+let cursor = '0';
+do {
+  const [newCursor, keys] = await redis.scan(cursor, 'MATCH', 'user:*', 'COUNT', 100);
+  cursor = newCursor;
+  // process keys
+} while (cursor !== '0');
+```
+
+## Rate limiting pattern
+
+```ts
+// Sliding window rate limit: max 100 requests per minute per user
+async function isRateLimited(userId: string): Promise<boolean> {
+  const key = `rate:${userId}:${Math.floor(Date.now() / 60000)}`;
+  const count = await redis.incr(key);
+  if (count === 1) await redis.expire(key, 120); // 2 min window safety margin
+  return count > 100;
+}
+```
+
+## Sorted sets for leaderboards and pagination
+
+```redis
+# Add score
+ZADD leaderboard:global 1500 "user:42"
+
+# Top 10
+ZREVRANGEBYSCORE leaderboard:global +inf -inf WITHSCORES LIMIT 0 10
+
+# Rank of a user (0-indexed)
+ZREVRANK leaderboard:global "user:42"
+```
+
+Cursor-based pagination with sorted sets:
+```redis
+# Page 1: get top 20
+ZREVRANGE leaderboard:global 0 19 WITHSCORES
+
+# Page 2: skip 20
+ZREVRANGE leaderboard:global 20 39 WITHSCORES
+```
+
+## Cache invalidation patterns
+
+| Pattern | When to use |
+| --- | --- |
+| **TTL expiry** | Acceptable staleness (most cases) |
+| **Write-through** | Update cache on every write — consistent but coupled |
+| **Write-behind** | Write to cache; async flush to DB — fast writes, risk of loss |
+| **Cache-aside** | App reads cache → miss → read DB → populate cache |
+| **Tag-based invalidation** | Delete multiple related keys via a shared tag key |
+
+Tag-based with a Set:
+```ts
+// On write: register the key under its tag
+await redis.sadd('tag:user:42', 'user:42:profile', 'user:42:orders');
+
+// On invalidation: delete all tagged keys
+const keys = await redis.smembers('tag:user:42');
+await redis.del(...keys, 'tag:user:42');
+```
+
+## Sources
+- Pipelining: https://redis.io/docs/latest/develop/using-commands/pipelining/
+- SCAN command: https://redis.io/docs/latest/commands/scan/
+- Sorted sets: https://redis.io/docs/latest/develop/data-types/sorted-sets/
+- Data types overview: https://redis.io/docs/latest/develop/data-types/