@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/redis/references/data-modeling.md

@@ -0,0 +1,152 @@
+# Redis — Data Modeling and Key Design
+
+## The golden rule
+
+In Redis, the **data structure determines your access pattern** — pick the structure based on what operations you need, not what the data looks like.
+
+## Data structure decision guide
+
+### String — simplest value
+
+Use for: counters, single scalar values, serialized blobs, feature flags.
+
+```redis
+SET user:42:points 1500
+INCR user:42:points              # atomic increment
+INCRBY user:42:points 50
+GET user:42:points
+
+# Serialized JSON (avoid if you only need individual fields — use Hash instead)
+SET product:99 '{"name":"Widget","price":9.99}'
+```
+
+### Hash — object with fields
+
+Use for: user profiles, session data, config objects with named fields. Avoids deserializing a full JSON blob to update one field.
+
+```redis
+HSET user:42 name "Alice" email "alice@example.com" plan "pro"
+HGET user:42 email
+HMGET user:42 name plan          # fetch specific fields
+HINCRBY user:42 login_count 1    # atomic field increment
+HDEL user:42 temp_field           # remove one field
+HGETALL user:42                   # get all fields (watch size)
+```
+
+Memory note: Hashes with ≤128 fields and short values use a compact ziplist encoding — much cheaper than separate String keys.
+
+### List — ordered sequence / queue
+
+Use for: message queues, activity feeds (append + trim), task lists.
+
+```redis
+LPUSH queue:emails '{"to":"a@b.com"}'   # push to head
+RPUSH queue:emails '{"to":"c@d.com"}'   # push to tail
+LPOP queue:emails                        # dequeue from head (FIFO)
+RPOP queue:emails                        # dequeue from tail (LIFO)
+LLEN queue:emails                        # current length
+LTRIM feed:user:42 0 99                  # keep only last 100 items
+```
+
+For producer/consumer queues in production prefer **Streams** (more features, consumer groups, acknowledgment).
+
+### Set — unordered unique values
+
+Use for: membership checks, unique visitors, tagging, deduplication.
+
+```redis
+SADD online_users user:42 user:99
+SISMEMBER online_users user:42   # O(1) membership check
+SMEMBERS online_users            # all members (avoid on large sets)
+SCARD online_users               # count
+SREM online_users user:42        # remove
+
+# Set operations (great for permission/feature checks)
+SUNION editors:org:1 editors:org:2          # union
+SINTER subscribers premium_users           # intersection
+```
+
+### Sorted Set (ZSET) — ordered by score
+
+Use for: leaderboards, rate limiting, scheduled jobs, range queries, time-series indexes.
+
+```redis
+ZADD leaderboard:global 1500 "user:42"    # score = 1500
+ZINCRBY leaderboard:global 100 "user:42"  # atomic score increment
+ZREVRANK leaderboard:global "user:42"      # rank (0-indexed, desc)
+ZREVRANGE leaderboard:global 0 9 WITHSCORES  # top 10 with scores
+
+# Range by score (e.g., all jobs due in next 60s)
+ZRANGEBYSCORE scheduled_jobs 0 1706000060 WITHSCORES LIMIT 0 10
+ZREM scheduled_jobs "job:123"             # remove after processing
+```
+
+### Stream — append-only log with consumer groups
+
+Use for: event sourcing, reliable message delivery, audit logs, notifications.
+
+```redis
+XADD events:orders '*' type order_created orderId 99 userId 42  # auto-ID
+XLEN events:orders
+XRANGE events:orders - +                 # all events
+XRANGE events:orders 1706000000000-0 +  # from timestamp
+
+# Consumer group for reliable delivery
+XGROUP CREATE events:orders workers $ MKSTREAM
+XREADGROUP GROUP workers consumer1 COUNT 10 STREAMS events:orders >  # read new
+XACK events:orders workers <message-id>  # acknowledge after processing
+```
+
+## Key naming
+
+```
+<entity>:<id>:<field>
+
+user:42:points          String — points counter
+user:42                 Hash   — user profile object
+leaderboard:global      ZSET   — global score board
+queue:emails            List   — email send queue
+online_users            Set    — currently online user IDs
+events:orders           Stream — order event log
+rate:user:42:202501     String — rate limit bucket
+session:abc123          String/Hash — session data
+```
+
+Rules:
+- Use `:` as separator.
+- Keep namespaces consistent across the codebase.
+- Include an entity type so `SCAN type:*` works for debugging.
+- Include a time bucket in rate limit keys so they auto-expire when the window passes.
+
+## TTL strategy
+
+| Key type | TTL strategy |
+| --- | --- |
+| Sessions | Explicit TTL on set, slide it on read (`EXPIRE key 3600`) |
+| Cache keys | Fixed TTL matching acceptable staleness |
+| Rate limit buckets | 2× the window duration |
+| Leaderboards | No TTL (explicit reset with `DEL`) |
+| Streams | Use `MAXLEN` to cap length, or `EXPIRE` on the whole stream |
+
+```redis
+# Sliding session TTL
+SET session:abc123 "{...}" EX 3600
+# On each read, reset the TTL:
+EXPIRE session:abc123 3600
+```
+
+## Avoid these patterns
+
+| Antipattern | Problem | Fix |
+| --- | --- | --- |
+| Storing JSON in String when you need individual fields | Full deser on every access | Use Hash |
+| Unbounded List/Set with no trim | Memory growth without bound | `LTRIM`, `SREM`, or `MAXLEN` |
+| `KEYS *` in production | Blocks event loop | Use `SCAN` |
+| No TTL on cache keys | Memory leak | Always set TTL |
+| Huge Hash (`HGETALL`) on hot path | Transfers more data than needed | Project with `HMGET` |
+| Sequences as String with `INCR` shared globally | Bottleneck at high QPS | Shard or batch |
+
+## Sources
+- Redis data types: https://redis.io/docs/latest/develop/data-types/
+- Streams: https://redis.io/docs/latest/develop/data-types/streams/
+- Sorted sets: https://redis.io/docs/latest/develop/data-types/sorted-sets/

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

