Koishi INI Database Plugin

Common errors

• EACCES: permission denied, open '...'

  cause The Koishi application process does not have sufficient read/write permissions for the directory configured in `path`.
  fix Ensure the directory specified in the `path` configuration (default: `data/database/inidb`) exists and the user running Koishi has full read/write access to it. You might need to adjust file permissions (`chmod`) or move the directory.

• [koishi] plugin load failed: koishi-plugin-database-inidb

  cause This generic error can indicate several issues, including missing peer dependencies (Koishi itself), invalid plugin configuration, or a syntax error within the database INI files.
  fix Verify that `koishi` is installed and meets the peer dependency version (`npm install koishi`). Check the plugin configuration passed to `app.plugin(plugin, config)` for any typos or invalid values. Inspect Koishi's console output for more specific error messages after this generic failure.

• INI parsing error: Invalid section or key/value pair in file '...'

  cause One of the INI database files has been corrupted or manually edited in a way that violates the INI file format specification.
  fix Examine the specified INI file for syntax errors (e.g., missing `[section]`, malformed `key=value` pairs). If the data is not critical or backed up, deleting the corrupted file might allow the plugin to regenerate it (though data will be lost for that table).

Warnings

• gotcha Performance may degrade significantly with very large datasets or high concurrent query rates due to the inherent overhead of file I/O operations and locking mechanisms for INI files. This plugin is best suited for small to medium-sized datasets.
  Fix: For applications requiring high throughput or managing extensive data, consider switching to a more performant database service like `koishi-plugin-database-sqlite` or `koishi-plugin-database-mongo`.
• breaking Manually editing the generated INI database files without proper care can lead to data corruption, schema inconsistencies, or parsing errors, potentially rendering parts or all of your data unusable.
  Fix: Always back up your database files (`path` directory) before manual modifications. Ensure INI syntax is strictly followed. It is generally recommended to interact with the database only through the Koishi application's API.
• gotcha The `path` configuration determines where your database files are stored. Misconfiguring this path (e.g., to a publicly accessible directory or one with insufficient permissions) can expose sensitive bot data or lead to file access errors.
  Fix: Ensure the configured `path` points to a secure, private directory with appropriate read/write permissions for the user running the Koishi application. Avoid placing database files in public web directories.
• gotcha The INI file format is not designed for complex data structures (e.g., nested objects, arrays) or advanced querying capabilities (e.g., JOINs, complex filters). Storing such data might lead to flattened or serialized representations that are less efficient to query.
  Fix: If your application requires rich data structures or sophisticated query logic, consider using a database plugin that supports SQL (e.g., SQLite, MySQL) or NoSQL (e.g., MongoDB) databases, which are better suited for these scenarios.

Install

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

Imports

• plugin
  wrong:

  const { plugin } = require('koishi-plugin-database-inidb')

  correct:

  import { plugin } from 'koishi-plugin-database-inidb'

  Primary export for the Koishi plugin function. Used with `ctx.plugin()`.
• Config
  wrong:

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

  correct:

  import { type Config } from 'koishi-plugin-database-inidb'

  TypeScript type for the plugin's configuration object. Use `type` for type-only imports.
• inidb
  wrong:

  const inidb = require('koishi-plugin-database-inidb').default

  correct:

  import inidb from 'koishi-plugin-database-inidb'

  While `plugin` is the idiomatic named export, some setups might alias the default export or directly consume it if one exists. Confirm default export behavior.

Quickstart

Demonstrates setting up a Koishi application and integrating `koishi-plugin-database-inidb`. It includes an example of using the database service to store and retrieve user data via simple commands.

import { Context, Schema, h } from 'koishi'
import { plugin } from 'koishi-plugin-database-inidb'

// Create a basic Koishi instance (replace with your actual setup)
const app = new Context({
  prefix: ['.'],
  port: 8080
});

// Apply the INI database plugin
app.plugin(plugin, {
  path: process.env.KOISHI_INI_DB_PATH ?? 'data/inidb'
});

// Example usage: register a command that interacts with the database
// (assuming database services are set up by the plugin)
app.command('set <key:text> <value:text>')
  .action(async ({ session }, key, value) => {
    if (!key || !value) return 'Usage: .set <key> <value>';
    await session.database.set('user', { id: session.userId }, { [key]: value });
    return `Set ${key} for user ${session.userId} to ${value}`;
  });

app.command('get <key:text>')
  .action(async ({ session }, key) => {
    if (!key) return 'Usage: .get <key>';
    const user = await session.database.get('user', { id: session.userId }, [key]);
    if (user && user[key]) {
      return `Value of ${key} for user ${session.userId} is ${user[key]}`;
    } else {
      return `Key ${key} not found for user ${session.userId}`;
    }
  });

app.start();
console.log('Koishi app with INI DB started.');