dojo.md 0.1.0 → 0.2.1

package/courses/mysql-query-optimization/scenarios/level-5/ai-database-future.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: ai-database-future
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Explore AI-powered MySQL optimization — evaluate autonomous tuning, AI query optimization, and the evolving DBA role"
+  tags: [MySQL, AI, autonomous-tuning, machine-learning, future, master]
+
+state: {}
+
+trigger: |
+  Your CTO asks you to evaluate how AI will transform MySQL operations
+  and recommend which AI-powered technologies to invest in.
+
+  Current AI-database landscape:
+  1. Autonomous tuning (OtterTune/Releem): ML-based my.cnf optimization
+  2. AI query optimization: learned optimizers replacing cost-based
+  3. AI-powered indexing: automatic index recommendations
+  4. AI monitoring: anomaly detection, predictive alerting
+  5. Natural language to SQL: text-to-SQL for non-technical users
+  6. MySQL HeatWave: Oracle's ML-in-database for analytics
+
+  Evaluation criteria:
+  - Production readiness
+  - ROI vs complexity
+  - Risk when AI is wrong
+  - Team skill requirements
+
+  Task: Write the technology evaluation. Include: assessment of each
+  technology, adoption roadmap, text-to-SQL safety framework, and
+  prediction of how the DBA role evolves.
+
+assertions:
+  - type: llm_judge
+    criteria: "Technologies are honestly assessed — autonomous tuning (semi-ready, good ROI), learned optimizers (research stage), index advisors (ready), AI monitoring (production-ready, high ROI), text-to-SQL (risky without guardrails), HeatWave (production-ready for analytics). Avoids both hype and dismissiveness"
+    weight: 0.35
+    description: "Honest assessment"
+  - type: llm_judge
+    criteria: "Adoption roadmap is practical — separates 'adopt now' (AI monitoring, index advisors), 'evaluate' (autonomous tuning, text-to-SQL), and 'watch' (learned optimizers). Each has implementation complexity and expected timeline"
+    weight: 0.35
+    description: "Practical roadmap"
+  - type: llm_judge
+    criteria: "DBA role evolution and safety are addressed — AI augments not replaces DBAs, text-to-SQL needs guardrails (read-only, query cost limits, audit logging), and the shift from manual tuning to AI supervision"
+    weight: 0.30
+    description: "DBA evolution and safety"

package/courses/mysql-query-optimization/scenarios/level-5/behavioral-science.yaml

@@ -0,0 +1,44 @@
+meta:
+  id: behavioral-science
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Apply behavioral science to MySQL operations — nudge engineers toward good query practices and prevent performance anti-patterns at scale"
+  tags: [MySQL, behavioral-science, nudge-theory, developer-experience, culture, master]
+
+state: {}
+
+trigger: |
+  Your organization has 300 engineers writing MySQL queries. Despite
+  training and documentation, the same anti-patterns keep appearing:
+  SELECT *, missing indexes, N+1 queries, and long-running transactions.
+
+  Anti-pattern frequency (last quarter):
+  - SELECT * on wide tables: 90 new instances
+  - N+1 queries in new endpoints: 35 instances
+  - Missing WHERE on UPDATE/DELETE: 5 production incidents
+  - Queries without LIMIT: 50 instances
+  - Long transactions blocking replication: 20 incidents
+
+  Traditional approaches tried:
+  - Documentation wiki: 10% read rate
+  - Training sessions: attendance drops 60% after first
+  - Code review checklist: reviewers skip DB items under pressure
+
+  Task: Design a behavioral system for MySQL query excellence. Write:
+  choice architecture (good defaults), automated nudge system, feedback
+  loops, social proof mechanisms, and change management plan.
+
+assertions:
+  - type: llm_judge
+    criteria: "Choice architecture makes good practices default — ORM defaults to explicit columns, query timeouts configured by default, CI/CD includes automatic EXPLAIN analysis, migration tools enforce safe patterns"
+    weight: 0.35
+    description: "Choice architecture"
+  - type: llm_judge
+    criteria: "Nudge system intervenes at the right moment — IDE warnings for SELECT *, PR bot with query performance estimates, pre-deploy checks showing estimated cost, post-deploy dashboards attributing latency to deployments"
+    weight: 0.35
+    description: "Timely nudges"
+  - type: llm_judge
+    criteria: "Feedback loops and social proof create sustainable change — real-time dashboards per team, automated performance reports, gamification elements, and change management addresses resistance with measurable success metrics"
+    weight: 0.30
+    description: "Sustainable feedback loops"

