tinysql

tinySQL is an embeddable SQL database engine written in Go, useful for learning database internals, local tools, tests, browser/WASM applications, and single-process services that need SQL without operating a database server. It is not a drop-in replacement for PostgreSQL, MySQL, or clustered production databases. ## Getting Started Requires Go 1.26.5+. Install with `go get github.com/SimonWaldherr/tinySQL@latest`. Create an in-memory database and run SQL with a simple Go API, including parameter binding with `?`, `$1`, or `:1` placeholders. A database/sql driver, streaming, columnar results, transactions, and a query builder are also available. The same engine embeds into other languages through one C ABI, with bindings for Rust, Python, Swift, and C. Python and Rust examples show creating tables, inserting rows, and querying with bound parameters. ## Workflows - Interactive exploration: demo, repl, or tinysql CLI - Query files or migrate data: query_files, fsql, or migrate - Embed a local SQL service: server or tinysqld - Build browser apps: query_files_wasm, wasm_browser, or wasm_node - Embed in Swift/Xcode apps: Swift package and Apple XCFramework for macOS, iOS, iPadOS - Use AI tooling or local RAG: tinysql-mcp-server and RAG guide ## Capabilities - **SQL**: DDL/DML, CTEs, joins, grouping, windows, views, triggers, table-valued functions, stored procedures, jobs, and common SQLite-compatible PRAGMAs - **Data**: CSV/TSV, JSON/NDJSON, XML, YAML, Excel, GeoJSON, TopoJSON, KML, OSM XML, routing graphs, Shapefiles, GeoPackage, MBTiles - **Search**: Full-text, vector, hybrid search, RAG helpers, regex, JSON, URL, HTML, date, math, bitmap, and hash functions - **Deployment**: Pure-Go embedded API, database/sql driver, Rust/Python/Swift/C bindings, CLI, HTTP/gRPC server, browser/WASM builds, multiple storage backends ## GIS, Routing, and Tiles Geometry is stored as GeoJSON or validated GEOMETRY. Includes measurement, predicates, editing, spatial search, choropleth classification, WKT/WKB, geohash, and Web Mercator helpers. Routing functions run Dijkstra or coordinate-guided A* over ordinary edge tables. Tile functions support Web Mercator and OGC TileMatrix workflows. ## Retrieval and RAG Vector, full-text, and hybrid retrieval can be combined with metadata filters and reranking. RAG_WARM and ROUTE_WARM prepare derived serving structures before traffic. ## Storage Modes - ModeMemory: tests, browser/WASM, temporary data - ModeWAL: in-memory tables with write-ahead-log recovery - ModeDisk: per-table GOB files with lazy loading - ModeJSON: human-readable, diffable per-table JSON - ModeIndex/ModeHybrid: disk-backed tables with bounded caching - ModePagedIndex: large equality lookups such as MBTiles - ModeSQLite: .sqlite file interoperable with SQLite tools (requires sqliteimport tag) Optional file support is built with build tags: `sqliteimport` for SQLite/GeoPackage/MBTiles, `shapefile` for ESRI Shapefile/ZIP imports. A `tinysql_minimal` tag drops optional features for size-sensitive embeddings like browser WASM bundles, shrinking the bundle from about 27.46 MB to 15.56 MB (43%) before wasm-opt with stripped symbols. ## Services and Operations server provides HTTP and gRPC APIs, optional TLS and bearer authentication, plus asynchronous read-only replicas. tinysqld is the durable DBMS entry point with health, scheduler, and optional tile endpoints. Replication is asynchronous; automatic failover, multi-primary writes, and distributed transactions are not implemented. ## Limitations - Embedded and single-process; server offers asynchronous primary/replica reads only - Composite primary/foreign keys, CHECK, target-bearing ON CONFLICT DO UPDATE, SAVEPOINT, ATTACH/DETACH, VACUUM, partial indexes, generated columns, and persistent ANN index files are not available - Secondary indexes accelerate equality/prefix seeks and numeric ranges; GEO_SEARCH is needed for indexed point-column bbox/radius queries - GIS validity is structural rather than full topology validation; GEO_DISSOLVE/GEO_UNION_AGG require clean, vertex-aligned adjacent polygons - RBAC is coarse and single-table oriented; encryption does not cover WAL-backed modes or metadata files tinySQL is primarily an educational and embeddable engine, keeping the parser, planner, executor, storage backends, and practical extensions easy to inspect, test, and adapt.