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 ofclient.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 BYvia 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
subclaim 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) includinguseMap,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): descriptionconvention for easy scanning - Migration guides: Breaking changes in major versions include migration instructions in the release notes