poached

349 downloads this week 12 stars Extension descriptor

SQL parsing and introspection for IDEs, editors, and developer tools

Compatibility Matrix

This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

Installing and Loading

INSTALL poached FROM community;
LOAD poached;

Example

-- Tokenize SQL for syntax highlighting (with byte positions)
SELECT * FROM tokenize_sql('SELECT * FROM users WHERE id = 1');
┌───────────────┬──────────────────┐
│ byte_position │     category     │
├───────────────┼──────────────────┤
│             0 │ KEYWORD          │
│             7 │ OPERATOR         │
│             9 │ KEYWORD          │
│            14 │ IDENTIFIER       │
│            20 │ KEYWORD          │
│            26 │ IDENTIFIER       │
│            29 │ OPERATOR         │
│            31 │ NUMERIC_CONSTANT │
└───────────────┴──────────────────┘

-- Validate SQL and get error messages
SELECT is_valid_sql('SELECT * FROM'), sql_error_message('SELECT * FROM');

-- Get SELECT column names without executing
SELECT * FROM parse_columns('SELECT 1 AS num, ''hello'' AS str', 0);
┌───────────┬──────────┐
│ col_index │ col_name │
├───────────┼──────────┤
│         0 │ num      │
│         1 │ str      │
└───────────┴──────────┘

-- Extract function calls with type info
SELECT * FROM parse_functions('SELECT COUNT(*), UPPER(name) FROM t');
┌───────────────┬───────────────┐
│ function_name │ function_type │
├───────────────┼───────────────┤
│ count_star    │ aggregate     │
│ upper         │ scalar        │
└───────────────┴───────────────┘

-- Get parsed statement information as JSON
SELECT sql_parse_json('SELECT 1 + 2 AS result');

About poached

poached is a DuckDB extension for SQL parsing and introspection, designed for building IDEs, SQL editors, query analyzers, and developer tools.

Tokenization: parse_tokens() (also available as tokenize_sql()) returns tokens with byte positions and categories (KEYWORD, IDENTIFIER, OPERATOR, NUMERIC_CONSTANT, STRING_CONSTANT) for syntax highlighting. Comments are stripped before tokenization.

Validation: is_valid_sql() and sql_error_message() for parse error detection and reporting.

Column introspection: parse_columns() returns SELECT column names without executing queries; parse_column_names() returns the names as a list.

Query analysis: parse_tables(), parse_functions(), parse_where() to extract structural information from queries.

JSON output: parse_sql_json() (also available as sql_parse_json()) returns parsed statement types and SQL text, or a parse error.

For more details, visit the extension repository.

Added Functions

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings