shishantbiswas/bknd
1
0
Fork 0
mirror of https://github.com/shishantbiswas/bknd.git synced 2026-03-16 04:27:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

updated docs on databases

Browse Source
This commit is contained in:
dswbx
2025-06-13 17:18:29 +02:00
parent 0710b5bf1f
commit 2239333f08
6 changed files with 160 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
docs/usage/database.mdx
View File

@@ -3,53 +3,132 @@ title: 'Database'
description: 'Choosing the right database configuration'
---
In order to use **bknd**, you need to prepare access information to your database and install the dependencies. Connections to the database are managed using Kysely. Therefore, all [its dialects](https://kysely.dev/docs/dialects) are theoretically supported.
In order to use **bknd**, you need to prepare access information to your database and potentially install additional dependencies. Connections to the database are managed using Kysely. Therefore, all [its dialects](https://kysely.dev/docs/dialects) are theoretically supported.
Currently supported and tested databases are:
- SQLite (embedded): Node.js SQLite, Bun SQLite, LibSQL, SQLocal
- SQLite (remote): Turso, Cloudflare D1
- Postgres: Vanilla Postgres, Supabase, Neon, Xata
## Database
### SQLite in-memory
The easiest to get started is using SQLite in-memory. When serving the API in the "Integrations",
the function accepts an object with connection details. To use an in-memory database, you can either omit the object completely or explicitly use it as follows:
```json
{
"url": ":memory:"
}
By default, bknd will try to use a SQLite database in-memory. Depending on your runtime, a different SQLite implementation will be used.
## Defining the connection
There are mainly 3 ways to define the connection to your database, when
1. creating an app using `App.create()` or `createApp()`
2. creating an app using a [Framework or Runtime adapter](/integration/introduction)
3. starting a quick instance using the [CLI](/usage/cli#using-configuration-file-bknd-config)
When creating an app using `App.create()` or `createApp()`, you can pass a connection object in the configuration object.
```typescript app.ts
import { createApp } from "bknd";
import { sqlite } from "bknd/adapter/sqlite";
// a connection is required when creating an app like this
const app = createApp({
connection: sqlite({ url: ":memory:" }),
});
```
### SQLite as file
Just like the in-memory option, using a file is just as easy:
When using an adapter, or using the CLI, bknd will automatically try to use a SQLite implementation depending on the runtime:
```json
{
"url": "file:<path/to/your/database.db>"
}
```
Please note that using SQLite as a file is only supported in server environments.
### SQLite using LibSQL
Turso offers a SQLite-fork called LibSQL that runs a server around your SQLite database. To
point **bknd** to a local instance of LibSQL, [install Turso's CLI](https://docs.turso.tech/cli/introduction) and run the following command:
```bash
turso dev
```javascript app.js
import { serve } from "bknd/adapter/node";
serve({
// connection is optional, but recommended
connection: { url: "file:data.db" },
});
```
The command will yield a URL. Use it in the connection object:
```json
{
"url": "http://localhost:8080"
}
You can also pass a connection instance to the `connection` property to explictly use a specific connection.
```javascript app.js
import { serve } from "bknd/adapter/node";
import { sqlite } from "bknd/adapter/sqlite";
serve({
connection: sqlite({ url: "file:data.db" }),
});
```
### SQLite using LibSQL on Turso
If you want to use LibSQL on Turso, [sign up for a free account](https://turso.tech/), create a database and point your
connection object to your new database:
```json
{
"url": "libsql://your-database-url.turso.io",
"authToken": "your-auth-token"
}
If you're using [`bknd.config.*`](/extending/config), you can specify the connection on the exported object.
```typescript bknd.config.ts
import type { BkndConfig } from "bknd";
export default {
connection: { url: "file:data.db" },
} as const satisfies BkndConfig;
```
Throughout the documentation, it is assumed you use `bknd.config.ts` to define your connection.
## SQLite
### Using config object
The `sqlite` adapter is automatically resolved based on the runtime.
| Runtime | Adapter | In-Memory | File | Remote |
| ------- | ------- | --------- | ---- | ------ |
| Node.js | `node:sqlite` | ✅ | ✅ | ❌ |
| Bun | `bun:sqlite` | ✅ | ✅ | ❌ |
| Cloudflare Worker/Browser/Edge | `libsql` | 🟠 | 🟠 | ✅ |
The bundled version of the `libsql` connection only works with remote databases. However, you can pass in a `Client` from `@libsql/client`, see [LibSQL](#libsql) for more details.
```typescript bknd.config.ts
import type { BkndConfig } from "bknd";
// no connection is required, bknd will use a SQLite database in-memory
// this does not work on edge environments!
export default {} as const satisfies BkndConfig;
// or explicitly in-memory
export default {
connection: { url: ":memory:" },
} as const satisfies BkndConfig;
// or explicitly as a file
export default {
connection: { url: "file:<path/to/your/database.db>" },
} as const satisfies BkndConfig;
```
### LibSQL
Turso offers a SQLite-fork called LibSQL that runs a server around your SQLite database. The edge-version of the adapter is included in the bundle (remote only):
```typescript bknd.config.ts
import type { BkndConfig } from "bknd";
import { libsql } from "bknd/data";
export default {
connection: libsql({
url: "libsql://your-database-url.turso.io",
authToken: "your-auth-token",
}),
} as const satisfies BkndConfig;
```
If you wish to use LibSQL as file, in-memory or make use of [Embedded Replicas](https://docs.turso.tech/features/embedded-replicas/introduction), you have to pass in the `Client` from `@libsql/client`:
```typescript bknd.config.ts
import type { BkndConfig } from "bknd";
import { libsql } from "bknd/data";
import { createClient } from "@libsql/client";
export default {
connection: libsql(createClient({
url: "libsql://your-database-url.turso.io",
authToken: "your-auth-token",
})),
} as const satisfies BkndConfig;
```
### Cloudflare D1
Using the [Cloudflare Adapter](/integration/cloudflare), you can choose to use a D1 database binding. To do so, you only need to add a D1 database to your `wrangler.toml` and it'll pick up automatically.
@@ -63,7 +142,29 @@ export default serve<Env>({
});
```
### PostgreSQL
### SQLocal
To use bknd with `sqlocal` for a offline expierence, you need to install the `@bknd/sqlocal` package. You can do so by running the following command:
```bash
npm install @bknd/sqlocal
```
This package uses `sqlocal` under the hood. Consult the [sqlocal documentation](https://sqlocal.dallashoffman.com/guide/setup) for connection options:
```js
import { createApp } from "bknd";
import { SQLocalConnection } from "@bknd/sqlocal";
const app = createApp({
connection: new SQLocalConnection({
databasePath: ":localStorage:",
verbose: true,
})
});
```
## PostgreSQL
To use bknd with Postgres, you need to install the `@bknd/postgres` package. You can do so by running the following command:
```bash
@@ -72,7 +173,7 @@ npm install @bknd/postgres
You can connect to your Postgres database using `pg` or `postgres` dialects. Additionally, you may also define your custom connection.
#### Using `pg`
### Using `pg`
To establish a connection to your database, you can use any connection options available on the [`pg`](https://node-postgres.com/apis/client) package.
@@ -91,7 +192,7 @@ const config = {
serve(config);
```
#### Using `postgres`
### Using `postgres`
To establish a connection to your database, you can use any connection options available on the [`postgres`](https://github.com/porsager/postgres) package.
@@ -104,7 +205,7 @@ serve({
});
```
#### Using custom connection
### Using custom connection
Several Postgres hosting providers offer their own clients to connect to their database, e.g. suitable for serverless environments.
@@ -148,31 +249,8 @@ serve({
});
```
### SQLocal
To use bknd with `sqlocal` for a offline expierence, you need to install the `@bknd/sqlocal` package. You can do so by running the following command:
```bash
npm install @bknd/sqlocal
```
This package uses `sqlocal` under the hood. Consult the [sqlocal documentation](https://sqlocal.dallashoffman.com/guide/setup) for connection options:
```js
import { createApp } from "bknd";
import { SQLocalConnection } from "@bknd/sqlocal";
const app = createApp({
connection: new SQLocalConnection({
databasePath: ":localStorage:",
verbose: true,
})
});
```
### Custom Connection
Any bknd app instantiation accepts as connection either `undefined`, a connection object like
described above, or an class instance that extends from `Connection`:
## Custom Connection
Creating a custom connection is as easy as extending the `Connection` class and passing constructing a Kysely instance.
```ts
import { createApp } from "bknd";