Bring your own database

@colyseus/database is the recommended path, but Colyseus does not require it. Any database or Node.js module works. Query it directly from your room’s lifecycle methods.

If you go this route, we still recommend Drizzle ORM (what @colyseus/database is built on). Other commonly used tools:

ORMs (Object-Relational Mappers)

ORMs are known for abstracting the database layer and providing a more object-oriented approach.

Query builders

Query builders are known for their simplicity and flexibility.

Backend-as-a-Service

Firebase (Firestore / Realtime Database) is a common choice when you want managed persistence, authentication, and hosting without running your own database. Use the Firebase Admin SDK from your server and call it from the room lifecycle methods below, just like any other database client.

Usage patterns with Colyseus

Query the database in onAuth()

You may fetch user data based on the options passed to the client on connection, or based on the authentication token.

// ...
async onAuth(client, options) {
    const user = await db.query('SELECT * FROM users WHERE id = ?', [options.userId]);
    return user;
}
 
async onJoin (client, options) {
    // ...
    await db.query('UPDATE users SET online = true WHERE id = ?', [client.auth.id]);
}

Update the database in onLeave()

You may update the database when the client leaves the room.

// ...
async onLeave(client, consented) {
    // ...
    await db.query('UPDATE users SET online = false WHERE id = ?', [client.auth.id]);
}