package/courses/mysql-query-optimization/scenarios/level-5/benchmark-design.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: benchmark-design
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Design MySQL benchmarks — create rigorous performance tests, avoid common pitfalls, and translate results into infrastructure decisions"
+  tags: [MySQL, benchmarks, sysbench, performance-testing, capacity-planning, master]
+
+state: {}
+
+trigger: |
+  Your company needs to decide between Aurora MySQL and self-managed
+  MySQL on EC2 for a $1.5M infrastructure decision. The CTO says "run
+  benchmarks by Friday." You know naive benchmarking leads to wrong
+  conclusions.
+
+  Context:
+  - Current: Self-managed MySQL 8.0 on r6g.4xlarge
+  - Candidate: Aurora MySQL 8.0 on db.r6g.4xlarge
+  - Workload: Mixed OLTP (75% reads, 25% writes), 80K TPS
+  - Data: 500GB active, 2TB total
+  - Critical queries: point lookups, range scans, JOINs, bulk inserts
+
+  Common mistakes you've seen:
+  1. Using sysbench with data fitting in RAM (no I/O test)
+  2. Running 5-minute benchmarks (not long enough)
+  3. Testing with uniform data (not real distribution)
+  4. Single-connection tests (not concurrent load)
+  5. Ignoring storage (Aurora I/O costs vs EBS provisioned IOPS)
+  6. Not testing failure scenarios
+
+  Task: Design the benchmark plan. Write: methodology, workload design,
+  metrics to collect, pitfalls to avoid, and decision framework.
+
+assertions:
+  - type: llm_judge
+    criteria: "Methodology is rigorous — tests data larger than RAM (500GB+), runs for hours with warm-up phase, includes concurrent load matching production (100+ connections), and tests both normal and degraded modes (replica failure, high connections)"
+    weight: 0.35
+    description: "Rigorous methodology"
+  - type: llm_judge
+    criteria: "Workload represents real usage — captures 75/25 read/write mix, uses representative queries (not just simple SELECTs), realistic data distributions, and tests at multiple concurrency levels to find saturation"
+    weight: 0.35
+    description: "Realistic workload"
+  - type: llm_judge
+    criteria: "Decision framework considers more than QPS — includes latency percentiles, cost-per-transaction, operational overhead, failure behavior, and long-term cost trajectory. Acknowledges benchmarks are one input alongside operational and strategic factors"
+    weight: 0.30
+    description: "Holistic decision framework"

package/courses/mysql-query-optimization/scenarios/level-5/board-strategy.yaml

@@ -0,0 +1,48 @@
+meta:
+  id: board-strategy
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Present MySQL strategy to the board — secure multi-year investment for database modernization and position infrastructure as competitive advantage"
+  tags: [MySQL, board-strategy, investment, modernization, governance, master]
+
+state: {}
+
+trigger: |
+  You're the CTO presenting database strategy to the Board of Directors.
+  You need to secure $4M over 3 years for MySQL modernization. IPO
+  planned in 24 months.
+
+  Company: $150M ARR SaaS, 3,000 enterprise customers
+  Current: 20 MySQL clusters, 30TB, 5 DBAs, $2.5M/year infrastructure
+  Issues: 4 major outages last year (20 hours downtime), SLA breach
+  (99.5% vs promised 99.9%)
+
+  The $4M program:
+  Year 1 ($1.8M): Upgrade MySQL 5.7→8.0, deploy HA, implement monitoring
+  Year 2 ($1.3M): Migrate to Aurora, implement auto-scaling, reduce team
+  Year 3 ($0.9M): Achieve 99.99% availability, self-service platform
+
+  Board concerns:
+  - "Why not just move to the cloud and let AWS handle it?"
+  - "Can't we just hire more DBAs?"
+  - "What if we delay until after IPO?"
+  - "How does this compare to competitors?"
+
+  Task: Write the board presentation. Include: strategic framing,
+  investment case with ROI, risk of inaction, phased plan, and
+  responses to board concerns.
+
+assertions:
+  - type: llm_judge
+    criteria: "Strategic framing resonates with board — database as business asset, reliability as customer retention driver, IPO readiness (due diligence will examine infrastructure), uses business language for non-technical board members"
+    weight: 0.35
+    description: "Board-appropriate framing"
+  - type: llm_judge
+    criteria: "Investment case is compelling — ROI quantified (avoided downtime costs, SLA penalty avoidance, infrastructure cost reduction), risk of inaction (SLA breach exposure, IPO risk), phased approach reduces execution risk"
+    weight: 0.35
+    description: "Compelling investment case"
+  - type: llm_judge
+    criteria: "Board concerns addressed directly — cloud migration alone doesn't solve optimization problems, more DBAs is a band-aid, delaying increases cost and risk, competitive benchmarking provided. Responses are concise and business-focused"
+    weight: 0.30
+    description: "Concerns addressed"

