Registry /
database / koishi-plugin-cache-database
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ import plugin from 'koishi-plugin-cache-database'
✗ import { apply } from 'koishi-plugin-cache-database'
Most Koishi plugins export their main application function as a default export or a named 'plugin' constant.
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);
});
Debug
Known issues
breakingThis 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.fixUpgrade your `koishi` dependency to `^4.10.0` or the latest v4.x release.
affects: <4.10.0
gotchaThis 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.fixInstall 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`.
affects: >=2.0.0
gotchaImproper 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.fixMonitor database performance, ensure proper indexing for cache tables, and consider using a high-performance database solution for production environments.
affects: >=2.0.0
deprecatedKoishi 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.fixRefer 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.
affects: >=4.0.0 of Koishi
Errors
Common errors & fixes
Error: Plugin 'koishi-plugin-cache-database' is not found.
The package was not correctly installed or not listed in `koishi.yml` or the main application entry point.
fixRun `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')
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.
fixEnsure 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
The `koishi-plugin-cache-database` plugin was not successfully applied to the Koishi context, or the `cache` service was not properly registered.
fixVerify that `app.plugin(databaseCachePlugin, config)` is correctly invoked in your Koishi application's setup, and that no errors occurred during its registration.
Audit
Dependencies
koishirequiredCore Koishi framework, this package is a plugin for Koishi.