@cubis/foundry 0.3.11 → 0.3.13

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/postgres-pro/references/extensions.md

@@ -1,404 +0,0 @@
-# PostgreSQL Extensions
-
-## Extension Management
-
-```sql
--- List available extensions
-SELECT * FROM pg_available_extensions ORDER BY name;
-
--- List installed extensions
-SELECT * FROM pg_extension;
-
--- Install extension
-CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-CREATE EXTENSION IF NOT EXISTS pg_trgm;
-
--- Drop extension
-DROP EXTENSION pg_stat_statements;
-
--- Update extension
-ALTER EXTENSION pg_stat_statements UPDATE TO '1.10';
-```
-
-## pg_stat_statements (Query Performance)
-
-```sql
--- Install and configure
-CREATE EXTENSION pg_stat_statements;
-
--- postgresql.conf:
--- shared_preload_libraries = 'pg_stat_statements'
--- pg_stat_statements.max = 10000
--- pg_stat_statements.track = all
-
--- Top 10 slowest queries by mean time
-SELECT
-  query,
-  calls,
-  total_exec_time,
-  mean_exec_time,
-  max_exec_time,
-  stddev_exec_time,
-  rows
-FROM pg_stat_statements
-ORDER BY mean_exec_time DESC
-LIMIT 10;
-
--- Most frequently called queries
-SELECT
-  query,
-  calls,
-  total_exec_time,
-  mean_exec_time
-FROM pg_stat_statements
-ORDER BY calls DESC
-LIMIT 10;
-
--- Most time-consuming queries (total time)
-SELECT
-  query,
-  calls,
-  total_exec_time / 1000 as total_seconds,
-  mean_exec_time,
-  (total_exec_time / sum(total_exec_time) OVER ()) * 100 as percentage
-FROM pg_stat_statements
-ORDER BY total_exec_time DESC
-LIMIT 10;
-
--- Reset statistics
-SELECT pg_stat_statements_reset();
-```
-
-## uuid-ossp (UUID Generation)
-
-```sql
-CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-
--- Generate UUIDs
-SELECT uuid_generate_v1();    -- Time-based + MAC address
-SELECT uuid_generate_v4();    -- Random (most common)
-
--- Use in tables
-CREATE TABLE users (
-  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
-  email TEXT NOT NULL,
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Insert
-INSERT INTO users (email) VALUES ('user@example.com')
-RETURNING id;
-```
-
-## pg_trgm (Fuzzy String Matching)
-
-```sql
-CREATE EXTENSION IF NOT EXISTS pg_trgm;
-
--- Similarity search
-SELECT
-  email,
-  similarity(email, 'john@example.com') as sim
-FROM users
-WHERE similarity(email, 'john@example.com') > 0.3
-ORDER BY sim DESC;
-
--- LIKE optimization with trigram index
-CREATE INDEX idx_users_email_trgm ON users USING GIN(email gin_trgm_ops);
-
--- Now these queries use index:
-SELECT * FROM users WHERE email ILIKE '%john%';
-SELECT * FROM users WHERE email % 'jon@example.com';  -- Similar to
-
--- Trigram operators
-SELECT 'hello' % 'helo';              -- True (similar)
-SELECT similarity('hello', 'helo');   -- 0.5
-SELECT word_similarity('hello', 'hello world');  -- 1.0
-
--- Set similarity threshold
-SET pg_trgm.similarity_threshold = 0.5;
-SELECT * FROM users WHERE email % 'searchtext';
-```
-
-## PostGIS (Spatial and Geographic)
-
-```sql
-CREATE EXTENSION IF NOT EXISTS postgis;
-
--- Create spatial table
-CREATE TABLE locations (
-  id SERIAL PRIMARY KEY,
-  name TEXT NOT NULL,
-  geom GEOMETRY(Point, 4326)  -- WGS84 lat/lng
-);
-
--- Add spatial index
-CREATE INDEX idx_locations_geom ON locations USING GIST(geom);
-
--- Insert point (longitude, latitude)
-INSERT INTO locations (name, geom)
-VALUES ('NYC', ST_SetSRID(ST_MakePoint(-74.0060, 40.7128), 4326));
-
--- Distance queries (in meters)
-SELECT
-  name,
-  ST_Distance(
-    geom::geography,
-    ST_SetSRID(ST_MakePoint(-73.9857, 40.7484), 4326)::geography
-  ) as distance_meters
-FROM locations
-ORDER BY distance_meters
-LIMIT 10;
-
--- Within radius (1km = 1000m)
-SELECT * FROM locations
-WHERE ST_DWithin(
-  geom::geography,
-  ST_SetSRID(ST_MakePoint(-74.0060, 40.7128), 4326)::geography,
-  1000
-);
-
--- Bounding box query (very fast with GIST index)
-SELECT * FROM locations
-WHERE geom && ST_MakeEnvelope(-74.1, 40.6, -73.9, 40.8, 4326);
-
--- Contains query
-SELECT * FROM zones
-WHERE ST_Contains(geom, ST_SetSRID(ST_MakePoint(-74.0060, 40.7128), 4326));
-
--- Area calculation
-SELECT
-  name,
-  ST_Area(geom::geography) / 1000000 as area_km2
-FROM zones;
-
--- GeoJSON export
-SELECT
-  name,
-  ST_AsGeoJSON(geom) as geojson
-FROM locations;
-```
-
-## pgvector (Vector Similarity Search)
-
-```sql
-CREATE EXTENSION IF NOT EXISTS vector;
-
--- Create table with vector column
-CREATE TABLE embeddings (
-  id SERIAL PRIMARY KEY,
-  content TEXT,
-  embedding vector(1536)  -- OpenAI embeddings are 1536 dimensions
-);
-
--- Add vector index (HNSW for better performance)
-CREATE INDEX ON embeddings USING hnsw (embedding vector_cosine_ops);
--- or IVFFlat for memory efficiency:
--- CREATE INDEX ON embeddings USING ivfflat (embedding vector_cosine_ops);
-
--- Insert vectors
-INSERT INTO embeddings (content, embedding)
-VALUES ('Hello world', '[0.1, 0.2, 0.3, ...]');
-
--- Similarity search (cosine distance)
-SELECT
-  content,
-  1 - (embedding <=> '[0.1, 0.2, ...]') as similarity
-FROM embeddings
-ORDER BY embedding <=> '[0.1, 0.2, ...]'
-LIMIT 10;
-
--- Distance operators
--- <-> L2 distance (Euclidean)
--- <#> negative inner product
--- <=> cosine distance (most common for embeddings)
-
--- Set index parameters for better recall
-SET hnsw.ef_search = 100;  -- Higher = better recall, slower query
-
--- Bulk insert optimization
-SET maintenance_work_mem = '2GB';
-```
-
-## pgcrypto (Encryption and Hashing)
-
-```sql
-CREATE EXTENSION IF NOT EXISTS pgcrypto;
-
--- Hash passwords (use bcrypt)
-INSERT INTO users (email, password_hash)
-VALUES ('user@example.com', crypt('password123', gen_salt('bf', 10)));
-
--- Verify password
-SELECT * FROM users
-WHERE email = 'user@example.com'
-  AND password_hash = crypt('password123', password_hash);
-
--- Generate random values
-SELECT gen_random_uuid();
-SELECT gen_random_bytes(32);
-
--- Encrypt/decrypt data
-SELECT
-  pgp_sym_encrypt('sensitive data', 'encryption-key'),
-  pgp_sym_decrypt(encrypted_column, 'encryption-key')
-FROM table_name;
-
--- Digest functions
-SELECT digest('data', 'sha256');
-SELECT encode(digest('data', 'sha256'), 'hex');
-```
-
-## postgres_fdw (Foreign Data Wrapper)
-
-```sql
-CREATE EXTENSION IF NOT EXISTS postgres_fdw;
-
--- Create foreign server
-CREATE SERVER remote_db
-FOREIGN DATA WRAPPER postgres_fdw
-OPTIONS (host 'remote-host', port '5432', dbname 'remote_db');
-
--- User mapping
-CREATE USER MAPPING FOR current_user
-SERVER remote_db
-OPTIONS (user 'remote_user', password 'remote_password');
-
--- Import foreign schema
-IMPORT FOREIGN SCHEMA public
-FROM SERVER remote_db
-INTO remote_schema;
-
--- Or create specific foreign table
-CREATE FOREIGN TABLE remote_users (
-  id INTEGER,
-  email TEXT,
-  created_at TIMESTAMPTZ
-)
-SERVER remote_db
-OPTIONS (schema_name 'public', table_name 'users');
-
--- Query remote table (transparent)
-SELECT * FROM remote_users WHERE created_at > NOW() - INTERVAL '1 day';
-
--- Join local and remote tables
-SELECT
-  l.id,
-  l.name,
-  r.email
-FROM local_table l
-JOIN remote_users r ON l.user_id = r.id;
-```
-
-## pg_repack (Online Table Reorganization)
-
-```sql
-CREATE EXTENSION IF NOT EXISTS pg_repack;
-
--- Repack table (removes bloat, rebuilds indexes)
--- Run via command line, not SQL:
--- pg_repack -d mydb -t users
-
--- Check bloat before repack
-SELECT
-  schemaname,
-  tablename,
-  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size,
-  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename) -
-                 pg_relation_size(schemaname||'.'||tablename)) as index_size
-FROM pg_tables
-WHERE schemaname = 'public'
-ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
-
--- Repack entire database
--- pg_repack -d mydb
-
--- Repack with custom order
--- pg_repack -d mydb -t users -o "created_at DESC"
-```
-
-## timescaledb (Time-Series Data)
-
-```sql
-CREATE EXTENSION IF NOT EXISTS timescaledb;
-
--- Create hypertable (must have time column)
-CREATE TABLE metrics (
-  time TIMESTAMPTZ NOT NULL,
-  device_id INTEGER,
-  temperature DOUBLE PRECISION,
-  humidity DOUBLE PRECISION
-);
-
--- Convert to hypertable
-SELECT create_hypertable('metrics', 'time');
-
--- Set chunk interval (default 7 days)
-SELECT set_chunk_time_interval('metrics', INTERVAL '1 day');
-
--- Add compression
-ALTER TABLE metrics SET (
-  timescaledb.compress,
-  timescaledb.compress_segmentby = 'device_id',
-  timescaledb.compress_orderby = 'time DESC'
-);
-
--- Automatic compression policy (compress chunks older than 7 days)
-SELECT add_compression_policy('metrics', INTERVAL '7 days');
-
--- Retention policy (drop chunks older than 30 days)
-SELECT add_retention_policy('metrics', INTERVAL '30 days');
-
--- Continuous aggregates (materialized views for time-series)
-CREATE MATERIALIZED VIEW metrics_hourly
-WITH (timescaledb.continuous) AS
-SELECT
-  time_bucket('1 hour', time) AS bucket,
-  device_id,
-  AVG(temperature) as avg_temp,
-  MAX(temperature) as max_temp,
-  MIN(temperature) as min_temp
-FROM metrics
-GROUP BY bucket, device_id;
-
--- Refresh policy
-SELECT add_continuous_aggregate_policy('metrics_hourly',
-  start_offset => INTERVAL '3 hours',
-  end_offset => INTERVAL '1 hour',
-  schedule_interval => INTERVAL '1 hour'
-);
-```
-
-## Extension Recommendations by Use Case
-
-**Query Performance Monitoring:**
-- `pg_stat_statements` (essential)
-- `pg_stat_kcache` (cache hit statistics)
-
-**Text Search:**
-- `pg_trgm` (fuzzy matching, LIKE optimization)
-- Built-in full-text search (no extension needed)
-
-**Spatial Data:**
-- `postgis` (comprehensive spatial features)
-
-**Vector Embeddings / AI:**
-- `pgvector` (for semantic search, RAG applications)
-
-**Time-Series:**
-- `timescaledb` (automatic partitioning, compression)
-
-**Data Security:**
-- `pgcrypto` (hashing, encryption)
-- `pg_audit` (audit logging)
-
-**UUID Support:**
-- `uuid-ossp` (UUID generation)
-
-**Cross-Database Queries:**
-- `postgres_fdw` (query remote PostgreSQL)
-- `file_fdw` (query CSV files)
-
-**Table Maintenance:**
-- `pg_repack` (online bloat removal)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/postgres-pro/references/jsonb.md

