surql-parser 0.1.4

Use Cases

• Migration tools and schema analyzers
• Linters and formatters for .surql files
• IDE extensions (Zed, VS Code) with syntax analysis
• Code generation from SurrealQL definitions
• CI validation of SurrealQL files

Quick Start

use surql_parser::parse;

let ast = parse("SELECT name, age FROM user WHERE age > 18 ORDER BY name").unwrap();
assert_eq!(ast.expressions.len(), 1);

Parse DDL

let ast = surql_parser::parse(
    "DEFINE FUNCTION fn::greet($name: string) { RETURN 'Hello, ' + $name; }"
).unwrap();

Parse type annotations

let kind = surql_parser::parse_kind("option<record<user>>").unwrap();

Extract schema definitions

let defs = surql_parser::extract_definitions("
    DEFINE TABLE user SCHEMAFULL;
    DEFINE FIELD name ON user TYPE string;
    DEFINE FIELD age ON user TYPE int DEFAULT 0;
    DEFINE INDEX email_idx ON user FIELDS email UNIQUE;
    DEFINE FUNCTION fn::greet($name: string) { RETURN 'Hello, ' + $name; };
").unwrap();

assert_eq!(defs.tables.len(), 1);
assert_eq!(defs.fields.len(), 2);
assert_eq!(defs.indexes.len(), 1);
assert_eq!(defs.functions.len(), 1);

Check reserved keywords

assert!(surql_parser::is_reserved_keyword("SELECT"));
assert!(!surql_parser::is_reserved_keyword("username"));

Compile-Time Tools

surql-macros — proc-macro crate

Validate SurrealQL at compile time:

[dependencies]
surql-macros = "0.1"

use surql_macros::{surql_check, surql_function};

// Compile-time validated query — typo here is a compile error
const QUERY: &str = surql_check!("SELECT * FROM user WHERE age > 18");

// Compile-time validated function name
#[surql_function("fn::get_user")]
fn get_user_call(id: &str) -> String {
    format!("fn::get_user('{id}')")
}

Errors show both the SurrealQL location and the Rust source location:

error: Invalid SurrealQL: Unexpected token `WHERE`, expected FROM
 --> [1:10]
  |
1 | SELECT * WHERE age > 18
  |          ^^^^^

build.rs helper (feature build)

Validate .surql files and generate typed constants at build time:

[build-dependencies]
surql-parser = { version = "0.1", features = ["build"] }

// build.rs
fn main() {
    let out_dir = std::env::var("OUT_DIR").unwrap();
    surql_parser::build::validate_schema("surql/");
    surql_parser::build::generate_typed_functions(
        "surql/",
        format!("{out_dir}/surql_functions.rs"),
    );
}

This generates constants like FN_GET_USER: &str = "fn::get_user" with doc comments showing parameter types and return types. See examples/sample-project/ for a complete working example.

CLI Tool

cargo install surql-parser --features cli

surql check schema/**/*.surql      # validate .surql files
surql fmt file.surql               # format SurrealQL
surql info schema/                 # show schema summary
surql diff schema/                 # show uncommitted schema changes
surql docs schema/                 # generate markdown docs
surql lint schema/                 # run SurrealQL-specific lints
surql test tests/                  # run .surql test files

Testing

cargo test                               # parser tests (instant)
cargo test --features build              # + build helper tests
cargo test -p surql-macros               # proc-macro tests (trybuild)
cargo test -p surql-sample-project       # e2e: build.rs + macros
cargo test --features validate-mem       # + in-memory SurrealDB
cargo test --features validate-docker    # + real SurrealDB in Docker

Validation deps (surrealdb, testcontainers) are dev-dependencies only — they don't leak to library consumers.

SurrealDB Compatibility

Parser source is auto-synced from SurrealDB via an automated pipeline. See UPSTREAM_SYNC.md for details.

How It Works

The parser source code is extracted from SurrealDB using an AST-level Rust transformer (tools/transform/). This ensures 100% compatibility with SurrealDB's parser while removing engine-specific execution code.

The sync pipeline:

1. Copies syn/ (lexer, parser) and sql/ (AST types) from SurrealDB source
2. Rewrites imports via declarative rules (mappings.toml)
3. Strips execution-layer code (318 impl blocks removed automatically)
4. Validates compilation

Workspace

This repository is a Rust workspace with several crates:

License

Apache 2.0 — same as SurrealDB.