⚡

Bknd数据库配置Skill bknd-database-provision

这个技能用于为Bknd应用程序配置生产数据库，支持多种数据库类型如SQLite、PostgreSQL、Turso、Cloudflare D1、Neon、Supabase和Xata，提供UI和代码两种配置模式，适用于服务器、边缘计算和云服务部署场景，涵盖设置、连接测试和常见问题解决，帮助开发人员高效管理数据库连接和部署。关键词：Bknd数据库配置，生产数据库，SQLite，PostgreSQL，无服务器部署，数据库连接，DevOps，后端开发

后端开发 0 次安装 0 次浏览 更新于 3/8/2026

名称: bknd-database-provision 描述: 当为Bknd设置生产数据库时使用。涵盖SQLite文件、LibSQL/Turso、Cloudflare D1、PostgreSQL、Neon、Supabase和Xata配置。

配置生产数据库

为您的Bknd应用程序设置和配置生产数据库。

先决条件

  • 已定义架构的Bknd应用程序
  • 所选数据库提供商账户（用于云数据库）
  • 存储连接凭据的环境

何时使用UI模式

  • 通过提供商仪表板创建数据库（Turso、Neon、Cloudflare、Supabase）
  • 管理数据库设置和访问令牌
  • 查看数据库指标和日志

何时使用代码模式

  • 在Bknd中配置数据库连接
  • 用于数据库创建的CLI命令
  • 架构同步和迁移

数据库选择指南

数据库 最适用场景 平台兼容性 成本
SQLite文件 VPS、Docker、单服务器 Node.js、Bun 免费
LibSQL/Turso 无服务器、边缘、全球分布 所有平台 免费层
Cloudflare D1 Cloudflare Workers 仅Cloudflare 免费层
PostgreSQL 复杂查询、事务 VPS、Docker 自托管
Neon 无服务器Postgres Vercel、Lambda 免费层
Supabase Postgres + 额外功能 任何 免费层
Xata 无服务器 + 搜索 任何 免费层

SQLite文件（VPS/Docker）

最适用场景： 具有完全控制的单服务器部署

步骤1：配置连接

// bknd.config.ts
export default {
  app: (env) => ({
    connection: {
      url: env.DB_URL ?? "file:data.db",  // 相对于当前工作目录
    },
  }),
};

步骤2：设置环境变量

# 相对路径（项目目录）
DB_URL=file:data.db

# 绝对路径（生产推荐）
DB_URL=file:/var/data/myapp/bknd.db

步骤3：确保目录存在

mkdir -p /var/data/myapp

Docker卷

# docker-compose.yml
services:
  bknd:
    volumes:
      - bknd-data:/app/data
    environment:
      - DB_URL=file:/app/data/bknd.db

volumes:
  bknd-data:

LibSQL / Turso

最适用场景： 无服务器、边缘部署、全球分布

步骤1：安装Turso CLI

# macOS/Linux
curl -sSfL https://get.tur.so/install.sh | bash

# 认证
turso auth login

步骤2：创建数据库

# 创建数据库
turso db create my-bknd-db

# 可选：指定区域
turso db create my-bknd-db --location lax  # 洛杉矶

步骤3：获取连接详情

# 获取连接URL
turso db show my-bknd-db --url
# 输出：libsql://my-bknd-db-username.turso.io

# 创建认证令牌
turso db tokens create my-bknd-db
# 输出：eyJhbGciOi...

步骤4：配置Bknd

// bknd.config.ts
export default {
  app: (env) => ({
    connection: {
      url: env.DB_URL,       // libsql://...
      authToken: env.DB_TOKEN,
    },
  }),
};

步骤5：设置环境变量

DB_URL=libsql://my-bknd-db-username.turso.io
DB_TOKEN=eyJhbGciOi...

Turso位置

常见区域：ams（阿姆斯特丹）、fra（法兰克福）、lax（洛杉矶）、lhr（伦敦）、nrt（东京）、syd（悉尼）

turso db locations  # 列出所有区域

Cloudflare D1

最适用场景： Cloudflare Workers部署

步骤1：创建D1数据库

wrangler d1 create my-bknd-db

输出：

创建了D1数据库 'my-bknd-db'
database_name = "my-bknd-db"
database_id = "abc123-def456-..."

步骤2：配置wrangler.toml

name = "my-bknd-app"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[d1_databases]]
binding = "DB"
database_name = "my-bknd-db"
database_id = "abc123-def456-..."

步骤3：配置Bknd适配器

// src/index.ts
import { hybrid, type CloudflareBkndConfig } from "bknd/adapter/cloudflare";
import { d1Sqlite } from "bknd/adapter/cloudflare";

export default hybrid<CloudflareBkndConfig>({
  app: (env) => ({
    connection: d1Sqlite({ binding: env.DB }),
    isProduction: true,
  }),
});

D1 CLI命令

# 列出数据库
wrangler d1 list

# 执行SQL（本地开发）
wrangler d1 execute my-bknd-db --local --command "SELECT * FROM posts"

# 执行SQL（生产）
wrangler d1 execute my-bknd-db --command "SELECT * FROM posts"

# 导出备份
wrangler d1 backup create my-bknd-db

PostgreSQL（自托管）

最适用场景： 复杂查询、大型数据集、现有Postgres基础设施

步骤1：安装适配器

npm install postgres
# 或
npm install pg

步骤2：配置连接

使用 postgres（推荐）：

import { PostgresJsConnection } from "bknd/adapter/postgres";

export default {
  app: (env) => ({
    connection: new PostgresJsConnection({
      connectionString: env.DATABASE_URL,
    }),
  }),
};

