postgres: added pg and postgres, and examples for xata and neon

packages/postgres/README.md

@@ -1,5 +1,8 @@
 # Postgres adapter for `bknd` (experimental)
-This packages adds an adapter to use a Postgres database with [`bknd`](https://github.com/bknd-io/bknd). It is based on [`pg`](https://github.com/brianc/node-postgres) and the driver included in [`kysely`](https://github.com/kysely-org/kysely).
+This packages adds an adapter to use a Postgres database with [`bknd`](https://github.com/bknd-io/bknd). It works with both `pg` and `postgres` drivers, and supports custom postgres connections.
+* works with any Postgres database (tested with Supabase, Neon, Xata, and RDS)
+* choose between `pg` and `postgres` drivers
+* create custom postgres connections with any kysely postgres dialect
 
 ## Installation
 Install the adapter with:
@@ -7,44 +10,93 @@ Install the adapter with:
 npm install @bknd/postgres
 ```
 
-## Usage
+## Using `pg` driver
+Install the [`pg`](https://github.com/brianc/node-postgres) driver with:
+```bash
+npm install pg
+```
+
 Create a connection:
 
 ```ts
-import { PostgresConnection } from "@bknd/postgres";
+import { pg } from "@bknd/postgres";
 
-const connection = new PostgresConnection({
+// accepts `pg` configuration
+const connection = pg({
    host: "localhost",
    port: 5432,
    user: "postgres",
    password: "postgres",
-   database: "bknd",
+   database: "postgres",
+});
+
+// or with a connection string
+const connection = pg({
+   connectionString: "postgres://postgres:postgres@localhost:5432/postgres",
 });
 ```
 
-Use the connection depending on which framework or runtime you are using. E.g., when using `createApp`, you can use the connection as follows:
+## Using `postgres` driver
 
-```ts
-import { createApp } from "bknd";
-import { PostgresConnection } from "@bknd/postgres";
-
-const connection = new PostgresConnection();
-const app = createApp({ connection });
+Install the [`postgres`](https://github.com/porsager/postgres) driver with:
+```bash
+npm install postgres
 ```
 
-Or if you're using it with a framework, say Next.js, you can add the connection object to where you're initializating the app:
+Create a connection:
 
 ```ts
-// e.g. in src/app/api/[[...bknd]]/route.ts
-import { serve } from "bknd/adapter/nextjs";
-import { PostgresConnection } from "@bknd/postgres";
+import { postgresJs } from "@bknd/postgres";
 
-const connection = new PostgresConnection();
-const handler = serve({
-   connection
-})
-
-// ...
+// accepts `postgres` configuration
+const connection = postgresJs("postgres://postgres:postgres@localhost:5432/postgres");
 ```
 
-For more information about how to integrate Next.js in general, check out the [Next.js documentation](https://docs.bknd.io/integration/nextjs).
+## Using custom postgres dialects
+
+You can create a custom kysely postgres dialect by using the `createCustomPostgresConnection` function.
+
+```ts
+import { createCustomPostgresConnection } from "@bknd/postgres";
+
+const connection = createCustomPostgresConnection(MyDialect)({
+   // your custom dialect configuration
+   supports: {
+      batching: true
+   },
+   excludeTables: ["my_table"],
+   plugins: [new MyKyselyPlugin()],
+});
+```
+
+### Custom `neon` connection
+
+```typescript
+import { createCustomPostgresConnection } from "@bknd/postgres";
+import { NeonDialect } from "kysely-neon";
+
+const connection = createCustomPostgresConnection(NeonDialect)({
+   connectionString: process.env.NEON,
+});
+```
+
+### Custom `xata` connection
+
+```typescript
+import { createCustomPostgresConnection } from "@bknd/postgres";
+import { XataDialect } from "@xata.io/kysely";
+import { buildClient } from "@xata.io/client";
+
+const client = buildClient();
+const xata = new client({
+   databaseURL: process.env.XATA_URL,
+   apiKey: process.env.XATA_API_KEY,
+   branch: process.env.XATA_BRANCH,
+});
+
+const connection = createCustomPostgresConnection(XataDialect, {
+   supports: {
+      batching: false,
+   },
+})({ xata });
+```