{"id":16415,"library":"koishi-plugin-database-csvdb","title":"Koishi CSV Database Plugin","description":"koishi-plugin-database-csvdb provides a lightweight, file-based database service for the Koishi chatbot framework, leveraging CSV files for data storage. Currently at version 1.2.0, this plugin offers a simple, no-additional-dependency solution for persistent storage within Koishi applications. Its primary differentiators are its ease of use, the universal compatibility of the CSV format (allowing direct editing with spreadsheet software like Excel), and its built-in concurrency safety achieved through file locking mechanisms. This makes it suitable for smaller to medium-scale Koishi bots where a full-fledged relational or NoSQL database might be overkill. Release cadence is tied to bug fixes and feature enhancements, typically following the Koishi core framework's evolution. It's an ideal choice for developers seeking minimal overhead and direct data accessibility.","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","csv","typescript"],"install":[{"cmd":"npm install koishi-plugin-database-csvdb","lang":"bash","label":"npm"},{"cmd":"yarn add koishi-plugin-database-csvdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add koishi-plugin-database-csvdb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the Koishi framework itself, as this is a Koishi plugin.","package":"koishi","optional":false}],"imports":[{"note":"Used for type-checking the plugin's configuration object when using TypeScript.","symbol":"Config","correct":"import { Config } from 'koishi-plugin-database-csvdb'"},{"note":"Koishi plugins typically export an `apply` function (or similar named export) as their main entry point, rather than a default export. This `apply` function receives the `Context` object and plugin options.","wrong":"import plugin from 'koishi-plugin-database-csvdb'","symbol":"apply","correct":"import { apply } from 'koishi-plugin-database-csvdb'"},{"note":"While Koishi supports ESM, many existing Koishi projects and some plugin loading patterns still use CommonJS `require`. When dynamically loading or if `apply` isn't directly imported, `require` is common. The plugin's main export will be the `apply` function.","wrong":"import * as plugin from 'koishi-plugin-database-csvdb'; ctx.plugin(plugin, options)","symbol":"plugin","correct":"ctx.plugin(require('koishi-plugin-database-csvdb'), options)"}],"quickstart":{"code":"import { Context, Schema } from 'koishi'\nimport { apply, Config } from 'koishi-plugin-database-csvdb'\n\n// A minimal Koishi application setup\nconst app = new Context()\n\n// Register the CSVDB plugin\n// The configuration 'path' specifies where the CSV files will be stored.\n// Ensure this path is writable by the Koishi process.\napp.plugin(apply, {\n  path: process.env.CSVDB_PATH || './data/csv_database'\n})\n\n// Example: Define a simple service that uses the database\napp.model.extend('user', {\n  id: 'string',\n  name: 'string',\n  karma: { type: 'integer', initial: 0 }\n})\n\napp.command('mydata <key:string> [value:string]')\n  .action(async ({ session }, key, value) => {\n    if (!session?.user) return 'User data not found.'\n\n    const userId = session.user.id\n    const user = await app.database.getUser(session.platform, userId, [key])\n\n    if (value) {\n      // Set data\n      await app.database.setUser(session.platform, userId, { [key]: value })\n      return `Set user ${key} to ${value}`\n    } else {\n      // Get data\n      return `Current user ${key} is: ${user?.[key] || 'not set'}`\n    }\n  })\n\n// Koishi application start (example for local development)\n// app.start()\n// console.log('Koishi app with CSVDB started.')\n","lang":"typescript","description":"Demonstrates how to initialize a Koishi application and register the `koishi-plugin-database-csvdb` plugin with a custom data path, then interact with the database using a simple command."},"warnings":[{"fix":"For applications requiring extremely high throughput or storing millions of records, consider migrating to more robust database plugins like `koishi-plugin-database-mysql` or `koishi-plugin-database-sqlite`.","message":"Performance degradation with very large datasets or high concurrent writes. While the plugin includes file locking for concurrency safety, continuous high-volume write operations to CSV files can inherently be slower than dedicated database systems due to I/O overhead and sequential file access.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the directory specified by `path` exists and that the user running the Koishi application has read and write permissions to it. For example, `mkdir -p data/csv_database && chmod 700 data/csv_database`.","message":"The `path` configuration option, which specifies the database file location, must be a writable directory for the Koishi process. Incorrect permissions or non-existent directories will lead to database initialization failures or runtime errors during data persistence.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Only edit CSV files when the Koishi application is stopped to avoid conflicts with file locks. Strictly adhere to CSV formatting rules (e.g., proper escaping of commas, newlines). Backup your `path` directory regularly before manual modifications.","message":"Direct manual editing of CSV database files outside of Koishi can lead to data corruption if not done carefully. While CSV is human-readable, invalid formatting, missing headers, or incorrect encoding can render the data unreadable by the plugin, especially if file locks are ignored during manual edits.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Koishi core framework to version `^4.17.1` or higher to ensure compatibility. Check the `peerDependencies` in `package.json` for precise version requirements.","message":"This plugin is designed for Koishi v4. If you are using an older version of Koishi (e.g., v3 or earlier), this plugin will likely not be compatible due to significant API changes between major Koishi versions.","severity":"breaking","affected_versions":"<4.17.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Create the directory specified by `path` (e.g., `mkdir -p data/csv_database`) and ensure the Koishi process has appropriate read/write permissions.","cause":"The directory specified in the `path` configuration does not exist, or the Koishi process lacks write permissions to create files within it.","error":"ENOENT: no such file or directory, open 'data/csv_database/users.csv'"},{"fix":"Verify that `app.plugin(apply, config)` is called correctly during Koishi initialization and that no preceding errors prevented the plugin from successfully loading and registering its services.","cause":"The Koishi context (`ctx`) or `app` instance was not properly initialized or the plugin failed to load, meaning the `database` service was not bound.","error":"TypeError: Cannot read properties of undefined (reading 'database')"},{"fix":"Ensure the Koishi process has full read/write permissions to the `path` directory and its contents. Check if another instance of Koishi or another application is accessing the same database files simultaneously and close the conflicting process.","cause":"The Koishi process attempted to acquire a file lock but was denied due to operating system permissions or another process holding an exclusive lock.","error":"Error: EPERM: operation not permitted, acquire 'data/csv_database/lock'"}],"ecosystem":"npm"}