Koishi Database Migration Plugin

Common errors

• Error: Plugin 'koishi-plugin-migrate-database' not found.

  cause The plugin package was not correctly installed or registered, or the import path is incorrect.
  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)`.

• Peer dependency 'koishi@^4.17.5' not met.

  cause Your installed Koishi version does not satisfy the requirements of the migration plugin.
  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`).

• TypeError: Cannot read properties of undefined (reading 'database')

  cause The Koishi context or database service was not properly initialized or available when the plugin attempted to access it.
  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.

• Error: SQLITE_CANTOPEN: unable to open database file

  cause The specified database file path is incorrect, or there are insufficient permissions to access or create the database file.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install koishi-plugin-migrate-database npm
• yarn add koishi-plugin-migrate-database yarn
• pnpm add koishi-plugin-migrate-database pnpm

Imports

• apply
  wrong:

  import migrateDatabase from 'koishi-plugin-migrate-database'

  correct:

  import { apply } from 'koishi-plugin-migrate-database'

  Koishi plugins often export an `apply` function or a default object with an `apply` method. This plugin uses a named `apply` export.
• Config

  import { Config } from 'koishi-plugin-migrate-database'

  Used for type-checking the plugin's configuration schema in TypeScript projects.
• koishi-plugin-migrate-database
  wrong:

  const migrateDatabase = require('koishi-plugin-migrate-database')

  correct:

  ctx.plugin(apply, config)

  Koishi v4 and later primarily use ES Modules. CommonJS `require()` is not officially supported for Koishi plugins and can lead to issues.

Quickstart

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.

import { Context, Schema } from 'koishi';
import { apply, Config } from 'koishi-plugin-migrate-database';

// Assuming you have a koishi.config.ts or similar configuration setup
// This demonstrates how to register the plugin within your Koishi application.

const ctx = new Context({
  // Your Koishi configuration, e.g., database, adapters, etc.
  database: {
    // Example database configuration for a new database
    // type: 'sqlite',
    // path: 'data.db',
  },
  // ... other configurations
});

// Register the migration plugin. Be extremely cautious when using this in production.
// Ensure you have backups and understand the migration process.
ctx.plugin(apply, {
  // Example configuration for the migration plugin (adjust as needed)
  // sourceDatabase: 'sqlite',
  // sourcePath: 'old_data.db',
  // targetDatabase: 'mysql',
  // targetUri: process.env.MYSQL_URI ?? '',
  // dryRun: true, // It is highly recommended to use dryRun first
  // enable: true, // Only enable when explicitly ready to migrate
});

ctx.start();

console.log('Koishi application started with migration plugin registered.');
console.log('Ensure to check plugin logs for migration status and potential errors.');