wasm-dbms-sql 0.10.0

SQL front-end (parser, planner, executor) for the wasm-dbms DBMS engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

#![crate_name = "wasm_dbms_sql"]
#![crate_type = "lib"]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(clippy::print_stdout)]
#![deny(clippy::print_stderr)]

//! # wasm-dbms-sql
//!
//! SQL front-end for the [`wasm-dbms`](https://crates.io/crates/wasm-dbms)
//! DBMS engine.
//!
//! The crate turns SQL text into operations on a `wasm-dbms` database. The
//! schema is still defined with `#[derive(Table)]`; SQL only reads and writes
//! data.
//!
//! ## Supported SQL
//!
//! - `SELECT` with `JOIN`, `WHERE`, `DISTINCT`, aggregate functions,
//!   `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT`, and `OFFSET`
//! - `INSERT`, `UPDATE`, and `DELETE`; the last two require a `WHERE` clause
//! - `BEGIN`, `COMMIT`, and `ROLLBACK`, addressed by the transaction id passed to `execute`
//! - positional `?` parameters
//!
//! The full dialect is described in the
//! [SQL reference](https://wasm-dbms.cc/reference/sql.html).
//!
//! ## Usage
//!
//! [`SqlEngine`] runs statements. It takes the database schema once and the
//! [`DbmsContext`](wasm_dbms::DbmsContext) on every call:
//!
//! ```rust,ignore
//! use wasm_dbms::prelude::*;
//! use wasm_dbms_api::prelude::*;
//! use wasm_dbms_memory::prelude::HeapMemoryProvider;
//! use wasm_dbms_sql::SqlEngine;
//!
//! #[derive(Clone, DatabaseSchema)]
//! #[tables(User = "users")]
//! pub struct MySchema;
//!
//! let ctx = DbmsContext::new(HeapMemoryProvider::default());
//! MySchema::register_tables(&ctx)?;
//! let engine = SqlEngine::new(MySchema);
//!
//! engine.execute(
//!     &ctx,
//!     None,
//!     "INSERT INTO users (id, name) VALUES (?, ?)",
//!     &[Value::from(1u32), Value::from("Alice")],
//! )?;
//!
//! let result = engine.execute(
//!     &ctx,
//!     None,
//!     "SELECT name FROM users WHERE id = 1",
//!     &[],
//! )?;
//! ```
//!
//! [`parse`] exposes the parser on its own. It returns the syntax tree of a
//! statement, as defined in [`ast`], without touching a database.
//!
//! ## Layout
//!
//! | Module    | Role                                                              |
//! |-----------|-------------------------------------------------------------------|
//! | `lexer`   | Splits SQL text into tokens with their line and column            |
//! | `parser`  | Builds the [`ast`] from the tokens                                |
//! | `planner` | Resolves names, converts values, and builds `Query` and `Filter`  |
//! | `engine`  | Runs the plan on the database, outside or inside a transaction    |
//!
//! The result and error types, `SqlResult` and `SqlError`, are defined in
//! `wasm-dbms-api` behind its `sql` feature, which this crate enables.

#![doc(html_playground_url = "https://play.rust-lang.org")]
#![doc(
    html_favicon_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-128.png"
)]
#![doc(
    html_logo_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-512.png"
)]

pub mod ast;
#[cfg(test)]
mod docs_tests;
mod engine;
mod lexer;
mod parser;
mod planner;
#[cfg(test)]
mod test_schema;

pub use self::engine::SqlEngine;
pub use self::parser::{ParsedStatement, parse};