Skip to content

Releases

Release v0.2.0

Choose a tag to compare

@homer6 homer6 released this 16 Nov 05:52
bb9994a

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 with modernc.org/sqlite v1.38.2 (SQLite 3.50.3 translated to pure Go; no cgo, no libc). lake-sqlite --version prints 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) and LAKE_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, with truncated when 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 answers SELECT 1 within 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 codes sql_error, invalid_request, invalid_params, unauthorized, not_allowed, not_found, method_not_allowed, body_too_large, response_too_large, busy, unavailable, timeout and disk_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:

  • ATTACH and DETACH, with no database attachable (SQLITE_LIMIT_ATTACHED=0), which also refuses VACUUM and VACUUM 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 by tools/sbom.py.
  • README.md from the public template; CONTRIBUTING.md (contributions under the copyright-assignment CLA), CODE_OF_CONDUCT.md and SECURITY.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 scratch instead of gcr.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 sent BEGIN/COMMIT through /v1/exec must 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_LIMIT no longer runs PRAGMA 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 with PRAGMA auto_vacuum = INCREMENTAL before their first table can use PRAGMA 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): /healthz shares 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 sql holding several statements runs all of them, each committing on its own, and /v1/query answers 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