A Modern Embedded SQL Database in Pure Rust
Documentation • Playground • Releases • Benchmarks
```bash
git clone https://github.com/stoolap/stoolap-studio.git
cd stoolap-studio && npm install && npm run dev
```
## Core SQL Capabilities
### Transactions and Time-Travel
```sql
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;
SELECT * FROM accounts AS OF TIMESTAMP '2024-01-15 10:30:00';
SELECT * FROM inventory AS OF TRANSACTION 1234;
```
### Cost-Based Query Optimizer
```sql
ANALYZE orders;
ANALYZE customers;
EXPLAIN SELECT * FROM orders WHERE customer_id = 100;
EXPLAIN ANALYZE
SELECT o.*, c.name
FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE c.country = 'US';
```
### Indexing
```sql
-- Auto-selected by data type
CREATE INDEX idx_created_at ON orders(created_at); -- B-tree
CREATE INDEX idx_email ON users(email); -- Hash
CREATE INDEX idx_active ON users(is_active) USING BITMAP;
-- Multi-column
CREATE INDEX idx_lookup ON events(user_id, event_type);
```
### Advanced SQL
```sql
WITH ranked AS (
SELECT
customer_id,
amount,
ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY amount DESC) AS rn
FROM orders
)
SELECT * FROM ranked WHERE rn = 1;
```
## Vector and Semantic Search
Stoolap supports native vectors via `VECTOR(N)` and approximate nearest-neighbor search with HNSW.
```sql
CREATE TABLE embeddings (
id INTEGER PRIMARY KEY,
content TEXT,
embedding VECTOR(384)
);
CREATE INDEX idx_emb ON embeddings(embedding)
USING HNSW WITH (metric = 'cosine', m = 32, ef_construction = 400, ef_search = 128);
SELECT id, content,
VEC_DISTANCE_COSINE(embedding, '[0.1, 0.2, ...]') AS dist
FROM embeddings
ORDER BY dist
LIMIT 10;
```
For built-in semantic text embeddings, enable the `semantic` feature:
```toml
[dependencies]
stoolap = { version = "0.4", features = ["semantic"] }
```
```sql
SELECT EMBED('How to reset my password');
```
See [Vector Search](https://stoolap.io/docs/data-types/vector-search/) and [Semantic Search](https://stoolap.io/docs/data-types/semantic-search/) docs for full workflows.
## Storage and Durability
Stoolap uses a hot/cold volume storage architecture inspired by Apache Iceberg and Delta Lake:
- **Hot buffer**: in-memory MVCC store with WAL for active writes
- **Cold volumes**: immutable columnar files with zone maps, bloom filters, dictionary encoding, and LZ4 compression
- **Adaptive compaction**: background thread merges cold volumes with size-aware, fully dynamic merge strategy
- **Crash recovery**: atomic manifest writes, fsync-before-rename, WAL replay from checkpoint LSN
- **Column pruning**: cold scans materialize only columns referenced by filters and projections
```
file://./mydb?sync_mode=normal&compression=on&checkpoint_interval=60
```
| DSN Parameter | Default | Description |
|---------------|---------|-------------|
| `sync_mode` | `normal` | `none` (no fsync, data durable at checkpoint), `normal` (fsync every 1s), `full` (fsync every write) |
| `compression` | `on` | LZ4 for both WAL and volumes |
| `wal_compression` | `on` | LZ4 for WAL entries only |
| `volume_compression` | `on` | LZ4 for cold volume files only |
| `checkpoint_interval` | `60` | Seconds between checkpoint cycles |
| `compact_threshold` | `4` | Sub-target volumes per table before merging |
| `target_volume_rows` | `1048576` | Target rows per cold volume |
## Performance
Detailed benchmark results are in [BENCHMARKS.md](BENCHMARKS.md).
Benchmark figures are point-in-time and workload-dependent. Validate on your own hardware, data distribution, and query patterns.
## Documentation
- Installation: https://stoolap.io/docs/getting-started/installation/
- SQL commands: https://stoolap.io/docs/sql-commands/sql-commands/
- Data types: https://stoolap.io/docs/data-types/data-types/
- Functions: https://stoolap.io/docs/functions/sql-functions-reference/
- Architecture: https://stoolap.io/docs/architecture/architecture/
- Drivers: [Node.js](https://stoolap.io/docs/drivers/nodejs/) | [Python](https://stoolap.io/docs/drivers/python/) | [PHP](https://stoolap.io/docs/drivers/php/) | [WASM](https://stoolap.io/docs/drivers/wasm/) | [C](https://stoolap.io/docs/drivers/c/)
## Development
```bash
cargo build
cargo nextest run
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
Apache License 2.0. See [LICENSE](LICENSE).