chat-state-mysql

library0.1.0jsnpmunverified

Community MySQL state adapter for Chat SDK, built with mysql2. Currently at version 0.1.0. Provides state persistence for Chat SDK bots using MySQL as the primary datastore, supporting subscriptions, distributed locking, key-value caching with TTL, and automatic table creation. Supports MySQL 5.7+. Compared to the built-in Redis adapter, this is a lighter alternative when you already have MySQL and want to avoid a separate Redis instance, though it has higher latency and lacks automatic expired row cleanup. The adapter automatically detects MYSQL_URL or DATABASE_URL environment variables, or accepts an explicit URL or an existing mysql2 pool instance. It is fully typed (TypeScript) and published on npm.

database

npm install chat-state-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CHAT-STATE-MYSQL

chat-state-mysql

databasejavascriptv0.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createMySqlState

✓ import { createMySqlState } from 'chat-state-mysql'

✗ import createMySqlState from 'chat-state-mysql'

The default export is not available; you must use named import.

MySqlStateOptions

✓ import { MySqlStateOptions } from 'chat-state-mysql'

This type is exported for TypeScript users. Use to type the options object passed to createMySqlState.

createMySqlState with require

✓ const { createMySqlState } = require('chat-state-mysql')

✗ const createMySqlState = require('chat-state-mysql')

CommonJS users must destructure, as the package does not export a default.

Shows how to create a MySQL state adapter and use it with the Chat SDK bot instance.

import { Chat } from 'chat'; import { createMySqlState } from 'chat-state-mysql'; const state = createMySqlState({ url: process.env.MYSQL_URL ?? 'mysql://root:root@localhost:3306/chat', }); const bot = new Chat({ userName: 'mybot', adapters: { /* ... */ }, state, }); bot.start(); // The bot now uses MySQL for state persistence.

Debug

Known issues

gotchaExpired rows (locks, cache, queues) are not automatically cleaned up by MySQL. The adapter only cleans expired entries on access, which may lead to accumulation in high-throughput scenarios.

fix

Run periodic cleanup SQL queries (as described in the README) or schedule a cron job to delete expired rows.

affects: >=0.1.0

gotchaLocking performance is worse than Redis. The MySQL adapter uses InnoDB row-level locking and INSERT ... ON DUPLICATE KEY UPDATE, which is safe but slower under high contention.

fix

Use the Redis state adapter for high-contention distributed locking, or keep contention low.

affects: >=0.1.0

gotchaThe adapter requires one of: explicit `url` option, MYSQL_URL environment variable, DATABASE_URL environment variable, or `client` (existing mysql2 pool). If none is provided, the adapter throws an error.

fix

Pass the url or client option, or set MYSQL_URL or DATABASE_URL.

affects: >=0.1.0

gotchaThe adapter automatically creates tables on `connect()`. Make sure the provided MySQL user has CREATE TABLE privileges.

fix

Grant CREATE TABLE privileges or create the tables manually in advance.

affects: >=0.1.0

Errors

Common errors & fixes

Error: createMySqlState: either url, client, or MYSQL_URL/DATABASE_URL env must be provided

No MySQL connection configuration was supplied.

fix

Set MYSQL_URL environment variable or pass url/client option to createMySqlState.

ER_ACCESS_DENIED_ERROR: Access denied for user 'user'@'host' to database 'chat'

MySQL user lacks permissions to connect to the database or perform operations.

fix

Grant necessary privileges to the user: GRANT ALL PRIVILEGES ON chat.* TO 'user'@'host';

TypeError: Cannot read properties of undefined (reading 'createPool')

The mysql2 package is not installed or not imported correctly.

fix

Ensure mysql2 is installed: npm install mysql2. If using an existing client, verify the import path.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

chatrequiredPeer dependency; the core Chat SDK that this state adapter works with.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/DivyanshGolyan/chat-state-mysql ↗

packagechat-state-mysql ↗

homepagehttps://github.com/DivyanshGolyan/chat-state-mysql#readme ↗