package/courses/mysql-query-optimization/scenarios/level-5/comprehensive-platform.yaml

@@ -0,0 +1,49 @@
+meta:
+  id: comprehensive-platform
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Design a MySQL database platform — architect self-service provisioning, automated operations, and unified observability for a large organization"
+  tags: [MySQL, platform, self-service, automation, observability, master]
+
+state: {}
+
+trigger: |
+  You're VP of Database Platform at a company with 5,000 engineers.
+  The CEO mandates "database as a platform" — engineers should provision
+  and manage databases without DBA tickets.
+
+  Current state:
+  - 300 MySQL databases, 60 teams
+  - Provisioning time: 2 weeks (ticket-based)
+  - 12 DBAs handling all requests (bottleneck)
+  - No self-service, every change requires DBA approval
+  - No cost attribution — database costs are one lump sum
+
+  Target state:
+  - Self-service provisioning in <10 minutes
+  - Automated schema change review and deployment
+  - Unified observability across all 300 databases
+  - Cost attribution per team
+  - Automated incident detection and remediation
+
+  Budget: $3M/year for platform team (15 engineers)
+  Migration: 18 months to onboard all 300 databases
+
+  Task: Design the database platform. Write: platform architecture,
+  self-service provisioning, governance model, migration strategy for
+  300 databases, and success metrics.
+
+assertions:
+  - type: llm_judge
+    criteria: "Platform covers key components — provisioning (Terraform/Kubernetes operator), schema management (GitOps), query governance (CI/CD), observability (centralized monitoring), cost management (per-team attribution), security (automated RBAC), DR (automated backups)"
+    weight: 0.35
+    description: "Complete platform"
+  - type: llm_judge
+    criteria: "Self-service balances autonomy with governance — instant provisioning within guardrails, automated schema review, clear boundaries for self-service vs platform team approval"
+    weight: 0.35
+    description: "Balanced self-service"
+  - type: llm_judge
+    criteria: "Migration is phased and measurable — onboards 300 databases in phases, success metrics defined (provisioning time, incident MTTR, team satisfaction, cost per database), 15-engineer team structure with clear roles"
+    weight: 0.30
+    description: "Phased migration"

package/courses/mysql-query-optimization/scenarios/level-5/consulting-engagement.yaml