@@ -1,321 +0,0 @@
-# JSONB Operations
-
-## JSONB vs JSON
-
-```sql
--- Use JSONB (binary, indexed, faster)
-CREATE TABLE documents (
-  id SERIAL PRIMARY KEY,
-  data JSONB NOT NULL
-);
-
--- NOT json (text storage, no indexing)
--- Only use json if you need to preserve exact formatting/whitespace
-```
-
-## JSONB Operators
-
-### Retrieval Operators
-
-```sql
--- -> returns JSONB
-SELECT data -> 'user' FROM documents;                    -- {"id": 123, "name": "Alice"}
-SELECT data -> 'user' -> 'name' FROM documents;          -- "Alice" (still JSONB)
-
--- ->> returns text
-SELECT data ->> 'status' FROM documents;                 -- active (text)
-SELECT data -> 'user' ->> 'name' FROM documents;         -- Alice (text)
-
--- #> for nested paths (JSONB)
-SELECT data #> '{user,address,city}' FROM documents;    -- "NYC" (JSONB)
-
--- #>> for nested paths (text)
-SELECT data #>> '{user,address,city}' FROM documents;   -- NYC (text)
-
--- Array access
-SELECT data -> 'tags' -> 0 FROM documents;               -- First tag
-SELECT jsonb_array_elements(data -> 'tags') FROM documents;  -- Expand array
-```
-
-### Containment Operators
-
-```sql
--- @> contains (most useful for indexing)
-SELECT * FROM documents WHERE data @> '{"status": "active"}';
-SELECT * FROM documents WHERE data @> '{"tags": ["postgresql"]}';
-SELECT * FROM documents WHERE data -> 'user' @> '{"role": "admin"}';
-
--- <@ is contained by
-SELECT * FROM documents WHERE '{"status": "active"}' <@ data;
-
--- ? key exists
-SELECT * FROM documents WHERE data ? 'email';
-SELECT * FROM documents WHERE data -> 'user' ? 'email';
-
--- ?| any key exists
-SELECT * FROM documents WHERE data ?| ARRAY['email', 'phone'];
-
--- ?& all keys exist
-SELECT * FROM documents WHERE data ?& ARRAY['email', 'phone'];
-```
-
-### Modification Operators
-
-```sql
--- || concatenate/merge (shallow)
-UPDATE documents SET data = data || '{"updated_at": "2024-01-01"}'::jsonb;
-
--- - remove key
-UPDATE documents SET data = data - 'temp_field';
-
--- #- remove nested path
-UPDATE documents SET data = data #- '{user,temp_field}';
-
--- jsonb_set for deep updates
-UPDATE documents
-SET data = jsonb_set(data, '{user,email}', '"new@example.com"'::jsonb)
-WHERE id = 123;
-
--- jsonb_insert
-UPDATE documents
-SET data = jsonb_insert(data, '{tags,0}', '"new-tag"'::jsonb)
-WHERE id = 123;
-```
-
-## JSONB Indexing
-
-### GIN Index (Default for containment)
-
-```sql
--- Standard GIN index (for @>, ?, ?&, ?| operators)
-CREATE INDEX idx_documents_data ON documents USING GIN(data);
-
--- Queries that benefit:
-SELECT * FROM documents WHERE data @> '{"status": "active"}';
-SELECT * FROM documents WHERE data ? 'email';
-SELECT * FROM documents WHERE data ?& ARRAY['email', 'phone'];
-```
-
-### GIN Index on Specific Path
-
-```sql
--- Index specific path for better performance
-CREATE INDEX idx_documents_status ON documents USING GIN((data -> 'status'));
-CREATE INDEX idx_documents_user ON documents USING GIN((data -> 'user'));
-
--- Smaller index, faster queries on specific paths
-SELECT * FROM documents WHERE data -> 'status' @> '"active"';
-```
-
-### GIN Index with jsonb_path_ops
-
-```sql
--- Smaller, faster index for @> queries only
-CREATE INDEX idx_documents_path_ops ON documents USING GIN(data jsonb_path_ops);
-
--- Good for: WHERE data @> '{"key": "value"}'
--- Bad for: WHERE data ? 'key' (not supported)
--- ~20% smaller than default GIN, faster for containment
-```
-
-### B-tree Index on Extracted Values
-
-```sql
--- Index extracted value (most selective)
-CREATE INDEX idx_documents_status_btree ON documents((data ->> 'status'));
-CREATE INDEX idx_documents_user_id ON documents((CAST(data -> 'user' ->> 'id' AS INTEGER)));
-
--- Enables efficient equality and range queries
-SELECT * FROM documents WHERE data ->> 'status' = 'active';
-SELECT * FROM documents WHERE CAST(data -> 'user' ->> 'id' AS INTEGER) > 1000;
-```
-
-### Expression Index for Nested Values
-
-```sql
--- Index deep nested value
-CREATE INDEX idx_documents_user_email ON documents((data #>> '{user,email}'));
-
--- Enables:
-SELECT * FROM documents WHERE data #>> '{user,email}' = 'user@example.com';
-```
-
-## Query Patterns
-
-### Filtering
-
-```sql
--- Exact match
-SELECT * FROM documents WHERE data @> '{"status": "active"}';
-
--- Multiple conditions
-SELECT * FROM documents
-WHERE data @> '{"status": "active", "verified": true}';
-
--- Nested conditions
-SELECT * FROM documents
-WHERE data -> 'user' @> '{"role": "admin"}';
-
--- Array containment
-SELECT * FROM documents
-WHERE data -> 'tags' @> '["postgresql"]';
-
--- Text search in JSONB value
-SELECT * FROM documents
-WHERE data ->> 'title' ILIKE '%postgres%';
-```
-
-### Aggregation
-
-```sql
--- Extract and aggregate
-SELECT
-  data ->> 'status' as status,
-  COUNT(*) as count,
-  AVG(CAST(data ->> 'score' AS FLOAT)) as avg_score
-FROM documents
-GROUP BY data ->> 'status';
-
--- Array aggregation
-SELECT
-  jsonb_agg(data -> 'user') as users
-FROM documents
-WHERE data @> '{"status": "active"}';
-
--- Object aggregation
-SELECT
-  jsonb_object_agg(id, data -> 'user') as user_map
-FROM documents
-WHERE data ? 'user';
-```
-
-### Array Operations
-
-```sql
--- Expand array to rows
-SELECT
-  id,
-  jsonb_array_elements(data -> 'tags') as tag
-FROM documents;
-
--- Expand array to text
-SELECT
-  id,
-  jsonb_array_elements_text(data -> 'tags') as tag
-FROM documents;
-
--- Array length
-SELECT * FROM documents
-WHERE jsonb_array_length(data -> 'tags') > 5;
-
--- Filter array elements
-SELECT
-  id,
-  jsonb_path_query_array(data, '$.tags[*] ? (@ like_regex "^post.*" flag "i")') as postgres_tags
-FROM documents;
-```
-
-## JSONB Functions
-
-```sql
--- Build JSONB
-SELECT jsonb_build_object('id', 123, 'name', 'Alice', 'active', true);
-SELECT jsonb_build_array(1, 2, 'three', true);
-
--- Object keys
-SELECT jsonb_object_keys(data) FROM documents;
-
--- Pretty print
-SELECT jsonb_pretty(data) FROM documents;
-
--- Type checking
-SELECT jsonb_typeof(data -> 'score');  -- number, string, array, object, boolean, null
-
--- Strip nulls
-SELECT jsonb_strip_nulls(data) FROM documents;
-```
-
-## JSONB Path Queries (Postgres 12+)
-
-```sql
--- jsonb_path_query for flexible queries
-SELECT jsonb_path_query(data, '$.user.address.city') FROM documents;
-
--- With filters
-SELECT jsonb_path_query(data, '$.items[*] ? (@.price > 100)') FROM documents;
-
--- Exists check
-SELECT * FROM documents
-WHERE jsonb_path_exists(data, '$.tags[*] ? (@ == "postgresql")');
-
--- Array result
-SELECT jsonb_path_query_array(data, '$.items[*].name') FROM documents;
-```
-
-## Performance Best Practices
-
-### DO
-
-```sql
--- Use specific path indexes for hot paths
-CREATE INDEX idx_docs_status ON documents((data ->> 'status'));
-
--- Use GIN index with path ops for containment-only queries
-CREATE INDEX idx_docs_pathops ON documents USING GIN(data jsonb_path_ops);
-
--- Extract frequently queried values to columns
-ALTER TABLE documents ADD COLUMN status TEXT GENERATED ALWAYS AS (data ->> 'status') STORED;
-CREATE INDEX idx_docs_status_col ON documents(status);
-
--- Use @> for indexed queries
-WHERE data @> '{"status": "active"}'  -- Fast with GIN index
-```
-
-### DON'T
-
-```sql
--- Don't use ->> with @> (mixing types)
-WHERE data @> '{"score": "100"}'  -- Wrong, comparing string
-WHERE CAST(data ->> 'score' AS INTEGER) = 100  -- Better
-
--- Don't query without indexes
-SELECT * FROM documents WHERE data -> 'nested' -> 'deep' ->> 'value' = 'x';
--- Add index: CREATE INDEX ON documents((data #>> '{nested,deep,value}'));
-
--- Don't store huge arrays in JSONB
--- If you have 10k+ elements, use a separate table
-
--- Don't use JSONB for high-update columns
--- Extract to regular column if updated frequently
-```
-
-## Schema Validation (Postgres 15+)
-
-```sql
--- Using CHECK constraints
-ALTER TABLE documents
-ADD CONSTRAINT check_data_schema
-CHECK (
-  jsonb_typeof(data) = 'object' AND
-  data ? 'id' AND
-  data ? 'status' AND
-  data ->> 'status' IN ('active', 'pending', 'archived')
-);
-```
-
-## Migration Patterns
-
-```sql
--- Add JSONB column
-ALTER TABLE users ADD COLUMN metadata JSONB DEFAULT '{}'::jsonb;
-
--- Migrate existing columns to JSONB
-UPDATE users SET metadata = jsonb_build_object(
-  'preferences', preferences,
-  'settings', settings,
-  'flags', flags
-);
-
--- Drop old columns after validation
-ALTER TABLE users DROP COLUMN preferences, DROP COLUMN settings, DROP COLUMN flags;
-```