Add @fedify/mysql package with MysqlKvStore

[dahlia]

Summary

Closes #585

This pull request adds the @fedify/mysql package, which provides a MysqlKvStore class implementing the KvStore interface backed by MySQL or MariaDB via the mysql2 driver.

New package: @fedify/mysql

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

• Keys (KvKey) are serialized via JSON.stringify() into a VARCHAR(768) column with utf8mb4_bin collation for case-sensitive matching.
• Values are stored as a native JSON column; mysql2 parses them back to JS objects automatically on read.
• TTL is stored as an absolute DATETIME(6) computed at write time (DATE_ADD(NOW(6), INTERVAL ? SECOND)), and expired rows are filtered out on read.
• list() uses a LIKE prefix scan (with proper escaping of %, _, and \ characters).
• cas() (compare-and-swap) uses SELECT ... FOR UPDATE inside a transaction for atomicity. Relies on InnoDB REPEATABLE READ (the default) for gap locking on missing rows.
• The table is created lazily via initialize() and can be dropped with drop().
• Requires MySQL 8.0+ or MariaDB 10.6+.

Other changes

• CI: Added a MySQL 8 service container to all three test jobs (test, test-node, test-bun). Integration tests run when the MYSQL_URL environment variable is set.
• Docs: Added MysqlKvStore section to docs/manual/kv.md, and updated federation.md, basics.md, and relay.md to mention it alongside the other production-ready KvStore implementations.
• fedify init: Added MySQL/MariaDB as a KvStore option.
• Monorepo: Updated pnpm-workspace.yaml, root deno.json, and packages/fedify/README.md to register the new package.

Testing

19 integration tests cover all operations: initialize, get, set, delete, drop, list (including expired-row filtering, single-element keys, LIKE special characters, and empty-prefix listing), cas, cas with TTL, and various constructor validations. All pass against a local MySQL 8 instance.

Note

This PR implements only the KvStore half of #587. MysqlMessageQueue (#586) will follow in a separate PR.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances Fedify's data persistence capabilities by introducing a dedicated MySQL/MariaDB key-value store. This new integration provides a robust and scalable option for managing key-value data in production environments, complete with advanced features like time-to-live and atomic compare-and-swap operations. The changes also include comprehensive updates to documentation, build configurations, and the project initialization tool to fully support this new database adapter.

Highlights

• New @fedify/mysql Package: Introduced a new package, @fedify/mysql, providing a MysqlKvStore class for key-value storage backed by MySQL or MariaDB. This implementation supports TTL, prefix listing, and compare-and-swap (cas()) operations, leveraging the mysql2 driver.
• Enhanced Persistence Options: Expanded Fedify's production-ready KvStore implementations to include MySQL/MariaDB, offering more flexibility for users already utilizing these database systems.
• Documentation and Tooling Integration: Updated documentation, fedify init CLI tool, and monorepo configurations to reflect the availability and usage of the new MysqlKvStore, ensuring seamless integration and discoverability.
• Comprehensive Testing: Added 11 integration tests covering all MysqlKvStore operations, including initialize, get, set, delete, drop, list (with expired-row filtering and various prefixes), and cas (with and without TTL), ensuring robustness and reliability.

Changelog

• AGENTS.md
  • Updated documentation to include @fedify/mysql in the list of specific database adapters.
  • Updated monorepo build process description to include @fedify/mysql.
• CHANGES.md
  • Reordered existing changelog entries for @fedify/astro and @fedify/init.
  • Added a new changelog entry for the @fedify/mysql package, detailing its MysqlKvStore implementation and features.
• deno.json
  • Added @fedify/mysql to the workspace paths.
  • Added mysql2 and mysql2/promise as npm dependencies.
• deno.lock
  • Updated lock file to include mysql2 and its associated dependencies like aws-ssl-profiles, generate-function, is-property, long, lru.min, named-placeholders, and sql-escaper.
• docs/.vitepress/config.mts
  • Added @fedify/mysql to the list of JSR documentation references.
• docs/manual/federation.md
  • Updated the KvStore section to mention MysqlKvStore as a production-ready option.
• docs/manual/kv.md
  • Added a new section detailing the MysqlKvStore, including installation instructions, usage examples, and a discussion of its pros and cons.
• docs/manual/relay.md
  • Updated the warning about MemoryKvStore to include MysqlKvStore as a recommended persistent store for production.
• docs/package.json
  • Added @fedify/mysql as a workspace dependency.
• docs/tutorial/basics.md
  • Updated the tutorial to recommend MysqlKvStore as a persistent key-value store for production use.
• packages/fedify/README.md
  • Added @fedify/mysql to the list of packages in the monorepo README.
• packages/init/src/json/kv.json
  • Added mysql as a new KvStore option for the fedify init command, including its dependencies and environment variables.
• packages/mysql/README.md
  • Added a new README file for the @fedify/mysql package, describing its purpose and providing installation and usage examples.
• packages/mysql/deno.json
  • Added a new deno.json configuration file for the @fedify/mysql package, defining its name, version, exports, and tasks.
• packages/mysql/package.json
  • Added a new package.json file for the @fedify/mysql package, including metadata, dependencies, and build scripts.
• packages/mysql/src/kv.test.ts
  • Added a comprehensive suite of integration tests for MysqlKvStore, covering initialize, get, set, delete, drop, list (including expired entries and various prefixes), and cas operations.
• packages/mysql/src/kv.ts
  • Added the MysqlKvStore class implementation, which provides a MySQL/MariaDB-backed KvStore with support for TTL, compare-and-swap, and prefix listing.
• packages/mysql/src/mod.ts
  • Added the main export file for the @fedify/mysql package.
