{"id":18483,"library":"koishi-plugin-database-jsondb","title":"koishi-plugin-database-jsondb","description":"A lightweight JSON file-based database service plugin for Koishi chatbot framework. Current stable version is 1.2.0. It stores data in JSON files under `data/database/jsondb/` directory, with no external database dependencies, making it ideal for small bots and quick prototyping. Released as part of the Service More collection, it provides standard Koishi database operations (CRUD) with simple configuration. Compared to SQL-based alternatives, it sacrifices scalability for zero setup overhead. Ships TypeScript type definitions. Peer dependency on Koishi ^4.17.1.","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","typescript"],"install":[{"cmd":"npm install koishi-plugin-database-jsondb","lang":"bash","label":"npm"},{"cmd":"yarn add koishi-plugin-database-jsondb","lang":"bash","label":"yarn"},{"cmd":"pnpm add koishi-plugin-database-jsondb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: requires Koishi framework v4.17.1+ for database service integrations.","package":"koishi","optional":false}],"imports":[{"note":"This is a Koishi plugin; it must be used with Koishi's `app.plugin(DatabaseJsondb)` pattern.","wrong":"const DatabaseJsondb = require('koishi-plugin-database-jsondb')","symbol":"default","correct":"import DatabaseJsondb from 'koishi-plugin-database-jsondb'"},{"note":"Required in plugins that use database operations. Must be exported, not imported. This is provided by Koishi's dependency injection system.","wrong":"","symbol":"inject: database","correct":"export const inject = ['database']"},{"note":"Access database via context after injection. Available only after plugin is activated and database service is loaded.","wrong":"","symbol":"ctx.database","correct":"ctx.database.get('table', { field: value })"}],"quickstart":{"code":"// install: npm i koishi-plugin-database-jsondb\nimport { App } from 'koishi'\nimport databaseJsondb from 'koishi-plugin-database-jsondb'\n\nconst app = new App()\napp.plugin(databaseJsondb)\n\napp.plugin((ctx) => {\n  // Declare table types\n  declare module 'koishi' {\n    interface Tables {\n      demo: { id: string; name: string; count: number }\n    }\n  }\n\n  // Inject database\n  export const inject = ['database']\n\n  // Extend model\n  ctx.model.extend('demo', {\n    id: 'string',\n    name: 'string',\n    count: 'integer'\n  }, { primary: 'id' })\n\n  // Use database\n  ctx.middleware(async (session, next) => {\n    const userId = session.userId\n    let user = (await ctx.database.get('demo', { id: userId }))[0]\n    if (!user) {\n      user = { id: userId, name: 'new', count: 0 }\n      await ctx.database.create('demo', user)\n    } else {\n      user.count++\n      await ctx.database.set('demo', { id: userId }, { count: user.count })\n    }\n    return next()\n  })\n})\n\napp.start()","lang":"typescript","description":"Complete setup: install plugin, register it, declare table types, extend model, and use database operations (get, create, set) in a middleware."},"warnings":[{"fix":"Use only in single-process environments. For clustering, consider a proper database like SQLite or MySQL.","message":"Data is stored in JSON files under `data/database/jsondb/`. Multiple instances or concurrent writes may cause data corruption. Not suitable for multi-process deployments.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always specify `primary` option in `ctx.model.extend(table, fields, { primary: 'field' })`.","message":"Primary keys are required when extending a model. Without specifying a primary field, operations like `get` may return unexpected results.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Stay updated with Koishi changelogs. Currently `export const inject = ['database']` is correct.","message":"The `database` plugin injection method may change in future Koishi versions. Refer to Koishi documentation for updates.","severity":"deprecated","affected_versions":">=1.0.0 <2.0.0"},{"fix":"Migrate files manually from old directory to new one before upgrading.","message":"Version 1.0.0 changed the storage location from `data/jsondb/` to `data/database/jsondb/`. Existing data files may not be found.","severity":"breaking","affected_versions":">=0.x <1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run `npm install koishi-plugin-database-jsondb` and ensure import is `import DatabaseJsondb from 'koishi-plugin-database-jsondb'`.","cause":"Plugin not installed or incorrect import path.","error":"Error: Cannot find module 'koishi-plugin-database-jsondb'"},{"fix":"Add `export const inject = ['database']` to your plugin module and ensure `app.plugin(databaseJsondb)` is called before your plugin.","cause":"Missing `inject: ['database']` export or plugin not properly registered.","error":"TypeError: ctx.database.get is not a function"},{"fix":"Add `primary: 'fieldName'` option in `ctx.model.extend('table', fields, { primary: 'fieldName' })`.","cause":"Model extension did not specify a primary key.","error":"Error: Invalid model definition: missing primary key"},{"fix":"Ensure the application has write permissions to the data directory. Create the directory manually if needed: `mkdir -p data/database/jsondb`.","cause":"Storage directory does not exist; plugin should create it automatically, but permissions may be missing.","error":"ENOENT: no such file or directory, open '.../data/database/jsondb/demo.json'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}