@@ -0,0 +1,144 @@
+# Redis — Operations, Memory, and Latency
+
+## Memory management
+
+Redis stores all data in memory. Running out of memory is the #1 operational failure mode.
+
+### Monitor memory
+
+```redis
+INFO memory
+# Key fields:
+# used_memory_human        — actual data memory
+# used_memory_rss_human    — RSS from OS (includes fragmentation)
+# mem_fragmentation_ratio  — rss / used. >1.5 = high fragmentation
+# maxmemory                — configured limit (0 = unlimited — dangerous)
+# maxmemory_human          — human readable limit
+```
+
+Always set `maxmemory`:
+```redis
+CONFIG SET maxmemory 2gb
+```
+
+### Eviction policies
+
+When `maxmemory` is reached, Redis uses the configured eviction policy:
+
+| Policy | Behavior |
+| --- | --- |
+| `noeviction` | Returns error on writes — safe for primary data stores |
+| `allkeys-lru` | Evicts least recently used keys — good for caches |
+| `volatile-lru` | Evicts LRU keys that have a TTL set |
+| `allkeys-lfu` | Evicts least frequently used — better than LRU for skewed access |
+| `volatile-ttl` | Evicts keys with shortest remaining TTL first |
+| `allkeys-random` | Random eviction — rarely useful |
+
+For pure caches: `allkeys-lru` or `allkeys-lfu`.
+For mixed primary + cache data: `volatile-lru` (only evicts keys with TTL).
+
+```redis
+CONFIG SET maxmemory-policy allkeys-lru
+```
+
+### Handle fragmentation
+
+When `mem_fragmentation_ratio > 1.5`, trigger active defragmentation (Redis 4.0+):
+```redis
+CONFIG SET activedefrag yes
+CONFIG SET active-defrag-ignore-bytes 100mb
+CONFIG SET active-defrag-threshold-lower 10
+```
+
+## Latency diagnostics
+
+Redis should respond in microseconds. If you're seeing millisecond latency, investigate:
+
+```redis
+# Check for slow commands (logged automatically)
+SLOWLOG GET 10
+SLOWLOG LEN
+SLOWLOG RESET
+
+# Default slow threshold is 10ms — lower for tighter monitoring:
+CONFIG SET slowlog-log-slower-than 1000   # microseconds = 1ms
+
+# Latency history (built-in latency monitoring)
+LATENCY LATEST
+LATENCY HISTORY event_name
+LATENCY RESET
+```
+
+### Common latency causes
+
+| Cause | Symptom | Fix |
+| --- | --- | --- |
+| `KEYS *` in production | Periodic spikes | Replace with `SCAN` |
+| Large key values (MB-range) | Slow reads/writes | Chunk data or use a different store |
+| AOF fsync on every write | Consistent high latency | Switch to `fsync everysec` |
+| Memory pressure / eviction | Increasing latency trend | Add memory or tune eviction |
+| Blocking commands (`BLPOP`, `BRPOP`) | Thread holds connection | Use timeouts |
+| Fork for RDB/AOF rewrite | Latency spike every N minutes | Schedule rewrites in off-peak windows |
+
+## Persistence configuration
+
+Choose based on durability requirements:
+
+| Config | Durability | Performance |
+| --- | --- | --- |
+| No persistence | None (cache only) | Fastest |
+| RDB snapshots only | Up to snapshot interval | Fast |
+| AOF `everysec` | Up to ~1s of data loss | Good |
+| AOF `always` | No data loss | Slowest — 1 fsync per write |
+| RDB + AOF | Best of both | Moderate |
+
+For caches where losing data on restart is acceptable, disable persistence:
+```redis
+CONFIG SET save ""         # disable RDB
+CONFIG SET appendonly no   # disable AOF
+```
+
+## Monitor key space
+
+```redis
+# Count keys per database
+INFO keyspace
+
+# Sample key patterns (does not block)
+redis-cli --scan --pattern 'user:*' | head -20
+
+# Key size distribution — pick a sample
+redis-cli --bigkeys       # finds largest keys by type
+```
+
+## Connection limits
+
+```redis
+INFO clients
+# connected_clients       — current connections
+# maxclients              — configured limit (default 10000)
+```
+
+Redis is single-threaded for command execution. High connection counts add overhead via:
+- Select/poll overhead on the socket set.
+- Memory per connection (~20KB).
+
+Use a connection pool in your application. Most Redis clients (ioredis, redis-py) pool by default. Check pool size matches your concurrency model.
+
+## Key expiry and eviction monitoring
+
+```redis
+INFO stats
+# expired_keys     — keys removed by TTL expiry since start
+# evicted_keys     — keys removed by maxmemory policy
+# keyspace_hits    — cache hit count
+# keyspace_misses  — cache miss count
+
+# Hit rate = hits / (hits + misses). Below 80% suggests key design issues.
+```
+
+## Sources
+- Memory optimization: https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/memory-optimization/
+- Latency optimization: https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/latency/
+- Persistence options: https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/
+- SLOWLOG: https://redis.io/docs/latest/commands/slowlog/

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

@@ -0,0 +1,36 @@
+---
+name: sqlite
+description: SQLite local/edge data strategy, schema/index design, query planning, and WAL tuning.
+---
+
+# SQLite
+
+## Optimization workflow
+
+1. Inspect plan with `EXPLAIN QUERY PLAN`.
+2. Add multicolumn or covering indexes for hot read paths.
+3. Use keyset-style pagination for large datasets.
+4. Tune WAL/checkpoint behavior for write-heavy workloads.
+5. Re-check plans after schema/data-distribution changes.
+
+## Indexing techniques
+
+- Composite indexes for combined filter+sort paths.
+- Covering indexes when read latency is critical.
+- Keep indexes minimal on write-heavy local stores.
+
+## Pagination techniques
+
+- Offset is acceptable for small tables and shallow lists.
+- For large traversals, use deterministic keyset pagination.
+
+## Operational guardrails
+
+- Batch writes in explicit transactions.
+- Use WAL mode for mixed read/write concurrency.
+- Validate checkpoint strategy for mobile/edge IO limits.
+
+## References
+
+- `references/local-first.md`
+- `references/performance.md`

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/sqlite/references/local-first.md

@@ -0,0 +1,95 @@
+# SQLite — Local-First Design
+
+## When SQLite is the right fit
+
+SQLite is the right choice when:
+- Each user has their own private data (mobile app, desktop app, browser extension, edge function).
+- The application needs to work offline with local durability.
+- Data sync is done at the application layer, not the database layer.
+- Simplicity and zero-configuration matter.
+
+SQLite is **not** the right fit for:
+- High-concurrency write workloads with multiple simultaneous writers.
+- Data shared across multiple users in real-time (use Postgres or MySQL instead).
+- Analytics on large datasets (use ClickHouse or DuckDB instead).
+
+## Journal modes — choose WAL for mobile/desktop
+
+The default Rollback Journal blocks all reads during a write. Switch to WAL (Write-Ahead Log) for concurrent reads:
+
+```sql
+PRAGMA journal_mode = WAL;
+-- Persist across connections (set once after DB creation)
+```
+
+WAL mode allows:
+- Multiple simultaneous readers while a write is in progress.
+- Reads don't block writes; writes don't block reads.
+- Slightly better write performance for sequential inserts.
+
+Set `PRAGMA synchronous = NORMAL` with WAL (safe default, faster than `FULL`):
+```sql
+PRAGMA synchronous = NORMAL;
+```
+
+## Migration patterns
+
+Migrations must be deterministic and reversible. Use a migrations table to track applied versions:
+
+```sql
+CREATE TABLE IF NOT EXISTS _migrations (
+  id INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+```
+
+Migration rules:
+- **Never modify an applied migration** — create a new one instead.
+- **Always test on real device storage** — SD cards, old iPhones, and constrained flash behave differently than dev machines.
+- **Include a down migration** (rollback SQL) alongside every up migration.
+- Run migrations inside a transaction so partial failure is safe:
+  ```sql
+  BEGIN;
+  -- migration SQL here
+  INSERT INTO _migrations (id, name) VALUES (3, 'add_notes_column');
+  COMMIT;
+  ```
+
+## Multi-device sync and conflict handling
+
+SQLite has no built-in sync. Design conflict handling explicitly before writing any app code.
+
+Common strategies:
+- **Last-write-wins (LWW)**: each row has `updated_at`. On sync, higher timestamp wins. Simple but loses concurrent edits.
+- **CRDTs**: use conflict-free replicated data types for counters, sets, and ordered lists. Complex but correct.
+- **Event sourcing**: store immutable event log, derive state. Sync events instead of rows.
+- **Vector clocks**: each device has a logical clock; merge based on causal ordering.
+
+Always include a `sync_id` (UUID, globally unique) and `device_id` on every synced row. Never rely on local SQLite `ROWID` or autoincrement as a sync key.
+
+## Offline-first checklist
+
+- [ ] WAL mode enabled on database open.
+- [ ] All writes go through a local queue that syncs when connectivity is available.
+- [ ] Conflict resolution strategy defined before writing sync logic.
+- [ ] Migrations run before any app reads/writes.
+- [ ] Migration history table exists.
+- [ ] UI shows sync status (pending, syncing, error).
+- [ ] Sync tested under: airplane mode, partial connectivity, app killed mid-sync.
+
+## Appropriate use cases
+
+| Use | Verdict |
+| --- | --- |
+| Mobile app local data | ✅ Excellent |
+| Desktop app settings and cache | ✅ Excellent |
+| Embedded IoT / edge data | ✅ Excellent |
+| Read-heavy web server cache | ✅ Good (read-only or low-write) |
+| Multi-user web app backend | ❌ Use Postgres |
+| High-concurrency writes | ❌ Use Postgres or MySQL |
+
+## Sources
+- SQLite appropriate uses: https://sqlite.org/whentouse.html
+- Atomic commit behavior: https://sqlite.org/atomiccommit.html
+- WAL mode: https://sqlite.org/wal.html

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

