Using libsyntaqlite from Rust

The syntaqlite crate is libsyntaqlite's Rust API. In this tutorial you add it to a project, format a query, check the query against a schema, and print its syntax tree.

1. Create a project

cargo new sql-check
cd sql-check
cargo add syntaqlite

The default features include the parser, formatter, and analyzer. The parser is written in C, so building the crate needs a C compiler as well as Rust.

2. Format a query

Replace src/main.rs with:

use syntaqlite::Formatter;

fn main() {
    let mut fmt = Formatter::new();
    let output = fmt
        .format("select id,name,email from users where active=1 order by name")
        .expect("parse error");
    println!("{output}");
}

Run it:

cargo run
SELECT id, name, email FROM users WHERE active = 1 ORDER BY name;

You can keep one Formatter and call format for every query you need to format.

3. Validate against a schema

Replace src/main.rs with:

use syntaqlite::util::DiagnosticRenderer;
use syntaqlite::{AnalysisConfig, AnalysisContext, Analyzer, Catalog, sqlite_dialect};

fn main() {
    // Register the schema from CREATE TABLE statements.
    let schema = "CREATE TABLE users (id INTEGER, name TEXT, email TEXT, active INTEGER);";
    let (mut catalog, errors) = Catalog::from_ddl(sqlite_dialect(), &[schema]);
    assert!(errors.is_empty(), "schema errors: {errors:?}");

    // Analyze a query against the schema.
    let config = AnalysisConfig::default().with_strict_schema();
    let mut ctx = AnalysisContext::new(&mut catalog).with_config(config);
    let mut analyzer = Analyzer::new();
    let sql = "SELECT id, nme FROM users WHERE active = 1";
    let model = analyzer.analyze(sql, &mut ctx);

    let renderer = DiagnosticRenderer::new(sql, "query.sql");
    let mut out = std::io::stdout();
    for d in model.diagnostics() {
        renderer.render_diagnostic(d, &mut out).unwrap();
    }
}

Run it:

cargo run
error: unknown column 'nme'
 --> query.sql:1:12
  |
1 | SELECT id, nme FROM users WHERE active = 1
  |            ^~~
  = help: did you mean 'name'?

with_strict_schema makes unknown tables and columns errors. Without it, they are reported as warnings.

4. Parse and inspect the AST

Replace src/main.rs with:

use syntaqlite::{ParseOutcome, Parser};

fn main() {
    let parser = Parser::new();
    let mut session = parser.parse("SELECT 1 + 2; SELECT 'hello';");

    let mut i = 0;
    loop {
        match session.next() {
            ParseOutcome::Ok(stmt) => {
                i += 1;
                let mut dump = String::new();
                stmt.dump(&mut dump, 0);
                println!("--- statement {i} ---\n{dump}");
            }
            ParseOutcome::Err(err) => eprintln!("error: {}", err.message()),
            ParseOutcome::Done => break,
        }
    }
}

Run it:

cargo run
--- statement 1 ---
SelectStmt
  flags: (none)
  columns:
    ResultColumnList [1 items]
      ResultColumn
        flags: (none)
        alias: (none)
        alias_as: FALSE
        expr:
          BinaryExpr
            op: PLUS
            left:
              Literal
                literal_type: INTEGER
                source: "1"
            right:
              Literal
                literal_type: INTEGER
                source: "2"
  ...

The parser hands back one statement at a time, so memory use depends on the largest statement rather than the whole input.

Next steps