Driver

The driver is responsible for storing and querying room data used by the matchmaker.

When a room is created, deleted, or has its metadata updated, the driver persists this information. The matchmaker then uses it to find available rooms for players to join.

For single-process deployments, the default in-memory driver is sufficient. For multi-process or distributed deployments, you need an external driver (like Redis or PostgreSQL) so all server instances share the same room data.

Available Drivers

• In-Memory Driver (default)
• Redis Driver
• Database Driver (@colyseus/database)
• Drizzle Driver (PostgreSQL)
• MongoDB Driver

In-Memory Driver

The default driver used by Colyseus is the LocalDriver, which stores all room data in memory. This driver is suitable for development and small-scale single-process applications.

Redis Driver

The RedisDriver stores room data in a Redis database using ioredis. This driver is suitable for large-scale multi-process applications and is recommended for production environments.

npm install --save @colyseus/redis-driver

pnpm add @colyseus/redis-driver

yarn add @colyseus/redis-driver

bun add @colyseus/redis-driver

Basic Usage

import { defineServer } from "colyseus";
import { RedisDriver } from "@colyseus/redis-driver";
 
const server = defineServer({
    driver: new RedisDriver(),
    // ...
});

Connection Options

The driver accepts multiple connection formats:

// Using a connection URL
new RedisDriver("redis://username:password@localhost:6379/0")
 
// Using a port number (connects to localhost)
new RedisDriver(6379)
 
// Using RedisOptions object
new RedisDriver({
    host: "localhost",
    port: 6379,
    password: "your-password",
    db: 0,
    // ... any ioredis options
})

See ioredis connection options for the full list of available options.

Redis Cluster

For high-availability setups, the driver supports Redis Cluster mode:

import { defineServer } from "colyseus";
import { RedisDriver } from "@colyseus/redis-driver";
 
const server = defineServer({
    driver: new RedisDriver([
        { host: "node1.redis.example.com", port: 6379 },
        { host: "node2.redis.example.com", port: 6379 },
        { host: "node3.redis.example.com", port: 6379 },
    ], {
        // ClusterOptions (optional)
        redisOptions: { password: "your-password" }
    }),
    // ...
});

See ioredis Cluster documentation for all available cluster options.

Database Driver

The DatabaseDriver from @colyseus/database stores room data on the same connection your GameDatabase already uses for players, cloud saves, and configs. One pool, one dialect (SQLite, PostgreSQL, or PGlite), no second service to run. Use it when your server has a database: option. This driver is a different package from the Drizzle driver below, which manages its own PostgreSQL connection and roomcaches_v1 table.

import { defineServer } from "colyseus";
import { GameDatabase, DatabaseDriver } from "@colyseus/database";
 
export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });
 
export default defineServer({
    database: db,
    driver: new DatabaseDriver(), // adopts the GameDatabase connection
});

Without options, the driver binds to the most recently constructed GameDatabase. With more than one instance in the process, pass it explicitly: new DatabaseDriver({ database: db }). The class is also exported from the @colyseus/database/driver subpath.

The driver creates its colyseus_room_caches table at boot (CREATE TABLE IF NOT EXISTS) on whichever dialect the database uses. The table is driver-owned: a server that uses @colyseus/database with the in-memory or Redis driver never gets it. Room fields that are not columns (metadata and any custom option) are stored in the metadata JSON column and remain queryable by join() / joinOrCreate() filters.

Custom Table

To add columns or change the physical name, build the table with the roomCaches factory (see Customizing schemas) and pass it as schema. Extra columns persist with the room and work as matchmaking filters. schema is the only option needed: the driver still binds to the GameDatabase constructed above.

import { defineServer } from "colyseus";
import { GameDatabase, DatabaseDriver, tables } from "@colyseus/database";
import { text } from "drizzle-orm/sqlite-core";
 
export const db = new GameDatabase({ connectionString: "./game.db" });
 
const roomCaches = tables.sqlite.roomCaches("colyseus_room_caches", {
    region: text("region"),
});
 
