{"id":16417,"library":"koishi-plugin-migrate-database","title":"Koishi Database Migration Plugin","description":"koishi-plugin-migrate-database is a utility plugin for the Koishi chatbot framework, designed to facilitate the migration of data between different database instances. As of version 0.2.1, it provides basic functionality for moving existing Koishi data, which is critical for developers managing evolving bot infrastructures or changing database backends. This plugin is typically released on an as-needed basis to support specific migration scenarios or Koishi core updates. Its primary differentiator is its integration directly into the Koishi ecosystem, allowing for migrations that are aware of Koishi's internal data structures, unlike generic database migration tools. Users should be aware that, as a 0.x.x version, its API and internal workings may still evolve, and thorough testing is recommended before production use.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/koikirin/koishi-plugin-migrate-database","tags":["javascript","chatbot","koishi","plugin","database","migrate","typescript"],"install":[{"cmd":"npm install koishi-plugin-migrate-database","lang":"bash","label":"npm"},{"cmd":"yarn add koishi-plugin-migrate-database","lang":"bash","label":"yarn"},{"cmd":"pnpm add koishi-plugin-migrate-database","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core framework, required for the plugin to function and access Koishi's context and database systems.","package":"koishi","optional":false}],"imports":[{"note":"Koishi plugins often export an `apply` function or a default object with an `apply` method. This plugin uses a named `apply` export.","wrong":"import migrateDatabase from 'koishi-plugin-migrate-database'","symbol":"apply","correct":"import { apply } from 'koishi-plugin-migrate-database'"},{"note":"Used for type-checking the plugin's configuration schema in TypeScript projects.","symbol":"Config","correct":"import { Config } from 'koishi-plugin-migrate-database'"},{"note":"Koishi v4 and later primarily use ES Modules. CommonJS `require()` is not officially supported for Koishi plugins and can lead to issues.","wrong":"const migrateDatabase = require('koishi-plugin-migrate-database')","symbol":"koishi-plugin-migrate-database","correct":"ctx.plugin(apply, config)"}],"quickstart":{"code":"import { Context, Schema } from 'koishi';\nimport { apply, Config } from 'koishi-plugin-migrate-database';\n\n// Assuming you have a koishi.config.ts or similar configuration setup\n// This demonstrates how to register the plugin within your Koishi application.\n\nconst ctx = new Context({\n  // Your Koishi configuration, e.g., database, adapters, etc.\n  database: {\n    // Example database configuration for a new database\n    // type: 'sqlite',\n    // path: 'data.db',\n  },\n  // ... other configurations\n});\n\n// Register the migration plugin. Be extremely cautious when using this in production.\n// Ensure you have backups and understand the migration process.\nctx.plugin(apply, {\n  // Example configuration for the migration plugin (adjust as needed)\n  // sourceDatabase: 'sqlite',\n  // sourcePath: 'old_data.db',\n  // targetDatabase: 'mysql',\n  // targetUri: process.env.MYSQL_URI ?? '',\n  // dryRun: true, // It is highly recommended to use dryRun first\n  // enable: true, // Only enable when explicitly ready to migrate\n});\n\nctx.start();\n\nconsole.log('Koishi application started with migration plugin registered.');\nconsole.log('Ensure to check plugin logs for migration status and potential errors.');","lang":"typescript","description":"Installs and registers the koishi-plugin-migrate-database plugin within a Koishi application, demonstrating its integration into `koishi.config.ts` for database migration. It highlights the cautious approach needed due to data operations."},"warnings":[{"fix":"Before running, perform a complete backup of your source database. Test the migration on a non-production environment first. Use the `dryRun` option if available.","message":"This plugin directly manipulates database records. Improper use, misconfiguration, or unexpected schema differences can lead to irreversible data loss or corruption. Always perform a full database backup before attempting any migration.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Carefully review the plugin's documentation and your database's connection string/parameters. Ensure correct drivers and connection libraries are installed if needed by Koishi's database adapter.","message":"As a utility for database migration, this plugin's functionality is highly sensitive to the underlying database types (e.g., SQLite, MySQL, MongoDB) and their specific connection parameters. Generic settings may not work, and deep understanding of your database configuration is required.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your Koishi installation matches the required peer dependency version specified in `package.json`. Use `npm install` or `yarn install` to resolve peer dependencies, and upgrade Koishi if necessary.","message":"The plugin has a peer dependency on `koishi: ^4.17.5`. Using it with significantly older or newer major versions of Koishi may lead to runtime errors due to API changes in the core framework or database adapters.","severity":"breaking","affected_versions":"<4.17.5 || >4.x.x"},{"fix":"Regularly check the package's GitHub repository and `CHANGELOG.md` (if available) for updates. Pin the exact version (`\"koishi-plugin-migrate-database\": \"0.x.x\"`) in `package.json` to prevent unexpected updates in production until a stable `1.0.0` release.","message":"This plugin is in its early `0.x.x` development phase. The API, configuration options, and internal implementation may undergo significant changes in minor or patch releases without following strict semantic versioning for non-breaking changes, potentially requiring code adjustments.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed (`npm i koishi-plugin-migrate-database`) and correctly added to your Koishi configuration file (e.g., `koishi.config.ts`) using `ctx.plugin(apply, config)`.","cause":"The plugin package was not correctly installed or registered, or the import path is incorrect.","error":"Error: Plugin 'koishi-plugin-migrate-database' not found."},{"fix":"Upgrade or downgrade your Koishi installation to a version compatible with `^4.17.5` (e.g., `npm update koishi` or `npm install koishi@4.17.5`).","cause":"Your installed Koishi version does not satisfy the requirements of the migration plugin.","error":"Peer dependency 'koishi@^4.17.5' not met."},{"fix":"Verify that your Koishi instance is correctly configured with a database adapter and that the plugin is registered after the core Koishi services are set up.","cause":"The Koishi context or database service was not properly initialized or available when the plugin attempted to access it.","error":"TypeError: Cannot read properties of undefined (reading 'database')"},{"fix":"Check the `path` configuration for your database (e.g., SQLite) and ensure the Koishi process has read/write permissions for the directory containing the database file.","cause":"The specified database file path is incorrect, or there are insufficient permissions to access or create the database file.","error":"Error: SQLITE_CANTOPEN: unable to open database file"}],"ecosystem":"npm"}