Registry / database / koishi-plugin-mysql

koishi-plugin-mysql

library3.6.2jsnpmunverified

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.

database

npm install koishi-plugin-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOISHI-PLUGIN-MYSQ

koishi-plugin-mysql

databasejavascriptv3.6.2

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.

default

✓ import Koishi from 'koishi'; import mysql from 'koishi-plugin-mysql';

✗ const mysql = require('koishi-plugin-mysql');

ESM-only package — use ES module syntax.

Database

✓ import { Database } from 'koishi';

✗ import { Database } from 'koishi-plugin-mysql';

Database is from core, not from this plugin.

MySQLDriver

✓ import MySQLDriver from 'koishi-plugin-mysql';

✗ import { MySQLDriver } from 'koishi-plugin-mysql';

Default export is the driver class; no named export exists.

Initializes a Koishi application with MySQL database adapter using environment variables for configuration.

import Koishi from 'koishi'; import mysql from 'koishi-plugin-mysql'; const app = new Koishi({ port: 3306, database: { mysql: { host: process.env.MYSQL_HOST ?? 'localhost', port: parseInt(process.env.MYSQL_PORT ?? '3306', 10), user: process.env.MYSQL_USER ?? 'root', password: process.env.MYSQL_PASSWORD ?? '', database: process.env.MYSQL_DB ?? 'koishi', }, }, }); app.plugin(mysql); app.start().then(() => { console.log('Koishi with MySQL started'); });

Debug

Known issues

breakingkoishi-plugin-mysql v3 requires koishi-core ^3.14.2 — incompatible with older core versions.

fix

Update koishi-core to ^3.14.2.

affects: <3.14.2

breakingIn v3, the plugin is ESM-only. CommonJS require() throws MODULE_NOT_FOUND.

fix

Use ES module imports (import/import()) or enable ESM in your project.

affects: >=3.0.0

breakingConfiguration changed from koishi-core v2 to v3 — 'database: { mysql: { ... } }' inside Koishi options.

fix

Place MySQL config under database.mysql in the Koishi constructor options.

affects: >=3.0.0

gotchaDatabase instance is not available during plugin lifecycle 'apply' — access via ctx.database after app.start().

fix

Use ctx.database inside command handlers or after start.

affects: >=3.0.0

gotchaTable schemas are auto-created only if using Koishi's built-in models. Custom models require manual table creation.

fix

Define models via ctx.model() and the plugin creates tables automatically.

affects: >=3.0.0

deprecatedkoishi-plugin-mysql v2 is deprecated and receives no updates; upgrade to v3.

fix

Install koishi-plugin-mysql@3 and update config accordingly.

affects: <3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'koishi-plugin-mysql'

CJS require() used with ESM-only v3 package.

fix

Change to ES module import: import mysql from 'koishi-plugin-mysql';

TypeError: app.plugin is not a function

Using plugin before creating Koishi app instance.

fix

Ensure app = new Koishi(options) before calling app.plugin().

Error: ER_ACCESS_DENIED_ERROR: Access denied for user 'root'@'localhost'

Incorrect MySQL credentials in config.

fix

Verify MYSQL_USER, MYSQL_PASSWORD environment variables or config values.

Error: ER_BAD_DB_ERROR: Unknown database 'koishi'

MySQL database does not exist.

fix

CREATE DATABASE koishi; or change database name in config.

Error: listen EADDRINUSE: address already in use :::3306

Port conflicts; Koishi defaults to port 3306 for database, not the app.

fix

Change database port in config (database.mysql.port) or stop conflicting service.

Upgrade

Version history

3.6.2latest on npm

Audit

Dependencies

koishi-coreoptionalPeer dependency — provides Database API and plugin system

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/koishijs/koishi ↗

packagekoishi-plugin-mysql ↗

homepagehttps://github.com/koishijs/koishi/tree/master/packages/database-mysql#readme ↗