{"id":42967,"library":"koishi-plugin-mysql","title":"Koishi MySQL Database Plugin","description":"MySQL database adapter for the Koishi chatbot framework (v3.6.2). Provides persistent storage for user data, sessions, and application state via MySQL/MariaDB. Updated on the same cadence as Koishi core (~monthly). Differentiators: native integration with Koishi's ORM-style query API, full TypeScript types, and zero-config setup within Koishi projects. Alternatives like direct mysql2 usage lack Koishi's plugin lifecycle management.","status":"active","version":"3.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/koishijs/koishi","tags":["javascript","bot","qqbot","cqhttp","coolq","chatbot","koishi","database","mysql","typescript"],"install":[{"cmd":"npm install koishi-plugin-mysql","lang":"bash","label":"npm"},{"cmd":"yarn add koishi-plugin-mysql","lang":"bash","label":"yarn"},{"cmd":"pnpm add koishi-plugin-mysql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency — provides Database API and plugin system","package":"koishi-core","optional":true}],"imports":[{"note":"ESM-only package — use ES module syntax.","wrong":"const mysql = require('koishi-plugin-mysql');","symbol":"default","correct":"import Koishi from 'koishi'; import mysql from 'koishi-plugin-mysql';"},{"note":"Database is from core, not from this plugin.","wrong":"import { Database } from 'koishi-plugin-mysql';","symbol":"Database","correct":"import { Database } from 'koishi';"},{"note":"Default export is the driver class; no named export exists.","wrong":"import { MySQLDriver } from 'koishi-plugin-mysql';","symbol":"MySQLDriver","correct":"import MySQLDriver from 'koishi-plugin-mysql';"}],"quickstart":{"code":"import Koishi from 'koishi';\nimport mysql from 'koishi-plugin-mysql';\n\nconst app = new Koishi({\n  port: 3306,\n  database: {\n    mysql: {\n      host: process.env.MYSQL_HOST ?? 'localhost',\n      port: parseInt(process.env.MYSQL_PORT ?? '3306', 10),\n      user: process.env.MYSQL_USER ?? 'root',\n      password: process.env.MYSQL_PASSWORD ?? '',\n      database: process.env.MYSQL_DB ?? 'koishi',\n    },\n  },\n});\n\napp.plugin(mysql);\n\napp.start().then(() => {\n  console.log('Koishi with MySQL started');\n});","lang":"typescript","description":"Initializes a Koishi application with MySQL database adapter using environment variables for configuration."},"warnings":[{"fix":"Update koishi-core to ^3.14.2.","message":"koishi-plugin-mysql v3 requires koishi-core ^3.14.2 — incompatible with older core versions.","severity":"breaking","affected_versions":"<3.14.2"},{"fix":"Use ES module imports (import/import()) or enable ESM in your project.","message":"In v3, the plugin is ESM-only. CommonJS require() throws MODULE_NOT_FOUND.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Place MySQL config under database.mysql in the Koishi constructor options.","message":"Configuration changed from koishi-core v2 to v3 — 'database: { mysql: { ... } }' inside Koishi options.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use ctx.database inside command handlers or after start.","message":"Database instance is not available during plugin lifecycle 'apply' — access via ctx.database after app.start().","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Define models via ctx.model() and the plugin creates tables automatically.","message":"Table schemas are auto-created only if using Koishi's built-in models. Custom models require manual table creation.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Install koishi-plugin-mysql@3 and update config accordingly.","message":"koishi-plugin-mysql v2 is deprecated and receives no updates; upgrade to v3.","severity":"deprecated","affected_versions":"<3.0.0"}],"env_vars":null,"search_vec":"'adapt':7 'altern':57 'api':45 'applic':22 'bot':69 'cadenc':30 'chatbot':11,73 'config':52 'coolq':72 'core':33 'cqhttp':71 'data':19 'databas':3,6,75 'differenti':35 'direct':59 'framework':12 'full':46 'integr':37 'javascript':68 'koishi':1,10,32,39,55,63,74 'lack':62 'lifecycl':66 'like':58 'manag':67 'month':34 'mysql':2,5,76 'mysql/mariadb':25 'mysql2':60 'nativ':36 'orm':42 'orm-styl':41 'persist':15 'plugin':4,65 'project':56 'provid':14 'qqbot':70 'queri':44 'session':20 'setup':53 'state':23 'storag':16 'style':43 'type':48 'typescript':47,77 'updat':26 'usag':61 'user':18 'v3.6.2':13 'via':24 'within':54 'zero':51 'zero-config':50","created_at":"2026-06-05T16:57:31.834904+00:00","updated_at":"2026-06-05T16:57:31.834904+00:00","problems":[{"fix":"Change to ES module import: import mysql from 'koishi-plugin-mysql';","cause":"CJS require() used with ESM-only v3 package.","error":"Error: Cannot find module 'koishi-plugin-mysql'"},{"fix":"Ensure app = new Koishi(options) before calling app.plugin().","cause":"Using plugin before creating Koishi app instance.","error":"TypeError: app.plugin is not a function"},{"fix":"Verify MYSQL_USER, MYSQL_PASSWORD environment variables or config values.","cause":"Incorrect MySQL credentials in config.","error":"Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'root'@'localhost'"},{"fix":"CREATE DATABASE koishi; or change database name in config.","cause":"MySQL database does not exist.","error":"Error: ER_BAD_DB_ERROR: Unknown database 'koishi'"},{"fix":"Change database port in config (database.mysql.port) or stop conflicting service.","cause":"Port conflicts; Koishi defaults to port 3306 for database, not the app.","error":"Error: listen EADDRINUSE: address already in use :::3306"}],"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/koishijs/koishi/tree/master/packages/database-mysql#readme","github":"https://github.com/koishijs/koishi","docs":null,"changelog":null,"pypi":null,"npm":"koishi-plugin-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}}