@@ -0,0 +1,105 @@
+# SQLite — Performance Techniques
+
+## EXPLAIN QUERY PLAN
+
+Always check the planner before optimizing.
+
+```sql
+EXPLAIN QUERY PLAN
+SELECT * FROM orders WHERE user_id = 1 ORDER BY created_at DESC LIMIT 20;
+```
+
+Key output to read:
+- `SCAN orders` = full table scan — missing or unused index.
+- `SEARCH orders USING INDEX idx_orders_user (user_id=?)` = index seek — good.
+- `USE TEMP B-TREE FOR ORDER BY` = sort can't use the index — add a covering index with the sort column.
+
+## Index design
+
+SQLite uses B-tree indexes. Same leftmost-prefix rules as other SQL databases.
+
+```sql
+-- Equality first, sort last
+CREATE INDEX idx_orders_user_created ON orders (user_id, created_at DESC);
+
+-- Partial index for hot filtered subsets
+CREATE INDEX idx_orders_pending ON orders (user_id, created_at)
+WHERE status = 'pending';
+
+-- Covering index: include projected columns to avoid table fetch
+CREATE INDEX idx_orders_covering ON orders (user_id, status)
+-- SQLite doesn't have INCLUDE, so list all needed columns in the key
+```
+
+SQLite does not support `INCLUDE` columns — put all needed columns in the key if you want index-only reads.
+
+## Write performance — batch in transactions
+
+Every `INSERT`/`UPDATE`/`DELETE` outside a transaction is its own `fsync`. For bulk operations this is catastrophically slow.
+
+```sql
+-- BAD: 1000 individual fsyncs
+INSERT INTO logs VALUES (...);
+INSERT INTO logs VALUES (...);
+-- × 1000
+
+-- GOOD: one fsync
+BEGIN;
+INSERT INTO logs VALUES (...);
+INSERT INTO logs VALUES (...);
+-- × 1000
+COMMIT;
+```
+
+Rule of thumb: batch 100–10,000 rows per transaction. Benchmark for your hardware.
+
+## WAL and checkpoint tuning
+
+With WAL mode (see local-first.md), the WAL file grows until a checkpoint writes it back to the main DB file.
+
+```sql
+PRAGMA wal_autocheckpoint = 1000;   -- checkpoint after 1000 pages (default)
+-- Lower = more frequent checkpoints (less WAL growth, slightly more I/O)
+-- Higher = less frequent (better write throughput, larger WAL file)
+```
+
+Manual checkpoint before a backup:
+```sql
+PRAGMA wal_checkpoint(TRUNCATE);   -- flush WAL and truncate the file
+```
+
+## Memory and cache tuning
+
+```sql
+PRAGMA cache_size = -32000;    -- 32 MB page cache (negative = KB, default = 2MB)
+PRAGMA mmap_size = 268435456;  -- 256 MB memory-mapped I/O (faster reads on large DBs)
+PRAGMA temp_store = MEMORY;    -- keep temp tables in RAM instead of disk
+```
+
+Apply these after every `OPEN` — they are not persisted.
+
+## Seek pagination
+
+```sql
+-- BAD: OFFSET scans and discards N rows
+SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 10000;
+
+-- GOOD: seek on last seen id
+SELECT * FROM orders WHERE id > :last_seen_id ORDER BY id LIMIT 20;
+```
+
+## Connection management (multi-threaded apps)
+
+SQLite supports one writer at a time. For multi-threaded apps:
+- Use a single write connection with serialized writes.
+- Use a read connection pool (WAL mode allows concurrent readers).
+- Set `PRAGMA busy_timeout = 5000` to wait instead of failing immediately on a locked DB:
+  ```sql
+  PRAGMA busy_timeout = 5000;   -- wait up to 5s before returning SQLITE_BUSY
+  ```
+
+## Sources
+- EXPLAIN QUERY PLAN: https://sqlite.org/eqp.html
+- Query planner: https://sqlite.org/queryplanner.html
+- WAL mode: https://sqlite.org/wal.html
+- PRAGMA reference: https://sqlite.org/pragma.html

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

