{"id":16416,"library":"koishi-plugin-database-inidb","title":"Koishi INI Database Plugin","description":"koishi-plugin-database-inidb provides a lightweight database service for the Koishi chatbot framework. It stores all data in INI-formatted files, making the database easily inspectable and manually editable outside the application. Currently at stable version 1.2.0, this plugin aims for simplicity and ease of setup by having no external dependencies beyond Koishi itself. Its release cadence is typically event-driven, responding to Koishi framework updates or feature requests. A key differentiator is its file-based approach, which ensures portability and human readability, contrasted with traditional SQL or NoSQL databases. It also features file-locking mechanisms to maintain data consistency during concurrent access, which is crucial for a bot environment. This makes it suitable for smaller Koishi instances where a full-fledged database server is an overkill and resource usage is a primary concern.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/koishi-shangxue-plugins/service-more","tags":["javascript","bot","chatbot","koishi","plugin","database","client","storage","ini","typescript"],"install":[{"cmd":"npm install koishi-plugin-database-inidb","lang":"bash","label":"npm"},{"cmd":"yarn add koishi-plugin-database-inidb","lang":"bash","label":"yarn"},{"cmd":"pnpm add koishi-plugin-database-inidb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core framework this plugin extends and relies on.","package":"koishi","optional":false}],"imports":[{"note":"Primary export for the Koishi plugin function. Used with `ctx.plugin()`.","wrong":"const { plugin } = require('koishi-plugin-database-inidb')","symbol":"plugin","correct":"import { plugin } from 'koishi-plugin-database-inidb'"},{"note":"TypeScript type for the plugin's configuration object. Use `type` for type-only imports.","wrong":"import { Config } from 'koishi-plugin-database-inidb'","symbol":"Config","correct":"import { type Config } from 'koishi-plugin-database-inidb'"},{"note":"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.","wrong":"const inidb = require('koishi-plugin-database-inidb').default","symbol":"inidb","correct":"import inidb from 'koishi-plugin-database-inidb'"}],"quickstart":{"code":"import { Context, Schema, h } from 'koishi'\nimport { plugin } from 'koishi-plugin-database-inidb'\n\n// Create a basic Koishi instance (replace with your actual setup)\nconst app = new Context({\n  prefix: ['.'],\n  port: 8080\n});\n\n// Apply the INI database plugin\napp.plugin(plugin, {\n  path: process.env.KOISHI_INI_DB_PATH ?? 'data/inidb'\n});\n\n// Example usage: register a command that interacts with the database\n// (assuming database services are set up by the plugin)\napp.command('set <key:text> <value:text>')\n  .action(async ({ session }, key, value) => {\n    if (!key || !value) return 'Usage: .set <key> <value>';\n    await session.database.set('user', { id: session.userId }, { [key]: value });\n    return `Set ${key} for user ${session.userId} to ${value}`;\n  });\n\napp.command('get <key:text>')\n  .action(async ({ session }, key) => {\n    if (!key) return 'Usage: .get <key>';\n    const user = await session.database.get('user', { id: session.userId }, [key]);\n    if (user && user[key]) {\n      return `Value of ${key} for user ${session.userId} is ${user[key]}`;\n    } else {\n      return `Key ${key} not found for user ${session.userId}`;\n    }\n  });\n\napp.start();\nconsole.log('Koishi app with INI DB started.');","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The Koishi application process does not have sufficient read/write permissions for the directory configured in `path`.","error":"EACCES: permission denied, open '...'"},{"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.","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.","error":"[koishi] plugin load failed: koishi-plugin-database-inidb"},{"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).","cause":"One of the INI database files has been corrupted or manually edited in a way that violates the INI file format specification.","error":"INI parsing error: Invalid section or key/value pair in file '...'"}],"ecosystem":"npm"}