Instatic数据库变更管理：迁移脚本与版本控制完全指南

Instatic数据库变更管理迁移脚本与版本控制完全指南【免费下载链接】InstaticInstatic is a modern self-hosted visual CMS - get it running in 1 minute项目地址: https://gitcode.com/GitHub_Trending/in/Instatic作为一款现代化的自托管可视化CMSInstatic提供了强大的数据库变更管理机制让团队协作和版本升级变得简单可靠。无论你是开发者还是系统管理员掌握Instatic的迁移脚本和版本控制策略都能让你轻松应对数据库结构变化确保数据安全与系统稳定。 双数据库引擎支持PostgreSQL与SQLiteInstatic最独特的设计之一是同时支持PostgreSQL和SQLite两种数据库引擎。这意味着你可以开发环境使用轻量级的SQLite无需安装额外服务生产环境切换到功能更强大的PostgreSQL支持多用户并发访问无缝切换只需修改DATABASE_URL配置代码无需任何改动这种双引擎架构在server/db/目录中体现得淋漓尽致server/db/client.ts- 统一的数据库客户端接口server/db/postgres.ts- PostgreSQL适配器server/db/sqlite.ts- SQLite适配器server/db/migrations-pg.ts- PostgreSQL迁移脚本server/db/migrations-sqlite.ts- SQLite迁移脚本 迁移脚本安全升级的保障Instatic的迁移系统遵循严格的双向同步原则确保两种数据库引擎的变更完全一致。迁移脚本结构每个迁移都有唯一的ID和对应的SQL语句例如添加AI运行时支持的迁移// PostgreSQL版本 { id: 007_ai_runtime, sql: create table if not exists ai_provider_credentials ( id text primary key, user_id text not null references users(id) on delete cascade, provider_id text not null, auth_mode text not null, display_label text not null, ciphertext bytea, iv bytea, // ... 更多字段 ) , } // SQLite版本对应相同ID { id: 007_ai_runtime, sql: create table if not exists ai_provider_credentials ( id text primary key, user_id text not null references users(id) on delete cascade, provider_id text not null, auth_mode text not null, display_label text not null, ciphertext blob, // bytea → blob iv blob, // ... 更多字段 ) , }自动迁移执行Instatic在启动时会自动检查并执行未应用的迁移// server/db/runMigrations.ts export async function runMigrations(db: DbClient, migrations: Migration[]): Promisevoid { await db.unsafe( create table if not exists schema_migrations ( id text primary key, applied_at text not null default current_timestamp ) ) for (const migration of migrations) { const { rows } await db{ id: string } select id from schema_migrations where id ${migration.id} if (rows.length 0) continue // 已应用的跳过 await db.transaction(async (tx) { await tx.unsafe(migration.sql) // 执行迁移 await txinsert into schema_migrations (id) values (${migration.id}) }) } }️ 数据库变更的黄金法则1. 永远使用增量迁移Instatic严格遵循只增不减的原则新增列使用ALTER TABLE ADD COLUMN新增表使用CREATE TABLE修改约束通过重建表实现SQLite限制绝不删除已发布的迁移永不修改或删除2. JSON列命名规范所有存储JSON数据的列必须以_json结尾-- 正确 ✅ settings_json jsonb not null default {} metadata_json text not null default {} -- 错误 ❌ settings jsonb not null default {} metadata text not null default {}这个约定让数据库适配器能够自动处理JSON序列化与反序列化无论底层是PostgreSQL的jsonb还是SQLite的text类型。3. 跨数据库兼容性Instatic的迁移系统处理了所有数据库差异特性PostgreSQLSQLiteInstatic解决方案JSON存储jsonb类型text类型_json后缀 自动转换时间戳timestamptztext(ISO 8601)统一使用ISO字符串布尔值booleaninteger(0/1)适配器自动转换大整数bigintintegerSQLite支持64位整数 实际迁移案例解析案例1添加定时发布功能当Instatic需要支持定时发布功能时迁移脚本需要在PostgreSQL中添加新列和状态-- migrations-pg.ts alter table data_rows add column if not exists scheduled_publish_at timestamptz; alter table data_rows drop constraint if exists data_rows_status_check; alter table data_rows add constraint data_rows_status_check check (status in (draft, published, unpublished, scheduled));在SQLite中重建表因为SQLite不支持修改CHECK约束-- migrations-sqlite.ts pragma defer_foreign_keys on; create table data_rows__migr006 ( -- 原有列... scheduled_publish_at text, -- 新增列 constraint data_rows_status_check check (status in (draft, published, unpublished, scheduled)) ); -- 复制数据、删除旧表、重命名新表...案例2添加布局系统添加新的系统表layouts时需要扩展data_tables.kind枚举-- PostgreSQL修改CHECK约束 alter table data_tables drop constraint data_tables_kind_check; alter table data_tables add constraint data_tables_kind_check check (kind in (postType, data, page, component, layout)); -- SQLite重建表因为涉及RESTRICT外键引用 { id: 017_layouts_system_table, disableForeignKeys: true, // 临时禁用外键检查 sql: create table data_tables__migr017 ( -- 表结构... constraint data_tables_kind_check check (kind in (postType, data, page, component, layout)) ); -- 数据迁移逻辑... , } 迁移开发最佳实践1. 创建新迁移的步骤# 1. 确定下一个迁移ID按顺序递增 # 当前最新是019下一个就是020 # 2. 在migrations-pg.ts中添加PostgreSQL版本 { id: 020_your_feature_name, sql: -- PostgreSQL特定的DDL语句 create table if not exists new_table ( id text primary key, data_json jsonb not null default {} ) , } # 3. 在migrations-sqlite.ts中添加对应的SQLite版本 { id: 020_your_feature_name, sql: -- SQLite特定的DDL语句 create table if not exists new_table ( id text primary key, data_json text not null default {} ) , } # 4. 运行测试确保兼容性 bun test src/__tests__/architecture/migration-parity.test.ts2. 处理数据库差异PostgreSQL的优势支持ALTER TABLE DROP CONSTRAINT支持ADD COLUMN IF NOT EXISTS原生jsonb类型提供JSON查询能力SQLite的限制不支持修改CHECK约束不支持删除列需要通过重建表来实现结构变更Instatic的迁移系统封装了这些差异开发者只需关注业务逻辑。3. 数据迁移策略对于需要修改现有数据的迁移Instatic采用事务性批量更新-- 在事务中执行数据迁移 begin; update users set step_up_auth_mode required where step_up_auth_mode is null; commit; 版本控制与协作工作流1. 迁移追踪表Instatic使用schema_migrations表追踪已应用的迁移create table if not exists schema_migrations ( id text primary key, applied_at text not null default current_timestamp )每次启动时系统会检查并执行所有未应用的迁移确保数据库处于最新状态。2. 团队协作策略开发环境每次拉取代码后自动应用新迁移测试环境在CI/CD流水线中验证迁移生产环境部署前备份部署后自动迁移3. 回滚策略虽然Instatic不提供自动回滚遵循只向前原则但提供了完整的备份恢复机制数据库快照迁移前的数据备份详细的迁移日志 迁移统计与监控Instatic的迁移系统包含丰富的监控能力指标说明监控位置迁移总数已定义的迁移数量migrations-pg.ts行数已应用迁移数据库中已执行的迁移schema_migrations表最近迁移最后应用的迁移ID和时间启动日志迁移耗时每个迁移的执行时间服务器日志 核心优势总结1.零停机升级迁移在事务中执行失败自动回滚确保数据一致性。2.双向兼容一套代码两种数据库开发生产环境一致。3.自动版本管理系统自动追踪迁移状态无需手动干预。4.安全第一所有迁移都是增量的绝不删除已有数据。5.团队友好清晰的迁移历史便于协作和问题排查。 未来展望Instatic的数据库迁移系统将持续演进迁移验证工具在应用前模拟执行预测潜在问题数据迁移预览显示将受影响的数据量迁移回放在测试环境重放生产环境的迁移序列性能优化大规模数据迁移的批处理和进度指示无论你是个人开发者还是企业团队Instatic的数据库变更管理系统都能为你提供可靠、安全、高效的数据库升级体验。通过严格的版本控制和双向兼容设计确保你的CMS系统能够平稳演进同时保护珍贵的内容数据。掌握Instatic的迁移脚本和版本控制你就掌握了系统长期稳定运行的关键。从简单的字段添加到复杂的表结构重构Instatic的迁移系统都能为你提供坚实的保障。【免费下载链接】InstaticInstatic is a modern self-hosted visual CMS - get it running in 1 minute项目地址: https://gitcode.com/GitHub_Trending/in/Instatic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考