Quivr数据迁移：数据库迁移和版本升级

Quivr数据迁移：数据库迁移和版本升级

【免费下载链接】quivr Quivr，作为你的第二大脑，充分利用生成式人工智能（Generative AI）的力量成为你的个人智能助手！ 项目地址: https://gitcode.com/GitHub_Trending/qui/quivr

概述

在Quivr项目的迭代开发过程中，数据库迁移和版本升级是至关重要的环节。本文详细介绍了Quivr的数据库架构、迁移策略、版本管理以及实际操作指南，帮助开发者顺利完成数据迁移和系统升级。

Quivr数据库架构

Quivr采用Supabase作为后端数据库解决方案，使用PostgreSQL作为核心数据库引擎，并集成了向量扩展以支持AI功能。

核心数据表结构

主要数据表说明

表名	描述	关键字段
brains	大脑核心表	brain_id, name, model, brain_type
vectors	向量存储表	id, content, embedding
knowledge	知识文件表	id, file_name, url, brain_id
chats	聊天会话表	chat_id, user_id, chat_name
users	用户信息表	id, email

迁移策略与版本管理

迁移文件命名规范

Quivr使用时间戳格式的迁移文件命名：

-- 示例：20240103173626_init.sql
-- 格式：YYYYMMDDHHMMSS_description.sql

版本升级流程

实际操作指南

1. 环境准备

确保已安装Supabase CLI并配置正确的环境变量：

# 检查Supabase CLI版本
supabase -v

# 初始化Supabase项目
supabase init

# 启动本地开发环境
supabase start

2. 数据库备份

在执行迁移前务必进行完整备份：

-- 使用pg_dump进行完整备份
pg_dump -h localhost -p 54322 -U postgres -d postgres -F c -b -v -f quivr_backup_$(date +%Y%m%d).dump

-- 仅备份数据（不含结构）
pg_dump -h localhost -p 54322 -U postgres -d postgres -a -F c -f quivr_data_$(date +%Y%m%d).dump

3. 执行迁移

使用Supabase CLI执行迁移脚本：

# 查看待执行的迁移
supabase migration list

# 执行所有待处理的迁移
supabase migration up

# 执行特定迁移
supabase migration up --version 20240103173626

4. 常见迁移场景

场景一：添加新表

-- 示例：添加新功能表
CREATE TABLE IF NOT EXISTS public.new_feature_table (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    feature_name TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 添加索引
CREATE INDEX IF NOT EXISTS idx_new_feature_name ON public.new_feature_table(feature_name);

场景二：修改现有表结构

-- 添加新列
ALTER TABLE public.brains 
ADD COLUMN IF NOT EXISTS new_config JSONB DEFAULT '{}'::jsonb;

-- 修改列类型
ALTER TABLE public.user_settings 
ALTER COLUMN models TYPE JSONB USING models::jsonb;

-- 添加约束
ALTER TABLE public.knowledge
ADD CONSTRAINT knowledge_file_check 
CHECK ((file_name IS NOT NULL AND url IS NULL) OR (file_name IS NULL AND url IS NOT NULL));

场景三：数据迁移和转换

-- 迁移旧数据到新表
INSERT INTO public.new_vectors (id, content, metadata, embedding)
SELECT 
    gen_random_uuid(),
    content,
    metadata,
    embedding
FROM public.vectors_old
WHERE NOT EXISTS (
    SELECT 1 FROM public.vectors v WHERE v.content = vectors_old.content
);

-- 更新关联关系
UPDATE public.brains_vectors bv
SET vector_id = nv.id
FROM public.new_vectors nv
WHERE bv.vector_id::text = nv.metadata->>'old_id';

5. 回滚策略

# 回滚到上一个版本
supabase migration down

# 回滚到特定版本
supabase migration down --version 20240103173625

# 完全重置数据库（谨慎使用）
supabase db reset

版本兼容性处理

向后兼容性确保

-- 使用IF NOT EXISTS避免重复创建
CREATE TABLE IF NOT EXISTS public.compatible_table (...);

-- 使用ALTER TABLE IF EXISTS
ALTER TABLE IF EXISTS public.old_table RENAME TO new_table;

-- 条件性添加列
DO $$ 
BEGIN
    IF NOT EXISTS (
        SELECT 1 FROM information_schema.columns 
        WHERE table_name = 'brains' AND column_name = 'new_column'
    ) THEN
        ALTER TABLE public.brains ADD COLUMN new_column TEXT;
    END IF;
END $$;

数据验证脚本

-- 迁移后数据完整性验证
SELECT 
    (SELECT COUNT(*) FROM public.brains) as brain_count,
    (SELECT COUNT(*) FROM public.vectors) as vector_count,
    (SELECT COUNT(*) FROM public.knowledge) as knowledge_count,
    (SELECT COUNT(*) FROM public.chats) as chat_count;

-- 检查外键约束
SELECT 
    tc.table_name, 
    kcu.column_name, 
    ccu.table_name AS foreign_table_name,
    ccu.column_name AS foreign_column_name 
FROM 
    information_schema.table_constraints AS tc 
    JOIN information_schema.key_column_usage AS kcu ON tc.constraint_name = kcu.constraint_name
    JOIN information_schema.constraint_column_usage AS ccu ON ccu.constraint_name = tc.constraint_name
WHERE tc.constraint_type = 'FOREIGN KEY';

最佳实践

1. 迁移脚本编写规范

• 每个迁移脚本应该是幂等的（idempotent）
• 使用事务确保数据一致性
• 包含详细的注释说明变更目的
• 提供回滚操作的SQL语句

2. 测试策略

# 在测试环境验证迁移
supabase start --env-file .env.test
supabase migration up

# 运行数据完整性测试
psql -h localhost -p 54322 -U postgres -d postgres -f test_migration_integrity.sql

3. 监控和日志

-- 创建迁移日志表
CREATE TABLE IF NOT EXISTS public.migration_audit (
    id SERIAL PRIMARY KEY,
    migration_name VARCHAR(255) NOT NULL,
    executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    status VARCHAR(50) NOT NULL,
    error_message TEXT
);

-- 记录迁移执行情况
INSERT INTO public.migration_audit (migration_name, status)
VALUES ('20240103173626_init', 'completed');

故障排除

常见问题及解决方案

问题	原因	解决方案
迁移失败	外键约束冲突	检查数据完整性，临时禁用约束
版本冲突	迁移文件顺序错误	检查时间戳顺序，重新排序
性能问题	大数据量迁移	分批次处理，添加索引优化
权限错误	数据库用户权限不足	检查用户角色和权限设置

紧急恢复流程

总结

Quivr的数据库迁移和版本升级是一个系统性的工程，需要严谨的规划、测试和执行。通过本文介绍的策略和实践，开发者可以：

1. 理解架构：掌握Quivr的数据库设计和数据流
2. 制定计划：根据业务需求制定合适的迁移策略
3. 执行迁移：使用标准化流程完成数据迁移
4. 确保质量：通过验证和监控保证迁移成功
5. 处理异常：具备应对各种异常情况的能力

遵循这些最佳实践，可以确保Quivr系统的平稳升级和数据的安全迁移，为项目的持续发展奠定坚实的基础。

【免费下载链接】quivr Quivr，作为你的第二大脑，充分利用生成式人工智能（Generative AI）的力量成为你的个人智能助手！ 项目地址: https://gitcode.com/GitHub_Trending/qui/quivr