Changelog

TopGun follows Semantic Versioning (semver):

  • Major versions (X.0.0) introduce breaking changes to the public API or wire protocol
  • Minor versions (0.X.0) add new features in a backward-compatible manner
  • Patch versions (0.0.X) contain backward-compatible bug fixes

Releases

For the complete list of releases with detailed notes, visit the GitHub Releases page.

Unreleased — Changed (on-disk format): the store moves into a data directory

The server keeps its store in a data directory, TOPGUN_DATA_DIR (default: topgun-data beside TOPGUN_REDB_PATH when that is set, else ./topgun-data; the container image and the Helm chart use /data/topgun-data). The first start of this version moves an existing store into it by itself, once: nothing to run by hand, and the migration resumes where it stopped if the process is interrupted. TOPGUN_REDB_PATH now names only the store file of earlier versions. That file is kept as {TOPGUN_REDB_PATH}.pre-migration, and a small marker file at TOPGUN_REDB_PATH makes an older server binary refuse to start instead of serving an empty store. Copy the old file to another disk before upgrading, and keep 1.5 × its size plus 64 MiB free.

Rollback is only a return to the kept file, and loses on the server every write acknowledged since the upgrade; there is no tool that exports the new format back. Backup: stop the server and copy the whole data directory together with the WAL directory. See Storage backends and, if the server refuses to start, Troubleshooting.

Unreleased — Postgres backend removed

The server keeps its data in an embedded store (redb) inside the process, so there is no database to run. The Postgres backend has been removed: the postgres cargo feature, STORAGE_BACKEND=postgres, reading DATABASE_URL, the Postgres service and dbtools profile of the compose file, and the PostgreSQL choice in the topgun CLI setup are gone.

If you ran on Postgres: the server now refuses to start when STORAGE_BACKEND=postgres is set or when DATABASE_URL is set (an empty value counts). Unset DATABASE_URL to start on the embedded store. There is no migration tool: data kept by the Postgres backend remains available with the server built from the tag postgres-backend-last.

Backup: stop the server, copy the data directory (TOPGUN_DATA_DIR, see the entry above) and the WAL directory (TOPGUN_WAL_DIR), start it again. A copy of a running server’s files is not a supported backup. See Storage backends.

Deployment: the cluster and auto-setup compose services keep data on named volumes, and the Helm chart gets a persistent volume, correct probe paths, replicaCount: 1 and the disruption budget off by default.

v0.13.0 — Data Platform (Intermediate)

New features and documentation for the v2.0 Data Platform milestone:

Unified Query API (breaking change):

  • client.query() now supports field projection (fields: string[]) and result limits (limit: number)
  • Efficient Merkle delta reconnect — on reconnect, only changed records are re-sent instead of the full result set
  • Writer exclusion — query subscribers no longer receive echo of their own writes
  • The separate Shapes API (subscribeShape()) has been removed; all partial replication features are now part of client.query()

New v2.0 features (server):

  • Schema system — TypeScript-first schema definition with server-side validation (@topgunbuild/core)
  • DataFusion SQL queries — SELECT, WHERE, GROUP BY, ORDER BY via Apache DataFusion (feature-gated: --features datafusion)
  • RSA JWT auto-detection — server automatically detects HMAC vs RSA/EC key format

Security fixes:

  • Re-enabled JWT expiration validation with configurable leeway
  • CORS origins default changed from wildcard to empty (deny-all)
  • Missing sub claim in JWT now rejected

Documentation:

  • New guide pages: Schema & Type Safety, SQL Queries, Troubleshooting, FAQ, Benchmarks, Tutorials (Todo App)
  • Updated Live Queries guide with field projection, limits, and Merkle reconnect
  • Fixed misleading auth/security/RBAC documentation
  • Brand color token system replacing hardcoded Tailwind classes

Updated packages: @topgunbuild/core, @topgunbuild/client, @topgunbuild/react

v1.0.0 — Launch Release

The first stable release of TopGun, featuring:

  • Rust server with all 7 domain services (CRDT, Sync, Query, Search, Messaging, Persistence, Coordination)
  • TypeScript client SDK (@topgunbuild/client) with offline-first LWWMap and ORMap CRDTs
  • React hooks (@topgunbuild/react) including useMap, useQuery, useMutation, useTopic
  • IndexedDB adapter (@topgunbuild/adapters) for browser-side persistence
  • PostgreSQL storage for server-side durability
  • Cluster protocol with 271-partition data distribution
  • Full-text search powered by Tantivy
  • MerkleTree delta sync for efficient reconnection
  • JWT authentication and role-based access control
  • Apache 2.0 license

Pre-release History

Development milestones leading to v1.0:

  • Phase 3: Rust server with all domain services, integration tests (TS client to Rust server)
  • Phase 2.5: Research sprint — storage architecture, cluster architecture, service patterns
  • Phase 2: Core Rust library — CRDTs, HLC, MerkleTree, message schema
  • Phase 1: TypeScript implementation — client SDK, React hooks, sync engine

Tracking Changes

  • GitHub Releases: github.com/topgunbuild/topgun/releases — detailed notes for every release
  • Commit log: Each commit follows the type(scope): description convention for easy scanning
  • Migration guides: Breaking changes in major versions include migration instructions in the release notes