Merge pull request #19 from dahlia/postgres

Add PostgreSQL repository package

Author: dahlia

CHANGES.md

@@ -56,6 +56,15 @@ To be released.
 [#14]: https://github.com/fedify-dev/botkit/pull/14
 [#18]: https://github.com/fedify-dev/botkit/issues/18
 
+### @fedify/botkit-postgres
+
+ -  Added a new PostgreSQL repository package, *`@fedify/botkit-postgres`*,
+    which provides `PostgresRepository`, `PostgresRepositoryOptions`, and
+    `initializePostgresRepositorySchema()`.  [[#11], [#19]]
+
+[#11]: https://github.com/fedify-dev/botkit/issues/11
+[#19]: https://github.com/fedify-dev/botkit/pull/19
+
 
 Version 0.3.1
 -------------

deno.json

@@ -35,7 +35,7 @@
     "check-versions": "deno run --allow-read --allow-write scripts/check_versions.ts",
     "fmt": "deno fmt && deno task hongdown --write",
     "install": "deno cache packages/*/src/*.ts && pnpm install",
-    "test": "deno test --allow-read --allow-write --allow-env --allow-net=hollo.social --parallel",
+    "test": "deno test --allow-read --allow-write --allow-env --allow-net=hollo.social,localhost,127.0.0.1 --parallel",
     "test:node": "pnpm install && pnpm run -r test",
     "test-all": {
       "dependencies": ["check", "test", "test:node"]

deno.lock

@@ -97,6 +97,12 @@ the key–value store specified in the [`kv`](#createbotoptions-kv) option.
 
 For more information, see the [*Repository* section](./repository.md).
 
+If you want to use a SQL-backed repository directly instead of
+[`KvRepository`](./repository.md#kvrepository), BotKit also provides concrete
+repository packages such as
+[`SqliteRepository`](./repository.md#sqliterepository) and
+[`PostgresRepository`](./repository.md#postgresrepository).
+
 ### `~CreateBotOptions.identifier`
 
 The internal identifier of the bot actor.  It is used for the URI of the bot

docs/concepts/bot.md

@@ -135,6 +135,88 @@ properties:
 [`node:sqlite`]: https://nodejs.org/api/sqlite.html
 
 
+`PostgresRepository`
+--------------------
+
+*This API is available since BotKit 0.4.0.*
+
+The `PostgresRepository` is a repository that stores data in PostgreSQL using
+the [Postgres.js] driver.  It is suited for deployments where multiple bot
+processes need to share the same persistent repository state, or where you
+already operate PostgreSQL for other infrastructure.
+
+Unlike [`KvRepository`](#kvrepository), `PostgresRepository` stores BotKit data
+in ordinary PostgreSQL tables rather than a key-value abstraction.  It creates
+tables inside a dedicated PostgreSQL schema, uses transactions for multi-step
+updates, and supports either an internally owned connection pool or an injected
+Postgres.js client.
+
+In order to use `PostgresRepository`, you need to install the
+*@fedify/botkit-postgres* package:
+
+::: code-group
+
+~~~~ sh [Deno]
+deno add jsr:@fedify/botkit-postgres
+~~~~
+
+~~~~ sh [npm]
+npm add @fedify/botkit-postgres
+~~~~
+
+~~~~ sh [pnpm]
+pnpm add @fedify/botkit-postgres
+~~~~
+
+~~~~ sh [Yarn]
+yarn add @fedify/botkit-postgres
+~~~~
+
+:::
+
+The `PostgresRepository` constructor accepts an options object with the
+following properties:
+
+`sql`
+:   An existing [Postgres.js] client.  When this is provided, the repository
+    does not own the client and calling `close()` will not shut it down.
+
+`url`
+:   A PostgreSQL connection string used to create an internal connection pool.
+    Exactly one of `sql` and `url` must be provided.
+
+`schema` (optional)
+:   The PostgreSQL schema used for BotKit tables.  Defaults to `"botkit"`.
+
+`maxConnections` (optional)
+:   The maximum number of connections for the internally created pool.  This
+    option is only valid when `url` is used.
+
+`prepare` (optional)
+:   Whether to use prepared statements for repository queries.  Defaults to
+    `true`.
+
+These options are mutually exclusive: use either `sql` or `url`.  The
+`maxConnections` option is only meaningful together with `url`.
+
+The repository initializes its tables and indexes automatically.  If you want
+to provision them before creating the repository, use the exported
+`initializePostgresRepositorySchema()` helper:
+
+~~~~ typescript
+import postgres from "postgres";
+import { initializePostgresRepositorySchema } from "@fedify/botkit-postgres";
+
+const sql = postgres("postgresql://localhost/botkit");
+await initializePostgresRepositorySchema(sql, "botkit");
+~~~~
+
+If you disable prepared statements for PgBouncer-style deployments, pass
+`false` as the third argument so schema initialization uses the same setting.
+
+[Postgres.js]: https://github.com/porsager/postgres
+
+
 `MemoryRepository`
 ------------------