Skip to content

docs: redesign README in the goptics house style, add a logo - #18

Merged
fahimfaisaal merged 6 commits into
perf/group-commit-bargefrom
docs/readme-redesign
Oct 23, 2026
Merged

fahimfaisaal merged 6 commits into
perf/group-commit-bargefrom
docs/readme-redesign

Conversation

@fahimfaisaal

Copy link
Copy Markdown
Member

Stacked on #16 (feat/enqueue-once). README only: no code changes.

What changes

  • Logo: assets/text-logo.svg and text-logo-dark.svg, built like redisq's (three stacked queue bars and the wordmark) in SQLite blue. The README picks the light or dark version with <picture>.
  • Layout: follows redisq's — logo, badges, tagline, section links, then:
    • Features, Installation, Quick Start, Usage, Storage;
    • Configuration, Delivery Guarantees, Upgrading from v0.2, How It Works;
    • Development, API Reference, Star History, Contributing, License.
  • Installation: states the requirements: Go 1.24+ and cgo (mattn/go-sqlite3 needs CGO_ENABLED=1 and a C compiler).
  • New sections:
    • an option table;
    • a delivery-guarantees table;
    • an upgrade list from v0.2. It notes that the path is a plain path, not a DSN, that an open name returns one shared handle, and that recovery runs once per file open, which replaces RequeueNoAckRows.
  • CI badge: now links the sqliteq.yml workflow; it pointed at go.yml, which doesn't exist.
  • Corrections:
    • the column list gains ack and priority;
    • the single-file name rules mention the __sqliteq_* index names;
    • the case-insensitive path note is corrected for Windows;
    • "-wal/-shm" files are described as present only while the file is open.
  • Removed:
    • the measured WAL sizes, until the benchmark that produced them is published (varmq-benchmarks#3); the computed sizes stay;
    • the Author section, to match redisq and varmq.

Checked

Every claim was checked against the code, with probes where reading wasn't enough. Every Go snippet was compiled and run, including the varmq one against varmq main. Links and anchors were checked against GitHub's heading rules.

Queue.EnqueueOnce(item, id) and PriorityQueue.EnqueueOnce(item,
priority, id) implement varmq's IDedupQueue and IDedupPriorityQueue.
Opening a table adds a job_id TEXT column when it is missing and a
unique partial index on it over the rows that have one. The insert
ends in ON CONFLICT (job_id) WHERE job_id IS NOT NULL DO NOTHING, so a
repeat stores nothing and returns true, while a NOT NULL failure such
as Enqueue(nil) still fails. Enqueue and an empty id bind NULL.

The index is <name>__sqliteq_job_id rather than <name>_job_id, for the
reason the pending index has its suffix: tables and indexes share one
namespace, and a queue named orders_job_id could not open beside orders.
A short EnqueueOnce section: a repeat stores nothing and returns true,
and the id is remembered while its row exists (pending, processing, or
completed with WithRemoveOnComplete(false)). The Compatibility line now
says batch pops and EnqueueOnce need varmq v1.10.0 or later, and the
schema list names job_id.
A nil option panicked in New, in the registry's option loop and in
newQueue. All three now return one error, so New, NewQueue and
NewPriorityQueue never panic on it; a rejected call creates no folder,
file or table.

Two tests pin the EnqueueOnce id: a job claimed and never acked keeps
its id through the requeue on the next open, so a repeat stores nothing
and the job runs once; Purge frees the ids of pending and processing
rows.

README: any name SQLite accepts as a table name under WithSingleFile,
the same handle only while it is open, the single-file layout does not
create its folder, batch claims only for a worker whose sole source is
the sqliteq queue, a Durability section for WAL with synchronous=NORMAL,
and the Windows device names as queue names in the folder layout.
A text logo in light and dark variants, built like redisq's: three
stacked queue bars and the wordmark, in SQLite blue. The README follows
redisq's layout: logo, badges, tagline and section links, then
features, installation (Go 1.24+ and cgo), quick start, usage, storage,
configuration, delivery guarantees, upgrading from v0.2, how it works,
development, contributing and license.

New sections: a delivery guarantees table; an upgrade list (the path is
a plain path, not a DSN; one shared handle per open name; recovery once
per file open, which replaces RequeueNoAckRows); an option table. The
CI badge now links the sqliteq.yml workflow. The column list gains ack
and priority, and the single-file name rules note the index names.

The measured WAL sizes are left out until the benchmark they come from
is published; the computed sizes stay.
Base automatically changed from feat/enqueue-once to perf/group-commit-barge October 23, 2026 13:15
@fahimfaisaal
fahimfaisaal merged commit 9c02972 into perf/group-commit-barge Oct 23, 2026
@fahimfaisaal
fahimfaisaal deleted the docs/readme-redesign branch October 23, 2026 13:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant