Skip to main content
UpNext server persistence is selected with UPNEXT_BACKEND or upnext server start --backend. Valid values are redis, sqlite, and postgres.

​
Backend comparison

BackendSet UPNEXT_BACKENDPersistent storeUPNEXT_DATABASE_URLMigrations
RedisredisRedis keysIgnored for persistenceNot used
SQLitesqliteSQLite fileOptional (defaults to sqlite+aiosqlite:///upnext.db)Auto-creates tables at startup
PostgreSQLpostgresPostgreSQLRequiredRequired before startup

​
Startup and migration matrix

BackendRequired envStartup behavior
RedisUPNEXT_BACKEND=redis, UPNEXT_REDIS_URLServer starts without SQL migrations
SQLiteUPNEXT_BACKEND=sqlite (optional UPNEXT_DATABASE_URL)Tables are auto-created on startup
PostgreSQLUPNEXT_BACKEND=postgres, UPNEXT_DATABASE_URLFails fast if required tables are missing; run migrations first

​
Choosing by scale

  • Use redis for the simplest deployment and low-scale persistence with no SQL dependency.
  • Use sqlite for local/dev setups that still need persistent history in a file.
  • Use postgres for larger or long-term deployments where query scale and retention are more demanding.

​
Redis vs PostgreSQL

If you need…Choose
Simplest setup with no SQL service dependencyUPNEXT_BACKEND=redis
Small, low-scale persistence with minimal infrastructureUPNEXT_BACKEND=redis
Long retention windows and growing historical query loadUPNEXT_BACKEND=postgres
Production-scale durability and analytics-heavy dashboardsUPNEXT_BACKEND=postgres
For many teams, redis is a great beta/default path and postgres is the natural upgrade path as usage grows.

​
Redis has two roles

Redis can be used in two separate ways:
  1. As the persistence backend when UPNEXT_BACKEND=redis.
  2. As the runtime stream/queue dependency through UPNEXT_REDIS_URL for workers and real-time server features.
These are related but separate settings. You can run SQL persistence (sqlite or postgres) while still using UPNEXT_REDIS_URL for stream processing and real-time updates.

​
Example startup commands

# Redis persistence backend (default behavior if UPNEXT_BACKEND is omitted)
UPNEXT_BACKEND=redis \
UPNEXT_REDIS_URL=redis://localhost:6379 \
upnext server start --port 8080

# SQLite persistence backend
UPNEXT_BACKEND=sqlite \
UPNEXT_DATABASE_URL=sqlite+aiosqlite:///upnext.db \
UPNEXT_REDIS_URL=redis://localhost:6379 \
upnext server start --port 8080

# PostgreSQL persistence backend
UPNEXT_BACKEND=postgres \
UPNEXT_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/upnext \
upnext server db upgrade head

UPNEXT_BACKEND=postgres \
UPNEXT_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/upnext \
UPNEXT_REDIS_URL=redis://localhost:6379 \
upnext server start --port 8080