Repository navigation
v1.1.0
SQLite as a database option. A small installation on one host can run vola on a single
SQLite file (VOLA_DATABASE_URL=file:<path>), with no database service and, if it does
without background jobs, no Redis. PostgreSQL stays the default and the full-featured option.
Every API route, answer and error code is the same on both. For the HTTP API, the CLI, the
image and their configuration, this release only adds things. Code that embeds
@vol-a/server and reaches into its database handle has two type changes, listed under
Breaking for code that embeds the server below. The version is still minor because no
@vol-a/* package had been published to npm before this release.
Added
- SQLite as a database option. Set
VOLA_DATABASE_URL=file:<path>(relative to the
working directory),file:///abs/path, or:memory:for tests, in place of
postgresql://…. The guide is
docs/SQLITE.md: which database fits, the quick start without Docker,
embedding the plugin, the worker, backups, the limits. The features by database are also
in the README. What SQLite gives:- Every feature of the API, with the same routes, answers and error codes: files, folders,
versions, shares, tus uploads, the four encryption modes, UDC lists andsubscribe,
statistics, transfer, and the CLI (vola migratecreates and migrates the file). - The driver is Node's built-in
node:sqlite(Node 24+), so there is no new dependency.
The database runs in WAL mode withforeign_keys = ON. There is one writer at a time:
every transaction isBEGIN IMMEDIATE, and the server's transactions take turns. Reads
outside a transaction use a second, read-only connection. - One server process per file. Without Redis everything runs inline: thumbnails render
on/thumb, and no OCR job is created. WithVOLA_REDIS_URLset, one worker process
on the same host opens the same file and runs thumbnail and OCR jobs as on PostgreSQL:- its writes are single statements, and tesseract runs with no transaction open;
- a process waiting for the other's write lock waits on a timer, up to 10 s, instead of
inside SQLite'sbusy_timeout, so it keeps serving; - the expired-upload sweep stays in the server, because the upload a tus
PATCHstreams
into is guarded in the server's memory (409 upload_locked, as on PostgreSQL); - only
:memory:refuses a worker:VOLA_WORKER_ENABLED=truewith it is a configuration
error.
- The OCR text search on SQLite has the same API as on PostgreSQL. The
ocrfilter with
words searches a contentless FTS5 index,drizzle-sqlite/0001_ocr_fts.sql(unicode61,
remove_diacritics 0). Triggers keep the index in step withvola_file_metadata, and the
migration indexes text already there.- Search rules: every word must occur, case-insensitively, with no stemming and no
ranking. Diacritics are kept (č≠c), and the first 500 000 characters are indexed,
as withocr_tsv. - One difference: any character that is not a letter or a digit separates words
(e-mailiseandmail). - The server quotes the words, so FTS5 syntax typed by a user is plain text. It refuses to
open a SQLite database built without FTS5 (Node's built-in one has it).
- Search rules: every word must occur, case-insensitively, with no stemming and no
- Its own migration set,
packages/server/drizzle-sqlite/, shipped in the package. The
server applies it at start, andvola migrateby hand, as with the PostgreSQL set.
pnpm db:generatewrites both.
- Every feature of the API, with the same routes, answers and error codes: files, folders,
Breaking for code that embeds the server
These are two exports of @vol-a/server. They do not affect the HTTP API, the CLI, the
image or the configuration.
DatabaseHandlecarriesdialectinstead ofpool(node-postgres'pg.Pool).Databaseis drizzle's query builder without the driver:PgDatabase<PgQueryResultHKT, …>
instead ofNodePgDatabase, so its type no longer has$client.
Code that reached for handle.pool or db.$client uses handle.db for queries and
handle.close() on shutdown.
Changed
VOLA_DATABASE_URL/VOLA_DATABASE_URL_TESTacceptfile:<path>and:memory:next to
postgres(ql)://.connect(url)picks the database from the URL scheme. Any other scheme
throws aConfigErrorthat names the scheme and never the rest of the URL.@vol-a/server's database layer goes through one dialect seam,db/dialect.ts, with
db/postgres.tsanddb/sqlite.tsbehind it. What is not portable goes through the seam:
the advisory lock on a content hash, unique-violation and lock-not-available errors,
count(*) filter, JSON fields,LIKE/ILIKE,FOR UPDATE NOWAIT,
ON CONFLICT … DO NOTHINGand the OCR text match (ocrMatch(words)).capabilitiessays
what a dialect has (rowLocks,ocrSearch). On PostgreSQL the SQL is the same as in 1.0.1.- The tables exported from
db/schema.tsare those of the database the process connected to
(db/schema-postgres.tsordb/schema-sqlite.ts, with the same row types), so a process
speaks one dialect. resolveJobsMode's input takesmemoryDatabase: an in-memory SQLite is alwayssync.- The server and CLI test suites run on both databases (Vitest projects
server/
server-sqlite,cli/cli-sqlite).VOLA_TEST_DIALECT=postgres|sqliteruns one
(docs/CONTRIBUTING.md).
Docker: docker pull ghcr.io/digital-cube/jsvola:1.1.0
npm: pnpm add @vol-a/client@1.1.0 · @vol-a/react · @vol-a/server · @vol-a/cli · @vol-a/core · @vol-a/lookups