MySQL

Install

Quick start

createMySqlState() auto-detects MYSQL_URL (or DATABASE_URL), so you can call it with no arguments:

import { Chat } from "chat";
import { createMySqlState } from "chat-state-mysql";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    /* ... */
  },
  state: createMySqlState(),
});

To provide a URL explicitly:

const state = createMySqlState({
  url: "mysql://root:root@localhost:3306/chat",
});

Using an existing client

import mysql from "mysql2/promise";

const client = mysql.createPool(process.env.MYSQL_URL);
const state = createMySqlState({ client });

Configuration

Either url, the MYSQL_URL / DATABASE_URL env var, or client is required.

Data model

The adapter creates these tables automatically on connect():

chat_state_subscriptions
chat_state_locks
chat_state_cache
chat_state_lists
chat_state_queues

All rows are namespaced by key_prefix. Prefixes, thread IDs, and cache keys are stored as text, with SHA-256 hash columns used for MySQL primary keys and indexes — so long platform IDs and multibyte prefixes remain supported.

The schema avoids window functions and generated columns, and is compatible with MySQL 5.7 and newer.

Locking considerations

The Redis state adapters use atomic SET NX PX for lock acquisition. The MySQL adapter uses InnoDB row-level locking through INSERT ... ON DUPLICATE KEY UPDATE, replacing a lock only when the stored expires_at timestamp has passed. That's safe for typical multi-instance workloads, but Redis remains a better fit for high-contention distributed locking.

Expired row cleanup

Unlike Redis, MySQL does not automatically delete expired rows. The adapter performs opportunistic cleanup:

• Expired locks are overwritten on the next acquireLock() call.
• Expired cache entries are deleted on the next get() call for that key.
• Expired queue entries are purged during queue operations.

For high-throughput deployments, run a periodic cleanup job:

DELETE FROM chat_state_locks WHERE expires_at <= CURRENT_TIMESTAMP(3);
DELETE FROM chat_state_cache WHERE expires_at <= CURRENT_TIMESTAMP(3);
DELETE FROM chat_state_lists WHERE expires_at <= CURRENT_TIMESTAMP(3);
DELETE FROM chat_state_queues WHERE expires_at <= CURRENT_TIMESTAMP(3);

Feature support