Repository navigation
The first tagged release of lake-sqlite: one SQLite database behind a small HTTP API with a bearer token, the web service behind lake's SQLite services. It is cut from dev at 6f5e0276 and carries the open-source launch work of epic #1. Tracking issue: #17. This release was not planned through a release epic, so these notes list what merged.
Images tagged 0.1.0 and 0.1.1 were published earlier without a Git tag or release notes. This release is the first with both, and it changes behavior (see Changes since 0.1.1), so it is a minor version.
What it includes
The service
- One static binary (
cmd/lake-sqlite) serving one SQLite database file over HTTP, built withmodernc.org/sqlitev1.38.2 (SQLite 3.50.3 translated to pure Go; no cgo, no libc).lake-sqlite --versionprints the version, and the startup log carries it. - Configuration from the environment:
LAKE_SQLITE_TOKEN(required),LAKE_SQLITE_PATH(default/data/main.db),LAKE_SQLITE_ADDR(default:8080) andLAKE_SQLITE_MEMORY_LIMIT(holds the Go heap to three quarters of the container limit). - Routes (
docs/api.md):POST /v1/query:{sql, params}answers{columns, rows}, at most 10,000 rows and 32 MiB of values, withtruncatedwhen cut.POST /v1/exec: answers{rows_affected, last_insert_id}.POST /v1/batch: up to 1,000 statements in one transaction that the server begins (IMMEDIATE) and commits; the first error rolls the whole batch back.GET /healthz: no token; 200 while the database answersSELECT 1within two seconds.
- Auth:
Authorization: Bearer <token>on every route but/healthz, compared in constant time on SHA-256 hashes; 401 before the route or method is looked at. - Values: every SQLite type both ways in real JSON types; blobs as
{"$base64": "..."}; integers exact to 64 bits; infinite reals as"Infinity"/"-Infinity". - Durability: WAL,
synchronous=FULL,foreign_keys=ON, a 5-second busy timeout, a pool of four connections, and a WAL checkpoint on graceful shutdown (SIGTERM/SIGINT, 30 s for in-flight requests). - Bounds: 16 MiB request bodies, 30 s per request with the running statement interrupted, header read in 10 s, idle connections closed after 2 minutes.
- Errors: one shape,
{"error": {"code", "message"}}, with the codessql_error,invalid_request,invalid_params,unauthorized,not_allowed,not_found,method_not_allowed,body_too_large,response_too_large,busy,unavailable,timeoutanddisk_full. - Logging: one JSON line per request (method, path, status, sizes, duration). The SQL, its parameters, the body, headers and the token are never logged.
The statement guard
Every connection carries an SQLite authorizer and limits (internal/server/guard.go; What a statement may do). The following are refused with 403 not_allowed:
ATTACHandDETACH, with no database attachable (SQLITE_LIMIT_ATTACHED=0), which also refusesVACUUMandVACUUM INTO;- transaction control (
BEGIN,COMMIT,END,ROLLBACK,SAVEPOINT,RELEASE); load_extension;- every pragma outside an allowlist. Schema and file pragmas are allowed. The connection's settings can be read but not set.
Values and rows are capped at 8 MiB (SQLITE_LIMIT_LENGTH). A connection a request left inside a transaction is rolled back, or discarded, before it serves another request.
The image
oramasearch/lake-sqlite:0.2.0 (also v0.2.0, same digest), linux/amd64, FROM scratch, public on Docker Hub (docker pull oramasearch/lake-sqlite:0.2.0). It holds the binary, a two-line /etc/passwd and /etc/group for user 65532:65532, and an empty /tmp (mode 1777). There is no shell, no libc and no distribution package, so no GPL, LGPL or AGPL file is in the image. There is no CA bundle, because the service makes no outbound TLS connections.
The repository
- MIT
LICENSE,COPYRIGHT(OramaSearch, Inc.) and an SPDX line in every source file (tools/spdx-headers.py --check). THIRD_PARTY_LICENSES: 9 linked Go packages, all MIT or BSD-3-Clause.- An SBOM in SPDX 2.3 and CycloneDX (
sbom.spdx.json,sbom.cdx.json), regenerated reproducibly bytools/sbom.py. README.mdfrom the public template;CONTRIBUTING.md(contributions under the copyright-assignment CLA),CODE_OF_CONDUCT.mdandSECURITY.md(private reports to security@orama.com).
Pull requests
#2 security policy, #3 internal material out of the tree, #4 licences, headers, notices and SBOM, #6 the scratch image, the README, the statement guard, and #4 combined with #3. The release pull request adds this page and the version.
Changes since 0.1.1
- The image runs
FROM scratchinstead ofgcr.io/distroless/static:nonroot(#5). - New refusals with
403 not_allowed:ATTACH,DETACH,VACUUM, transaction control in every route, and pragmas that change the connection. Clients that sentBEGIN/COMMITthrough/v1/execmust use/v1/batch. These fix security issues #7 to #9 and #13. - Values and rows are capped at 8 MiB, a response at 32 MiB of values, and a batch at 1,000 statements (
413 response_too_large,400 invalid_request), fixing #10. LAKE_SQLITE_MEMORY_LIMITno longer runsPRAGMA soft_heap_limit, which this SQLite build never enforced (#11).
What it does not include
- Replication, backups or a second copy of the database.
- Quotas inside the database beyond the volume size.
- TLS: it serves plain HTTP, for use behind TLS or inside the cluster.
VACUUM. Databases created withPRAGMA auto_vacuum = INCREMENTALbefore their first table can usePRAGMA incremental_vacuum.- A signed image or an image SBOM (attestation). The repository SBOM covers the source tree.
Known issues
Security first:
- #14 (low): a slow upload plus a long statement can pass the 45 s write timeout after the commit, so a retrying client can duplicate a write.
- #12 (low/medium):
/healthzshares the connection pool, so sustained load can fail the liveness probe and restart the pod. - #15 (low): the Go 1.23 toolchain is out of support; the builder gets no more security fixes.
- #16 (info): request JSON is more lenient than documented (case-insensitive keys, a stray closing brace accepted), and the DSN path is not escaped.
- The guard reads the driver's connection handle by reflection, because modernc.org/sqlite exposes no authorizer. A driver upgrade that changes the layout makes startup fail; it never runs unguarded.
Others:
- A
sqlholding several statements runs all of them, each committing on its own, and/v1/queryanswers only the last one's rows. - Many concurrent 16 MiB bodies are each buffered in memory; there is no limit on concurrent requests beyond the four-connection pool.
- zetta#1382: lake's service connectors cannot yet pull results past the 10,000-row cap.
Where it has run
Not on a cluster. By Steve's decision, this release skipped the dev-environment run. The image (oramasearch/lake-sqlite:0.2.0@sha256:c448ae8a49664573771fc086adc51466fd1041d6e0db879c791474b3daaabca5) was built from the tag and its file list read, but no Lake runs it yet. The operator's default image (lakeServices.sqliteImage) still names 0.1.1 until its bump is merged and an operator release rolls.
Verification
| Check | Result |
|---|---|
go build ./... && go vet ./... |
clean |
go test ./... (Go 1.27.4, darwin/arm64) |
23 tests and 48 subtests passed, 0 failed, 0 skipped |
go test -race ./internal/server/ |
passed |
Clean clone, empty module cache, GOPROXY=https://proxy.golang.org |
builds and passes |
tools/spdx-headers.py --check, tools/sbom.py --check |
pass |
| gitleaks and trufflehog, full history | one hit, local-dev-token, the README's throwaway example |
Image build, linux/amd64, cluster BuildKit, from a detached checkout of the tag |
main-bb9994a9@sha256:c448ae8a49664573771fc086adc51466fd1041d6e0db879c791474b3daaabca5 |
| Image binary reproducible | byte-identical (SHA-256 d1866223…) to a local CGO_ENABLED=0 GOOS=linux GOARCH=amd64 build of the tag with Go 1.23.12, the builder's toolchain |
| Image file list | etc, etc/group, etc/passwd, tmp (1777), lake-sqlite; user 65532:65532 |
Docker Hub 0.2.0 = v0.2.0 = main-bb9994a9 |
same digest sha256:c448ae8a…. Public since 2026-11-15: an anonymous pull of 0.2.0 resolves to it |