PocketBase迁移文件未生效问题分析与解决方案

问题背景

在使用PocketBase进行项目开发时，开发者可能会遇到迁移文件(pb_migrations目录下的JS文件)未被正确应用的情况。特别是在更换开发环境或迁移项目时，即使迁移文件存在且内容正确，数据库结构变更却未反映在实际运行环境中。

核心原因分析

经过深入排查，发现这类问题通常源于以下两个关键因素：

1. 执行环境配置不当：当使用自定义的Go程序(main.go)启动PocketBase而非直接使用预构建的可执行文件时，默认不会启用JSVM(JavaScript虚拟机)功能，而迁移文件的执行恰恰依赖于此功能。

2. 迁移机制理解偏差：PocketBase提供了两种迁移方式(Go迁移和JS迁移)，开发者需要明确当前项目使用的是哪种机制，并确保运行环境支持相应的执行方式。

详细解决方案

方案一：启用JSVM支持

对于使用自定义Go程序启动PocketBase的情况，需要在main.go中显式启用JSVM插件支持：

import (
    "github.com/pocketbase/pocketbase"
    "github.com/pocketbase/pocketbase/plugins/jsvm"
)

func main() {
    app := pocketbase.New()

    // 加载JSVM插件
    jsvm.MustRegister(app, jsvm.Config{
        // 可选的Hooks目录配置
        HooksWatch: true,
        // 可选的Hooks目录路径
        HooksDir: "pb_hooks",
        // 可选的迁移目录路径
        MigrationsDir: "pb_migrations",
    })

    if err := app.Start(); err != nil {
        log.Fatal(err)
    }
}

方案二：使用Go迁移替代JS迁移

对于更可控的迁移方案，建议采用Go原生迁移方式：

1. 创建迁移目录结构：

migrations/
├── 20230920_123456_init.go
└── ...

2. 示例迁移文件内容：

package migrations

import (
    "github.com/pocketbase/dbx"
    "github.com/pocketbase/pocketbase/daos"
    m "github.com/pocketbase/pocketbase/migrations"
)

func init() {
    m.Register(func(db dbx.Builder) error {
        dao := daos.New(db)
        
        // 创建集合
        collection := &models.Collection{
            Name: "Clients",
            Type: models.CollectionTypeBase,
            Schema: schema.NewSchema(
                &schema.SchemaField{
                    Name:     "nombre",
                    Type:     schema.FieldTypeText,
                    Required: false,
                },
                // 其他字段...
            ),
        }

        return dao.SaveCollection(collection)
    }, func(db dbx.Builder) error {
        // 回滚逻辑
        dao := daos.New(db)
        collection, _ := dao.FindCollectionByNameOrId("Clients")
        return dao.DeleteCollection(collection)
    })
}

最佳实践建议

1. 环境一致性：在项目迁移时，确保同时备份pb_data目录或明确记录数据库变更历史。

2. 迁移策略选择：

   • 简单项目：直接使用预构建的PocketBase可执行文件和JS迁移
   • 复杂项目：推荐使用Go迁移方案，便于版本控制和团队协作

3. 验证机制：每次迁移后，通过SQLite命令行工具验证表结构是否按预期变更：

sqlite3 pb_data/data.db '.tables'
sqlite3 pb_data/data.db 'PRAGMA table_info(Clients)'

4. 开发流程：建议将pb_migrations目录纳入版本控制，但pb_data目录应加入.gitignore。

通过理解PocketBase的迁移机制并正确配置执行环境，开发者可以有效避免迁移文件未生效的问题，确保数据库结构变更按预期执行。