Merge pull request #597 from dahlia/mysql

Add `@fedify/mysql` package with `MysqlKvStore`

Author: dahlia

.github/workflows/main.yaml

@@ -56,8 +56,21 @@ jobs:
           --health-retries 5
         ports:
         - 6379:6379
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: mysql
+          MYSQL_DATABASE: fedify
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -pmysql"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+        - 3306:3306
     env:
       AMQP_URL: amqp://guest:guest@localhost:5672
+      MYSQL_URL: mysql://root:mysql@localhost:3306/fedify
       POSTGRES_URL: postgres://postgres:postgres@localhost:5432/postgres
       REDIS_URL: redis://localhost:6379
     steps:
@@ -127,8 +140,21 @@ jobs:
           --health-retries 5
         ports:
         - 6379:6379
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: mysql
+          MYSQL_DATABASE: fedify
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -pmysql"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+        - 3306:3306
     env:
       AMQP_URL: amqp://guest:guest@localhost:5672
+      MYSQL_URL: mysql://root:mysql@localhost:3306/fedify
       POSTGRES_URL: postgres://postgres:postgres@localhost:5432/postgres
       REDIS_URL: redis://localhost:6379
     steps:
@@ -177,8 +203,21 @@ jobs:
           --health-retries 5
         ports:
         - 6379:6379
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: mysql
+          MYSQL_DATABASE: fedify
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -pmysql"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+        - 3306:3306
     env:
       AMQP_URL: amqp://guest:guest@localhost:5672
+      MYSQL_URL: mysql://root:mysql@localhost:3306/fedify
       POSTGRES_URL: postgres://postgres:postgres@localhost:5432/postgres
       REDIS_URL: redis://localhost:6379
     steps:

.hongdown.toml