@@ -0,0 +1,52 @@
+meta:
+  id: consulting-engagement
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Lead a MySQL consulting engagement — assess a client's infrastructure, deliver optimization roadmap, and quantify business impact"
+  tags: [MySQL, consulting, assessment, roadmap, business-impact, master]
+
+state: {}
+
+trigger: |
+  You're a MySQL consulting lead hired by a Series B e-commerce company
+  ($100M GMV) experiencing database growing pains. They've tripled
+  engineering from 50 to 150 in 18 months and MySQL is struggling.
+
+  Client briefing:
+  - Company: ShopFast (marketplace platform)
+  - Revenue: $100M GMV, $15M take rate
+  - Database: 6 MySQL clusters, 2TB total, all MySQL 5.7
+  - Team: 1 DBA (part-time, also does DevOps), 12 backend engineers
+  - Infrastructure cost: $80K/month (growing 25%/quarter)
+  - Incidents: 4 outages last quarter (18 hours total downtime)
+
+  Assessment findings:
+  1. All 6 clusters still on MySQL 5.7 (approaching EOL)
+  2. Buffer pool at 128MB default on 3 clusters (64GB RAM servers)
+  3. 500+ queries with full table scans
+  4. No connection pooling — services connect directly
+  5. Single primary, 1 async replica — no HA
+  6. Backups: mysqldump weekly (takes 8 hours), never tested restore
+  7. No Performance Schema analysis ever performed
+  8. 30% of tables have no primary key (InnoDB performance issue)
+  9. Largest table: 500M rows, never partitioned, never optimized
+  10. Application ORM generates N+1 queries extensively
+
+  Task: Write the consulting deliverable. Include: executive assessment,
+  prioritized roadmap (quick wins, medium-term, long-term), staffing
+  recommendations, cost projection, and risk register.
+
+assertions:
+  - type: llm_judge
+    criteria: "Assessment quantifies business impact — translates each finding into cost/risk (18 hours downtime = $X revenue loss, 500+ full table scans = Y seconds of excess latency, MySQL 5.7 EOL = security risk). Prioritizes by business impact, not technical severity"
+    weight: 0.35
+    description: "Business-impact assessment"
+  - type: llm_judge
+    criteria: "Roadmap is phased and realistic — quick wins (buffer pool tuning, top 10 slow queries, add PKs to tables missing them) in weeks 1-2, medium-term (connection pooling, MySQL 8.0 upgrade, index cleanup) in months 1-3, long-term (HA setup, partitioning, monitoring) in months 3-6. Each phase has estimated cost savings"
+    weight: 0.35
+    description: "Phased roadmap"
+  - type: llm_judge
+    criteria: "Staffing and cost projections are realistic — recommends hiring a dedicated senior DBA, projects infrastructure costs with vs without optimization, and provides a framework for ongoing performance management (monitoring, query review process)"
+    weight: 0.30
+    description: "Staffing and cost"

package/courses/mysql-query-optimization/scenarios/level-5/ma-database-integration.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: ma-database-integration
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Plan database integration after M&A — merge two companies' MySQL databases while maintaining service continuity"
+  tags: [MySQL, M&A, integration, migration, schema-merge, master]
+
+state: {}
+
+trigger: |
+  Your company ($150M ARR) acquired a competitor ($40M ARR). Both run
+  MySQL. The board mandates full integration within 12 months.
+
+  Acquirer: MySQL 8.0 on Aurora, 15 clusters, 20TB, well-documented
+  Acquired: MySQL 5.7 on EC2, 5 clusters, 5TB, monolithic, 1 DBA
+
+  Challenges:
+  1. Schema conflicts: both have users, orders, payments tables with
+     different schemas and overlapping IDs
+  2. 1,500 shared customers — data must be merged, not duplicated
+  3. Acquired company stores PII in plain text
+  4. MySQL 5.7→8.0 upgrade needed
+  5. Both products must stay operational during integration
+  6. API compatibility for 3rd-party integrations
+  7. 7-year financial data retention requirement
+
+  CEO's directive: "One database, one platform, one team — 12 months.
+  Zero data loss."
+
+  Task: Write the integration plan. Include: system assessment, schema
+  unification strategy, data migration plan, phased timeline, and risk
+  mitigation.
+
+assertions:
+  - type: llm_judge
+    criteria: "Schema unification handles conflicts — defines approach for merging tables (ID mapping, namespacing), resolves overlapping customer records (deduplication with merge rules), and preserves data lineage for regulatory compliance"
+    weight: 0.35
+    description: "Schema unification"
+  - type: llm_judge
+    criteria: "Timeline is phased and realistic — breaks into assessment, preparation, parallel run, migration, decommission phases. Includes MySQL 5.7→8.0 upgrade and PII encryption remediation. Both products remain operational throughout"
+    weight: 0.35
+    description: "Phased timeline"
+  - type: llm_judge
+    criteria: "Risk mitigation covers business-critical concerns — rollback plan at each phase, data validation (row counts, financial totals), parallel running period, API compatibility layer for 3rd parties, and kill switch if customer impact detected"
+    weight: 0.30
+    description: "Business-critical risk mitigation"

