@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/claude-code/db-expression-index/SKILL.md

@@ -0,0 +1,211 @@
+# Expression and Specialized Indexes
+
+> Indexes on computed expressions and specialized index types (GIN, GiST) for non-scalar data like JSONB, arrays, and full-text search.
+
+## When to Use
+
+- Case-insensitive searches using `lower()` or `upper()`
+- JSONB key lookups and containment queries
+- Full-text search with `tsvector` and `tsquery`
+- Array containment queries (`@>`, `&&`)
+- Geometric, spatial, or range data types
+
+## Instructions
+
+### Key Concepts
+
+An **expression index** indexes the result of a function or expression, not the raw column value:
+
+```sql
+CREATE INDEX idx_users_lower_email ON users (lower(email));
+```
+
+The query **must use the exact same expression** for the planner to match it:
+
+```sql
+-- Uses the index (expression matches):
+SELECT * FROM users WHERE lower(email) = 'user@example.com';
+
+-- Does NOT use the index (different function):
+SELECT * FROM users WHERE upper(email) = 'USER@EXAMPLE.COM';
+```
+
+**GIN (Generalized Inverted Index)** is designed for values containing multiple elements:
+
+```sql
+-- Array containment:
+CREATE INDEX idx_posts_tags ON posts USING GIN (tags);
+SELECT * FROM posts WHERE tags @> ARRAY['postgresql'];
+
+-- JSONB containment:
+CREATE INDEX idx_events_meta ON events USING GIN (metadata);
+SELECT * FROM events WHERE metadata @> '{"type": "purchase"}';
+```
+
+GIN indexes build an inverted index -- each distinct element (array value, JSONB key, text lexeme) maps to a list of row locations. This makes containment and membership queries fast.
+
+**GiST (Generalized Search Tree)** supports geometric, range, and full-text data with operators like overlap (`&&`), contains (`@>`), and nearest-neighbor (`<->`):
+
+```sql
+CREATE INDEX idx_locations_geo ON locations USING GiST (coordinates);
+SELECT * FROM locations WHERE coordinates && circle('(0,0)', 10);
+```
+
+### Worked Example
+
+JSONB metadata search on an events table with 20M rows:
+
+```sql
+CREATE TABLE events (
+  id         SERIAL PRIMARY KEY,
+  event_type TEXT NOT NULL,
+  metadata   JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+**Approach 1: GIN index for ad-hoc JSONB queries:**
+
+```sql
+CREATE INDEX idx_events_meta_gin ON events USING GIN (metadata);
+```
+
+```sql
+EXPLAIN ANALYZE
+SELECT id, event_type
+FROM events
+WHERE metadata @> '{"type": "purchase", "source": "mobile"}';
+```
+
+```
+Bitmap Heap Scan on events
+  (cost=45.21..12345.67 rows=2100 width=12)
+  (actual time=1.234..8.901 rows=1987 loops=1)
+  Recheck Cond: (metadata @> '{"type": "purchase", "source": "mobile"}')
+  ->  Bitmap Index Scan on idx_events_meta_gin
+        (actual time=1.102..1.102 rows=1987 loops=1)
+Execution Time: 9.432 ms
+```
+
+**Approach 2: Expression index for a single frequently queried key:**
+
+```sql
+CREATE INDEX idx_events_type_expr ON events ((metadata->>'type'));
+```
+
+```sql
+EXPLAIN ANALYZE
+SELECT id, event_type
+FROM events
+WHERE metadata->>'type' = 'purchase';
+```
+
+```
+Index Scan using idx_events_type_expr on events
+  (cost=0.43..4521.23 rows=18500 width=12)
+  (actual time=0.025..12.341 rows=18200 loops=1)
+  Index Cond: ((metadata ->> 'type') = 'purchase')
+Execution Time: 13.102 ms
+```
+
+**When to use which:** GIN for ad-hoc queries across any combination of JSONB keys. Expression index for a single known key queried at high frequency -- smaller index, faster single-key lookup.
+
+### Anti-Patterns
+
+1. **Expression mismatch.** Index on `lower(email)` but query uses `UPPER(email)` -- the planner cannot match different functions. The expression must be identical.
+
+2. **GIN on small scalar columns.** GIN is designed for multi-element data types. Using GIN on a simple TEXT column is overkill -- use a B-tree.
+
+3. **Expensive expressions in indexes.** The expression is evaluated on every INSERT and UPDATE. A computationally expensive function (e.g., involving network calls or complex parsing) in an expression index severely impacts write performance.
+
+4. **GiST when B-tree suffices.** For simple scalar comparisons, B-tree is faster and smaller. GiST is for data types with complex relationships (geometry, ranges, full-text).
+
+### PostgreSQL Specifics
+
+**Trigram indexes for pattern matching.** The `pg_trgm` extension enables GIN indexes that support `LIKE '%pattern%'` (leading wildcard) queries:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE INDEX idx_users_name_trgm ON users USING GIN (name gin_trgm_ops);
+
+-- Now this uses the index:
+SELECT * FROM users WHERE name LIKE '%alice%';
+```
+
+**Full-text search with tsvector and GIN:**
+
+```sql
+CREATE INDEX idx_posts_fts ON posts USING GIN (to_tsvector('english', body));
+SELECT * FROM posts WHERE to_tsvector('english', body) @@ to_tsquery('postgresql & indexing');
+```
+
+**GIN fastupdate.** By default, GIN indexes use a "pending list" to batch insertions, trading faster writes for slightly slower reads. Disable for read-heavy workloads:
+
+```sql
+CREATE INDEX idx_meta_gin ON events USING GIN (metadata) WITH (fastupdate = off);
+```
+
+## Details
+
+### Advanced Topics
+
+**GIN pending list.** The `gin_pending_list_limit` setting (default 4MB) controls the pending list size. Larger values improve write throughput at the cost of slower first reads after inserts. `VACUUM` flushes the pending list.
+
+**GiST vs SP-GiST.** SP-GiST (Space-Partitioned GiST) is optimized for data that can be partitioned into non-overlapping regions (quad-trees, k-d trees). Use SP-GiST for IP addresses (`inet`), text with prefix matching, and point data with spatial partitioning.
+
+**BRIN indexes** (Block Range Indexes) for naturally ordered data like time-series. BRIN stores min/max values per block range rather than per row -- extremely small indexes for large, physically ordered tables:
+
+```sql
+CREATE INDEX idx_events_brin ON events USING BRIN (created_at);
+```
+
+**RUM indexes** (extension) extend GIN with ordering support for full-text search, enabling `ORDER BY ts_rank()` without a separate sort step.
+
+### Engine Differences
+
+**MySQL 8.0** supports functional indexes with similar syntax:
+
+```sql
+CREATE INDEX idx_lower_email ON users ((LOWER(email)));
+```
+
+**MySQL has no GIN equivalent.** Full-text search uses FULLTEXT indexes with different syntax:
+
+```sql
+-- MySQL full-text:
+CREATE FULLTEXT INDEX idx_posts_body ON posts (body);
+SELECT * FROM posts WHERE MATCH(body) AGAINST('postgresql indexing' IN BOOLEAN MODE);
+```
+
+MySQL FULLTEXT indexes use an inverted index internally but with different operators and ranking algorithms than PostgreSQL's GIN + tsvector approach.
+
+**MySQL spatial indexes** use R-tree (similar to GiST) via the `SPATIAL` keyword but support fewer operators and data types than PostgreSQL's GiST.
+
+### Real-World Case Studies
+
+**Multi-tenant SaaS storing tenant configuration in JSONB.** Each tenant had a `config JSONB` column with nested feature flags, plan details, and custom settings. Before indexing, admin queries like `WHERE config @> '{"feature_flags": {"beta": true}}'` scanned 2M tenant rows (12 seconds). Adding a GIN index on the `config` column enabled Bitmap Index Scan, dropping the query to 15ms. The GIN index consumed 180MB -- acceptable for eliminating full table scans on an admin dashboard used hundreds of times daily.
+
+## Source
+
+- [PostgreSQL Expression Indexes](https://www.postgresql.org/docs/current/indexes-expressional.html)
+- [PostgreSQL GIN Indexes](https://www.postgresql.org/docs/current/gin.html)
+- [PostgreSQL GiST Indexes](https://www.postgresql.org/docs/current/gist.html)
+
+## Process
+
+1. Read the key concepts to understand expression indexes, GIN, and GiST and their appropriate use cases.
+2. Apply expression indexes when queries use function-wrapped columns, GIN for multi-element containment queries, and GiST for geometric/range data.
+3. Verify with EXPLAIN ANALYZE that the planner uses the specialized index and that the query expression matches the index expression exactly.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-btree-index, db-partial-index, db-composite-index, db-explain-reading
+
+## Success Criteria
+
+- Expression indexes match the exact expression used in queries.
+- GIN is chosen for array, JSONB, and full-text containment queries.
+- GiST is chosen for geometric, range, and nearest-neighbor queries.
+- Anti-patterns (expression mismatch, GIN on scalars) are avoided.

package/dist/agents/skills/claude-code/db-expression-index/skill.yaml

@@ -0,0 +1,40 @@
+name: db-expression-index
+version: '1.0.0'
+description: Indexes on computed expressions, functional indexes, and specialized index types (GIN, GiST)
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-btree-index
+  - db-partial-index
+  - db-composite-index
+  - db-explain-reading
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - expression-index
+  - functional-index
+  - GIN
+  - GiST
+  - computed-index
+  - jsonb-index
+  - full-text-search
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/indexes-expressional.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/db-first-normal-form/SKILL.md

@@ -0,0 +1,190 @@
+# First Normal Form (1NF)
+
+> Every column holds a single atomic value, no repeating groups exist, and every row is uniquely identifiable by a primary key.
+
+## When to Use
+
+- Designing new tables from scratch
+- Reviewing an existing schema for normalization violations
+- Refactoring columns that store CSV lists, JSON arrays, or delimited strings
+- Migrating data from spreadsheets or flat files into a relational database
+- Auditing tables that lack a primary key
+
+## Instructions
+
+First Normal Form defines the baseline for a well-structured relational table. A table is in 1NF when it satisfies three rules.
+
+### Rule 1: Every Column Holds Atomic Values
+
+Each cell must contain a single, indivisible value. No lists, no comma-separated strings, no embedded structures.
+
+**BAD -- tags crammed into one column:**
+
+```sql
+CREATE TABLE articles (
+  id       SERIAL PRIMARY KEY,
+  title    TEXT NOT NULL,
+  tags     TEXT  -- 'postgresql,normalization,database'
+);
+```
+
+Querying "find all articles tagged postgresql" now requires `LIKE '%postgresql%'` or string splitting -- neither is indexable or correct (matches "not-postgresql" too).
+
+**GOOD -- junction table for multi-valued relationship:**
+
+```sql
+CREATE TABLE articles (
+  id    SERIAL PRIMARY KEY,
+  title TEXT NOT NULL
+);
+
+CREATE TABLE tags (
+  id   SERIAL PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE
+);
+
+CREATE TABLE article_tags (
+  article_id INT REFERENCES articles(id),
+  tag_id     INT REFERENCES tags(id),
+  PRIMARY KEY (article_id, tag_id)
+);
+```
+
+Now `SELECT a.title FROM articles a JOIN article_tags at ON a.id = at.article_id JOIN tags t ON at.tag_id = t.id WHERE t.name = 'postgresql';` is indexable, correct, and constraint-enforced.
+
+### Rule 2: No Repeating Groups
+
+Do not model a variable-length list as numbered columns.
+
+**BAD -- phone1/phone2/phone3 pattern:**
+
+```sql
+CREATE TABLE contacts (
+  id     SERIAL PRIMARY KEY,
+  name   TEXT NOT NULL,
+  phone1 TEXT,
+  phone2 TEXT,
+  phone3 TEXT
+);
+```
+
+This caps phones at three, wastes space when contacts have one, and makes queries painful (`WHERE phone1 = ? OR phone2 = ? OR phone3 = ?`).
+
+**GOOD -- separate rows:**
+
+```sql
+CREATE TABLE contacts (
+  id   SERIAL PRIMARY KEY,
+  name TEXT NOT NULL
+);
+
+CREATE TABLE contact_phones (
+  id         SERIAL PRIMARY KEY,
+  contact_id INT REFERENCES contacts(id),
+  phone      TEXT NOT NULL,
+  label      TEXT  -- 'mobile', 'work', 'home'
+);
+```
+
+### Rule 3: Every Table Has a Primary Key
+
+Every row must be uniquely identifiable. Without a primary key, the table is a bag of rows -- duplicates are undetectable and foreign keys cannot reference it.
+
+```sql
+CREATE TABLE products (
+  id    SERIAL PRIMARY KEY,
+  sku   TEXT NOT NULL UNIQUE,
+  name  TEXT NOT NULL,
+  price NUMERIC(10,2) NOT NULL CHECK (price >= 0)
+);
+```
+
+### Worked Example: E-Commerce Order Import
+
+A CSV export contains: `order_id, customer, items("Widget,Gadget,Bolt"), quantities("2,1,5")`.
+
+Step 1 -- create atomic tables:
+
+```sql
+CREATE TABLE orders (
+  id       SERIAL PRIMARY KEY,
+  customer TEXT NOT NULL
+);
+
+CREATE TABLE order_lines (
+  id        SERIAL PRIMARY KEY,
+  order_id  INT REFERENCES orders(id),
+  item_name TEXT NOT NULL,
+  quantity  INT NOT NULL CHECK (quantity > 0)
+);
+```
+
+Step 2 -- load one row per item instead of one row per order.
+
+### Anti-Patterns
+
+1. **JSON arrays as a normalization shortcut.** Storing `tags jsonb DEFAULT '[]'` avoids the junction table but makes constraint enforcement, joins, and indexing harder. Reserve JSONB for genuinely schemaless data.
+2. **TEXT columns for structured data.** A `metadata TEXT` column containing key-value pairs is a schema within a schema. Define real columns or use a typed JSONB column with a CHECK constraint.
+3. **Missing primary keys.** Tables without a primary key invite duplicate rows and block foreign key references. Every table gets a primary key -- no exceptions.
+4. **Splitting atoms too far.** Do not split a phone number into country code, area code, and subscriber number unless you query those parts independently. Atomicity is relative to your query patterns.
+
+### PostgreSQL Specifics
+
+PostgreSQL arrays (`TEXT[]`, `INT[]`) technically violate 1NF but are acceptable for specific use cases:
+
+- Tag lists that are always read and written as a whole
+- Full-text search vectors (`tsvector`)
+- GIN-indexed containment queries (`WHERE tags @> ARRAY['postgresql']`)
+
+When you find yourself using `unnest()` to join array elements with another table, that is the signal to normalize into a junction table instead.
+
+### MySQL Callout
+
+MySQL lacks native array types. 1NF violations in MySQL typically manifest as comma-separated strings parsed with `FIND_IN_SET()`. This is always wrong in production -- it defeats indexing, prevents constraint enforcement, and returns incorrect results for substring matches.
+
+## Details
+
+### Why 1NF Matters
+
+- **Query correctness.** Atomic values enable exact-match queries and proper joins. Comma-separated values require pattern matching that produces false positives.
+- **Indexing.** B-tree indexes work on atomic column values. You cannot efficiently index into a substring of a TEXT column.
+- **Constraint enforcement.** Foreign keys, UNIQUE constraints, and CHECK constraints operate on column values. Non-atomic values bypass all of them.
+- **Aggregation.** `COUNT`, `SUM`, and `GROUP BY` operate on rows. If one row contains multiple values packed into a string, aggregations are wrong without preprocessing.
+
+### The Array Exception in PostgreSQL
+
+PostgreSQL arrays with GIN indexes support efficient containment queries:
+
+```sql
+CREATE INDEX idx_tags ON articles USING GIN (tags);
+SELECT * FROM articles WHERE tags @> ARRAY['postgresql'];
+```
+
+This is valid when: (1) you never need to join tag values to another table, (2) you never need referential integrity on tag values, and (3) the array is small and treated as an opaque unit. When any of these conditions fails, normalize.
+
+### Real-World Case Study: Logging Platform Migration
+
+A SaaS logging platform stored log labels as `labels TEXT` containing `"env=prod,service=api,region=us-east"`. Queries used `LIKE '%service=api%'`. After normalizing into a `log_labels(log_id, key, value)` table with a composite index on `(key, value)`, query latency dropped from 1200ms to 8ms for label-filtered searches. Storage increased 15% but query performance improved 150x.
+
+## Source
+
+- [PostgreSQL DDL Basics](https://www.postgresql.org/docs/current/ddl-basics.html)
+- Date, C.J. "An Introduction to Database Systems" (8th Edition), Chapter 12
+- Codd, E.F. "A Relational Model of Data for Large Shared Data Banks" (1970)
+
+## Process
+
+1. Read the rules and examples in this document.
+2. Apply the three 1NF rules to your schema design, decomposing non-atomic columns and adding primary keys.
+3. Verify your implementation by checking that every column holds a single value, no numbered column groups exist, and every table has a primary key.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-second-normal-form, db-third-normal-form, db-denormalization
+
+## Success Criteria
+
+- The three rules of 1NF are applied correctly to every table in the schema.
+- Anti-patterns listed in this document (CSV columns, repeating groups, missing keys) are identified and eliminated.

package/dist/agents/skills/claude-code/db-first-normal-form/skill.yaml

@@ -0,0 +1,38 @@
+name: db-first-normal-form
+version: '1.0.0'
+description: Atomic values, no repeating groups, and primary key requirement for First Normal Form (1NF)
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-second-normal-form
+  - db-third-normal-form
+  - db-denormalization
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - normalization
+  - first-normal-form
+  - 1NF
+  - atomic-values
+  - repeating-groups
+  - primary-key
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/ddl-basics.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/db-graph-in-relational/SKILL.md

@@ -0,0 +1,212 @@
+# Graph Relationships in Relational Databases
+
+> Modeling vertices and edges in SQL tables for social graphs, dependency networks, and recommendation systems with recursive queries -- and knowing when SQL stops being practical.
+
+## When to Use
+
+- Social connections (followers, friends, blocking relationships)
+- Dependency graphs (package managers, build systems, task dependencies)
+- Recommendation engines (user-item-user collaborative filtering)
+- Fraud detection networks (transaction chains between accounts)
+- Any many-to-many relationship with path traversal queries where the graph is secondary to the primary relational model
+
+## Instructions
+
+### Key Concepts
+
+**Basic graph schema** -- vertices (nodes) and edges (relationships):
+
+```sql
+CREATE TABLE vertices (
+  id         serial PRIMARY KEY,
+  label      varchar NOT NULL,
+  properties jsonb DEFAULT '{}'
+);
+
+CREATE TABLE edges (
+  id         serial PRIMARY KEY,
+  source_id  int NOT NULL REFERENCES vertices(id) ON DELETE CASCADE,
+  target_id  int NOT NULL REFERENCES vertices(id) ON DELETE CASCADE,
+  label      varchar NOT NULL,
+  weight     float DEFAULT 1.0,
+  properties jsonb DEFAULT '{}'
+);
+
+CREATE INDEX idx_edges_source ON edges (source_id);
+CREATE INDEX idx_edges_target ON edges (target_id);
+```
+
+**Directed vs undirected:** For undirected graphs, either store both directions (A->B and B->A) or query with `WHERE source_id = ? OR target_id = ?`. Storing both directions doubles storage but simplifies and speeds up queries.
+
+**Path queries via recursive CTE:**
+
+```sql
+-- All nodes reachable from vertex 1 within 3 hops
+WITH RECURSIVE reachable AS (
+  SELECT target_id AS id, 1 AS hops, ARRAY[source_id, target_id] AS path
+  FROM edges WHERE source_id = 1
+
+  UNION ALL
+
+  SELECT e.target_id, r.hops + 1, r.path || e.target_id
+  FROM edges e
+  JOIN reachable r ON e.source_id = r.id
+  WHERE r.hops < 3
+    AND e.target_id != ALL(r.path)  -- cycle detection
+)
+SELECT DISTINCT id, hops FROM reachable;
+```
+
+The `path` array tracks visited nodes for cycle detection. The `hops < 3` clause bounds traversal depth.
+
+**When SQL stops being practical:**
+
+- Variable-length paths exceeding 5-6 hops
+- Graph algorithms (PageRank, community detection, betweenness centrality)
+- Real-time traversals on graphs with more than 10M edges
+- Pattern matching across multiple edge types simultaneously
+
+At these thresholds, consider a dedicated graph database (Neo4j, Amazon Neptune) or a graph extension (Apache AGE for PostgreSQL).
+
+### Worked Example
+
+Social network "people you may know" (friends-of-friends):
+
+```sql
+CREATE TABLE users (
+  id   serial PRIMARY KEY,
+  name varchar NOT NULL
+);
+
+CREATE TABLE friendships (
+  user_id   int NOT NULL REFERENCES users(id),
+  friend_id int NOT NULL REFERENCES users(id),
+  PRIMARY KEY (user_id, friend_id)
+);
+
+CREATE INDEX idx_friendships_friend ON friendships (friend_id);
+```
+
+**Direct friends of user 1:**
+
+```sql
+SELECT u.* FROM users u
+JOIN friendships f ON u.id = f.friend_id
+WHERE f.user_id = 1;
+```
+
+**Friends-of-friends (2-hop) excluding direct friends:**
+
+```sql
+WITH direct_friends AS (
+  SELECT friend_id FROM friendships WHERE user_id = 1
+),
+friends_of_friends AS (
+  SELECT DISTINCT f2.friend_id
+  FROM friendships f1
+  JOIN friendships f2 ON f1.friend_id = f2.user_id
+  WHERE f1.user_id = 1
+    AND f2.friend_id != 1
+    AND f2.friend_id NOT IN (SELECT friend_id FROM direct_friends)
+)
+SELECT u.*, count(*) AS mutual_friends
+FROM friends_of_friends fof
+JOIN friendships f ON fof.friend_id = f.friend_id
+JOIN direct_friends df ON f.user_id = df.friend_id
+JOIN users u ON u.id = fof.friend_id
+GROUP BY u.id, u.name
+ORDER BY mutual_friends DESC;
+```
+
+**The performance cliff:** On a graph with 1M edges, 2-hop traversal completes in ~50ms. 3-hop: ~2 seconds. 4-hop: timeout. Each additional hop multiplies the working set by the average node degree.
+
+### Anti-Patterns
+
+1. **Storing graph data in a single self-join table when traversal depth varies.** Use proper vertex/edge tables with indexes on both source and target.
+2. **Unbounded recursive CTEs on user-generated graphs.** Without depth limits, a densely connected graph causes infinite loops or memory exhaustion. Always include a `hops < N` bound.
+3. **Using SQL for graph algorithms.** PageRank, shortest-path-with-weights (Dijkstra), and community detection are impractical in SQL. Use a graph DB or application-layer library (NetworkX, igraph).
+4. **Not indexing both `source_id` and `target_id` on the edges table.** Reverse traversals (who points to X?) are common and require the target index.
+5. **Modeling everything as a graph.** If your queries are primarily key-value or tabular, adding graph structure adds complexity without benefit.
+
+### PostgreSQL Specifics
+
+**Apache AGE extension** adds the Cypher query language to PostgreSQL:
+
+```sql
+-- After installing AGE extension
+SELECT * FROM cypher('social_graph', $$
+  MATCH (a:User {name: 'Alice'})-[:FRIENDS_WITH*2..3]-(b:User)
+  WHERE a <> b
+  RETURN DISTINCT b.name
+$$) AS (name agtype);
+```
+
+AGE allows graph queries without leaving PostgreSQL -- useful when the graph is a secondary concern alongside relational data.
+
+**Recursive CTE with CYCLE clause** (PostgreSQL 14+):
+
+```sql
+WITH RECURSIVE paths AS (
+  SELECT source_id, target_id, 1 AS depth FROM edges WHERE source_id = 1
+  UNION ALL
+  SELECT p.source_id, e.target_id, p.depth + 1
+  FROM paths p JOIN edges e ON p.target_id = e.source_id
+  WHERE p.depth < 5
+)
+CYCLE target_id SET is_cycle USING path
+SELECT * FROM paths WHERE NOT is_cycle;
+```
+
+**JSONB properties** on vertices and edges enable flexible schema evolution. Add a GIN index for filtered graph queries: `CREATE INDEX ON vertices USING gin (properties);`.
+
+## Details
+
+### Advanced Topics
+
+**Weighted shortest path (Dijkstra in SQL):** Technically possible with recursive CTEs tracking cumulative weight, but impractical for large graphs. Each step explores all outgoing edges, and pruning (stopping when a shorter path is already found) requires subquery tricks that the optimizer handles poorly. For weighted shortest path, export to an application-layer library.
+
+**Bidirectional search:** Start from both source and target, meeting in the middle. Reduces traversal from O(b^d) to O(2 \* b^(d/2)) where b is branching factor and d is depth. Implementable in SQL with two recursive CTEs joined on intersection, but complex to write correctly.
+
+**Materialized graph views:** Pre-compute common traversals (e.g., 2-hop friend connections) in a materialized table. Refresh periodically. Trades storage and freshness for query speed.
+
+**Hybrid architecture:** Use PostgreSQL for transactional graph storage and integrity. Export to Neo4j or NetworkX for analytics (PageRank, community detection, path algorithms). This avoids a full migration to a graph database while enabling graph-native operations where SQL falls short.
+
+### Engine Differences
+
+MySQL 8.0+ supports recursive CTEs for graph traversal with compatible syntax.
+
+Key MySQL differences:
+
+- MySQL lacks the `CYCLE` clause -- cycle detection requires manual path tracking with a VARCHAR or JSON column
+- MySQL lacks JSONB -- use `JSON` column type with generated columns for indexing vertex/edge properties
+- No Apache AGE equivalent for MySQL
+- MySQL's `cte_max_recursion_depth` (default 1000) limits traversal depth
+- MySQL recursive CTE performance is comparable to PostgreSQL for shallow traversals (under 5 hops)
+
+### Real-World Case Studies
+
+**Fraud detection platform modeling transaction networks.** 5M accounts as vertices, 50M transactions as edges. The core query: "who transacted with someone who transacted with suspect X?" (2-hop). PostgreSQL with indexed edges: 120ms for 2-hop queries. 3-hop queries: 8 seconds -- unacceptable for real-time alerting. The team moved 3+ hop analysis to Neo4j while keeping transactional data and 1-2 hop queries in PostgreSQL. The hybrid approach saved 6 months of engineering time compared to a full migration to a graph database. PostgreSQL handles ACID transactions on account balances; Neo4j handles network pattern detection.
+
+## Source
+
+- [PostgreSQL WITH RECURSIVE](https://www.postgresql.org/docs/current/queries-with.html)
+- [Apache AGE](https://age.apache.org/)
+
+## Process
+
+1. Read the key concepts to understand vertex/edge schema design and recursive CTE traversal patterns.
+2. Apply bounded recursive queries with cycle detection for graph traversal in SQL.
+3. Verify with EXPLAIN ANALYZE that traversal queries use indexes and complete within acceptable latency at each hop count.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-adjacency-list, db-closure-table, db-hierarchical-data, db-query-rewriting
+
+## Success Criteria
+
+- Graph queries are bounded by depth (max hops specified).
+- Performance is validated with EXPLAIN ANALYZE at each hop count to detect performance cliffs.
+- A dedicated graph DB is considered when traversal regularly exceeds 3-4 hops on large datasets.
+- Both source and target columns on the edges table are indexed.