Web and SQLite
The SDK includes two libraries, libraries/sprig-web for HTTP services and libraries/sprig-sqlite for SQLite databases. It also includes example projects that use them: examples/mini_web, examples/sqlite, examples/sqlite_migrations and examples/ledger.
These are experimental examples that show how far Sprig can go. They aren't frameworks you can put straight into production.
Run the ledger backend
examples/ledger is a complete bookkeeping backend: an HTTP API, SQLite storage and generated API documentation. From the root of a built Sprig repository, run:
cd examples/ledger
../../bin/sprig resolve
../../bin/sprig check --offline
../../bin/sprig run --offline -- ledger.sqlite 8080When you see LEDGER_READY 8080, the server is up. Open http://localhost:8080/docs to try the API in Swagger UI; /openapi.json is the machine-readable description. The Swagger page loads its assets from a CDN, so it needs a network connection. The backend itself only listens on your machine and runs fully offline once dependencies are resolved and cached. Press Ctrl+C to stop it.
In VS Code, run long-running programs like this one with Sprig: Run in Terminal.
| Method | Path | What it does |
|---|---|---|
| GET, POST | /api/accounts | Lists or creates accounts |
| GET, POST | /api/categories | Lists or creates categories |
| GET, POST | /api/transactions | Lists or creates transactions |
| DELETE | /api/transactions/{id} | Deletes a transaction: 204 if deleted, 404 if it doesn't exist |
| GET | /api/statistics/monthly?month=2026-09 | Number of transactions and totals for a month |
Amounts are integers in the smallest currency unit (cents, for example) and can be negative. The ledger README lists the request fields, storage and validation rules.
Handlers are ordinary Sprig functions
A route handler has the type fn(web.Request) -> web.Response throws Error, with one rule: an answer the client should see, whether it's a 404 or a 400 that says which field is wrong, is a Response you return, and an error you don't handle escapes for the server to answer. These excerpts are from examples/mini_web/src/main.spr:
import "@web/web.spr" as web
let app = web.App(title="Mini Web", cors_origin="http://localhost:5173")
func root(req: web.Request) -> web.Response:
return web.text("Hello, Sprig!", 200).with_header("X-Sprig", "mini-web")
func hello(req: web.Request) -> web.Response:
let name = req.path_param("name")
let greeting = req.query("greeting")
if name != null:
if greeting != null:
return web.text(greeting + ", " + name + "!", 200)
return web.text("Hello, " + name + "!", 200)
return web.text("Missing name", 400)
func echo(req: web.Request) -> web.Response throws Error:
return web.json_response(req.json(), 200)
app.get("/", fn(req: web.Request) => root(req))- Register handlers with
app.get,app.post,app.put,app.patchandapp.delete.app.run(port)listens on 127.0.0.1 only; to be reachable from other machines or outside a container, useapp.run_on("0.0.0.0", port)(no TLS: put a reverse proxy in front). To document the route as well, pass aweb.Routetoapp.route, with a summary and the shapes of the parameters, request and response. There are no decorators and no Java annotations. - Build responses with module functions:
web.text(body, status)andweb.json_response(value, status). There's no staticResponse.textform. req.path_param,req.queryandreq.headerreturnString?, so "no such parameter" and "an empty parameter" stay distinct.req.bodyis UTF-8 text, andreq.json()parses the body into a JSON value. To find a field in it, usejson.find_member, which tells apart a missing key, a JSONnullvalue and a value that isn't an object; see the language quick reference.- If the body isn't valid JSON,
req.json()throws anError, andweb.json_responsethrows one for a value it can't write as JSON. When the client needs no more than "bad request", declarethrows Errorlikeechoabove and let it escape; when you want to say what's wrong, return a 400Responseyourself. Don't catch an error only to return a generic 400 or 500: the server does that. - Malformed requests get a 400 (so does a body
req.json()can't parse, when the handler lets that error escape), unknown routes a 404, and any other error that escapes a handler a controlled 500.
API documentation
The OpenAPI document comes from Schema, FieldSchema and QueryParameter values that you write out explicitly; the library never reflects over arbitrary classes. These descriptions are documentation only, so handlers still validate the values they receive. Duplicate query parameters and conflicting path templates are rejected when you register a route.
The libraries/sprig-web README describes the behavior in full. After sprig resolve, sprig api @web/app.spr --json lists the signature of everything in the library.
SQL stays in plain sight
The SQLite library gets a pinned org.xerial:sqlite-jdbc:3.46.1.0 from Maven, recorded in the lock file.
- SQL statements are ordinary strings that you write, and they count as trusted application code. Values from users always go in through prepared-statement parameters, which come in four kinds:
Integer,Text,BooleanandNull. This is not a SQL sandbox. - Each SQL string holds one statement. A trailing semicolon or comment is fine; a second statement is an error instead of being silently skipped, so a multi-statement script belongs in a migration file.
- A query returns a typed snapshot of the results, already disconnected from the database. Connections, statements and result sets are closed when they're done. A single query can return at most 10,000 rows (more is an error), and the whole result is held in memory.
Database.batchruns a list of statements in one transaction; if any of them fails, all of them are rolled back. When a query (includingINSERT ... RETURNING) fails, anything it wrote is rolled back too.sqlite.transaction(database, callback)supports read-check-write workflows: the callback receives aTransactionwithqueryandexecutemethods that share one connection and see earlier writes. Success commits and returns the callback result; an escapingErroror SQL failure rolls back. JDBC causes and primary failures survive cleanup. Even a caught SQL-operation error prevents commit.- A transaction is valid only during its synchronous callback and on that thread; use after return throws
Error. Nested scoped transactions and savepoints are unsupported. Inside the callback, use the suppliedTransactionthroughout: a call on the database itself (database.query,execute,batch) throwsErrorright away, because it would open a second connection that can't see the transaction's writes. For a callback that returns nothing, callsqlite.transaction_run(database, callback). DetachedRowsmay be returned and used later. - You can't write transaction statements such as
BEGINorCOMMITyourself; the library manages transactions. See the runnable account transfer example. - There's no ORM, no automatic conversion from REAL to Int, and no BLOB or Decimal parameters. Only ordinary database files are supported, not
:memory:databases.
Database migrations (experimental)
Import @sqlite/migrations.spr and call Migrations(database=database, directory="migrations").apply():
- Migration files are named
NNN_description.sql, and the three-digit numbers must be unique. - Files run in filename order, and the names of applied files are recorded in the
sprig_schema_migrationstable. Before running anything,apply()checks the whole directory against that table: if a name doesn't fit the pattern, two files share a number, or an applied file sorts after one that hasn't been applied, it stops and nothing runs. - Each file's SQL and its record are committed in the same transaction. If something fails, both are rolled back, and you can run again after fixing the file.
- Don't edit a file that has already been applied: file contents aren't checksummed yet, so the change would go unnoticed. The migrations directory counts as trusted project code.
See examples/sqlite_migrations for a complete example, and the libraries/sprig-sqlite README for the full API.
Limitations
This is a synchronous, single-user example. It has no authentication, sessions, connection pooling or async handling, and it isn't designed for public deployment. Request bodies and query results are held in memory in full. Type checking makes sure the types are right, but it can't make your business rules or arithmetic correct.
How it's tested
The repository's tests start a real local HTTP server, work with temporary SQLite files, check that data survives a restart and verify the structure of the OpenAPI document:
python3 tests/callables/check_callables.py
python3 tests/web/check_web.py
python3 tests/sqlite/check_sqlite.py
./scripts/verify.shThe development record is in docs/history/milestones/WEB_SQLITE_ENGINEERING_REPORT.md. For a command-line tool made of several files, with option parsing, see examples/json_select.
