Skip to main content
Version: 1.14.0

Upgrading

Quark is a standard Go module on the stable v1.x line. Upgrading is go get plus a few minutes of reading — this page tells you what to read and in what order.

The versioning promise​

Quark follows semantic versioning:

  • Patch and minor releases (v1.x.y) keep API compatibility. Code that compiles against v1.3 compiles against every later v1.x. New features arrive as new options and methods, not as changed signatures.
  • Breaking changes go to v2. If that day comes, v2 will be a new module path (github.com/jcsvwinston/quark/v2, per Go convention), released with a migration guide — you will never be broken by a routine go get -u.
  • Behavior fixes are called out. When a bug fix changes observable behavior (for example, a query that used to silently produce wrong results now returns an error), the release notes say so explicitly, per release.

Before you upgrade: read the notes​

The Release Notes are written to be read top-down before an upgrade: each version has its own section describing what changed and what to check. If you are skipping versions, read every section between your current version and the target — upgrade implications don't repeat themselves in later entries.

Commit-level detail lives on GitHub Releases, which is also the place to watch (or subscribe to) for new versions.

To find out what you are running now:

go list -m github.com/jcsvwinston/quark

Step by step​

  1. Pin the new version. Use an explicit tag, not latest, in anything scripted:

    go get github.com/jcsvwinston/quark@v1.3.1
    go mod tidy

  2. Compile and run your test suite:

    go build ./...
    go test ./...

  3. Run your integration tests against a real database. Quark is tested against all six engines, but your models and queries are yours — the engine-specific paths (upserts, locking, set operations) deserve a real round-trip, not just unit tests.

  4. Upgrade the CLI too, if you use it:

    go install github.com/jcsvwinston/quark/cmd/quark@latest
    quark version

    The CLI is its own Go module with its own tag series, so there is no library version to name here — @latest is the selector, and quark version prints which Quark release the binary it just installed carries:

    quark v0.1.0 linux/amd64 (go1.26.6)
    built against github.com/jcsvwinston/quark v1.13.0

    That second line is what to compare against the library version you just moved to; the two are released together, so upgrading both in one sitting keeps them equal. If you run the CLI from a release archive rather than from go install, download the archive for the new library tag — the archives are named after it — and verify its signature and provenance before you replace the binary — Verifying a release.

  5. Verify the schema before rolling out. If you use the model-diff flow, quarkmigrate verify exits non-zero when the database has drifted from your models — run it in CI so an upgrade that changes type mapping or introspection surfaces as a failed pipeline, not a surprise in production. See the migrations guide.

Rolling back a library upgrade is the same procedure with an older tag — within v1.x there are no compatibility cliffs in either direction. Database migrations you applied are a separate concern: rolling back the Go module does not un-apply them, so treat schema rollbacks with the care described in Production Deployment.

If you are on v0.x​

The last breaking change was in v0.9.0; every release from v0.10.0 through current v1.x is a drop-in upgrade. Coming from v0.8 or earlier, follow the v0.9.0 migration notes linked from the Release Notes first, then jump straight to the latest v1.x.

Quark and the Quantum suite​

Quark is developed as part of Quantum, a small suite of Go modules by the same author. The suite repository publishes a versions.yaml manifest; each suite release certifies a specific set of module versions (Quark among them) that were tested together.

What this means for you:

  • Quark is standalone. It has its own releases, its own versioning promise, and no dependency on the rest of the suite. If you only use Quark — the common case — the suite changes nothing about how you install or upgrade it.
  • If you use other Quantum modules, prefer the combination certified in the current versions.yaml over mixing arbitrary versions. A newer Quark than the certified one is usually fine (minor releases are compatible), but the certified set is the one that was exercised end to end.