YAML SQL Navigator

Smart navigation and SQL linting for YAML configurations with embedded SQL references

A VS Code extension that supercharges your workflow when working with YAML configuration files that reference SQL scripts. Perfect for Airflow DAGs, data pipelines, and any project where YAML orchestrates SQL execution.

---

✨ Key Features

🔗 1. YAML Anchor Navigation & IntelliSense

Navigate between YAML anchor definitions and their references instantly, just like code navigation in programming languages. Plus, get smart autocomplete when typing anchor references!

Example:

# Define reusable configuration
variables: &common_vars
  schema: analytics
  date_from: '2024-01-01'
  date_to: '2024-12-31'

als_features: &als_author_features_table
  schema: ml_features
  table: als_author_v1

tasks:
  load_users:
    type: 'dlh'
    # Reference the anchor - Cmd+Click to see all usages!
    vars: *common_vars
    
  load_orders:
    vars: *common_vars  # Jump between all references
    
  join_features:
    # Type * and get autocomplete popup with all anchors! 🎯
    join_table: *als_author_features_table

What you can do:

• Type * → Get IntelliSense popup with all available anchors (like method autocomplete!)
  • Shows anchor name with preview of value
  • Displays line number where defined
  • Full YAML snippet in tooltip
  • Filters as you type (e.g., *als shows only anchors starting with "als")
• Cmd+Click on &common_vars → See all places where *common_vars is used
• Cmd+Click on *common_vars → Jump to the &common_vars definition
• Find All References → List all usages of any anchor across your YAML file
• Get red error markers for broken anchor links (e.g., *undefined_anchor)
• Anchor name validation → Warns about invalid names (dots, special chars) that cause Airflow errors

---

🔍 2. SQL File Navigation & Smart Preview with Variable Replacement

Click through to SQL files directly from your YAML, with instant previews on hover that show both raw SQL and replaced SQL with your actual values!

Example:

tasks:
  calculate_metrics:
    type: 'dlh'
    sql_file: support_tables/analytics/calculate_revenue.sql
    replacements:
      start_date: '2024-01-01'
      schema: prod_analytics
      table_name: revenue_facts

What you can do:

• Hover over the SQL file path → See:
  • 📄 Raw SQL with {variables} placeholders
  • 📊 Line count and detected SQL variables
  • ✨ SQL after replacements - see the actual query that will run!
  • 🎯 Full variable substitution using your YAML replacements section
• Cmd+Click on the path → Open the SQL file instantly
• Autocomplete → Type sql_file: and get suggestions from your SQL scripts folder
• Get red error markers for missing SQL files
• Works with inline SQL via YAML anchors too!

---

🚨 3. Smart SQL Linting with sqruff

Real-time validation of your SQL files with intelligent error reporting directly in your YAML.

Example YAML:

tasks:
  user_analysis:
    type: 'dlh'
    sql_file: analytics/user_stats.sql
    variables:
      schema: analytics
      table_name: users
      # Missing: date_from (required by SQL)

Example SQL (user_stats.sql):

SELECT 
    user_id,
    COUNT(*) as action_count,
    MAX(created_at) as last_action
FROM {schema}.{table_name}
WHERE created_at >= '{date_from}'  -- date_from is missing in YAML!
  AND created_at <= '{date_to}'     -- date_to is also missing!
GROUP BY user_id

What you get:

• ✅ Red underlines on task names and sql_file lines when variables are missing
• ✅ Clickable tooltips showing which variables are missing
• ✅ SQL quality checks using sqruff (linting for style, syntax, best practices)
• ✅ Trino dialect support for type: 'dlh' tasks with automatic dialect detection
• ✅ Quick Fix button to auto-fix SQL formatting issues
• ✅ Inline SQL support - works with YAML anchors containing SQL queries

Tooltip example:

❌ Missing variables in SQL file:
  - date_from (line 5)
  - date_to (line 6)

⚠️ SQL linting errors:
  sqruff CP01 (Line 2): Keywords must be consistently lower case
  sqruff CP03 (Line 3): Function names must be consistently upper case
  
🔧 Click to fix SQL issues

---

🎯 4. Trino SQL Interval Validation

Automatic detection and fixing of incorrect Trino interval syntax.

Before (incorrect):

SELECT *
FROM events
WHERE event_time >= CURRENT_DATE - interval '3 days'

After (correct):

SELECT *
FROM events
WHERE event_time >= CURRENT_DATE - INTERVAL '3' DAY

What you get:

• 🔴 Error markers for incorrect interval syntax
• 🔧 One-click fix to convert to proper Trino syntax
• ✅ Works with: days, hours, minutes, seconds, months, years

---

📊 5. DAG Visualization

Visual dependency graph of your YAML tasks and task groups.

