Keyv

Keyv is a simple key-value store that works with multiple backends. It's fully scalable for sharding and supports JSON storage.

Installation

npm install keyv

Keyv requires an additional package depending on which persistent backend you would prefer to use. If you want to keep everything in memory, you can skip this part. Otherwise, install one of the below.

npm install @keyv/redis
npm install @keyv/mongo
npm install @keyv/sqlite
npm install @keyv/postgres
npm install @keyv/mysql

Create an instance of Keyv once you've installed Keyv and any necessary drivers.

const { Keyv } = require('keyv');

// One of the following
const keyv = new Keyv(); // for in-memory storage
const keyv = new Keyv('redis://user:pass@localhost:6379');
const keyv = new Keyv('mongodb://user:pass@localhost:27017/dbname');
const keyv = new Keyv('sqlite://path/to/database.sqlite');
const keyv = new Keyv('postgresql://user:pass@localhost:5432/dbname');
const keyv = new Keyv('mysql://user:pass@localhost:3306/dbname');

Make sure to handle connection errors.

keyv.on('error', (err) => console.error('Keyv connection error:', err));

For a more detailed setup, check out the Keyv readme.

Usage

Keyv exposes a familiar Map-like API. However, it only has set, get, delete, and clear methods. Additionally, instead of immediately returning data, these methods return Promises that resolve with the data.

(async () => {
	// true
	await keyv.set('foo', 'bar');

	// bar
	await keyv.get('foo');

	// undefined
	await keyv.clear();

	// undefined
	await keyv.get('foo');
})();

Application

Although Keyv can assist in any scenario where you need key-value data, we will focus on setting up a per-guild prefix configuration using Sqlite.

This section will still work with any provider supported by Keyv. We recommend PostgreSQL for larger applications.

Do note that "large" here should be interpreted as absolutely massive. Sqlite is used at scale by many companies and products you use every single day. The slight overhead should not be noticeable for the application of a Discord bot at all unless you are dealing with super complicated queries or are using specific features that do not exist in sqlite.

You can find out if sqlite might be a good choice for your project (it very likely is) by reading their own article on the topic.

Setup

const { Keyv } = require('keyv');
const { Client, Events, GatewayIntentBits } = require('discord.js');
const { globalPrefix, token } = require('./config.json');

const client = new Client({
	intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
});
const prefixes = new Keyv('sqlite://path/to.sqlite');

Command handler

This guide example is from a time where parsing the message content of Discord messages was the only option for commands. We have since moved on from this and recommend you do the same with slash commands. It can still serve as an example for using databases in a more integrated example. We hope it can help you understand the core idea and apply it to your own use cases!

client.on(Events.MessageCreate, async (message) => {
	if (message.author.bot) return;

	let args;
	// handle messages in a guild
	if (message.guild) {
		let prefix;

		if (message.content.startsWith(globalPrefix)) {
			prefix = globalPrefix;
		} else {
			// check the guild-level prefix
			const guildPrefix = await prefixes.get(message.guild.id);
			if (message.content.startsWith(guildPrefix)) prefix = guildPrefix;
		}

		// if we found a prefix, setup args; otherwise, this isn't a command
		if (!prefix) return;
		args = message.content.slice(prefix.length).trim().split(/\s+/);
	} else {
		// handle DMs
		const slice = message.content.startsWith(globalPrefix) ? globalPrefix.length : 0;
		args = message.content.slice(slice).split(/\s+/);
	}

	// get the first space-delimited argument after the prefix as the command
	const command = args.shift().toLowerCase();
});

Prefix command

Now that you have a command handler, you can make a command to allow people to use your prefix system.

client.on(Events.MessageCreate, async (message) => {
	// ...
	if (command === 'prefix') {
		// if there's at least one argument, set the prefix
		if (args.length) {
			await prefixes.set(message.guild.id, args[0]);
			return message.channel.send(`Successfully set prefix to \`${args[0]}\``);
		}

		return message.channel.send(`Prefix is \`${(await prefixes.get(message.guild.id)) || globalPrefix}\``);
	}
});

You will probably want to set up additional validation, such as required permissions and maximum prefix length.

Next steps

Various other applications can use Keyv, such as guild settings; create another instance with a different namespace for each setting. Additionally, it can be extended to work with whatever storage backend you prefer.

Check out the Keyv repository for more information.