wasm_dbms_sql/
lib.rs

1#![crate_name = "wasm_dbms_sql"]
2#![crate_type = "lib"]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4#![deny(clippy::print_stdout)]
5#![deny(clippy::print_stderr)]
6
7//! # wasm-dbms-sql
8//!
9//! SQL front-end for the [`wasm-dbms`](https://crates.io/crates/wasm-dbms)
10//! DBMS engine.
11//!
12//! The crate turns SQL text into operations on a `wasm-dbms` database. The
13//! schema is still defined with `#[derive(Table)]`; SQL only reads and writes
14//! data.
15//!
16//! ## Supported SQL
17//!
18//! - `SELECT` with `JOIN`, `WHERE`, `DISTINCT`, aggregate functions,
19//!   `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT`, and `OFFSET`
20//! - `INSERT`, `UPDATE`, and `DELETE`; the last two require a `WHERE` clause
21//! - `BEGIN`, `COMMIT`, and `ROLLBACK`, addressed by the transaction id passed to `execute`
22//! - positional `?` parameters
23//!
24//! The full dialect is described in the
25//! [SQL reference](https://wasm-dbms.cc/reference/sql.html).
26//!
27//! ## Usage
28//!
29//! [`SqlEngine`] runs statements. It takes the database schema once and the
30//! [`DbmsContext`](wasm_dbms::DbmsContext) on every call:
31//!
32//! ```rust,ignore
33//! use wasm_dbms::prelude::*;
34//! use wasm_dbms_api::prelude::*;
35//! use wasm_dbms_memory::prelude::HeapMemoryProvider;
36//! use wasm_dbms_sql::SqlEngine;
37//!
38//! #[derive(Clone, DatabaseSchema)]
39//! #[tables(User = "users")]
40//! pub struct MySchema;
41//!
42//! let ctx = DbmsContext::new(HeapMemoryProvider::default());
43//! MySchema::register_tables(&ctx)?;
44//! let engine = SqlEngine::new(MySchema);
45//!
46//! engine.execute(
47//!     &ctx,
48//!     None,
49//!     "INSERT INTO users (id, name) VALUES (?, ?)",
50//!     &[Value::from(1u32), Value::from("Alice")],
51//! )?;
52//!
53//! let result = engine.execute(
54//!     &ctx,
55//!     None,
56//!     "SELECT name FROM users WHERE id = 1",
57//!     &[],
58//! )?;
59//! ```
60//!
61//! [`parse`] exposes the parser on its own. It returns the syntax tree of a
62//! statement, as defined in [`ast`], without touching a database.
63//!
64//! ## Layout
65//!
66//! | Module    | Role                                                              |
67//! |-----------|-------------------------------------------------------------------|
68//! | `lexer`   | Splits SQL text into tokens with their line and column            |
69//! | `parser`  | Builds the [`ast`] from the tokens                                |
70//! | `planner` | Resolves names, converts values, and builds `Query` and `Filter`  |
71//! | `engine`  | Runs the plan on the database, outside or inside a transaction    |
72//!
73//! The result and error types, `SqlResult` and `SqlError`, are defined in
74//! `wasm-dbms-api` behind its `sql` feature, which this crate enables.
75
76#![doc(html_playground_url = "https://play.rust-lang.org")]
77#![doc(
78    html_favicon_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-128.png"
79)]
80#![doc(
81    html_logo_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-512.png"
82)]
83
84pub mod ast;
85#[cfg(test)]
86mod docs_tests;
87mod engine;
88mod lexer;
89mod parser;
90mod planner;
91#[cfg(test)]
92mod test_schema;
93
94pub use self::engine::SqlEngine;
95pub use self::parser::{ParsedStatement, parse};
wasm_dbms_sql/lib.rs

wasm_dbms_sql/
lib.rs
