Unverified Commit 899ecd27 authored by Hong Minhee's avatar Hong Minhee
Browse files

Mention PostgreSQL drivers on docs 

[ci skip]
parent fb5e57aa

docs/manual/federation.md

+11 −4
Original line number Diff line number Diff line
@@ -51,13 +51,17 @@ testing and development purposes, and the `DenoKvStore` class is Deno KV-backed 
implementation for production use (as you can guess from the name, it is only

available in Deno runtime).



As a separate package, [@fedify/redis] provides [`RedisKvStore`] class, which is

a Redis-backed implementation for production use.

As separate packages, [@fedify/redis] provides [`RedisKvStore`] class, which is

a Redis-backed implementation for production use, and [@fedify/postgres]

provides [`PostgresKvStore`] class, which is a PostgreSQL-backed implementation

for production use.



Further details are explained in the [*Key–value store* section](./kv.md).



[@fedify/redis]: https://github.com/dahlia/fedify-redis

[`RedisKvStore`]: https://jsr.io/@fedify/redis/doc/kv/~/RedisKvStore

[@fedify/postgres]: https://github.com/dahlia/fedify-postgres

[`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/kv/~/PostgresKvStore



### `kvPrefixes`
@@ -96,8 +100,10 @@ and the `DenoKvMessageQueue` class is a Deno KV-backed implementation for 
production use (as you can guess from the name, it is only available in Deno

runtime).



As a separate package, [@fedify/redis] provides [`RedisMessageQueue`] class,

which is a Redis-backed implementation for production use.

As separate packages, [@fedify/redis] provides [`RedisMessageQueue`] class,

which is a Redis-backed implementation for production use,

and [@fedify/postgres] provides [`PostgresMessageQueue`] class, which is a

PostgreSQL-backed implementation for production use.



Further details are explained in the [*Message queue* section](./mq.md).
@@ -109,6 +115,7 @@ Further details are explained in the [*Message queue* section](./mq.md). 
> and can cause performance issues.



[`RedisMessageQueue`]: https://jsr.io/@fedify/redis/doc/mq/~/RedisMessageQueue

[`PostgresMessageQueue`]: https://jsr.io/@fedify/postgres/doc/mq/~/PostgresMessageQueue



### `manuallyStartQueue`

docs/manual/kv.md

+35 −0
Original line number Diff line number Diff line
@@ -107,6 +107,41 @@ const federation = createFederation<void>({ 
[@fedify/redis]: https://github.com/dahlia/fedify-redis

[`RedisKvStore`]: https://jsr.io/@fedify/redis/doc/kv/~/RedisKvStore



### [`PostgresKvStore`]



> [!NOTE]

> The [`PostgresKvStore`] class is available in the [@fedify/postgres] package.



[`PostgresKvStore`] is a key–value store implementation that uses PostgreSQL as

the backend storage. It provides scalability and high performance, making it

suitable for production use in distributed systems.  It requires a PostgreSQL

server setup and maintenance.



Best for

:   Production use, a system that already uses PostgreSQL.



Pros

:   Scalable, no additional setup required if already using PostgreSQL.



Cons

:   Requires PostgreSQL setup and maintenance.



~~~~ typescript{6-8} twoslash

import { createFederation } from "@fedify/fedify";

import { PostgresKvStore } from "@fedify/postgres";

import postgres from "postgres";



const federation = createFederation<void>({

  kv: new PostgresKvStore(

    postgres("postgresql://user:pass@localhost/db"),

  ),

  // ... other options

});

~~~~



[`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/kv/~/PostgresKvStore

[@fedify/postgres]: https://github.com/dahlia/fedify-postgres





Implementing a custom `KvStore`

-------------------------------

docs/manual/mq.md

+45 −1
Original line number Diff line number Diff line
@@ -124,6 +124,50 @@ const federation = createFederation<void>({ 
[`RedisMessageQueue`]: https://jsr.io/@fedify/redis/doc/mq/~/RedisMessageQueue

[@fedify/redis]: https://github.com/dahlia/fedify-redis



### [`PostgresMessageQueue`]



> [!NOTE]

> The [`PostgresMessageQueue`] class is available in the [@fedify/postgres]

> package.



[`PostgresMessageQueue`] is a message queue implementation that uses

a PostgreSQL database as the message queue backend.  Under the hood,

it uses a table for maintaining the queue, and [`LISTEN`]/[`NOTIFY`] for

real-time message delivery.  It's suitable for production use if you

already rely on PostgreSQL in your application.



Best for

:   Production use, a system that already uses PostgreSQL.



Pros

:   Persistent, scalable, supports multiple workers.



Cons

:   Requires PostgreSQL setup.



~~~~ typescript{6-8} twoslash

import type { KvStore } from "@fedify/fedify";

// ---cut-before---

import { createFederation } from "@fedify/fedify";

import { PostgresMessageQueue } from "@fedify/postgres";

import postgres from "postgres";



const federation = createFederation<void>({

// ---cut-start---

  kv: null as unknown as KvStore,

// ---cut-end---

  queue: new PostgresMessageQueue(

    postgres("postgresql://user:pass@localhost/db"),

  ),

  // ... other options

});

~~~~



[`PostgresMessageQueue`]: https://jsr.io/@fedify/postgres/doc/mq/~/PostgresMessageQueue

[@fedify/postgres]: https://github.com/dahlia/fedify-postgres

[`LISTEN`]: https://www.postgresql.org/docs/current/sql-listen.html

[`NOTIFY`]: https://www.postgresql.org/docs/current/sql-notify.html





Implementing a custom `MessageQueue`

------------------------------------
@@ -238,7 +282,7 @@ const federation = createFederation<void>({ 
Separating message processing from the main process

---------------------------------------------------



*This API is available since Fedify 0.12.0.*

*This API is available since Fedify 1.0.0.*



On high-traffic servers, it's common to separate message processing from

the main server process to avoid blocking the main event loop.  To achieve this,

docs/package.json

+3 −1
Original line number Diff line number Diff line 
{

  "devDependencies": {

    "@deno/kv": "^0.8.2",

    "@fedify/fedify": "1.0.0-dev.409",

    "@fedify/fedify": "1.0.0-dev.410",

    "@fedify/postgres": "0.1.0-dev.2",

    "@fedify/redis": "0.2.0-dev.10",

    "@hono/node-server": "^1.12.2",

    "@js-temporal/polyfill": "^0.4.4",
@@ -18,6 +19,7 @@ 
    "markdown-it-footnote": "^4.0.0",

    "markdown-it-jsr-ref": "^0.3.2",

    "mermaid": "^10.9.1",

    "postgres": "^3.4.4",

    "stringify-entities": "^4.0.4",

    "vitepress": "^1.3.1",

    "vitepress-plugin-mermaid": "^2.0.16",

docs/pnpm-lock.yaml

+30 −6
Original line number Diff line number Diff line
@@ -12,8 +12,11 @@ importers: 
        specifier: ^0.8.2

        version: 0.8.2

      '@fedify/fedify':

        specifier: 1.0.0-dev.409

        version: 1.0.0-dev.409(web-streams-polyfill@3.3.3)

        specifier: 1.0.0-dev.410

        version: 1.0.0-dev.410(web-streams-polyfill@3.3.3)

      '@fedify/postgres':

        specifier: 0.1.0-dev.2

        version: 0.1.0-dev.2(web-streams-polyfill@3.3.3)

      '@fedify/redis':

        specifier: 0.2.0-dev.10

        version: 0.2.0-dev.10(web-streams-polyfill@3.3.3)
@@ -62,6 +65,9 @@ importers: 
      mermaid:

        specifier: ^10.9.1

        version: 10.9.1

      postgres:

        specifier: ^3.4.4

        version: 3.4.4

      stringify-entities:

        specifier: ^4.0.4

        version: 4.0.4
@@ -367,8 +373,11 @@ packages: 
    resolution: {integrity: sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==}

    engines: {node: '>=14'}



  '@fedify/fedify@1.0.0-dev.409':

    resolution: {integrity: sha512-Lbk8eiJZrH2u1JeOdjQp9lSt9CtZkBK3LHW5akoV7znVY9TMZ5E6BHWlzoi0HxYJPIpOHXaQOWHo9v3CBnz9QQ==}

  '@fedify/fedify@1.0.0-dev.410':

    resolution: {integrity: sha512-1/Go2BF9/Eg2tx+aA9pk3lvJ4JycIbvb7urt5LkMNtYE6tVPc9/2yPHvps27WPvua76djALDyrxndNpvXb4eMQ==}



  '@fedify/postgres@0.1.0-dev.2':

    resolution: {integrity: sha512-KeLhfRgprJF7EXVgzPBRQAJKHnX79IdoZgrWWqD78bAIx3IiRLMXc+LS7/UmQaD0PiNmFXK+cUzKUE00/HbyDg==}



  '@fedify/redis@0.2.0-dev.10':

    resolution: {integrity: sha512-OMaqK0Hpvl+HpGMTCjszM/DmYrljRGJaA9wTN4pWEtDBhwxwbMsuOlq8AdqsiFx7yJCxmosPL4iwuLRC21FxRg==}
@@ -1417,6 +1426,10 @@ packages: 
    resolution: {integrity: sha512-7KTLTdzdZZYscUc65XmjFiB73vBhBfbPztCYdUNvlaso9PrzjzcmjqBPR0lNGkcVlcO4BjiO5rK/qNz+XAen1Q==}

    engines: {node: ^10 || ^12 || >=14}



  postgres@3.4.4:

    resolution: {integrity: sha512-IbyN+9KslkqcXa8AO9fxpk97PA4pzewvpi2B3Dwy9u4zpV32QicaEdgmF3eSQUzdRk7ttDHQejNgAEr4XoeH4A==}

    engines: {node: '>=12'}



  preact@10.24.0:

    resolution: {integrity: sha512-aK8Cf+jkfyuZ0ZZRG9FbYqwmEiGQ4y/PUO4SuTWoyWL244nZZh7bd5h2APd4rSNDYTBNghg1L+5iJN3Skxtbsw==}
@@ -1952,7 +1965,7 @@ snapshots: 


  '@fastify/busboy@2.1.1': {}



  '@fedify/fedify@1.0.0-dev.409(web-streams-polyfill@3.3.3)':

  '@fedify/fedify@1.0.0-dev.410(web-streams-polyfill@3.3.3)':

    dependencies:

      '@deno/shim-crypto': 0.3.1

      '@deno/shim-deno': 0.18.2
@@ -1972,10 +1985,19 @@ snapshots: 
    transitivePeerDependencies:

      - web-streams-polyfill



  '@fedify/postgres@0.1.0-dev.2(web-streams-polyfill@3.3.3)':

    dependencies:

      '@deno/shim-deno': 0.18.2

      '@fedify/fedify': 1.0.0-dev.410(web-streams-polyfill@3.3.3)

      '@js-temporal/polyfill': 0.4.4

      postgres: 3.4.4

    transitivePeerDependencies:

      - web-streams-polyfill



  '@fedify/redis@0.2.0-dev.10(web-streams-polyfill@3.3.3)':

    dependencies:

      '@deno/shim-deno': 0.18.2

      '@fedify/fedify': 1.0.0-dev.409(web-streams-polyfill@3.3.3)

      '@fedify/fedify': 1.0.0-dev.410(web-streams-polyfill@3.3.3)

      '@js-temporal/polyfill': 0.4.4

      ioredis: 5.4.1

    transitivePeerDependencies:
@@ -3322,6 +3344,8 @@ snapshots: 
      picocolors: 1.1.0

      source-map-js: 1.2.1



  postgres@3.4.4: {}



  preact@10.24.0: {}



  property-information@6.5.0: {}