Python API reference

The Python package is pure Python and ships with a bundled syntaqlite CLI binary. Requires Python 3.10+. Wheels are published for macOS (arm64, x86_64), Linux (x86_64, aarch64), and Windows (x86_64).

import syntaqlite

with syntaqlite.Syntaqlite() as sq:
    print(sq.format_sql("select 1"))
    stmts = sq.parse("select * from users")

syntaqlite.Syntaqlite

The entry point for all SQL operations. Create one instance and reuse it across many calls — each instance spins up a worker on construction and keeps it alive until close() is called.

syntaqlite.Syntaqlite(*, dialect_path=None, dialect_name=None, binary=None)

Supports the context-manager protocol, so with syntaqlite.Syntaqlite() as sq: cleans up automatically. Not intended for concurrent use — if you want parallelism, create one instance per thread.

sq.format_sql

Format SQL with configurable options.

sq.format_sql(sql, *, line_width=80, indent_width=2, keyword_case="upper", semicolons=True)

Returns: str — the formatted SQL.

Raises: FormatError when the input cannot be parsed.

>>> sq.format_sql("select 1")
'SELECT 1;\n'
>>> sq.format_sql("select 1", keyword_case="lower", semicolons=False)
'select 1\n'

sq.parse

Parse SQL into a list of typed AST nodes.

sq.parse(sql)

Returns: list — one typed AST node per statement. Each node is a __slots__ class (e.g. SelectStmt, CreateTableStmt) with typed attributes.

>>> stmt = sq.parse("SELECT 1 + 2 FROM foo")[0]
>>> type(stmt).__name__
'SelectStmt'
>>> stmt.columns[0].expr
BinaryExpr(...)
>>> stmt.from_clause
TableRef(...)
>>> stmt.where_clause is None
True

Enum and flag fields are IntEnum/IntFlag from syntaqlite.enums:

>>> from syntaqlite.enums import BinaryOp
>>> stmt.columns[0].expr.op
<BinaryOp.PLUS: 0>

Node classes support isinstance checks:

>>> from syntaqlite.nodes import SelectStmt
>>> isinstance(stmt, SelectStmt)
True

The parser recovers from errors and continues; any unparseable fragment comes through as an Error node in the list.

sq.parse_raw

Same as parse but returns plain JSON-shaped dicts without the typed-class wrapping. Use this for performance-sensitive code that doesn't need attribute-style access.

>>> sq.parse_raw("SELECT 1")[0]["type"]
'SelectStmt'

sq.analyze

Analyze SQL against an optional Schema.

sq.analyze(sql, schema=None, *, output=AnalysisOutput.STRUCTURED, render_options=None)

Schema can be built from explicit tables/views, from DDL text, or both:

sq.analyze(
    sql,
    syntaqlite.Schema(
        tables=[syntaqlite.Table("users", ["id", "name"])],
        views=[syntaqlite.View("active", ["id"])],
    ),
)

Returns (when output=AnalysisOutput.STRUCTURED): an Analysis.

Returns (when output=AnalysisOutput.TEXT): str with the diagnostics rendered with source context, matching the CLI output.

>>> schema = syntaqlite.Schema(tables=[syntaqlite.Table("users", ["id", "name"])])
>>> r = sq.analyze("SELECT id FROM users", schema)
>>> r.diagnostics
[]

>>> # Rendered text output with a custom file label
>>> text = sq.analyze(
...     "SELECT nme FROM users", schema,
...     output=syntaqlite.AnalysisOutput.TEXT,
...     render_options=syntaqlite.RenderOptions(source_name="query.sql"),
... )
>>> print(text)
error: unknown column 'nme'
 --> query.sql:1:8
...

sq.tokenize

Tokenize SQL into a list of token dicts.

sq.tokenize(sql)

Returns: list[dict] — one entry per token:

>>> sq.tokenize("SELECT 1")
[{'text': 'SELECT', 'offset': 0, 'length': 6, 'type': 161, 'category': 'keyword'},
 ...]

sq.close

Release the worker and stop accepting calls. Called automatically when the instance is used as a context manager.

sq.close()

After close(), any method call raises SyntaqliteError.

Schema types

syntaqlite.Schema

A catalog schema. Everything that contributes to the analyzer's catalog lives here — pick whichever combination fits your use case.

syntaqlite.Schema(*, tables=None, views=None, ddl=None, modules=None)

syntaqlite.Table

syntaqlite.Table(name, columns=None)

syntaqlite.View

syntaqlite.View(name, columns=None)

Same fields as Table.

Result types

Analysis

Returned by analyze when output=AnalysisOutput.STRUCTURED.

Statement

Per-statement analysis, available on Analysis.statements.

Lineage

Column lineage for a query-bearing statement.

ColumnLineage

ColumnOrigin

RelationAccess

Diagnostic

AnalysisOutput

StrEnum selecting the return shape of analyze:

RenderOptions

Options that shape AnalysisOutput.TEXT output.

syntaqlite.RenderOptions(*, source_name="")

DiagnosticCode

IntEnum of machine-readable diagnostic kinds:

DefinedRelation

Exceptions

syntaqlite.FormatError

Raised by format_sql when the input SQL cannot be parsed. Inherits from Exception.

try:
    sq.format_sql("SELECT FROM")
except syntaqlite.FormatError as e:
    print(e)

syntaqlite.SyntaqliteError

Base class for runtime errors raised by a Syntaqlite instance — for example, calls made after close. Inherits from RuntimeError.