@@ -26,6 +26,7 @@ proper_nouns = [
   "@fedify/h3",
   "@fedify/hono",
   "@fedify/koa",
+  "@fedify/mysql",
   "@fedify/nestjs",
   "@fedify/postgres",
   "@fedify/redis",

AGENTS.md

@@ -169,8 +169,8 @@ Common tasks
 1.  For core KV/MQ interfaces: implement in *packages/fedify/src/federation/kv.ts*
     and *packages/fedify/src/federation/mq.ts*
 2.  For specific database adapters: create dedicated packages
-    (*packages/sqlite/*, *packages/postgres/*, *packages/redis/*,
-    *packages/amqp/*)
+    (*packages/sqlite/*, *packages/postgres/*, *packages/mysql/*,
+    *packages/redis/*, *packages/amqp/*)
 3.  Follow the pattern from existing database adapter packages
 4.  Implement both KV store and message queue interfaces as needed
 
@@ -326,8 +326,8 @@ The monorepo uses different build processes for different packages:
 3.  **Database adapters and integrations**: Use tsdown for TypeScript compilation:
      -  *packages/amqp/*, *packages/astro/*, *packages/elysia*,
         *packages/express/*, *packages/h3/*,
-        *packages/sqlite/*, *packages/postgres/*, *packages/redis/*,
-        *packages/nestjs/*
+        *packages/mysql/*, *packages/sqlite/*, *packages/postgres/*,
+        *packages/redis/*, *packages/nestjs/*
      -  Built to support Node.js and Bun environments
 
 Ensure changes work across all distribution formats and target environments.

CHANGES.md

@@ -19,28 +19,6 @@ To be released.
 [#473]: https://github.com/fedify-dev/fedify/issues/473
 [#589]: https://github.com/fedify-dev/fedify/pull/589
 
-### @fedify/astro
-
- -  Added `@fedify/astro` package for integrating Fedify with [Astro].
-    It provides `fedifyIntegration()` for Vite SSR configuration and
-    `fedifyMiddleware()` for request handling.  [[#50] by Chanhaeng Lee]
-
-[Astro]: https://astro.build/
-[#50]: https://github.com/fedify-dev/fedify/issues/50
-
-### @fedify/init
-
- -  Changed `fedify init` to add `"temporal"` to `deno.json`'s `"unstable"`
-    field only when the installed Deno version is earlier than 2.7.0.
-    On Deno 2.7.0 or later, it is no longer added.
-
- -  `fedify init` now omits the `"unstable"` field entirely when no unstable
-    feature is required for the generated Deno project.
-
- -  Supported [Astro] as a web framework option in `fedify init`, with
-    runtime-specific templates for Deno, Bun, and Node.js environments.
-    [[#50] by ChanHaeng Lee]
-
 ### @fedify/vocab
 
  -  Fixed `Endpoints.toJsonLd()` to no longer emit invalid
@@ -63,6 +41,40 @@ To be released.
     compact form) in the serialized JSON-LD.  This is useful for types
     that are not real vocabulary types but rather anonymous object structures.
 
+### @fedify/init
+
+ -  Changed `fedify init` to add `"temporal"` to `deno.json`'s `"unstable"`
+    field only when the installed Deno version is earlier than 2.7.0.
+    On Deno 2.7.0 or later, it is no longer added.
+
+ -  `fedify init` now omits the `"unstable"` field entirely when no unstable
+    feature is required for the generated Deno project.
+
+ -  Supported [Astro] as a web framework option in `fedify init`, with
+    runtime-specific templates for Deno, Bun, and Node.js environments.
+    [[#50] by ChanHaeng Lee]
+
+[Astro]: https://astro.build/
+[#50]: https://github.com/fedify-dev/fedify/issues/50
+
+### @fedify/astro
+
+ -  Added `@fedify/astro` package for integrating Fedify with [Astro].
+    It provides `fedifyIntegration()` for Vite SSR configuration and
+    `fedifyMiddleware()` for request handling.  [[#50] by Chanhaeng Lee]
+
+### @fedify/mysql
+
+ -  Added `@fedify/mysql` package, a MySQL/MariaDB-backed `KvStore`
+    implementation.  It provides `MysqlKvStore`, which stores key–value
+    pairs in a MySQL table using the [`mysql2`] driver.  Supports TTL,
+    prefix listing, and compare-and-swap (`cas()`) operations.
+    [[#585], [#597]]
+
+[`mysql2`]: https://www.npmjs.com/package/mysql2
+[#585]: https://github.com/fedify-dev/fedify/issues/585
+[#597]: https://github.com/fedify-dev/fedify/pull/597
+
 
 Version 2.0.3
 -------------

deno.json

@@ -16,6 +16,7 @@
     "./packages/hono",
     "./packages/koa",
     "./packages/lint",
+    "./packages/mysql",
     "./packages/postgres",
     "./packages/redis",
     "./packages/relay",
@@ -63,6 +64,8 @@
     "hono": "jsr:@hono/hono@^4.8.3",
     "ioredis": "npm:ioredis@^5.8.2",
     "json-preserve-indent": "npm:json-preserve-indent@^1.1.3",
+    "mysql2": "npm:mysql2@^3.18.0",
+    "mysql2/promise": "npm:mysql2@^3.18.0/promise",
     "postgres": "npm:postgres@^3.4.7",
     "preact": "npm:preact@10.19.6",
     "tsdown": "npm:tsdown@^0.18.4"

deno.lock

@@ -102,6 +102,7 @@ const REFERENCES = {
     { text: "@fedify/h3", link: "https://jsr.io/@fedify/h3/doc" },
     { text: "@fedify/hono", link: "https://jsr.io/@fedify/hono/doc" },
     { text: "@fedify/koa", link: "https://jsr.io/@fedify/koa/doc" },
+    { text: "@fedify/mysql", link: "https://jsr.io/@fedify/mysql/doc" },
     { text: "@fedify/postgres", link: "https://jsr.io/@fedify/postgres/doc" },
     { text: "@fedify/redis", link: "https://jsr.io/@fedify/redis/doc" },
     { text: "@fedify/relay", link: "https://jsr.io/@fedify/relay/doc" },

docs/.vitepress/config.mts

@@ -52,16 +52,19 @@ implementation for production use (as you can guess from the name, it is only
 available in Deno runtime).
 
 As separate packages, [`@fedify/redis`] provides [`RedisKvStore`] class, which
-is a Redis-backed implementation for production use, and [`@fedify/postgres`]
+is a Redis-backed implementation for production use, [`@fedify/postgres`]
 provides [`PostgresKvStore`] class, which is a PostgreSQL-backed implementation
-for production use.
+for production use, and [`@fedify/mysql`] provides [`MysqlKvStore`] class, which
+is a MySQL/MariaDB-backed implementation for production use.
 
 Further details are explained in the [*Key–value store* section](./kv.md).
 
 [`@fedify/redis`]: https://github.com/fedify-dev/fedify/tree/main/packages/redis
 [`RedisKvStore`]: https://jsr.io/@fedify/redis/doc/kv/~/RedisKvStore
 [`@fedify/postgres`]: https://github.com/fedify-dev/fedify/tree/main/packages/postgres
 [`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/kv/~/PostgresKvStore
+[`@fedify/mysql`]: https://github.com/fedify-dev/fedify/tree/main/packages/mysql
+[`MysqlKvStore`]: https://jsr.io/@fedify/mysql/doc/kv/~/MysqlKvStore
 
 ### `kvPrefixes`
 

docs/manual/federation.md

@@ -306,6 +306,65 @@ const federation = createFederation<void>({
 
 [`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/kv/~/PostgresKvStore
 
+### [`MysqlKvStore`]
+
+*This API is available since Fedify 2.1.0.*
+
+To use the [`MysqlKvStore`], you need to install the *@fedify/mysql* package
+first:
+
+::: code-group
+
+~~~~ bash [Deno]
+deno add jsr:@fedify/mysql
+~~~~
+
+~~~~ bash [npm]
+npm add @fedify/mysql mysql2
+~~~~
+
+~~~~ bash [pnpm]
+pnpm add @fedify/mysql mysql2
+~~~~
+
+~~~~ bash [Yarn]
+yarn add @fedify/mysql mysql2
+~~~~
+
+~~~~ bash [Bun]
+bun add @fedify/mysql mysql2
+~~~~
+
+:::
+
+[`MysqlKvStore`] is a key-value store implementation that uses MySQL (or
+MariaDB) as the backend storage.  It provides scalability and high performance,
+making it suitable for production use in distributed systems.  It requires
+a MySQL or MariaDB server setup and maintenance.
+
+Best for
+:   Production use, a system that already uses MySQL or MariaDB.
+
+Pros
+:   Scalable, no additional setup required if already using MySQL/MariaDB.
+
+Cons
+:   Requires MySQL/MariaDB setup and maintenance.
+
+~~~~ typescript twoslash
+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),
+  // ... other options
+});
+~~~~
+
+[`MysqlKvStore`]: https://jsr.io/@fedify/mysql/doc/kv/~/MysqlKvStore
+
 ### `WorkersKvStore` (Cloudflare Workers only)
 
 *This API is available since Fedify 1.6.0.*