Koishi CSV Database Plugin

Common errors

• ENOENT: no such file or directory, open 'data/csv_database/users.csv'

  cause The directory specified in the `path` configuration does not exist, or the Koishi process lacks write permissions to create files within it.
  fix Create the directory specified by `path` (e.g., `mkdir -p data/csv_database`) and ensure the Koishi process has appropriate read/write permissions.

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

  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.
  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.

• Error: EPERM: operation not permitted, acquire 'data/csv_database/lock'

  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.
  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.

Warnings

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

Install

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

Imports

• Config

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

  Used for type-checking the plugin's configuration object when using TypeScript.
• apply
  wrong:

  import plugin from 'koishi-plugin-database-csvdb'

  correct:

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

  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.
• plugin
  wrong:

  import * as plugin from 'koishi-plugin-database-csvdb'; ctx.plugin(plugin, options)

  correct:

  ctx.plugin(require('koishi-plugin-database-csvdb'), options)

  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.

Quickstart

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.

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

// A minimal Koishi application setup
const app = new Context()

// Register the CSVDB plugin
// The configuration 'path' specifies where the CSV files will be stored.
// Ensure this path is writable by the Koishi process.
app.plugin(apply, {
  path: process.env.CSVDB_PATH || './data/csv_database'
})

// Example: Define a simple service that uses the database
app.model.extend('user', {
  id: 'string',
  name: 'string',
  karma: { type: 'integer', initial: 0 }
})

app.command('mydata <key:string> [value:string]')
  .action(async ({ session }, key, value) => {
    if (!session?.user) return 'User data not found.'

    const userId = session.user.id
    const user = await app.database.getUser(session.platform, userId, [key])

    if (value) {
      // Set data
      await app.database.setUser(session.platform, userId, { [key]: value })
      return `Set user ${key} to ${value}`
    } else {
      // Get data
      return `Current user ${key} is: ${user?.[key] || 'not set'}`
    }
  })

// Koishi application start (example for local development)
// app.start()
// console.log('Koishi app with CSVDB started.')