gh-whamp-whamp-claude-tools-pocketbase-plugin/skills/pocketbase/references/go/go_console_commands.md

go_console_commands - Go Extensions

Overview

PocketBase exposes Cobra-based console commands that you can extend from either Go extensions or JavaScript pb_hooks. Use them for background jobs, data migrations, administrative helpers, or build-time automation. Review go_overview.md for extension setup and wiring custom commands into the root CLI.

---

Data Migration Commands

Import/export workflows benefit from running inside PocketBase where you can wrap operations in transactions, reuse the ORM, and uphold access rules. At a minimum:

1. Register a command on $app.RootCmd() (Go) or $app.rootCmd (JS hooks).
2. Accept flags for batch size, dry-run execution, and optional upsert keys.
3. Wrap writes in app.RunInTransaction(...) when consistency matters.
4. Use app.FindCollectionByNameOrId and core.NewRecord (Go) or new Record(collection) (JS) to construct records.
5. Stream large payloads in chunks to keep memory stable and close files promptly.

Go skeleton

package migrations

import (
    "encoding/json"
    "os"

    "github.com/pocketbase/pocketbase"
    "github.com/pocketbase/pocketbase/core"
    "github.com/spf13/cobra"
)

func Register(app *pocketbase.PocketBase) {
    var batchSize int

    cmd := &cobra.Command{
        Use:   "data:import <collection> <file>",
        Short: "Import records from a JSON file",
        Args:  cobra.ExactArgs(2),
        RunE: func(cmd *cobra.Command, args []string) error {
            collectionName, filePath := args[0], args[1]
            payload, err := os.ReadFile(filePath)
            if err != nil {
                return err
            }
            var rows []map[string]any
            if err := json.Unmarshal(payload, &rows); err != nil {
                return err
            }

            return app.RunInTransaction(func(txApp core.App) error {
                collection, err := txApp.FindCollectionByNameOrId(collectionName)
                if err != nil {
                    return err
                }
                for idx, row := range rows {
                    record := core.NewRecord(collection)
                    record.Load(row)
                    if err := txApp.Save(record); err != nil {
                        return err
                    }
                    if batchSize > 0 && (idx+1)%batchSize == 0 {
                        cmd.Printf("Imported %d records\n", idx+1)
                    }
                }
                return nil
            })
        },
    }

    cmd.Flags().IntVar(&batchSize, "batch", 500, "Records per transaction chunk")
    app.RootCmd().AddCommand(cmd)
}

Adapt the skeleton with streaming readers, upsert logic, or batch logging as needed. For a JavaScript equivalent, see the example in Data Migration Workflows.

---

Automation Notes

• Prefer purpose-built commands (data:import, data:export) to avoid confusion with the built-in migrate schema command.
• Add validation flags (e.g., --dry-run, --allow-save-no-validate) to make commands safer in production.
• Consider registering complementary commands for exporting manifests, truncating collections, or rehydrating relation fields.
• If you need to expose the same logic via HTTP, see go_routing.md for admin-only endpoints that invoke the same import/export routines under the hood.