• packages/mysql/tsdown.config.ts
  • Added a new tsdown.config.ts file for the @fedify/mysql package, configuring its build process for ESM and CJS formats.
• packages/relay/README.md
  • Updated the KvStore recommendations to include MysqlKvStore for production use.
• pnpm-lock.yaml
  • Updated lock file to include new dependencies for @fedify/mysql and mysql2.
• pnpm-workspace.yaml
  • Added packages/mysql to the monorepo workspace.
  • Added mysql2 to the catalog of shared dependencies.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/main.yaml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces the @fedify/mysql package, providing a MysqlKvStore for using MySQL or MariaDB as a persistent key-value store with Fedify. The implementation is robust, correctly handling key serialization, TTLs with DATETIME(6), and atomic compare-and-swap operations using transactions. The changes are well-integrated into the project, with thorough tests, documentation updates across the manual and tutorials, and inclusion in the fedify init tool. My review found only minor inconsistencies in the naming within documentation files. Overall, this is an excellent and valuable addition to the Fedify ecosystem.

_{Note: Security Review did not run due to the size of the PR.}

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new @fedify/mysql package, providing a KvStore implementation for MySQL and MariaDB. The implementation is well-structured and includes comprehensive tests and documentation updates. I've identified a few areas for improvement in the MysqlKvStore implementation concerning potential key length limitations, performance of the key expiration mechanism, and the robustness of prefix searching. Additionally, there's an opportunity to simplify the TTL duration calculation.

_{Note: Security Review did not run due to the size of the PR.}

[Copilot]

Pull request overview

This PR introduces a new @fedify/mysql package that provides a MySQL/MariaDB-backed KvStore implementation (MysqlKvStore) using the mysql2 driver, and wires it into the monorepo, documentation, CI, and fedify init.

Changes:

• Added @fedify/mysql package with MysqlKvStore, build config, and integration tests.
• Updated workspace/dependency configuration (pnpm + Deno) to include mysql2 and the new package.
• Updated docs, changelog, CI, and fedify init templates to reference/use MySQL/MariaDB KV storage.

Reviewed changes

Copilot reviewed 22 out of 24 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
pnpm-workspace.yaml	Adds packages/mysql to the workspace and introduces mysql2 to the catalog.
pnpm-lock.yaml	Locks new workspace package and mysql2 dependency graph.
packages/relay/README.md	Mentions MysqlKvStore as a production KV option for relay usage.
packages/mysql/tsdown.config.ts	Adds build configuration, including Temporal polyfill intro injection.
packages/mysql/src/mod.ts	Exports MysqlKvStore public API surface.
packages/mysql/src/kv.ts	Implements MysqlKvStore (get/set/delete/list/cas + initialize/drop).
packages/mysql/src/kv.test.ts	Adds MySQL integration tests for the KV store operations.
packages/mysql/package.json	Defines the new package metadata, exports, and deps/peers.
packages/mysql/deno.json	Adds Deno/JSR metadata and tasks for the new package.
packages/mysql/README.md	Adds package README with installation and usage snippet.
packages/init/src/json/kv.json	Adds MySQL/MariaDB as a fedify init KV backend option.
packages/fedify/README.md	Registers @fedify/mysql in the monorepo package list.
docs/tutorial/basics.md	Mentions MysqlKvStore as a production KV option in the tutorial.
docs/package.json	Adds @fedify/mysql to docs dependencies for examples/build.
docs/manual/relay.md	Updates relay manual to include MySQL/MariaDB KV store option.
docs/manual/kv.md	Adds a new MysqlKvStore section with install + example code.
docs/manual/federation.md	Mentions @fedify/mysql as an additional production KV backend.
docs/.vitepress/config.mts	Adds @fedify/mysql to references list.
deno.lock	Locks npm:mysql2 and transitive deps for Deno usage.
deno.json	Registers packages/mysql workspace path and adds mysql2 imports.
CHANGES.md	Adds changelog entry for the new @fedify/mysql package.
AGENTS.md	Updates contributor/agent instructions to include packages/mysql.
.github/workflows/main.yaml	Adds a MySQL 8 service and MYSQL_URL to CI test jobs.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[codecov]

Codecov Report

❌ Patch coverage is 94.92386% with 10 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/mysql/src/kv.ts	94.89%	10 Missing ⚠️

Files with missing lines	Coverage Δ
packages/mysql/src/mod.ts	100.00% <100.00%> (ø)
packages/mysql/src/kv.ts	94.89% <94.89%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new package @fedify/mysql which provides a MysqlKvStore for using MySQL or MariaDB as a key-value store with Fedify. The implementation is robust, well-tested, and covers all the necessary features of the KvStore interface, including atomic operations and TTL handling. The changes also include updates to documentation, CI, and the project initializer to integrate the new package.

I've identified a small area for improvement in the durationToSeconds helper function within packages/mysql/src/kv.ts, where using the Temporal.Duration.prototype.total() method can simplify the code. This comment aligns with general best practices and does not contradict any specific rules.

_{Note: Security Review did not run due to the size of the PR.}

[Copilot]

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated 9 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the @fedify/mysql package, providing a MysqlKvStore implementation. The changes include the new package with its source code, tests, and documentation, as well as updates to the monorepo configuration and documentation to integrate the new package. The implementation of MysqlKvStore uses MySQL-specific features like INSERT ... ON DUPLICATE KEY UPDATE and transactional locking with SELECT ... FOR UPDATE to ensure correctness and efficiency. The test suite is comprehensive and covers various use cases and edge cases. After a thorough review, I have not identified any issues of medium or higher severity.

_{Note: Security Review did not run due to the size of the PR.}

[Copilot]

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported