Registry / database / telegraf-session-mysql

telegraf-session-mysql

JSON →
library5.3.0jsnpmunverified

MySQL-powered session middleware for Telegraf (Telegram Bot Framework) v5.3.0. Persists session data both in MySQL and in-memory for performance, with automatic table creation, configurable lifetime and garbage collection. Requires Node >=12 and MySQL >=5.5.62. Forked from telegraf-session-redis, focused on SQL-based storage. Supports scoped sessions per user, chat, or custom key functions.

database
npm install telegraf-session-mysql
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · TELEGRAF-SESSION-M
T
telegraf-session-mysql
databasejavascriptv5.3.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.

MySQLSession
✓ const MySQLSession = require('telegraf-session-mysql')
CJS only; no ESM export provided
MySQLSession
✓ import MySQLSession from 'telegraf-session-mysql'
✗ import { MySQLSession } from 'telegraf-session-mysql'
Default import only as CJS module; named import will result in undefined
session (middleware)
✓ const session = new MySQLSession(...); telegraf.use(session.middleware())
✗ telegraf.use(new MySQLSession().middleware())
Must call connect() before using middleware, or session is not initialized

Minimal bot with session counter using MySQL middleware. Shows setup, connection, and usage.

const Telegraf = require('telegraf'); const MySQLSession = require('telegraf-session-mysql'); const bot = new Telegraf(process.env.BOT_TOKEN); const session = new MySQLSession({ host: process.env.MYSQL_HOST ?? 'localhost', user: process.env.MYSQL_USER ?? 'root', password: process.env.MYSQL_PASSWORD ?? '', database: process.env.MYSQL_DATABASE ?? 'telegraf_sessions' }); bot.use(session.middleware()); (async () => { await session.connect(); bot.on('text', (ctx) => { ctx.session.counter = (ctx.session.counter || 0) + 1; ctx.reply(`Session counter: ${ctx.session.counter}`); }); await bot.launch(); })();
Debug
Known issues
breakingVersion 3.0.0 changed from mysql to mysql2 package for connection. Old config object with host/user/pass/database still works but uses mysql2 internally.
fix
Ensure mysql2 is installed (npm install mysql2); no code changes needed unless you used direct mysql connection methods.
affects: >=3.0.0
deprecatedThe getSessionKey function signature changed in v4: now receives context object, not update. Old (update) => {} still works but will break if you depend on non-context properties.
fix
Update getSessionKey to accept ctx and use ctx.from, ctx.chat as needed.
affects: >=4.0.0 <5.0.0
gotchaSession data is stored in-memory and only flushed to MySQL on process exit or explicit save. In case of crash, unsaved sessions are lost.
fix
Use saveSession() explicitly if you need guaranteed persistence. Not suitable for critical data without additional persistence layer.
affects: >=1.0.0
gotchaDefault table name is 'session', which may conflict with reserved words in SQL or existing tables. Always set a custom table name via options.table.
fix
Set { table: 'bot_sessions' } in constructor options.
affects: >=1.0.0
gotchaThe lifetime garbage collector only runs when interval is set. Default interval is 300000 ms, but if set to 0, no cleanup happens and old sessions persist indefinitely.
fix
Set interval to a reasonable value or implement your own cleanup.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'mysql2'
mysql2 is a runtime dependency but not listed as a peer dependency; you must install it separately.
fix
Run: npm install mysql2
TypeError: session.middleware is not a function
You may have forgotten to instantiate MySQLSession with 'new', or you imported the constructor incorrectly.
fix
Ensure you use 'new MySQLSession(...)' and call .middleware() on the instance.
ER_BAD_DB_ERROR: Unknown database 'telegraf_sessions'
The MySQL database does not exist. The middleware does not create the database, only the table.
fix
Create the database manually: CREATE DATABASE telegraf_sessions;
Cannot read properties of undefined (reading 'counter')
ctx.session is undefined because the session middleware is not applied correctly or the session key function returns undefined.
fix
Check that telegraf.use(session.middleware()) is called before any handlers, and verify getSessionKey returns a valid key.
Upgrade
Version history
5.3.0latest on npm
Audit
Dependencies
telegrafrequiredPeer dependency: Telegraf bot framework middleware interface
mysql2requiredRuntime dependency for MySQL connection and queries
Agent activity
19 hits · last 30 days
node
16
Meta
2
OpenAI (training)
1
Resources
githubhttps://github.com/hnaderi/telegraf-session-mysql ↗
packagetelegraf-session-mysql ↗
homepagehttps://github.com/hnaderi/telegraf-session-mysql#readme ↗
telegraf-session-mysql — npm install telegraf-session-mysql · libregistry