Skip to content

Implement KvStore for MySQL/MariaDB (@fedify/mysql) #585

@dahlia

Description

@dahlia

Summary

Add a new @fedify/mysql package that provides a MysqlKvStore class implementing the KvStore interface, backed by MySQL or MariaDB.

Motivation

Fedify currently supports PostgreSQL, Redis, SQLite, and Deno KV as KvStore backends. MySQL and MariaDB remain popular choices in many production environments, and developers already running these databases should be able to use them as a Fedify storage backend without introducing additional infrastructure.

Proposed API

import { createFederation } from "@fedify/fedify";
import { MysqlKvStore } from "@fedify/mysql";
import mysql from "mysql2/promise";

const pool = mysql.createPool("mysql://user:pass@localhost/db");
const federation = createFederation<void>({
  kv: new MysqlKvStore(pool),
  // ...
});

Implementation notes

  • Use the mysql2 package as the underlying driver, as it is the de facto standard MySQL/MariaDB driver in the Node.js ecosystem.
  • The table schema should store the key (as a serialized string), the value (as JSON), and an optional expiry timestamp for TTL support.
  • TTL should be handled by storing the expiry timestamp alongside the value and filtering out expired entries on read, similar to how other KvStore implementations handle it. A periodic cleanup job or an ON DELETE trigger may also be considered.
  • The cas() (compare-and-swap) method should be implemented using a transaction to ensure atomicity.
  • The list() method should be implemented using a prefix scan with a LIKE query or equivalent.
  • MySQL 8.0+ and MariaDB 10.6+ should be the minimum supported versions, as SELECT ... FOR UPDATE SKIP LOCKED is available from these versions onward (which is needed for the companion MysqlMessageQueue implementation).

Checklist

  • Implement MysqlKvStore class in a new @fedify/mysql package
  • Support get(), set() (with TTL), delete(), cas(), and list()
  • Write unit tests (with a real MySQL/MariaDB instance via Docker)
  • Document the new KvStore in docs/manual/kv.md
  • Add the package to README.md, AGENTS.md, CONTRIBUTING.md, etc. per the contributing guide

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    Status

    Backlog

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions