shishantbiswas/bknd
1
0
Fork 0
mirror of https://github.com/shishantbiswas/bknd.git synced 2026-03-15 20:17:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
dswbx
2025-06-06 16:52:07 +02:00
parent abbd372ddf
commit 58c7aba1a4
21 changed files with 509 additions and 247 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
packages/postgres/README.md
View File

@@ -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 });
```

14
packages/postgres/examples/neon.ts Normal file
View File

@@ -0,0 +1,14 @@
import { serve } from "bknd/adapter/bun";
import { createCustomPostgresConnection } from "../src";
import { NeonDialect } from "kysely-neon";
const neon = createCustomPostgresConnection(NeonDialect);
export default serve({
connection: neon({
connectionString: process.env.NEON,
}),
// ignore this, it's only required within this repository
// because bknd is installed via "workspace:*"
distPath: "../../app/dist",
});

24
packages/postgres/examples/xata.ts Normal file
View File

@@ -0,0 +1,24 @@
import { serve } from "bknd/adapter/bun";
import { createCustomPostgresConnection } from "../src";
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 });
export default serve({
connection,
// ignore this, it's only required within this repository
// because bknd is installed via "workspace:*"
distPath: "../../../app/dist",
});

13
packages/postgres/package.json
View File

@@ -1,6 +1,6 @@
{
"name": "@bknd/postgres",
"version": "0.0.1",
"version": "0.1.0",
"type": "module",
"main": "dist/index.js",
"module": "dist/index.js",
@@ -17,15 +17,20 @@
"docker:start": "docker run --rm --name bknd-test-postgres -d -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres -e POSTGRES_DB=bknd -p 5430:5432 postgres:17",
"docker:stop": "docker stop bknd-test-postgres"
},
"dependencies": {
"optionalDependencies": {
"kysely": "^0.27.6",
"kysely-postgres-js": "^2.0.0",
"pg": "^8.14.0",
"kysely": "^0.27.6"
"postgres": "^3.4.7"
},
"devDependencies": {
"@types/bun": "^1.2.5",
"@types/node": "^22.13.10",
"@types/pg": "^8.11.11",
"@xata.io/client": "^0.0.0-next.v93343b9646f57a1e5c51c35eccf0767c2bb80baa",
"@xata.io/kysely": "^0.2.1",
"bknd": "workspace:*",
"kysely-neon": "^1.3.0",
"tsup": "^8.4.0",
"typescript": "^5.8.2"
},
@@ -36,7 +41,7 @@
"clean": true,
"minify": true,
"dts": true,
"external": ["bknd", "pg", "kysely"]
"external": ["bknd", "pg", "kysely", "kysely-postgres-js"]
},
"files": ["dist", "README.md", "!*.map", "!metafile*.json"]
}

32
packages/postgres/src/PgPostgresConnection.ts Normal file
View File

@@ -0,0 +1,32 @@
import { Kysely, PostgresDialect } from "kysely";
import { PostgresIntrospector } from "./PostgresIntrospector";
import { PostgresConnection, plugins } from "./PostgresConnection";
import { customIntrospector } from "bknd/data";
import $pg from "pg";
export type PgPostgresConnectionConfig = $pg.PoolConfig;
export class PgPostgresConnection extends PostgresConnection {
private pool: $pg.Pool;
constructor(config: PgPostgresConnectionConfig) {
const pool = new $pg.Pool(config);
const kysely = new Kysely({
dialect: customIntrospector(PostgresDialect, PostgresIntrospector, {
excludeTables: [],
}).create({ pool }),
plugins,
});
super(kysely);
this.pool = pool;
}
override async close(): Promise<void> {
await this.pool.end();
}
}
export function pg(config: PgPostgresConnectionConfig): PgPostgresConnection {
return new PgPostgresConnection(config);
}

45
packages/postgres/src/PostgresConnection.ts
View File

@@ -1,56 +1,33 @@
import { Connection, type FieldSpec, type SchemaResponse } from "bknd/data";
import { Connection, type DbFunctions, type FieldSpec, type SchemaResponse } from "bknd/data";
import {
ParseJSONResultsPlugin,
type ColumnDataType,
type ColumnDefinitionBuilder,
type DatabaseIntrospector,
Kysely,
ParseJSONResultsPlugin,
PostgresDialect,
type Kysely,
type KyselyPlugin,
type SelectQueryBuilder,
} from "kysely";
import { jsonArrayFrom, jsonBuildObject, jsonObjectFrom } from "kysely/helpers/postgres";
import pg from "pg";
import { PostgresIntrospector } from "./PostgresIntrospector";
export type PostgresConnectionConfig = pg.PoolConfig;
export type QB = SelectQueryBuilder<any, any, any>;
const plugins = [new ParseJSONResultsPlugin()];
export const plugins = [new ParseJSONResultsPlugin()];
class CustomPostgresDialect extends PostgresDialect {
override createIntrospector(db: Kysely<any>): DatabaseIntrospector {
return new PostgresIntrospector(db, {
excludeTables: [],
});
}
}
export class PostgresConnection extends Connection {
export abstract class PostgresConnection<DB = any> extends Connection<DB> {
protected override readonly supported = {
batching: true,
};
private pool: pg.Pool;
constructor(config: PostgresConnectionConfig) {
const pool = new pg.Pool(config);
const kysely = new Kysely({
dialect: new CustomPostgresDialect({
pool,
}),
plugins,
//log: ["query", "error"],
});
constructor(kysely: Kysely<DB>, fn?: Partial<DbFunctions>, _plugins?: KyselyPlugin[]) {
super(
kysely,
{
fn ?? {
jsonArrayFrom,
jsonBuildObject,
jsonObjectFrom,
},
plugins,
_plugins ?? plugins,
);
this.pool = pool;
}
override getFieldSchema(spec: FieldSpec): SchemaResponse {
@@ -90,10 +67,6 @@ export class PostgresConnection extends Connection {
];
}
override async close(): Promise<void> {
await this.pool.end();
}
protected override async batch<Queries extends QB[]>(
queries: [...Queries],
): Promise<{

41
packages/postgres/src/PostgresJsConnection.ts Normal file
View File

@@ -0,0 +1,41 @@
import { Kysely } from "kysely";
import { PostgresIntrospector } from "./PostgresIntrospector";
import { PostgresConnection, plugins } from "./PostgresConnection";
import { customIntrospector } from "bknd/data";
import { PostgresJSDialect } from "kysely-postgres-js";
import $postgresJs, { type Sql, type Options, type PostgresType } from "postgres";
export type PostgresJsConfig = Options<Record<string, PostgresType>>;
export class PostgresJsConnection extends PostgresConnection {
private postgres: Sql;
constructor(opts: { postgres: Sql }) {
const kysely = new Kysely({
dialect: customIntrospector(PostgresJSDialect, PostgresIntrospector, {
excludeTables: [],
}).create({ postgres: opts.postgres }),
plugins,
});
super(kysely);
this.postgres = opts.postgres;
}
override async close(): Promise<void> {
await this.postgres.end();
}
}
export function postgresJs(
connectionString: string,
config?: PostgresJsConfig,
): PostgresJsConnection;
export function postgresJs(config: PostgresJsConfig): PostgresJsConnection;
export function postgresJs(
first: PostgresJsConfig | string,
second?: PostgresJsConfig,
): PostgresJsConnection {
const postgres = typeof first === "string" ? $postgresJs(first, second) : $postgresJs(first);
return new PostgresJsConnection({ postgres });
}

43
packages/postgres/src/custom.ts Normal file
View File

@@ -0,0 +1,43 @@
import type { Constructor } from "bknd/core";
import { customIntrospector, type DbFunctions } from "bknd/data";
import { Kysely, type Dialect, type KyselyPlugin } from "kysely";
import { plugins, PostgresConnection } from "./PostgresConnection";
import { PostgresIntrospector } from "./PostgresIntrospector";
export type CustomPostgresConnection = {
supports?: PostgresConnection["supported"];
fn?: Partial<DbFunctions>;
plugins?: KyselyPlugin[];
excludeTables?: string[];
};
export function createCustomPostgresConnection<
T extends Constructor<Dialect>,
C extends ConstructorParameters<T>[0],
>(
dialect: Constructor<Dialect>,
options?: CustomPostgresConnection,
): (config: C) => PostgresConnection<any> {
const supported = {
batching: true,
...((options?.supports ?? {}) as any),
};
return (config: C) =>
new (class extends PostgresConnection<any> {
protected override readonly supported = supported;
constructor(config: C) {
super(
new Kysely({
dialect: customIntrospector(dialect, PostgresIntrospector, {
excludeTables: options?.excludeTables ?? [],
}).create(config),
plugins: options?.plugins ?? plugins,
}),
options?.fn,
options?.plugins,
);
}
})(config);
}

5
packages/postgres/src/index.ts
View File

@@ -1,2 +1,5 @@
export { PostgresConnection, type PostgresConnectionConfig } from "./PostgresConnection";
export { pg, PgPostgresConnection, type PgPostgresConnectionConfig } from "./PgPostgresConnection";
export { PostgresIntrospector } from "./PostgresIntrospector";
export { PostgresConnection, type QB, plugins } from "./PostgresConnection";
export { postgresJs, PostgresJsConnection, type PostgresJsConfig } from "./PostgresJsConnection";
export { createCustomPostgresConnection } from "./custom";

19
packages/postgres/test/base.test.ts
View File

@@ -1,19 +0,0 @@
import { describe, it, expect } from "bun:test";
import { PostgresConnection } from "../src";
import { createConnection, cleanDatabase } from "./setup";
describe(PostgresConnection, () => {
it("should connect to the database", async () => {
const connection = createConnection();
expect(await connection.ping()).toBe(true);
});
it("should clean the database", async () => {
const connection = createConnection();
await cleanDatabase(connection);
const tables = await connection.getIntrospector().getTables();
expect(tables).toEqual([]);
});
});

113
packages/postgres/test/integration.test.ts
View File

@@ -1,113 +0,0 @@
import { describe, it, expect, beforeAll, afterAll, afterEach } from "bun:test";
import { createApp } from "bknd";
import * as proto from "bknd/data";
import { createConnection, cleanDatabase } from "./setup";
import type { PostgresConnection } from "../src";
let connection: PostgresConnection;
beforeAll(async () => {
connection = createConnection();
await cleanDatabase(connection);
});
afterEach(async () => {
await cleanDatabase(connection);
});
afterAll(async () => {
await connection.close();
});
describe("integration", () => {
it("should create app and ping", async () => {
const app = createApp({
connection,
});
await app.build();
expect(app.version()).toBeDefined();
expect(await app.em.ping()).toBe(true);
});
it("should create a basic schema", async () => {
const schema = proto.em(
{
posts: proto.entity("posts", {
title: proto.text().required(),
content: proto.text(),
}),
comments: proto.entity("comments", {
content: proto.text(),
}),
},
(fns, s) => {
fns.relation(s.comments).manyToOne(s.posts);
fns.index(s.posts).on(["title"], true);
},
);
const app = createApp({
connection,
initialConfig: {
data: schema.toJSON(),
},
});
await app.build();
expect(app.em.entities.length).toBe(2);
expect(app.em.entities.map((e) => e.name)).toEqual(["posts", "comments"]);
const api = app.getApi();
expect(
(
await api.data.createMany("posts", [
{
title: "Hello",
content: "World",
},
{
title: "Hello 2",
content: "World 2",
},
])
).data,
).toEqual([
{
id: 1,
title: "Hello",
content: "World",
},
{
id: 2,
title: "Hello 2",
content: "World 2",
},
] as any);
// try to create an existing
expect(
(
await api.data.createOne("posts", {
title: "Hello",
})
).ok,
).toBe(false);
// add a comment to a post
await api.data.createOne("comments", {
content: "Hello",
posts_id: 1,
});
// and then query using a `with` property
const result = await api.data.readMany("posts", { with: ["comments"] });
expect(result.length).toBe(2);
expect(result[0].comments.length).toBe(1);
expect(result[0].comments[0].content).toBe("Hello");
expect(result[1].comments.length).toBe(0);
});
});

16
packages/postgres/test/pg.test.ts Normal file
View File

@@ -0,0 +1,16 @@
import { describe } from "bun:test";
import { pg } from "../src/PgPostgresConnection";
import { testSuite } from "./suite";
describe("pg", () => {
testSuite({
createConnection: () =>
pg({
host: "localhost",
port: 5430,
user: "postgres",
password: "postgres",
database: "bknd",
}),
});
});

16
packages/postgres/test/postgresjs.test.ts Normal file
View File

@@ -0,0 +1,16 @@
import { describe } from "bun:test";
import { postgresJs } from "../src/PostgresJsConnection";
import { testSuite } from "./suite";
describe("postgresjs", () => {
testSuite({
createConnection: () =>
postgresJs({
host: "localhost",
port: 5430,
user: "postgres",
password: "postgres",
database: "bknd",
}),
});
});

25
packages/postgres/test/setup.ts
View File

@@ -1,25 +0,0 @@
import type { Kysely } from "kysely";
import { PostgresConnection, PostgresIntrospector, type PostgresConnectionConfig } from "../src";
export const info = {
host: "localhost",
port: 5430,
user: "postgres",
password: "postgres",
database: "bknd",
};
export function createConnection(config: PostgresConnectionConfig = {}) {
return new PostgresConnection({
...info,
...config,
});
}
export async function cleanDatabase(connection: PostgresConnection) {
const kysely = connection.kysely;
// drop all tables & create new schema
await kysely.schema.dropSchema("public").ifExists().cascade().execute();
await kysely.schema.createSchema("public").execute();
}

155
packages/postgres/test/suite.ts Normal file
View File

@@ -0,0 +1,155 @@
import { describe, beforeAll, afterAll, expect, it, afterEach } from "bun:test";
import type { PostgresConnection } from "../src";
import { createApp } from "bknd";
import * as proto from "bknd/data";
import { disableConsoleLog, enableConsoleLog } from "bknd/utils";
export type TestSuiteConfig = {
createConnection: () => InstanceType<typeof PostgresConnection>;
cleanDatabase?: (connection: InstanceType<typeof PostgresConnection>) => Promise<void>;
};
export async function defaultCleanDatabase(connection: InstanceType<typeof PostgresConnection>) {
const kysely = connection.kysely;
// drop all tables & create new schema
await kysely.schema.dropSchema("public").ifExists().cascade().execute();
await kysely.schema.createSchema("public").execute();
}
async function cleanDatabase(
connection: InstanceType<typeof PostgresConnection>,
config: TestSuiteConfig,
) {
if (config.cleanDatabase) {
await config.cleanDatabase(connection);
} else {
await defaultCleanDatabase(connection);
}
}
export function testSuite(config: TestSuiteConfig) {
beforeAll(() => disableConsoleLog(["log", "warn", "error"]));
afterAll(() => enableConsoleLog());
describe("base", () => {
it("should connect to the database", async () => {
const connection = config.createConnection();
expect(await connection.ping()).toBe(true);
});
it("should clean the database", async () => {
const connection = config.createConnection();
await cleanDatabase(connection, config);
const tables = await connection.getIntrospector().getTables();
expect(tables).toEqual([]);
});
});
describe("integration", () => {
let connection: PostgresConnection;
beforeAll(async () => {
connection = config.createConnection();
await cleanDatabase(connection, config);
});
afterEach(async () => {
await cleanDatabase(connection, config);
});
afterAll(async () => {
await connection.close();
});
it("should create app and ping", async () => {
const app = createApp({
connection,
});
await app.build();
expect(app.version()).toBeDefined();
expect(await app.em.ping()).toBe(true);
});
it("should create a basic schema", async () => {
const schema = proto.em(
{
posts: proto.entity("posts", {
title: proto.text().required(),
content: proto.text(),
}),
comments: proto.entity("comments", {
content: proto.text(),
}),
},
(fns, s) => {
fns.relation(s.comments).manyToOne(s.posts);
fns.index(s.posts).on(["title"], true);
},
);
const app = createApp({
connection,
initialConfig: {
data: schema.toJSON(),
},
});
await app.build();
expect(app.em.entities.length).toBe(2);
expect(app.em.entities.map((e) => e.name)).toEqual(["posts", "comments"]);
const api = app.getApi();
expect(
(
await api.data.createMany("posts", [
{
title: "Hello",
content: "World",
},
{
title: "Hello 2",
content: "World 2",
},
])
).data,
).toEqual([
{
id: 1,
title: "Hello",
content: "World",
},
{
id: 2,
title: "Hello 2",
content: "World 2",
},
] as any);
// try to create an existing
expect(
(
await api.data.createOne("posts", {
title: "Hello",
})
).ok,
).toBe(false);
// add a comment to a post
await api.data.createOne("comments", {
content: "Hello",
posts_id: 1,
});
// and then query using a `with` property
const result = await api.data.readMany("posts", { with: ["comments"] });
expect(result.length).toBe(2);
expect(result[0].comments.length).toBe(1);
expect(result[0].comments[0].content).toBe("Hello");
expect(result[1].comments.length).toBe(0);
});
});
}