DocsGuidesTopGun + Your PostgreSQL

TopGun + Your PostgreSQL

TopGun uses PostgreSQL as a durability backend with its own storage format. It lives alongside your existing database, not on top of it.

TopGun is NOT a sync layer

Unlike PowerSync or ElectricSQL, TopGun does not sync your existing SQL tables to clients. TopGun owns its own storage and uses PostgreSQL purely for durability. Your existing tables are never read or modified by TopGun.

How TopGun Uses PostgreSQL

TopGun stores data in its own topgun_* tables using MsgPack-encoded BYTEA columns. This is fundamentally different from sync tools that mirror your existing schema:

Your tables contain your application data in your schema
TopGun tables contain CRDT-encoded data in TopGun’s internal format
Both coexist in the same PostgreSQL instance
TopGun never reads from or writes to your tables

Your Tables

users, orders, products…
Your schema, your migrations
Accessed by your API
Unchanged by TopGun

TopGun Tables

topgun_maps
MsgPack BYTEA format
Managed by TopGun server
Auto-created on startup

Comparison: Sync Tools vs TopGun

Aspect	PowerSync / ElectricSQL	TopGun
Storage model	Syncs your existing schema to clients	Owns its storage, lives alongside your DB
Schema changes	Must match source database	Independent — TopGun schema is internal
Query language	SQL on your tables	TopGun queries on TopGun data
Use case	Offline-first SQL apps	Real-time reactive features
What it syncs	Rows from your tables	CRDT state from TopGun maps
Database access	Reads your tables via replication	Never touches your tables

Configuration

Point TopGun at your existing PostgreSQL instance using the DATABASE_URL environment variable:

terminal

# Point TopGun at your existing PostgreSQL instance
# TopGun creates its own tables alongside yours
DATABASE_URL=postgres://user:pass@localhost/myapp \
PORT=8080 \
cargo run --bin test-server --release

That’s it. TopGun connects to the same PostgreSQL instance your application uses but creates its own separate tables.

What TopGun Creates

On first startup, TopGun automatically creates its tables:

TopGun Tables (auto-created)

-- TopGun automatically creates this table on startup
-- Your existing tables are NOT modified

CREATE TABLE IF NOT EXISTS topgun_maps (
  map_name        TEXT    NOT NULL,
  key             TEXT    NOT NULL,
  value           BYTEA   NOT NULL,  -- MsgPack-encoded CRDT data
  expiration_time BIGINT  NOT NULL DEFAULT 0,
  is_backup       BOOLEAN NOT NULL DEFAULT FALSE,
  created_at      BIGINT  NOT NULL,
  updated_at      BIGINT  NOT NULL,
  PRIMARY KEY (map_name, key, is_backup)
);

-- Index for efficient map-level queries
CREATE INDEX IF NOT EXISTS idx_topgun_maps_map
  ON topgun_maps (map_name);

Safe Coexistence

TopGun uses the topgun_ prefix for all its tables. It never creates, modifies, or drops tables outside this namespace. Your existing data is safe.

When to Use a Separate Database

For production deployments, you may want TopGun to use a separate PostgreSQL database to isolate resource usage:

# Separate database for TopGun (recommended for high-traffic production)
DATABASE_URL=postgres://user:pass@localhost/topgun_data cargo run --bin test-server --release

Consider a separate database when:

TopGun write volume is high and you want to isolate I/O
You want independent backup/restore for TopGun data
Your existing database is already under heavy load

Server API Reference

For the full Rust server configuration including the PostgresDataStore API, see the Server API reference.

Adoption Path

Next Guide

Performance