Koishi Database Cache Plugin

Common errors

• Error: Plugin 'koishi-plugin-cache-database' is not found.

  cause The package was not correctly installed or not listed in `koishi.yml` or the main application entry point.
  fix Run `npm install koishi-plugin-cache-database` (or `yarn add`) and ensure the plugin is applied using `app.plugin(require('koishi-plugin-cache-database'))` or `app.plugin(pluginFromImport)` in your Koishi application.

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

  cause The underlying database service that `koishi-plugin-cache-database` depends on was not initialized or failed to start before the cache plugin tried to access it.
  fix Ensure a compatible Koishi database plugin (e.g., `@koishijs/plugin-database-sqlite`) is installed and applied to the context *before* `koishi-plugin-cache-database`.

• TypeError: app.cache.set is not a function

  cause The `koishi-plugin-cache-database` plugin was not successfully applied to the Koishi context, or the `cache` service was not properly registered.
  fix Verify that `app.plugin(databaseCachePlugin, config)` is correctly invoked in your Koishi application's setup, and that no errors occurred during its registration.

Warnings

• breaking This plugin requires Koishi v4.10.0 or higher. Older Koishi versions will likely encounter compatibility issues or fail to load the plugin due to API changes in the core framework.
  Fix: Upgrade your `koishi` dependency to `^4.10.0` or the latest v4.x release.
• gotcha This plugin provides a database-backed cache *service* but does not include a database *driver*. You must install and configure a separate Koishi database plugin (e.g., `@koishijs/plugin-database-sqlite`, `@koishijs/plugin-database-mysql`) *before* applying this cache plugin.
  Fix: Install a suitable Koishi database plugin (e.g., `npm i @koishijs/plugin-database-sqlite`) and apply it to your Koishi context before `koishi-plugin-cache-database`.
• gotcha Improper database configuration for the underlying storage (e.g., insufficient connection pool, slow I/O, unoptimized queries) can severely impact the performance of the cache service and the overall bot responsiveness.
  Fix: Monitor database performance, ensure proper indexing for cache tables, and consider using a high-performance database solution for production environments.
• deprecated Koishi v4 has made significant internal changes to how user and channel data is handled, including the removal of direct `user/channel` cache access in certain contexts. While this plugin provides a general-purpose cache, direct reliance on removed Koishi internal cache mechanisms might lead to issues.
  Fix: Refer to Koishi v4 migration guides for specific `user` and `channel` related caching and data access patterns. Use the generic `ctx.cache` methods provided by this plugin for custom caching needs.

Install

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

Imports

• Context

  import { Context } from 'koishi'

  The core Koishi context object, essential for plugin development and interaction.
• Config

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

  Type definition for the plugin's configuration options.
• plugin
  wrong:

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

  correct:

  import plugin from 'koishi-plugin-cache-database'

  Most Koishi plugins export their main application function as a default export or a named 'plugin' constant.

Quickstart

This quickstart demonstrates how to set up Koishi with a SQLite database, integrate `koishi-plugin-cache-database`, and perform basic cache operations like setting and retrieving values, including optional expiration.

import { Context, Schema } from 'koishi';
import databaseCachePlugin from 'koishi-plugin-cache-database';
import sqlitePlugin from '@koishijs/plugin-database-sqlite'; // Example database plugin

// Define the Koishi application context
const app = new Context();

// Register a database plugin first, as cache-database relies on it.
// Ensure your SQLite database file path is correct.
app.plugin(sqlitePlugin, {
  path: './data/koishi-cache.db'
});

// Register the database cache plugin
app.plugin(databaseCachePlugin, {
  // Optional: configure cache expiration or other database-specific settings
  maxAge: 1000 * 60 * 60 * 24 // Cache items expire after 24 hours
});

app.on('ready', async () => {
  console.log('Koishi application is ready.');

  // Example usage of the cache service
  const cacheKey = 'my-important-data';
  const cacheValue = { message: 'Hello from cache!' };
  const ttl = 1000 * 60 * 5; // Cache for 5 minutes

  await app.cache.set(cacheKey, cacheValue, ttl);
  console.log(`Set cache key '${cacheKey}' with value:`, await app.cache.get(cacheKey));

  // Test retrieving non-existent key
  console.log('Non-existent key:', await app.cache.get('non-existent-key'));

  // Test cache expiration (demonstrative, would need time to pass)
  // setTimeout(async () => {
  //   console.log('After expiration (approx):', await app.cache.get(cacheKey));
  // }, ttl + 1000);
});

// Start the Koishi application (this would typically be in your main index.ts)
app.start().catch(err => {
  console.error('Failed to start Koishi:', err);
  process.exit(1);
});