Backstage 从 SQLite 切换到 PostgreSQL：生产部署的数据库切换实践-北京尧图网络

Backstage 从 SQLite 切换到 PostgreSQL生产部署的数据库切换实践【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 默认使用内存版 SQLite 作为后端数据库适合本地快速体验但无法用于生产。本文基于官方教程 switching-sqlite-postgres.md 的完整步骤结合当前仓库中的配置与连接器源码讲清如何为 Backstage 换上 PostgreSQL安装驱动、编写backend.database配置、覆盖连接池参数以及使用pluginDivisionMode: schema在单个数据库中隔离各插件数据。读完你可以独立完成一次从开发环境到生产环境可落地的数据库切换并理解每个配置项在源码中的真实作用。为什么默认是 SQLitebackstage/create-app生成的应用默认使用 SQLite 内存数据库因为它无需任何环境准备非常适合初次实验。本仓库根目录的 app-config.yaml 中就体现了这一默认配置backend: database: client: better-sqlite3 connection: :memory:Database Service 的文档说明了两点关键行为插件通过coreServices.database拿到一个挂接了knex客户端的服务用于持久化该服务按插件per plugin作用域避免不同插件之间的表名冲突如果完全未提供backend.database配置会自动得到一个进程级的内存 SQLite 数据库内容在服务重启后丢失。因此一旦你要把 Backstage 部署到生产环境、或希望本地开发具备持久化能力就应当切换到 PostgreSQL。Backstage 底层使用 Knex 这个 SQL 查询构造器数据库后端切换主要是换驱动改配置的事情。第一步为 backend 安装 PostgreSQL 驱动在 Backstage 仓库根目录执行# From your Backstage root directory yarn --cwd packages/backend add pg这条命令把pgnode-postgres 驱动安装到packages/backend这个承载后端运行的工作区包中。注意当前仓库的后端入口就位于 packages/backend 下教程给出的命令是相对该目录布局的。由于 Knex 抽象了驱动差异backend.database.client支持的取值在 packages/backend-defaults/config.d.ts 中有明确定义client: better-sqlite3 | sqlite3 | pg | embedded-postgres;即当前版本除了 PostgreSQL也支持嵌入式 Postgres 客户端但生产部署的主线路径仍是client: pg。第二步在 app-config.yaml 中添加 PostgreSQL 配置修改根目录的app-config.yaml把backend.database从 SQLite 替换为 PostgreSQL 配置backend: database: # highlight-remove-start client: better-sqlite3 connection: :memory: # highlight-remove-end # highlight-add-start # config options: https://node-postgres.com/apis/client client: pg connection: host: ${POSTGRES_HOST} port: ${POSTGRES_PORT} user: ${POSTGRES_USER} password: ${POSTGRES_PASSWORD} # https://node-postgres.com/features/ssl # you can set the sslmode configuration option via the PGSSLMODE environment variable # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) # ssl: # ca: # if you have a CA file and want to verify it you can uncomment this section # $file: file-path/ca/server.crt # highlight-add-end要点说明连接属性直接透传给 node-postgres 的 Client 配置host/port/user/password之外还可使用ssl等标准选项生产环境建议用${POSTGRES_*}环境变量注入机密Backstage 的配置系统支持这种插值写法教程中的highlight-add/remove注释行来自教程文档的差异高亮标记实际编写配置时保留新增部分、删除旧部分即可如果你本地还有app-config.local.yaml需要做同样的修改。本地开发既可以在启动前设置POSTGRES_环境变量也可以直接去掉${...}插值、写入真实值。配置完成后Backstage App 就以 PostgreSQL 作为 backing database 启动了。连接对象的其他写法与 role 支持connection除了字符串与逐字段对象外packages/backend-defaults/config.d.ts 中还定义了面向云环境的结构化形式例如 Azure 的 Entra 认证type: azuretokenCredential、Google Cloud SQLtype: cloudsqlinstance、AWS RDS IAM 认证type: rds需要aws-sdk/rds-signer。另外backend.database.role字段可以让连接在建立后切换为指定数据库角色。从源码看createPgDatabaseClient 在配置了role时会监听连接池的createSuccess事件并对每个新建的 pg Client 执行SET ROLE %Iif (role) { database.client.pool.on( createSuccess, async (_event: number, pgClient: Client) { const query format(SET ROLE %I, role); await pgClient.query(query); }, ); }这意味着 Backstage 可以用一个具备管理权限的账号建库建 schema但业务查询实际运行在一个受限角色之下是多账号权限隔离的实用手段。覆盖 PostgreSQL 连接池的默认配置如果你需要调整连接池例如提高并发上限或调整获取连接的超时可以通过knexConfig.pool覆盖教程给出的示例为backend: database: # highlight-remove-start client: better-sqlite3 connection: :memory: # highlight-remove-end # highlight-add-start # config options: https://node-postgres.com/apis/client client: pg connection: host: ${POSTGRES_HOST} port: ${POSTGRES_PORT} user: ${POSTGRES_USER} password: ${POSTGRES_PASSWORD} # you can set the sslmode configuration option via the PGSSLMODE environment variable # ssl: # ca: # if you have a CA file and want to verify it you can uncomment this section # $file: file-path/ca/server.crt # Refer to Tarn docs for default values on PostgreSQL pool configuration - https://github.com/Vincit/tarn.js knexConfig: pool: min: 3 max: 12 acquireTimeoutMillis: 60000 idleTimeoutMillis: 60000 # highlight-add-end连接池由 Knex 底层的 Tarn 实现min/max控制池中常备与最大连接数acquireTimeoutMillis是等待获取连接的超时idleTimeoutMillis是空闲连接的回收时间knexConfig是一个任意透传给 Knex 的 JSON 对象config.d.ts 注释特别提到debug与asyncStackTraces两个常用布尔项因此上面只是最常见的一类覆盖其他 Knex 选项同样可以这样传入。单数据库部署pluginDivisionMode 与 schemaPrefix默认情况下每个后端插件都会获得自己独立的逻辑数据库PostgreSQL database以保证不同插件之间的表名不冲突、职责相互隔离。如果你的托管服务限制你只能使用单个数据库可以在client: pg时启用pluginDivisionMode: schema让各插件在同一个数据库里获得各自独立的 PostgreSQL Schema 来代替独立数据库backend: database: client: pg pluginDivisionMode: schema # defaults to database, but changing this to schema means plugins will be given their own schema (in the specified/default database)若还需要避免与你数据库中已有的 schema 命名冲突可以为所有插件 schema 加前缀backend: database: client: pg pluginDivisionMode: schema schemaPrefix: backstage_ # defaults to empty string这会创建形如backstage_catalog、backstage_auth的 schema 名且前缀加插件 ID 的总长不得超过 63 字节。源码视角两种分离模式如何落地上述行为由 PostgreSQL 连接器 packages/backend-defaults/src/entrypoints/database/connectors/postgres.ts 中的computePgPluginConfig计算得出几个值得注意的实现细节默认值与取值pluginDivisionMode未配置时默认databasepostgres.ts#L734-L735配置声明中也只允许database | schema两种取值并注明该选项当前仅pg客户端支持database 模式下的库名未显式指定database时插件库名为backstage_plugin_pluginId形式的自动前缀名postgres.ts#L771-L774并且每个插件连接会带上application_name: backstage_plugin_pluginId方便在 PostgreSQL 侧通过pg_stat_activity区分来源schema 模式下的 schema 名与 search_pathschema 名为schemaPrefix pluginId连接器会将其设置到 Knex 连接的searchPath让插件 SQL 天然落在自己的 schema 内超过 63 字节时直接抛出配置错误而不是静默截断postgres.ts#L783-L792自动建库建 schemaensureExists默认为true插件首次取客户端时若目标数据库/ schema 不存在连接器会通过专门的管理连接池PgAdminPool执行创建且 DDL 操作被p-limit限制为串行避免并发建库竞态ensureSchemaExists默认为false可单独打开以只确保 schema 存在相关测试覆盖postgres.test.ts 中有pluginDivisionMode专项 describe 块覆盖了默认值、显式指定、以及 schema 模式下保留基础连接中database字段等场景可作为行为验证依据。已有部署启用 schemaPrefix 的警告:::caution[Existing Deployments]对已存在的部署启用schemaPrefix只会创建新的带前缀 schema而不会把原有无前缀 schema 中的数据迁移过来。该配置面向新部署或用于规避数据库中已有 schema 的命名冲突。如果你在现网实例上开启它旧数据仍留在原无前缀 schema 中而 Backstage 将使用新的带前缀 schema——相当于数据消失。:::配套能力迁移、跳过迁移与按插件覆盖切换数据库后有几个与backend.database直接相关的配套配置值得了解均见 config.d.ts迁移工作流根目录的 knexfile.js 注释说明了在插件中创建迁移的标准方式——yarn workspace package knex migrate:make name_with_underscores生成的迁移文件放在各插件自己的migrations目录由插件在初始化时执行例如 docs/backend-system/core-services/database.md 示例中的client.migrate.latestskipMigrations可跳过数据库迁移适合迁移已由外部流程管理的场景按插件覆盖plugin.pluginId可以为单个插件单独覆盖client、connection、ensureExists、knexConfig、role等。computePgPluginConfig中的合并逻辑是插件级配置优先、基础配置兜底例如某插件的client可独立于全局指定适合过渡期让个别插件暂留 SQLite 的灰度场景。小结切换清单与适用前提前提PostgreSQL 实例可达且账号具备建库/建 schema 权限或已手动创建并由ensureExists: false接管操作yarn --cwd packages/backend add pg→ 修改app-config.yaml的backend.databaseclient: pg 连接参数机密用环境变量注入→ 本地app-config.local.yaml同步修改可选增强knexConfig.pool调池、ssl配 TLS、role做角色降权、pluginDivisionMode: schemaschemaPrefix适配单数据库场景注意 63 字节限制与存量部署的数据迁移警告;验证启动后端后在 PostgreSQL 侧可见backstage_plugin_*数据库database 模式或schemaPrefixpluginIdschemaschema 模式插件连接在pg_stat_activity中的application_name亦带插件 ID便于定位与排查。按此流程Backstage 就从内存 SQLite 的实验形态进入PostgreSQL 支撑的可部署形态而 Knex 抽象保证了后续如更换其他受支持客户端时的配置级切换能力。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Backstage 从 SQLite 切换到 PostgreSQL：生产部署的数据库切换实践

相关推荐

Archon archon-post-review-to-pr 详解：将代码审查结果自动发布为 GitHub PR 评论的确定性 Agent 命令模板

低功耗SerDes架构级优化：CTOE动态偏移与前瞻DFE设计

CopilotKit × LangGraph TypeScript：用共享状态实现 UI 与 Agent 双向读写的实战解析

更多资讯

Arduino-ESP32 开发板选型完全指南：从 SoC 家族到官方开发板与第三方板卡

SoC硬件权衡：算力、带宽、功耗与生态的12种实战组合

Gymnasium + MuJoCo 连续控制环境从零跑通与避坑指南

深入浅出SysTick：从寄存器到裸机时基的完整实践

CAMEL 多智能体框架上手指南：装好环境，跑通两个 AI 的第一次协作

LeetCode-Go 题解：2166. Design Bitset —— 双数组懒翻转实现 O(1) 位集操作

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？