Koishi TXT DB Database Service

1.2.0 verified Sat Apr 25 auth: no javascript

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.

Common errors

error TypeError: TxtDb is not a constructor ↓

cause Using default import incorrectly (named import instead of default) because package is ESM-only.

fix

Use import TxtDb from 'koishi-plugin-database-txtdb' (no curly braces)

error Error: Cannot find module 'koishi-plugin-database-txtdb' ↓

cause Package not installed or incorrect import path.

fix

Run 'npm install koishi-plugin-database-txtdb' and ensure import matches package name exactly.

error error: Failed to create table: EACCES: permission denied ↓

cause Node process does not have write permission to the configured path.

fix

Set path to a directory the process can write to, or run with appropriate permissions.

Warnings

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

fix Set path to a persistent location, e.g., './data/txtdb' inside your project directory.

gotcha Table IDs are numeric and auto-incremented. If you insert a record with a specific ID, it may conflict with auto-generated IDs. ↓

fix Do not manually set ID field; let the database assign it.

gotcha File size may grow unbounded; no built-in compaction or cleanup. Old records are not automatically removed. ↓

fix Implement periodic cleanup or delete records using ctx.database.remove()

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

fix Use a full-featured database such as koishi-plugin-database-sqlite or koishi-plugin-database-mysql for production bots.

Install

npm install koishi-plugin-database-txtdb

yarn add koishi-plugin-database-txtdb

pnpm add koishi-plugin-database-txtdb

Imports

default

wrong

const TxtDb = require('koishi-plugin-database-txtdb')

correct

import TxtDb from 'koishi-plugin-database-txtdb'

ESM-only package; default export is the plugin class.

Plugin

wrong

import { TxtDb } from 'koishi-plugin-database-txtdb'

correct

import type { Plugin } from 'koishi'
import TxtDb from 'koishi-plugin-database-txtdb'

Named export 'TxtDb' does not exist; use default import.

install
wrong
```
ctx.use(TxtDb)
```
correct
```
ctx.plugin(TxtDb, { path: './data' })
```
TxtDb is a Koishi service plugin; use ctx.plugin() to install with options.

Quickstart

Install and use TxtDB plugin. Shows import, plugin registration, table creation, insertion, and query using Koishi database API.

// Install: npm install koishi-plugin-database-txtdb
// In your Koishi config:
import { Context } from 'koishi'
import TxtDb from 'koishi-plugin-database-txtdb'

export function apply(ctx: Context) {
  // Install the TXT DB service
  ctx.plugin(TxtDb, {
    path: 'data/database/txtdb' // default path
  })

  // Now you can use ctx.database
  ctx.on('ready', async () => {
    // Create a table
    await ctx.database.create('users')
    // Insert a record
    const id = await ctx.database.set('users', 1, { name: 'Alice', score: 100 })
    console.log('Inserted id:', id)
    // Query
    const user = await ctx.database.get('users', 1)
    console.log('User:', user)
  })
}