使用 pg：

import { PgPostgresConnection } from "bknd/adapter/postgres";

export default {
  app: (env) => ({
    connection: new PgPostgresConnection({
      connectionString: env.DATABASE_URL,
    }),
  }),
};

步骤3：设置连接字符串

DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require

Neon（无服务器Postgres）

最适用场景： Vercel、无服务器、自动扩展Postgres

步骤1：在neon.tech创建项目

  1. 在 neon.tech 注册
  2. 创建新项目
  3. 从仪表板复制连接字符串

步骤2：安装Neon方言

npm install kysely-neon

步骤3：配置连接

import { createCustomPostgresConnection } from "bknd";
import { NeonDialect } from "kysely-neon";

const neon = createCustomPostgresConnection("neon", NeonDialect);

export default {
  app: (env) => ({
    connection: neon({
      connectionString: env.NEON_DATABASE_URL,
    }),
  }),
};

步骤4：设置环境变量

NEON_DATABASE_URL=postgres://user:password@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require

Supabase

最适用场景： 全功能Postgres附加功能（认证、存储、实时）

步骤1：在supabase.com创建项目

  1. 在 supabase.com 注册
  2. 创建新项目
  3. 转到设置 > 数据库 > 连接字符串

步骤2：获取直接连接字符串

使用"直接连接"（非连接池）用于Bknd：

postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres

步骤3：配置连接

export default {
  app: (env) => ({
    connection: {
      url: env.SUPABASE_DB_URL,
    },
  }),
};

步骤4：设置环境变量

SUPABASE_DB_URL=postgresql://postgres:your-password@db.abcdefgh.supabase.co:5432/postgres

Xata

最适用场景： 无服务器Postgres带内置搜索

步骤1：在xata.io创建数据库

  1. 在 xata.io 注册
  2. 创建工作空间和数据库

步骤2：安装Xata方言

npm install @xata.io/kysely

步骤3：配置连接

import { createCustomPostgresConnection } from "bknd";
import { XataDialect } from "@xata.io/kysely";

const xata = createCustomPostgresConnection("xata", XataDialect);

export default {
  app: (env) => ({
    connection: xata({
      apiKey: env.XATA_API_KEY,
      workspace: "your-workspace",
      database: "your-database",
    }),
  }),
};

架构同步

配置数据库后，Bknd在第一次请求时自动同步架构。手动控制：

# 干运行（预览更改）
npx bknd sync --dry-run

# 应用更改
npx bknd sync

# 强制同步（谨慎使用）
npx bknd sync --force

连接测试

验证连接

// test-connection.ts
import { app } from "bknd";

const bknd = app({
  connection: {
    url: process.env.DB_URL!,
    authToken: process.env.DB_TOKEN,
  },
});

async function test() {
  await bknd.build();
  console.log("连接成功！");
  console.log("实体：", Object.keys(bknd.modules.data.entities));
  process.exit(0);
}

test().catch((e) => {
  console.error("连接失败：", e);
  process.exit(1);
});

运行：

npx tsx test-connection.ts

常见陷阱

“连接被拒绝” 或 “ECONNREFUSED”

问题： 无法连接到数据库

解决方法：

  • 验证连接URL格式
  • 检查防火墙/安全组规则
  • 确保数据库运行中
  • 对于云服务：验证IP白名单包括您的服务器

“需要认证令牌”（LibSQL/Turso）

问题： 缺少或无效的认证令牌

解决方法：

# 生成新令牌
turso db tokens create my-bknd-db

# 设置环境变量
export DB_TOKEN="eyJhbGciOi..."

“D1绑定未找到”

问题： env.DB 未定义 在Cloudflare Workers中

解决方法： 检查wrangler.toml绑定名称匹配代码：

[[d1_databases]]
binding = "DB"  # 必须匹配 env.DB

“需要SSL”（PostgreSQL）

问题： 连接失败无SSL

解决方法： 添加 ?sslmode=require 到连接字符串：

DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require

“未知数据库” 或 “数据库不存在”

问题： 数据库未创建

解决方法：

# Turso
turso db create my-bknd-db

# D1
wrangler d1 create my-bknd-db

# PostgreSQL
createdb my-bknd-db

架构同步失败

问题： 迁移在生产数据库失败

解决方法：

# 先预览更改
npx bknd sync --dry-run

# 如果卡住，使用 --force（可能导致数据丢失！）
npx bknd sync --force --drop

从开发迁移

导出开发数据

# SQLite
sqlite3 data.db .dump > backup.sql

# 使用API
curl http://localhost:3000/api/data/posts > posts.json

导入到生产

# 通过种子函数（推荐）
# 参考bknd-seed-data技能

# 直接SQL（仅SQLite到SQLite）
cat backup.sql | turso db shell my-bknd-db

应该与不应该

应该：

  • 为无服务器使用云数据库（Turso、D1、Neon）
  • 在环境变量中存储凭据
  • 部署前测试连接
  • 为PostgreSQL连接使用SSL
  • 保持认证令牌安全
  • 为生产数据启用备份

不应该：

  • 在无服务器/边缘中使用基于文件的SQLite
  • 在源代码中硬编码凭据
  • 跨环境共享认证令牌
  • 跳过连接测试
  • 没有备份时使用 --force --drop
  • 直接暴露数据库到互联网（使用Bknd API）

相关技能

  • bknd-deploy-hosting - 部署到托管平台
  • bknd-production-config - 生产安全设置
  • bknd-env-config - 环境变量设置
  • bknd-seed-data - 用初始数据填充数据库
  • bknd-local-setup - 本地开发（预生产）