This guide walks you through installing Gudu SQL Omni, running your first analysis, and exploring every major feature. You should be seeing real results within five minutes.
That is it. The extension ships with a bundled Java runtime, so you do not need to install Java or configure any paths. Gudu SQL Omni activates automatically whenever you open a .sql file.
Open or create any .sql file to get started. The examples below use a simple query, but the extension supports 34 database dialects out of the box.
What this does: Tells the parser which SQL dialect to use so it can parse vendor-specific syntax correctly.
Why you'd use it: If you write PostgreSQL, BigQuery, or Snowflake SQL, setting the dialect avoids false validation errors.
The extension also auto-detects dialects, so if you skip this step it will still try to parse your SQL correctly.
What this does: Parses your SQL and reports syntax errors with line and column positions.
Why you'd use it: Catch syntax mistakes before you run a query against a live database.
.sql file with one or more SQL statements.What this does: Identifies every table and column referenced in your SQL, including those inside CTEs, subqueries, and table-valued functions.
Why you'd use it: Quickly inventory what a complex query touches without reading it line by line.
.sql file.
Data lineage is the flagship feature. It traces how data moves from source columns through transformations to target columns.
What this does: Generates an interactive graph showing column-level data flow for the SQL in your editor.
Why you'd use it: Understand which source columns feed into each output column -- essential for debugging transformations, impact analysis, and compliance.
.sql file containing one or more SELECT, INSERT, or CREATE statements.
You can export the diagram as a PNG using the save button in the graph toolbar.
What this does: Opens a panel where you can fine-tune lineage behavior.
Why you'd use it: Control whether intermediate/temporary results appear, toggle restrict/group relations, and set query depth (1-20).
What this does: Generates an entity-relationship diagram from CREATE TABLE and DDL statements.
Why you'd use it: Visualize your database schema and table relationships without a separate diagramming tool.
.sql file containing CREATE TABLE statements (or any DDL).You can export ER diagrams as PNG using the save button.
The Gudu SQL Explorer lives in the Activity Bar and provides three panels for working with SQL across your entire workspace.
This is your home base for workspace-wide lineage. It lists every directory you have scanned, the tables discovered, and lets you query upstream and downstream dependencies.
The toolbar at the top of the Lineage Index panel gives you one-click access to:
Workspace scanning analyzes all SQL files in a directory tree, builds a lineage index, and lets you explore cross-file data dependencies.
What this does: Recursively finds all .sql files in a directory, parses them, and builds a unified lineage index.
Why you'd use it: Understand data flow across an entire project, not just a single file.
After scanning, the Lineage Index panel populates with your scan roots and discovered tables. Expand any scan root to browse the tables and columns found.
What this does: Starting from any table or column, traces all upstream sources or downstream consumers across your scanned SQL files.
Why you'd use it: Answer "where does this data come from?" or "what breaks if I change this column?"
You do not need to memorize keyboard shortcuts. Every major command is available from the editor right-click menu.
Right-click inside any .sql file to see the GSP: commands:
All commands are also available through the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Type GSP to filter the list.
| Command | Windows / Linux | macOS |
|---|---|---|
| Validate SQL | Ctrl+Shift+V | Cmd+Shift+V |
| Extract Tables & Columns | Ctrl+Shift+E | Cmd+Shift+E |
| SQL to XML | Ctrl+Shift+X | Cmd+Shift+X |
| Data Lineage | Ctrl+Alt+L | Cmd+Alt+L |
| Configure Lineage Options | Ctrl+Alt+O | Cmd+Alt+O |
| Impact Analysis | Ctrl+Alt+I | Cmd+Alt+I |
| Graph for Symbol | Ctrl+Alt+G | Cmd+Alt+G |
Open settings via the Command Palette (GSP: Open Settings) or navigate to Settings > Extensions > Gudu SQL Omni.
| Setting | Description | Default |
|---|---|---|
| Default DB Vendor | The SQL dialect used for parsing | Auto-detect |
| Log Level | Logging verbosity (debug, info, warn, error, none) | info |
| Enable Telemetry | Send anonymous error reports to help improve the extension | true |
| CodeLens Enabled | Show inline table/column counts above SQL statements | true |
| Show Temporary Results | Include intermediate/temporary tables in lineage | false |
| Show Restrict/Group Relations | Include restrict and group-by relations in lineage | false |
| Query Depth | Maximum depth for upstream/downstream queries (1-20) | 5 |
| ER Diagram Enabled | Enable ER diagram features | true |
When enabled, CodeLens displays table and column counts directly above each SQL statement in the editor. This gives you a quick inventory without running any command. Toggle it via GSP: Toggle CodeLens in the Command Palette or in settings.
Gudu SQL Omni works in free trial mode out of the box. The trial allows analysis of SQL with up to 10 tables. For unlimited analysis, you need a license.
Run GSP: Show License Status from the Command Palette to see your current license state, expiration date, and table limit.
Run GSP: Clear License to remove the current license and return to trial mode.
Right-click in the editor to access all commands without opening the Command Palette. This is the fastest way to switch between validation, lineage, and ER diagrams.
The default DB vendor setting persists across sessions. If you work with one database platform most of the time, set it once and let auto-detection handle the exceptions.
When scanning directories, point the scan at your project root to capture cross-file dependencies. The scanner handles subdirectories recursively.
Both lineage and ER diagrams support PNG export. Use this to embed diagrams in wikis, PRDs, or architecture docs without maintaining a separate diagramming tool.
After running a lineage analysis, use the upstream/downstream query feature to trace dependencies beyond the current file. This is particularly useful for multi-file ETL pipelines.
The inline table and column counts give reviewers immediate visibility into what each statement touches, making SQL code reviews faster and more thorough.
| Problem | Cause | Solution |
|---|---|---|
| Extension does not activate | File is not a .sql file |
Rename to .sql or set the file language to SQL (bottom-right status bar) |
| "Bundled JRE not found" | Platform-specific JRE missing from extension | Reinstall the extension; contact support if the issue persists |
| "Server jar not found" | Language server JAR missing | Reinstall the extension |
| Server fails to start | Java compatibility issue | Check the Output panel (SQL LSP Minimal) for error details |
| Validation shows false errors | Wrong SQL dialect selected | Set the correct dialect via GSP: Set Default DB Vendor |
| Lineage diagram is empty | SQL has no data flow (e.g., DDL only) | Use SELECT, INSERT, or CREATE AS SELECT statements for lineage |
| "Table limit exceeded" | Trial mode restriction | Activate a license to remove the 10-table limit |
| Slow scanning on large projects | Many SQL files being parsed | This is expected for very large projects; the scan runs in the background |
| Diagrams not rendering | Webview blocked by VS Code security | Check that the extension has webview permissions; restart VS Code |
If you encounter an issue not listed here, use GSP: Submit Feedback from the Command Palette to send a bug report directly to the development team.
Install Gudu SQL Omni, open a SQL file, and see your data lineage in seconds -- no cloud, no setup, no risk.