{"id":44030,"library":"telegraf-session-mysql","title":"telegraf-session-mysql","description":"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.","status":"active","version":"5.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/hnaderi/telegraf-session-mysql","tags":["javascript","telegram","telegram bot","telegraf","bot framework","session","middleware","mysql"],"install":[{"cmd":"npm install telegraf-session-mysql","lang":"bash","label":"npm"},{"cmd":"yarn add telegraf-session-mysql","lang":"bash","label":"yarn"},{"cmd":"pnpm add telegraf-session-mysql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: Telegraf bot framework middleware interface","package":"telegraf","optional":false},{"reason":"Runtime dependency for MySQL connection and queries","package":"mysql2","optional":false}],"imports":[{"note":"CJS only; no ESM export provided","symbol":"MySQLSession","correct":"const MySQLSession = require('telegraf-session-mysql')"},{"note":"Default import only as CJS module; named import will result in undefined","wrong":"import { MySQLSession } from 'telegraf-session-mysql'","symbol":"MySQLSession","correct":"import MySQLSession from 'telegraf-session-mysql'"},{"note":"Must call connect() before using middleware, or session is not initialized","wrong":"telegraf.use(new MySQLSession().middleware())","symbol":"session (middleware)","correct":"const session = new MySQLSession(...); telegraf.use(session.middleware())"}],"quickstart":{"code":"const Telegraf = require('telegraf');\nconst MySQLSession = require('telegraf-session-mysql');\n\nconst bot = new Telegraf(process.env.BOT_TOKEN);\n\nconst session = new MySQLSession({\n  host: process.env.MYSQL_HOST ?? 'localhost',\n  user: process.env.MYSQL_USER ?? 'root',\n  password: process.env.MYSQL_PASSWORD ?? '',\n  database: process.env.MYSQL_DATABASE ?? 'telegraf_sessions'\n});\n\nbot.use(session.middleware());\n\n(async () => {\n  await session.connect();\n  bot.on('text', (ctx) => {\n    ctx.session.counter = (ctx.session.counter || 0) + 1;\n    ctx.reply(`Session counter: ${ctx.session.counter}`);\n  });\n  await bot.launch();\n})();","lang":"javascript","description":"Minimal bot with session counter using MySQL middleware. Shows setup, connection, and usage."},"warnings":[{"fix":"Ensure mysql2 is installed (npm install mysql2); no code changes needed unless you used direct mysql connection methods.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update getSessionKey to accept ctx and use ctx.from, ctx.chat as needed.","message":"The 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.","severity":"deprecated","affected_versions":">=4.0.0 <5.0.0"},{"fix":"Use saveSession() explicitly if you need guaranteed persistence. Not suitable for critical data without additional persistence layer.","message":"Session data is stored in-memory and only flushed to MySQL on process exit or explicit save. In case of crash, unsaved sessions are lost.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set { table: 'bot_sessions' } in constructor options.","message":"Default table name is 'session', which may conflict with reserved words in SQL or existing tables. Always set a custom table name via options.table.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set interval to a reasonable value or implement your own cleanup.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'12':39 '5.5.62':42 'automat':29 'base':53 'bot':13,68,70 'chat':60 'collect':36 'configur':32 'creation':31 'custom':62 'data':18 'focus':49 'fork':43 'framework':14,71 'function':64 'garbag':35 'in-memori':23 'javascript':65 'key':63 'lifetim':33 'memori':25 'middlewar':9,73 'mysql':4,6,21,41,74 'mysql-pow':5 'node':38 'per':58 'perform':27 'persist':16 'power':7 'redi':48 'requir':37 'scope':56 'session':3,8,17,47,57,72 'sql':52 'sql-base':51 'storag':54 'support':55 'tabl':30 'telegraf':2,11,46,69 'telegraf-session-mysql':1 'telegraf-session-redi':45 'telegram':12,66,67 'user':59 'v5.3.0':15","created_at":"2026-06-05T17:02:38.127188+00:00","updated_at":"2026-06-05T17:02:38.127188+00:00","problems":[{"fix":"Run: npm install mysql2","cause":"mysql2 is a runtime dependency but not listed as a peer dependency; you must install it separately.","error":"Error: Cannot find module 'mysql2'"},{"fix":"Ensure you use 'new MySQLSession(...)' and call .middleware() on the instance.","cause":"You may have forgotten to instantiate MySQLSession with 'new', or you imported the constructor incorrectly.","error":"TypeError: session.middleware is not a function"},{"fix":"Create the database manually: CREATE DATABASE telegraf_sessions;","cause":"The MySQL database does not exist. The middleware does not create the database, only the table.","error":"ER_BAD_DB_ERROR: Unknown database 'telegraf_sessions'"},{"fix":"Check that telegraf.use(session.middleware()) is called before any handlers, and verify getSessionKey returns a valid key.","cause":"ctx.session is undefined because the session middleware is not applied correctly or the session key function returns undefined.","error":"Cannot read properties of undefined (reading 'counter')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/hnaderi/telegraf-session-mysql#readme","github":"https://github.com/hnaderi/telegraf-session-mysql","docs":null,"changelog":null,"pypi":null,"npm":"telegraf-session-mysql","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}