README
¶
TinySQL commands
This directory contains runnable TinySQL applications, demos, servers, and WebAssembly builds. For engine capabilities, GIS, storage modes, imports, and limitations, start with the root README.
Choose a command
| Goal | Command | Start here |
|---|---|---|
| Explore SQL features with seed data | demo |
go run ./cmd/demo |
| Use an interactive SQL shell | repl |
go run ./cmd/repl |
| Use a SQLite-like CLI | tinysql |
go run ./cmd/tinysql |
| Format, lint, validate, or explain SQL | sqltools |
go run ./cmd/sqltools |
| Diagnose SQL against a fresh database | debug |
go run ./cmd/debug |
| Query files directly with SQL | query_files |
go run ./cmd/query_files |
| Query filesystem metadata and content | fsql |
build from cmd/fsql |
| Move data between files and databases | migrate |
build from cmd/migrate |
Servers and applications
| Goal | Command | Notes |
|---|---|---|
| HTTP and gRPC SQL API | server |
General-purpose API server |
| Exercise the API under load | server/loadtest |
Companion load generator |
| Durable DBMS daemon and tile server | tinysqld |
Health, jobs, storage, optional tiles |
| Browser database manager | accessweb |
Datasheets, CRUD, SQL, export |
| SQL-driven HTML pages | tinysqlpage |
Render pages from .sql definitions |
| Form application | formigo |
TinySQL or SQL Server backend |
| Desktop SQL application | studio |
Wails desktop app |
| MCP server for AI hosts | tinysql-mcp-server |
stdio Model Context Protocol server |
Reference and local applications
| Goal | Command | Notes |
|---|---|---|
| Inspect catalog and scheduled jobs | catalog_demo |
Console demo or browser dashboard for tables, views, functions, and jobs |
| Search a support knowledge base | supportdesk |
Console demo or persistent browser help desk with FTS and tickets |
| Explore a read-only POI snapshot | offline_demo |
CLI snapshot search or browser explorer; no map tiles required |
| Evaluate local RAG retrieval | ragdemo |
Requires a local embedding server |
| Explore tinyORM | tinyorm_demo |
CLI demo or persistent places directory with migrations and named parameters |
Practical local applications
| Goal | Command | Notes |
|---|---|---|
| Track zone entry and exit events | geofence-service |
GeoJSON zones, browser UI, and position-ingest API (:8091) |
| Search a local document directory | docsearch |
Persistent full-text index and browser UI (:8092) |
| Validate CSV before importing it | import-validate |
Rules, error history, and explicit commit (:8093) |
| Record work and break time | worklog |
Timeout checkout, reports, and CSV export (:8094) |
The application-specific browser modes in the two sections above expose small
JSON APIs for local integrations. They intentionally do not implement login,
authorization, or TLS. Bind them to loopback with -addr 127.0.0.1:<port> for
local use, or put them behind suitable authentication and TLS before exposing
them to a network.
Browser and WebAssembly
| Goal | Command | Start here |
|---|---|---|
| Full local-first SQL playground | query_files_wasm |
GitHub Pages app and GIS map editor |
| Minimal browser WASM UI | wasm_browser |
./build.sh --serve |
| Run TinySQL from Node.js WASM | wasm_node |
./build.sh --run |
The focused map demo
is built by query_files_wasm and its data generator in
mbtilesdemo. It runs tile lookups and GeoJSON edits through
the same in-browser TinySQL engine.
Build conventions
Most commands can be built from the repository root:
go build ./cmd/<name>
go run ./cmd/<name> --help
fsql, migrate, studio, and the WebAssembly applications have their own
build workflows; follow their command README. Optional file importers use build
tags:
go build -tags=sqliteimport ./...
go build -tags=shapefile ./...
go build -tags=sqliteimport,shapefile ./...
Use go test ./... from the repository root for the main suite. See the
development guide for the Make targets and
release/demo workflow.
Directories
¶
| Path | Synopsis |
|---|---|
|
catalog_demo – tinySQL Catalog & Scheduler demonstration.
|
catalog_demo – tinySQL Catalog & Scheduler demonstration. |
|
debug – tinySQL SQL diagnostic tool.
|
debug – tinySQL SQL diagnostic tool. |
|
Package main provides a practical SQL playground for tinySQL.
|
Package main provides a practical SQL playground for tinySQL. |
|
Command docsearch provides a local, persistent document search with a small browser UI.
|
Command docsearch provides a local, persistent document search with a small browser UI. |
|
Command geofence-service is a small, persistent GPS geofencing service with a browser UI.
|
Command geofence-service is a small, persistent GPS geofencing service with a browser UI. |
|
Command import-validate is a local CSV intake tool.
|
Command import-validate is a local CSV intake tool. |
|
internal
|
|
|
webapp
Package webapp contains deliberately small building blocks shared by the runnable web applications in cmd/.
|
Package webapp contains deliberately small building blocks shared by the runnable web applications in cmd/. |
|
Command offline_demo is a small local-first tinySQL example.
|
Command offline_demo is a small local-first tinySQL example. |
|
Command ragdemo exercises a complete local RAG pipeline with LM Studio and TinySQL.
|
Command ragdemo exercises a complete local RAG pipeline with LM Studio and TinySQL. |
|
Command supportdesk is a compact support-search application built with tinySQL.
|
Command supportdesk is a compact support-search application built with tinySQL. |
|
Command tinysqld is the enterprise DBMS daemon entry point.
|
Command tinysqld is the enterprise DBMS daemon entry point. |
|
internal/referencegen
Package referencegen extracts the ordered example overview used by the browser-based function reference.
|
Package referencegen extracts the ordered example overview used by the browser-based function reference. |
|
tools
command
|
|
|
Command worklog is a compact, persistent work-time tracker.
|
Command worklog is a compact, persistent work-time tracker. |
Click to show internal directories.
Click to hide internal directories.