About mz-sql-navigation
mz-sql-navigation is a skill for navigating Materialize SQL projects through the mz-deploy language server. It helps developers resolve object definitions and dependencies with semantic navigation rather than text search.
Key features
- 01Go to SQL object definitions
- 02Inspect columns and types on hover
- 03List file and workspace symbols
- 04Surface parser diagnostics after edits
- 05Check dependencies before changes
Use cases
- 01Find a view defined in another schema
- 02Locate an object when its file is unknown
- 03Review downstream dependencies before editing
- 04Identify SQL parse errors after an edit
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/mz-sql-navigationin Claude Code to confirm it loaded.
Details
From the project READMENavigating Materialize SQL
The mz-deploy language server answers questions about an mz-deploy project's object
graph. Use the LSP tool for these instead of text search — grep finds strings that look
like an object name, the language server finds the object.
What to use it for
- Go to definition — resolve where a referenced view, table, source, or index is defined, including across schemas.
- Hover — inspect an object's columns and their types without opening its definition.
- Document symbols — list the objects a single
.sqlfile defines. - Workspace symbols — locate an object by name when you don't know its file.
Before changing an object, use these to find what depends on it. In Materialize a view's definition constrains everything downstream of it, so an edit that type-checks in isolation can still break dependents.
Diagnostics
Parse errors surface automatically after each edit. Treat them as authoritative for
syntax; they come from the same parser mz-deploy uses to build the project.
Requirements
mz-deploy must be on PATH (which mz-deploy). If every navigation request comes back
empty while the server looks healthy, the plugin's mz-deploy project directory
setting is pointing somewhere other than the directory holding project.toml. The
server takes that directory as its project root, and a project nested in a subdirectory
needs the setting to name that subdirectory. Report this rather than falling back to
grep — a stale setting is worth fixing once.