package/courses/mysql-query-optimization/scenarios/level-5/master-optimization-shift.yaml

@@ -0,0 +1,56 @@
+meta:
+  id: master-optimization-shift
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Master optimization shift — advise a CEO on a complete MySQL transformation combining M&A integration, compliance, and 10x scaling"
+  tags: [MySQL, shift-simulation, transformation, comprehensive, master]
+
+state: {}
+
+trigger: |
+  You're an external database strategy advisor. A CEO calls with an
+  urgent, complex situation.
+
+  DataFlow ($300M ARR, 1,500 engineers) acquired two companies:
+  - MedTrack ($30M ARR, healthcare SaaS, HIPAA-regulated)
+  - EuroPay ($60M ARR, EU fintech, GDPR + PCI DSS)
+
+  DataFlow: MySQL 8.0 on Aurora, 20 clusters, 60TB
+  MedTrack: MySQL 5.7 on EC2, 4 clusters, 5TB
+  EuroPay: MariaDB 10.6 on Galera Cluster, 8 clusters, 25TB
+
+  Board mandates (18-month timeline):
+  1. Integrate all three databases into unified platform
+  2. Achieve HIPAA + GDPR + PCI DSS compliance
+  3. Prepare for IPO (99.99% availability, SOX compliance)
+  4. Support 10x growth ($300M → $3B ARR in 5 years)
+
+  Constraints:
+  - Combined team: 10 DBAs
+  - Infrastructure cost: $1.5M/month
+  - Zero customer data loss
+  - All 3 products remain operational during integration
+  - EU healthcare data currently stored in US (violation)
+
+  CEO: "Give me the plan — architecture, timeline, budget, risk, and
+  what to tell the board."
+
+  Task: Write the comprehensive advisory. Include: unified architecture
+  (Aurora + EC2 + Galera), compliance strategy (4 frameworks),
+  integration timeline (18 months), budget projection, and board
+  communication strategy.
+
+assertions:
+  - type: llm_judge
+    criteria: "Unified architecture handles all 3 platforms — addresses Aurora + self-managed MySQL + MariaDB/Galera consolidation, MySQL 5.7 and MariaDB 10.6 upgrade paths, and designs for 10x scale (60TB → 600TB trajectory). Architecture is realistic given 10 DBAs"
+    weight: 0.35
+    description: "Viable unified architecture"
+  - type: llm_judge
+    criteria: "Compliance achieves all 4 frameworks — HIPAA (PHI encryption, access logging), GDPR (EU data residency, right to erasure), PCI DSS (cardholder tokenization), SOX (audit trails, separation of duties). Addresses the immediate EU data residency violation. Identifies overlapping requirements to reduce effort"
+    weight: 0.35
+    description: "Multi-framework compliance"
+  - type: llm_judge
+    criteria: "Timeline, budget, and board communication are executive-ready — 18-month phased plan with milestones, budget includes infrastructure + personnel + migration costs, risk register with top 5 risks, and board narrative frames integration as competitive advantage not just cost"
+    weight: 0.30
+    description: "Executive-ready delivery"

package/courses/mysql-query-optimization/scenarios/level-5/product-development.yaml

@@ -0,0 +1,48 @@
+meta:
+  id: product-development
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Build a MySQL performance product — design a SaaS tool for MySQL optimization from architecture to go-to-market"
+  tags: [MySQL, product-development, SaaS, monitoring, optimization, master]
+
+state: {}
+
+trigger: |
+  You're a technical co-founder building a SaaS product for MySQL
+  performance optimization. After 10 years as a MySQL DBA, you want
+  to productize your expertise.
+
+  Product vision: "Autopilot for MySQL performance"
+  - Connects to any MySQL database (RDS, Aurora, self-managed)
+  - Analyzes query performance via Performance Schema
+  - Recommends indexes, configuration changes, query rewrites
+  - Optionally applies safe optimizations automatically
+
+  Competitive landscape:
+  - Percona PMM (open-source monitoring)
+  - Datadog Database Monitoring ($23/host/mo)
+  - SolarWinds Database Performance Analyzer
+  - Releem (AI-powered MySQL tuning)
+  - VividCortex/SolarWinds (query analytics)
+
+  You have $2M seed funding, 5 engineers, 12 months to product-market
+  fit (40 paying customers).
+
+  Task: Write the product strategy. Include: product architecture,
+  MVP scope, go-to-market strategy, pricing model, and 12-month
+  technical roadmap.
+
+assertions:
+  - type: llm_judge
+    criteria: "Architecture is technically sound — data collection via Performance Schema (minimal overhead), analysis engine for index/query recommendations, safe application path with testing, and multi-tenant data isolation"
+    weight: 0.35
+    description: "Sound architecture"
+  - type: llm_judge
+    criteria: "MVP is focused on fastest path to customers — identifies highest-value feature first, scopes achievable in 3-4 months, defines clear success metrics for product-market fit"
+    weight: 0.35
+    description: "Focused MVP"
+  - type: llm_judge
+    criteria: "GTM and pricing are realistic — target customer profile identified, distribution channels (MySQL community, DevOps conferences), pricing justified against competitors, 12-month roadmap with realistic milestones to 40 customers"
+    weight: 0.30
+    description: "Realistic GTM"

package/courses/mysql-query-optimization/scenarios/level-5/regulatory-compliance.yaml

@@ -0,0 +1,48 @@
+meta:
+  id: regulatory-compliance
+  level: 5
+  course: mysql-query-optimization
+  type: output
+  description: "Navigate MySQL regulatory compliance — design configurations for GDPR, PCI DSS, HIPAA, and SOX across multi-region deployments"
+  tags: [MySQL, compliance, GDPR, PCI-DSS, HIPAA, SOX, data-sovereignty, master]
+
+state: {}
+
+trigger: |
+  Your company is expanding into healthcare (HIPAA) and EU markets
+  (GDPR). Your MySQL infrastructure wasn't designed for regulatory
+  compliance. Legal gives you 6 months to comply or $25M in deals
+  will be lost.
+
+  Current MySQL infrastructure:
+  - 15 clusters, all US-East
+  - No data classification
+  - Audit logging: only general log (not tamper-evident)
+  - Encryption: TLS in transit, no at-rest encryption
+  - Access: 3 shared database users for 150 engineers
+  - Data retention: no automated deletion
+  - Backups: mysqldump, stored unencrypted
+
+  Requirements:
+  1. GDPR: EU data residency, right to erasure, breach notification
+  2. HIPAA: PHI encryption, access controls, 6-year audit retention
+  3. PCI DSS: cardholder data encryption, quarterly scans
+  4. SOX: change audit trail, separation of duties
+
+  Task: Design the compliance architecture. Write: data classification
+  strategy, encryption architecture, audit logging system, access
+  control redesign, and compliance automation.
+
+assertions:
+  - type: llm_judge
+    criteria: "Data classification and encryption are addressed — defines tiers (public/internal/confidential/restricted), maps PII/PHI/cardholder data, designs multi-region for EU residency, implements InnoDB tablespace encryption and column-level encryption for sensitive fields"
+    weight: 0.35
+    description: "Classification and encryption"
+  - type: llm_judge
+    criteria: "Access control is redesigned — replaces 3 shared users with role-based access per engineer, implements MySQL Enterprise Audit or audit plugin for tamper-evident logging, retains per regulation requirements"
+    weight: 0.35
+    description: "Access control redesign"
+  - type: llm_judge
+    criteria: "Compliance automation is continuous — automated checks, drift detection, compliance dashboard rather than point-in-time audits. Addresses right-to-erasure with soft-delete and scheduled purge"
+    weight: 0.30
+    description: "Continuous compliance"

package/courses/postgresql-query-optimization/course.yaml

@@ -0,0 +1,11 @@
+id: postgresql-query-optimization
+name: "Database Query Optimization (PostgreSQL)"
+description: >
+  Master PostgreSQL query optimization from reading execution plans to
+  enterprise database architecture. Learn indexing strategies, JOIN
+  optimization, partitioning, parallel queries, connection pooling,
+  write optimization, monitoring, and high-availability configurations
+  for large-scale PostgreSQL deployments.
+levels: 5
+scenarios_per_level: 10
+tags: [development, PostgreSQL, database, query-optimization, performance, SQL, DevOps]

