{"id":18484,"library":"koishi-plugin-database-txtdb","title":"Koishi TXT DB Database Service","description":"A Koishi plugin that provides a simple, file-based database service using plain text files. Data is stored line-by-line as JSON strings, making it highly readable and easy to debug. It is designed for small-scale or prototype bots that do not require a full database engine. Current stable version: 1.2.0. Released as needed. Key differentiators: no dependencies beyond Koishi, zero parsing overhead, file-lock based concurrency safety.","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","txt","typescript"],"install":[{"cmd":"npm install koishi-plugin-database-txtdb","lang":"bash","label":"npm"},{"cmd":"yarn add koishi-plugin-database-txtdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add koishi-plugin-database-txtdb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core peer dependency; plugin requires Koishi runtime v4.17.1+","package":"koishi","optional":false}],"imports":[{"note":"ESM-only package; default export is the plugin class.","wrong":"const TxtDb = require('koishi-plugin-database-txtdb')","symbol":"default","correct":"import TxtDb from 'koishi-plugin-database-txtdb'"},{"note":"Named export 'TxtDb' does not exist; use default import.","wrong":"import { TxtDb } from 'koishi-plugin-database-txtdb'","symbol":"Plugin","correct":"import type { Plugin } from 'koishi'\nimport TxtDb from 'koishi-plugin-database-txtdb'"},{"note":"TxtDb is a Koishi service plugin; use ctx.plugin() to install with options.","wrong":"ctx.use(TxtDb)","symbol":"install","correct":"ctx.plugin(TxtDb, { path: './data' })"}],"quickstart":{"code":"// Install: npm install koishi-plugin-database-txtdb\n// In your Koishi config:\nimport { Context } from 'koishi'\nimport TxtDb from 'koishi-plugin-database-txtdb'\n\nexport function apply(ctx: Context) {\n  // Install the TXT DB service\n  ctx.plugin(TxtDb, {\n    path: 'data/database/txtdb' // default path\n  })\n\n  // Now you can use ctx.database\n  ctx.on('ready', async () => {\n    // Create a table\n    await ctx.database.create('users')\n    // Insert a record\n    const id = await ctx.database.set('users', 1, { name: 'Alice', score: 100 })\n    console.log('Inserted id:', id)\n    // Query\n    const user = await ctx.database.get('users', 1)\n    console.log('User:', user)\n  })\n}","lang":"typescript","description":"Install and use TxtDB plugin. Shows import, plugin registration, table creation, insertion, and query using Koishi database API."},"warnings":[{"fix":"Set path to a persistent location, e.g., './data/txtdb' inside your project directory.","message":"Data is not persistent across restarts if path points to a tmpfs or in-memory filesystem? Actually it persists, but ensure the path directory exists and is writable.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Do not manually set ID field; let the database assign it.","message":"Table IDs are numeric and auto-incremented. If you insert a record with a specific ID, it may conflict with auto-generated IDs.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement periodic cleanup or delete records using ctx.database.remove()","message":"File size may grow unbounded; no built-in compaction or cleanup. Old records are not automatically removed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use a full-featured database such as koishi-plugin-database-sqlite or koishi-plugin-database-mysql for production bots.","message":"TXT DB does not support complex queries (e.g., where, sort, limit). Koishi's database API may assume these capabilities; unsupported methods will throw or behave unexpectedly.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use import TxtDb from 'koishi-plugin-database-txtdb' (no curly braces)","cause":"Using default import incorrectly (named import instead of default) because package is ESM-only.","error":"TypeError: TxtDb is not a constructor"},{"fix":"Run 'npm install koishi-plugin-database-txtdb' and ensure import matches package name exactly.","cause":"Package not installed or incorrect import path.","error":"Error: Cannot find module 'koishi-plugin-database-txtdb'"},{"fix":"Set path to a directory the process can write to, or run with appropriate permissions.","cause":"Node process does not have write permission to the configured path.","error":"error: Failed to create table: EACCES: permission denied"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}