export default defineServer({
    database: db,
    driver: new DatabaseDriver({ schema: roomCaches }),
});

import { defineServer } from "colyseus";
import { GameDatabase, DatabaseDriver, tables } from "@colyseus/database";
import { text } from "drizzle-orm/pg-core";
 
export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });
 
const roomCaches = tables.pg.roomCaches("colyseus_room_caches", {
    region: text("region"),
});
 
export default defineServer({
    database: db,
    driver: new DatabaseDriver({ schema: roomCaches }),
});

Without a GameDatabase

The driver also works on a Drizzle instance you manage yourself (node-sqlite, postgres-js, or PGlite). Pass the SQL flavor, since it cannot be detected from the instance. In this mode the driver closes the connection on server shutdown; set closeOnShutdown: false if you share the instance elsewhere:

import { defineServer } from "colyseus";
import { DatabaseDriver } from "@colyseus/database";
import { drizzle } from "drizzle-orm/node-sqlite";
 
const sdb = drizzle({ connection: { path: "game.db" } });
 
export default defineServer({
    driver: new DatabaseDriver({ drizzle: sdb, dialect: "sqlite" }),
});

Drizzle Driver (PostgreSQL)

The PostgresDriver stores room data in a PostgreSQL database using Drizzle ORM. This driver is suitable for large-scale multi-process applications and is recommended for production environments.

npm install --save @colyseus/drizzle-driver

pnpm add @colyseus/drizzle-driver

yarn add @colyseus/drizzle-driver

bun add @colyseus/drizzle-driver

Basic Usage

The simplest way to use the driver is to set the DATABASE_URL environment variable:

import { defineServer } from "colyseus";
import { PostgresDriver } from "@colyseus/drizzle-driver";
 
const server = defineServer({
    driver: new PostgresDriver(),
    // ...
});

The driver will automatically connect using the DATABASE_URL environment variable, or fall back to postgresql://postgres:postgres@localhost:5432/postgres.

Using an Existing Database Instance

If you already have a Drizzle database instance in your application, you can pass it to the driver:

import { defineServer } from "colyseus";
import { drizzle } from "drizzle-orm/postgres-js";
import { PostgresDriver } from "@colyseus/drizzle-driver";
 
// Your existing database instance
const db = drizzle(process.env.DATABASE_URL);
 
const server = defineServer({
    driver: new PostgresDriver({ db }),
    // ...
});

Custom Schema

You can provide a custom schema if you need to modify the table structure:

import { defineServer } from "colyseus";
import { PostgresDriver, roomcaches } from "@colyseus/drizzle-driver";
import { pgTable, integer, boolean, timestamp, jsonb, varchar } from "drizzle-orm/pg-core";
 
// Custom schema with additional fields or different table name
const customRoomCaches = pgTable('my_room_caches', {
    roomId: varchar({ length: 9 }).primaryKey(),
    processId: varchar({ length: 9 }),
    name: varchar({ length: 64 }).notNull(),
    clients: integer().notNull(),
    maxClients: integer().notNull(),
    locked: boolean(),
    private: boolean(),
    metadata: jsonb(),
    publicAddress: varchar({ length: 255 }),
    createdAt: timestamp().notNull().defaultNow(),
    unlisted: boolean(),
    // Add your custom fields here
});
 
const server = defineServer({
    driver: new PostgresDriver({ schema: customRoomCaches }),
    // ...
});

Default Table Schema

The driver creates a roomcaches_v1 table with the following structure:

MongoDB Driver

The MongooseDriver stores room data in a MongoDB database. This driver is not actively maintained and is not recommended for production environments.

import { defineServer } from "colyseus";
import { MongooseDriver } from "@colyseus/mongoose-driver";
 
const server = defineServer({
    driver: new MongooseDriver(/* connection URI (falls back to MONGO_URI env, then mongodb://127.0.0.1:27017/colyseus) */),
    // ...
});