Example YAML:

tasks:
  support_tables:
    users:
      map_ids:
        type: 'dlh'
        sql_file: support_tables/users/map_ids.sql
    
    analytics:
      daily_stats:
        type: 'dlh'
        sql_file: support_tables/analytics/daily_stats.sql
        depends_on:
          - support_tables.users.map_ids

What you can do:

• Open Command Palette (Cmd+Shift+P)
• Run "Open YAML DAG Preview" or use shortcut Cmd+K V
• See interactive graph with:
  • Task groups as main nodes
  • Sequential tasks flowing left-to-right
  • Parallel tasks stacked vertically
  • Dependency arrows showing data flow

---

🚀 Quick Start

Installation

1. Download the latest .vsix file
2. Open VS Code
3. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
4. Type "Extensions: Install from VSIX..."
5. Select the downloaded file
6. Reload VS Code

Requirements

• VS Code 1.74.0 or higher
• sqruff installed globally: pip install sqruff or cargo install sqruff
• Optional: .sqruff config file in your workspace root for custom linting rules

Usage

1. Open any YAML configuration file
2. The extension activates automatically
3. Type * to get autocomplete suggestions for YAML anchors
4. Hover over SQL file paths for previews
5. Cmd+Click on anchors or file paths to navigate
6. Check the Problems panel for SQL linting errors and anchor validation

---

📝 Supported YAML Patterns

# SQL file references (all formats)
sql_file: support_tables/users/load_users.sql
SQL_SCRIPT_FILE_NAME: "analytics/revenue.sql"
sql_file: 'data/extract.sql'

# YAML anchors (navigation + autocomplete support)
config: &base_config
  schema: analytics
  owner: data_team

task1:
  vars: *base_config  # Cmd+Click to jump to definition
  # Type * to see all available anchors in autocomplete popup!

# Inline SQL (validation support)
sql_query: &revenue_query |
  SELECT 
    DATE(order_date) as date,
    SUM(amount) as revenue
  FROM orders
  WHERE status = 'completed'
  GROUP BY DATE(order_date)

calculate_revenue:
  sql_file: *revenue_query  # Works with inline SQL too!

# Task dependencies
depends_on:
  - support_tables.users.map_ids
  - external_features.als_item

---

⚙️ Configuration

Workspace .sqruff Config

Create a .sqruff file in your workspace root to customize SQL linting:

[sqlfluff]
templater = "placeholder"
sql_file_exts = ".sql"

[sqlfluff.templater.placeholder]
param_style = "colon"
param_regex = "\{[a-zA-Z_][a-zA-Z0-9_]*\}"

[sqlfluff.rules.capitalisation.keywords]
capitalisation_policy = "upper"

[sqlfluff.rules.capitalisation.functions]
extended_capitalisation_policy = "upper"

The extension will automatically use this config for linting.

---

🎯 Common Use Cases

Use Case 1: Managing Complex DAGs

Navigate between 50+ YAML tasks and their SQL files effortlessly with Cmd+Click navigation and hover previews.

Use Case 2: Debugging Missing Variables

Find missing SQL variables instantly with red error markers pointing to exact lines in both YAML and SQL files.

Use Case 3: Maintaining Code Quality

Enforce SQL style standards across your team with automatic sqruff linting integrated into your editor.

Use Case 4: Understanding Dependencies

Visualize task dependencies and execution flow with the built-in DAG graph viewer.

Use Case 5: Refactoring YAML Anchors

Safely refactor shared configurations using "Find All References" to see all usages before making changes. Type * to quickly discover and reuse existing anchors without searching manually.

---

🆚 Why This Extension?

Without Extension	With Extension
🔍 Search for SQL file manually	🎯 Cmd+Click to open instantly
🤷 Guess which variables are needed	✅ See missing variables with red markers
📝 Check SQL syntax separately	🚨 Live linting in your YAML
🗺️ Mental map of dependencies	📊 Visual DAG graph
🔗 Search for anchor usages manually	🎯 "Find All References" built-in
🔤 Type anchor names from memory	💡 IntelliSense autocomplete with *
⚠️ Discover anchor errors at runtime	🔴 Validate anchor names before deployment
🔮 Guess final SQL after replacements	✨ See replaced SQL on hover instantly

---

📋 Keyboard Shortcuts

Action	Mac	Windows/Linux
Autocomplete YAML anchors	Type *	Type *
Navigate to SQL file	Cmd+Click	Ctrl+Click
Open DAG preview	Cmd+K V	Ctrl+K V
Find all anchor references	Shift+F12	Shift+F12
Go to anchor definition	F12	F12
Quick fix SQL issues	Cmd+.	Ctrl+.
Trigger IntelliSense manually	Ctrl+Space	Ctrl+Space

