Getting Started

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.

5 min readUpdated DocumentationEdit this page
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 tLock is 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

StatePackageDefaultShared implementation
Idempotency, cache, locks, rate limits (tIdempotent, tCache*, tLock, tRateLimit, tThrottle)@axiljs/runtimeIn process memorycreateSqlStores + useStores (@axiljs/stores)
HTTP rate limiting (rateLimit())@axiljs/securityMemoryStore per limiterrateLimit({ store: stores.rateLimit }), or ClusterStore within one host
Jobs@axiljs/queueInMemoryQueueStoreSqlQueueBackend (FOR UPDATE SKIP LOCKED)
AI budgets (withBudget)@axiljs/aiIn process memorywithBudget({ store: stores.budget })
Events@axiljs/eventsOne bus per processClusterTransport within one host

Setup

1. Open one connection

TypeScript
TS
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

TypeScript
TS
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, tThrottle

The 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

TypeScript
TS
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

TypeScript
TS
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

TypeScript
TS
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:

TypeScript
TS
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

TypeScript
TS
await jobs.stop()
stores.close()          // cleanup timers only; never closes the connection
await db.disconnect()

Choosing a database

DatabaseUse it for
PostgreSQLRecommended for multi-server deployments. Every store operation is a single atomic statement or a short transaction; supports advisory locks (lock: 'advisory')
MySQL 8Supported for multi-server deployments. Counters use an upsert plus SELECT in one transaction
SQLiteSeveral 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/:

  • Scheduler cron 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 Map used as a cache.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY