Skip to main content
Version: v1.17.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, methods and types, not as changed signatures.
  • Your implementations of Quark's interfaces: extension points are frozen, plumbing is not. The promise above covers code that calls Quark, and code that implements an extension point — an interface or function type Quark calls, such as a dialect, a model hook, a cache store, a middleware or an observer. Within v1, Quark adds no method to an extension point and changes none; a new capability arrives as a separate, optional interface with a default for code that does not implement it. It does not cover your own implementation of a plumbing interface — one Quark implements and hands to you, such as Executor, Event or Expr: Quark may add a method to one of those in a minor release, never in a patch, and the release notes name it. Code that only calls it is unaffected. The extension contract marks every type as one or the other, and shows how to write your own implementation of plumbing so that it keeps compiling; the decision record has the reasoning.
  • 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.