package/courses/postgresql-query-optimization/scenarios/level-1/explain-analyze-basics.yaml

@@ -0,0 +1,80 @@
+meta:
+  id: explain-analyze-basics
+  level: 1
+  course: postgresql-query-optimization
+  type: output
+  description: "Read EXPLAIN ANALYZE output — interpret PostgreSQL query execution plans to identify performance bottlenecks"
+  tags: [PostgreSQL, EXPLAIN, execution-plan, query-optimization, beginner]
+
+state: {}
+
+trigger: |
+  You're a junior developer working on an e-commerce app. The product
+  listing page takes 8 seconds to load. Your tech lead asks you to
+  run EXPLAIN ANALYZE on the query and figure out what's slow.
+
+  The query:
+  SELECT p.id, p.name, p.price, c.name as category,
+         AVG(r.rating) as avg_rating
+  FROM products p
+  JOIN categories c ON c.id = p.category_id
+  LEFT JOIN reviews r ON r.product_id = p.id
+  WHERE p.active = true AND p.price BETWEEN 10 AND 100
+  GROUP BY p.id, p.name, p.price, c.name
+  ORDER BY avg_rating DESC NULLS LAST
+  LIMIT 20;
+
+  EXPLAIN ANALYZE output:
+  Limit (cost=45892.12..45892.17 rows=20 width=76)
+        (actual time=8234.521..8234.534 rows=20 loops=1)
+    -> Sort (cost=45892.12..46142.12 rows=100000 width=76)
+           (actual time=8234.519..8234.527 rows=20 loops=1)
+         Sort Key: (avg(r.rating)) DESC NULLS LAST
+         Sort Method: top-N heapsort Memory: 27kB
+      -> HashAggregate (cost=42391.50..43391.50 rows=100000 width=76)
+             (actual time=7891.234..8102.456 rows=85000 loops=1)
+           Group Key: p.id, p.name, p.price, c.name
+         -> Hash Left Join (cost=3456.78..38141.50 rows=850000 width=48)
+                (actual time=234.567..5678.901 rows=850000 loops=1)
+              Hash Cond: (r.product_id = p.id)
+              -> Seq Scan on reviews r (cost=0..28456.00 rows=1200000
+                     width=12) (actual time=0.023..1234.567 rows=1200000
+                     loops=1)
+              -> Hash (cost=3206.78..3206.78 rows=20000 width=44)
+                     (actual time=234.123..234.123 rows=18500 loops=1)
+                   Buckets: 32768 Batches: 1 Memory Usage: 1234kB
+                -> Hash Join (cost=12.50..3206.78 rows=20000 width=44)
+                       (actual time=0.345..198.765 rows=18500 loops=1)
+                     Hash Cond: (p.category_id = c.id)
+                     -> Seq Scan on products p (cost=0..3125.00
+                            rows=20000 width=40)
+                            (actual time=0.012..178.234 rows=18500
+                            loops=1)
+                           Filter: (active AND (price >= 10)
+                                    AND (price <= 100))
+                           Rows Removed by Filter: 81500
+                     -> Hash (cost=10.00..10.00 rows=200 width=12)
+                            (actual time=0.234..0.234 rows=200 loops=1)
+
+  Table sizes: products (100K rows), reviews (1.2M rows),
+  categories (200 rows).
+
+  Task: Analyze this execution plan. Explain: what each node means
+  (in plain English), where the time is being spent, why it's doing
+  sequential scans, what indexes would help, and write the optimized
+  version of this query with the recommended indexes. Explain the
+  difference between estimated and actual rows.
+
+assertions:
+  - type: llm_judge
+    criteria: "Execution plan is correctly interpreted — identifies that the sequential scan on reviews (1.2M rows) is the biggest bottleneck, explains cost vs actual time, estimated vs actual rows, and each node type (Seq Scan, Hash Join, HashAggregate, Sort, Limit). The explanation is in plain English a junior developer can understand"
+    weight: 0.35
+    description: "Correct plan interpretation"
+  - type: llm_judge
+    criteria: "Optimization recommendations are specific — suggests index on reviews(product_id) for the JOIN, index on products(active, price) for the filter, and explains why these indexes would replace sequential scans with index scans. May suggest a materialized view or covering index for further optimization"
+    weight: 0.35
+    description: "Specific optimization recommendations"
+  - type: llm_judge
+    criteria: "Explains key EXPLAIN ANALYZE concepts — cost units (arbitrary but relative), actual time (milliseconds), loops, rows removed by filter, sort methods, hash bucket sizing, and how to identify the slowest node by looking at actual time differences between parent and child nodes"
+    weight: 0.30
+    description: "Key concepts explained"