@@ -0,0 +1,35 @@
+---
+name: supabase
+description: Supabase/Postgres patterns for RLS, indexing, query optimization, pooling, and safe migrations.
+---
+
+# Supabase
+
+## Optimization workflow
+
+1. Confirm RLS policy shape and index policy predicates.
+2. Analyze query plans and use index advisor workflow.
+3. Choose proper connection mode (direct/session/transaction pooler).
+4. Use keyset pagination for heavy list endpoints.
+5. Include migration/rollback with version-awareness (managed vs self-hosted differences).
+
+## Indexing and RLS techniques
+
+- Index columns referenced by RLS policies.
+- Index join/filter columns used by API queries.
+- Remove redundant indexes that inflate write cost.
+
+## Pagination techniques
+
+- Prefer keyset pagination on stable, indexed sort columns.
+- Avoid blind offset scans on large tables.
+
+## Operational guardrails
+
+- Validate Supavisor mode based on runtime behavior.
+- Confirm compatibility when moving between managed and self-hosted environments.
+
+## References
+
+- `references/rls-auth.md`
+- `references/performance-operations.md`

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/supabase/references/performance-operations.md

@@ -0,0 +1,95 @@
+# Supabase — Query Performance and Connection Operations
+
+## Query optimization workflow
+
+1. Identify slow queries via Supabase Dashboard → Database → Query Performance (uses `pg_stat_statements`).
+2. Run `EXPLAIN (ANALYZE, BUFFERS)` on the slow query to read the actual plan.
+3. Check for: `Seq Scan` on large tables, `Sort` without index, high `Rows Removed by Filter` ratio.
+4. Add targeted index and re-test.
+
+```sql
+-- From the SQL editor in Supabase Dashboard
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT * FROM orders WHERE user_id = 'abc' ORDER BY created_at DESC LIMIT 20;
+```
+
+## Database Advisors
+
+Supabase runs automated advisors that flag common issues. Check Dashboard → Database → Advisors for:
+- **Unused indexes**: indexes with zero scans — drop them.
+- **Unindexed foreign keys**: FKs without an index cause full scans on joins and cascades.
+- **Seq scans on large tables**: tables being full-scanned when an index would help.
+- **Bloated tables**: high dead tuple ratio — may need `VACUUM`.
+
+```sql
+-- Manual unused index check
+SELECT schemaname, relname, indexrelname, idx_scan
+FROM pg_stat_user_indexes
+WHERE idx_scan = 0 AND schemaname = 'public'
+ORDER BY relname;
+```
+
+## Connection modes and when to use each
+
+Supabase provides three connection methods:
+
+| Mode | How | Use for |
+| --- | --- | --- |
+| **Direct** | `postgresql://...` port 5432 | Long-lived connections (background jobs, migrations) |
+| **Transaction pooler** (PgBouncer) | Port 6543 | Serverless functions, edge functions, short-lived requests |
+| **Session pooler** | Port 5432 alt | When you need session-level features (prepared statements, `SET`) |
+
+**Serverless / Edge Functions**: always use the transaction pooler (6543). Direct connections from serverless cold starts exhaust Postgres connection limits fast.
+
+```ts
+// Supabase JS — uses transaction pooler automatically when using the client library
+const supabase = createClient(url, anonKey);
+
+// Direct connection for migrations / background jobs (Prisma, Drizzle, etc.)
+DATABASE_URL=postgresql://user:pass@db.xxx.supabase.co:5432/postgres
+// Transaction pooler for Prisma in serverless
+DATABASE_URL=postgresql://user:pass@db.xxx.supabase.co:6543/postgres?pgbouncer=true
+```
+
+## Prepared statements and pooling
+
+PgBouncer in transaction mode does **not** support prepared statements — they are per-session. If your ORM uses prepared statements (Prisma does by default):
+
+```
+# Prisma — disable prepared statements when using transaction pooler
+DATABASE_URL="...?pgbouncer=true&connection_limit=1"
+# Or in schema.prisma:
+datasource db {
+  url = env("DATABASE_URL")
+  directUrl = env("DIRECT_URL")  # direct connection for migrations
+}
+```
+
+## Realtime performance considerations
+
+Supabase Realtime uses Postgres logical replication. High-volume tables with Realtime enabled generate significant WAL traffic.
+
+- Enable Realtime only on tables that clients actually subscribe to.
+- Filter subscriptions as tightly as possible: `channel.on('postgres_changes', { filter: 'user_id=eq.123' }, ...)`.
+- Monitor replication slot lag in Dashboard → Database → Replication.
+
+## Extensions useful for performance
+
+```sql
+-- Query statistics (enabled by default in Supabase)
+SELECT * FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;
+
+-- Index usage stats
+SELECT * FROM pg_stat_user_indexes ORDER BY idx_scan ASC;
+
+-- Table bloat estimate
+SELECT relname, n_dead_tup, n_live_tup, last_autovacuum
+FROM pg_stat_user_tables
+ORDER BY n_dead_tup DESC;
+```
+
+## Sources
+- Query optimization guide: https://supabase.com/docs/guides/database/query-optimization
+- Database advisors: https://supabase.com/docs/guides/database/database-advisors
+- Connecting to Postgres (poolers): https://supabase.com/docs/guides/database/connecting-to-postgres
+- pg_stat_statements: https://www.postgresql.org/docs/current/pgstatstatements.html