Running Multiple Instances
Run an AxilJS app on several workers or servers: which state is per process by default, and how to share idempotency, cache, locks, rate limits, jobs, AI budgets and events through your database.
On this page12
By default, idempotency records, cache entries, locks, rate-limit counters, AI budgets and queued jobs live in the memory of one process. That is correct for a single instance and wrong as soon as there are several, whether they are cluster workers on one machine or servers behind a load balancer:
- a retried payment reaches a server that has not seen its idempotency key, and runs twice;
- a
tLockis held by two servers at once; - a rate limit of 100 becomes 100 per instance;
- a job added on one server is only ever processed there, and is lost if that process exits.
AxilJS keeps this state in the database you already have, so no Redis is required.
Note
New in 0.3.6: useStores() and createSqlStores() make this a few lines. The saas-api and high-scale-api templates are set up this way.
What is per process by default
| State | Package | Default | Shared implementation |
|---|---|---|---|
Idempotency, cache, locks, rate limits (tIdempotent, tCache*, tLock, tRateLimit, tThrottle) | @axiljs/runtime | In process memory | createSqlStores + useStores (@axiljs/stores) |
HTTP rate limiting (rateLimit()) | @axiljs/security | MemoryStore per limiter | rateLimit({ store: stores.rateLimit }), or ClusterStore within one host |
| Jobs | @axiljs/queue | InMemoryQueueStore | SqlQueueBackend (FOR UPDATE SKIP LOCKED) |
AI budgets (withBudget) | @axiljs/ai | In process memory | withBudget({ store: stores.budget }) |
| Events | @axiljs/events | One bus per process | ClusterTransport within one host |
Setup
1. Open one connection
1import { createConnection } from '@axiljs/orm'
2import { fromConnection } from '@axiljs/stores'
3
4const db = await createConnection({ driver: 'postgres', url: process.env.DATABASE_URL })
5const sql = fromConnection(db)2. Install the shared stores
1import { createSqlStores } from '@axiljs/stores'
2import { useStores } from '@axiljs/runtime'
3
4const stores = createSqlStores(sql, { cleanupIntervalMs: 60_000 })
5await stores.ensureSchema() // create every table at startup
6useStores(stores) // tIdempotent, tCache, tLock, tRateLimit, tThrottleThe tables (axil_rate_limits, axil_idempotency, axil_cache, axil_cache_tags, axil_locks, axil_ai_budget) are created with CREATE TABLE IF NOT EXISTS; no migration is needed. See the stores overview for the options.
3. Share HTTP rate limits
import { rateLimit } from '@axiljs/security'
app.use(rateLimit({ max: 100, windowMs: 60_000, store: stores.rateLimit }))Limiters with different windows must not share keys in one table; give each its own SqlRateLimitStore table or a distinct key prefix. See Rate limiting.
4. Share the job queue
1import { Queue, SqlQueueBackend } from '@axiljs/queue'
2
3const jobs = new Queue('jobs', { backend: new SqlQueueBackend({ executor: sql }) })
4jobs.process('send-welcome', async (job) => sendEmail(job.data.to))
5jobs.start()Each job runs on one server. Delivery is at least once, so handlers must be idempotent; in backend mode use the async accessors (getJobsAsync(), getStatsAsync(), ...). See Queue across servers.
5. Share AI budgets
import { withBudget } from '@axiljs/ai'
const ai = withBudget(provider, { limits: { window: 'month', costUsd: 50 }, store: stores.budget })6. Within one host: cluster services
Cluster workers on one machine can also share rate-limit counters and events through the primary process, without a database. Install the primary-side services with serve()'s onPrimary hook:
1import { serve } from '@axiljs/scale'
2import { installClusterRateLimitPrimary } from '@axiljs/security'
3import { installClusterEventRelay } from '@axiljs/events'
4
5serve(createApp, {
6 port: 3000,
7 onPrimary: () => {
8 const stopRateLimits = installClusterRateLimitPrimary()
9 const stopRelay = installClusterEventRelay()
10 return () => { stopRateLimits(); stopRelay() }
11 }
12})Inside the app, use rateLimit({ store: new ClusterStore() }) and new EventBus({ transport: new ClusterTransport() }). Both behave like their in-process versions when there is only one worker. These services do not reach other machines; see cluster rate limiting and cross-process events.
7. Close on shutdown
await jobs.stop()
stores.close() // cleanup timers only; never closes the connection
await db.disconnect()Choosing a database
| Database | Use it for |
|---|---|
| PostgreSQL | Recommended for multi-server deployments. Every store operation is a single atomic statement or a short transaction; supports advisory locks (lock: 'advisory') |
| MySQL 8 | Supported for multi-server deployments. Counters use an upsert plus SELECT in one transaction |
| SQLite | Several processes on one machine sharing a database file, not several servers |
Tip
Keep server clocks in sync (NTP). Rate-limit windows, cache and idempotency expiries, and lock leases are computed from each server's clock.
Not covered
These still keep state per process; the readiness scan finds them in your src/:
Schedulercron tasks fire in every process that starts the scheduler.- WebSocket rooms only contain the clients connected to that process.
- Your own in-memory state, such as a
Mapused as a cache.
Related
Was this page helpful?