gofr-dev/gofr · error

failed to execute migration query

Error message

failed to execute migration query

What it means

errExecuteQuery is the sentinel error for the SurrealDB migrator in GoFr: 'failed to execute migration query'. It is returned by checkAndCreateMigrationTable when a query needed to create/ensure the migration table in SurrealDB fails, and it is embedded (%w) into wrapped errors at the call site so callers can errors.Is against it. It signals that a DDL/setup query sent to SurrealDB was rejected or the connection failed.

Source

Thrown at pkg/gofr/migration/surreal_db.go:13

package migration

import (
	"context"
	"errors"
	"fmt"
	"math"
	"time"

	"gofr.dev/pkg/gofr/container"
)

var errExecuteQuery = errors.New("failed to execute migration query")

type surrealDS struct {
	client SurrealDB
}

func (s surrealDS) Query(ctx context.Context, query string, vars map[string]any) ([]any, error) {
	return s.client.Query(ctx, query, vars)
}

func (s surrealDS) CreateNamespace(ctx context.Context, namespace string) error {
	return s.client.CreateNamespace(ctx, namespace)
}

func (s surrealDS) CreateDatabase(ctx context.Context, database string) error {
	return s.client.CreateDatabase(ctx, database)
}

func (s surrealDS) DropNamespace(ctx context.Context, namespace string) error {

View on GitHub (pinned to 187eb24962)

Solutions

1. Check SurrealDB connectivity, endpoint URL and credentials in the container config.
2. Verify the namespace and database are configured/selected for the SurrealDB datasource.
3. Test the migration-table queries manually against your SurrealDB version and upgrade/downgrade SurrealDB or the driver if the DDL is rejected.
4. Use errors.Is(err, errExecuteQuery) (or match the message) to confirm which stage failed, then inspect the wrapped inner error for details.

Example fix

// before: SurrealDB config missing namespace/database
datasource.SurrealDB{Endpoint: "ws://localhost:8000"}
// after
err := db.Use(ctx, "test", "test") // ensure ns/db selected before migrations
if err != nil {
	log.Fatalf("select ns/db: %v", err)
}

// pre-check SurrealDB reachability
if err := db.Health(ctx); err != nil {
	return fmt.Errorf("surrealdb unreachable: %w", err)
}

if s.SurrealDB == nil {
	return errors.New("surrealdb datasource not configured")
}

if err := surrealMigr.checkAndCreateMigrationTable(c); err != nil {
	if errors.Is(err, errExecuteQuery) {
		// setup-stage failure: log full error chain
		log.Printf("migration table setup failed: %v", err)
	}
	return err
}

When it happens

Trigger: s.SurrealDB.Query(ctx, q, nil) returns an error for any of getMigrationTableQueries() during checkAndCreateMigrationTable — e.g. SurrealDB unreachable, auth failure, or malformed DDL for the target SurrealDB version.

Common situations: SurrealDB instance down or wrong endpoint/credentials; SurrealDB version that doesn't accept the migration-table queries; namespace/database not selected in the connection config.

Related errors

• surrealdb: %w
• query error
• sql: %w
• %w: %s: %w
• regex pattern '^...$' is not supported, use mux patterns ins

AI-assisted analysis of gofr-dev/gofr@187eb24962 (2026-09-01). Data as JSON: /api/errors/ceba17d01b5cd66a. Report an issue: GitHub.