---

🐛 Troubleshooting

Q: SQL linting is not working

• Ensure sqruff is installed: sqruff --version
• Check that your SQL files use {variable} syntax for placeholders

Q: File paths are not clickable

• Verify your workspace has the dags/ folder structure
• Check that paths in YAML match your actual file structure

Q: Anchor autocomplete is not showing up

• Make sure you're typing * in a YAML file
• Try pressing Ctrl+Space to manually trigger IntelliSense
• Check that you have anchor definitions (&name) in your YAML file

Q: Anchor navigation is not working

• Ensure anchors use YAML syntax: &name for definition, *name for reference
• Check that anchors are not in comments

Q: Getting anchor name validation errors

• Anchor names cannot contain dots (.) - use underscores (_) instead
• Anchor names must start with a letter or underscore
• Use snake_case for best compatibility with Airflow

Q: DAG visualization shows errors

• Validate your YAML syntax with a YAML parser
• Ensure depends_on fields reference existing tasks

---

📦 Version History

0.23.10 (Latest)

• ✨ SQL Preview with Variable Replacement - Hover shows both raw SQL and fully replaced query
• 🎯 Full YAML anchor resolution in replacements - see the actual SQL that will execute
• 🎨 Visual separator between extension content and YAML metadata
• 💡 Works with both file-based SQL and inline SQL (YAML anchors)
• 🚀 Better debugging - instantly see how variables are replaced

0.23.0

• ✨ Inline SQL Support - sql_file can reference YAML anchors with SQL content
• 🔍 Hover preview for inline SQL queries
• ✅ Variable validation for inline SQL
• 📊 Full integration with existing linting and navigation

0.22.0

• 🔧 Improved SQL operator spacing validation (>=, <=, !=)
• 🐛 Fixed YAML parsing error handling
• ✅ Better diagnostic collection for undefined anchors

0.21.0

• ✨ YAML Anchor Autocomplete - Type * to get IntelliSense suggestions for all anchors
• 💡 Shows anchor preview, line number, and full YAML snippet in tooltip
• 🎯 Filters as you type for quick anchor discovery
• 🚀 Major productivity boost for working with YAML anchors

0.20.0

• ✨ YAML Anchor Name Validation - Catches invalid anchor names before Airflow
• 🔴 Error markers for dots, special chars, and naming convention issues
• 💡 Suggests correct snake_case anchor names
• ⚠️ Prevents runtime errors in Airflow DAGs

0.19.0

• 📝 Comprehensive README with examples and use cases
• 🎨 Better marketplace description and keywords
• 📦 Published to VS Code marketplace

0.18.1

• ✨ Added inline SQL support (YAML anchors with SQL content)
• ✨ YAML anchor navigation (Go to Definition, Find All References)
• 🐛 Fixed anchor validation breaking on undefined references

0.17.0

• ✨ Added Trino interval syntax validation and auto-fix
• 🔧 Enhanced SQL linting with clickable error links

0.16.0

• ✨ Added YAML anchor validation
• ✅ Red error markers for undefined anchor references

0.15.0

• ✨ Added DAG visualization with WebView panel
• 📊 Task group support with dependency graph
• ⌨️ Added keyboard shortcut Cmd+K V

---

📄 License

MIT

---

🤝 Contributing

Found a bug or have a feature request? This extension is actively maintained and improvements are welcome!

---

💎 Why VS Code/Cursor Users Love This Extension

This extension transforms YAML from a plain text format into a first-class development experience with IDE-level features:

🎯 IntelliSense for YAML Anchors

• Just like code completion - Type * and get instant suggestions
• No more guessing - See all available anchors with previews
• Faster workflow - No manual searching through large files
• Works in both VS Code and Cursor

🔍 Smart Navigation

• Jump to Definition (F12) - Like navigating functions in code
• Find All References (Shift+F12) - See everywhere an anchor is used
• Cmd+Click - Instant navigation to SQL files or anchor definitions

🛡️ Early Error Detection

• Catch errors before deployment - Validate anchor names, SQL variables, and file paths
• Visual feedback - Red underlines show problems immediately
• Actionable suggestions - Get recommended fixes in tooltips

🚀 Productivity Boost

• Write YAML faster - Autocomplete reduces typing and errors
• Understand code faster - Navigate like you do in Python/TypeScript
• Maintain quality - Built-in linting catches issues before CI/CD

🎨 Native IDE Experience

• Integrates seamlessly with VS Code's built-in features
• Works with Cursor's AI-powered editing
• Follows VS Code design patterns and UX conventions
• Feels natural for developers coming from programming languages

Perfect for data engineers who want the same powerful tools for YAML that they have for code!

---

Made with ❤️ for data engineers working with YAML + SQL