package/courses/postgresql-query-optimization/scenarios/level-1/first-optimization-shift.yaml

@@ -0,0 +1,77 @@
+meta:
+  id: first-optimization-shift
+  level: 1
+  course: postgresql-query-optimization
+  type: output
+  description: "First optimization shift — triage and fix multiple slow queries during a production performance incident"
+  tags: [PostgreSQL, optimization, shift-simulation, triage, beginner]
+
+state: {}
+
+trigger: |
+  You're on-call for a SaaS application when alerts fire at 9:00 AM
+  Monday (peak traffic). Database CPU is at 95% and climbing.
+  Response times have tripled. Users are complaining on Twitter.
+
+  Your monitoring dashboard shows:
+
+  Active connections: 180/200 (at limit)
+  Query queue: 45 queries waiting
+  Longest running query: 180 seconds (and counting)
+  Database CPU: 95%
+  Disk I/O: 98% utilization
+
+  Top 5 queries by current CPU consumption:
+
+  1. (45% CPU) Running for 180 seconds:
+     SELECT * FROM audit_logs WHERE created_at > '2020-01-01'
+     ORDER BY created_at;
+     (audit_logs has 200M rows, no LIMIT, someone ran it from an
+     admin panel)
+
+  2. (20% CPU) Running 500 concurrent copies:
+     SELECT u.*, p.* FROM users u
+     JOIN profiles p ON p.user_id = u.id
+     WHERE u.email = $1;
+     (Seq Scan on users — missing index on email)
+
+  3. (15% CPU) Running 200 concurrent copies:
+     SELECT COUNT(*) FROM products
+     WHERE category_id = $1 AND active = true;
+     (Seq Scan on products — missing index)
+
+  4. (10% CPU) Running every 5 seconds (background job):
+     UPDATE notifications SET checked_at = NOW()
+     WHERE user_id = $1 AND checked_at IS NULL;
+     (Seq Scan + row lock contention)
+
+  5. (5% CPU) Running 50 concurrent copies:
+     SELECT * FROM orders WHERE customer_id = $1
+     ORDER BY created_at DESC LIMIT 10;
+     (Using an index but fetching too many columns)
+
+  Available actions:
+  - Kill specific queries (pg_terminate_backend)
+  - Create indexes (takes time on large tables)
+  - Modify application code (requires deploy)
+  - Add connection pooling (PgBouncer not yet set up)
+  - Scale up database instance
+
+  Task: Triage and fix this incident. Write: the immediate actions
+  (first 5 minutes), the short-term fixes (next hour), the medium-
+  term improvements (this week), and the monitoring setup to prevent
+  this from recurring.
+
+assertions:
+  - type: llm_judge
+    criteria: "Immediate triage is correct — kills the 200M-row audit_logs query first (45% CPU), considers killing or limiting long-running queries, and doesn't create indexes under 95% CPU load (would make things worse). Prioritizes by impact"
+    weight: 0.35
+    description: "Correct immediate triage"
+  - type: llm_judge
+    criteria: "Short-term fixes address root causes — index on users(email) for the most frequent query, index on products(category_id, active) for the product count, application-level statement_timeout to prevent unbounded queries, and connection pooling to handle the 180/200 connection pressure"
+    weight: 0.35
+    description: "Root cause fixes"
+  - type: llm_judge
+    criteria: "Prevention measures are practical — sets statement_timeout for different query types, implements pg_stat_statements monitoring, adds connection pooling, puts row limits on admin panel queries, and sets up alerting on slow queries and connection count before hitting limits"
+    weight: 0.30
+    description: "Practical prevention measures"