{"record":{"id":"ceba17d01b5cd66a","repo":"gofr-dev/gofr","slug":"failed-to-execute-migration-query","errorCode":null,"errorMessage":"failed to execute migration query","messagePattern":"failed to execute migration query","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/gofr/migration/surreal_db.go","lineNumber":13,"sourceCode":"package migration\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"math\"\n\t\"time\"\n\n\t\"gofr.dev/pkg/gofr/container\"\n)\n\nvar errExecuteQuery = errors.New(\"failed to execute migration query\")\n\ntype surrealDS struct {\n\tclient SurrealDB\n}\n\nfunc (s surrealDS) Query(ctx context.Context, query string, vars map[string]any) ([]any, error) {\n\treturn s.client.Query(ctx, query, vars)\n}\n\nfunc (s surrealDS) CreateNamespace(ctx context.Context, namespace string) error {\n\treturn s.client.CreateNamespace(ctx, namespace)\n}\n\nfunc (s surrealDS) CreateDatabase(ctx context.Context, database string) error {\n\treturn s.client.CreateDatabase(ctx, database)\n}\n\nfunc (s surrealDS) DropNamespace(ctx context.Context, namespace string) error {","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/gofr-dev/gofr/blob/187eb24962502e91f1fee856230670958b66e89c/pkg/gofr/migration/surreal_db.go#L1-L31","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check SurrealDB connectivity, endpoint URL and credentials in the container config.","Verify the namespace and database are configured/selected for the SurrealDB datasource.","Test the migration-table queries manually against your SurrealDB version and upgrade/downgrade SurrealDB or the driver if the DDL is rejected.","Use errors.Is(err, errExecuteQuery) (or match the message) to confirm which stage failed, then inspect the wrapped inner error for details."],"exampleFix":"// before: SurrealDB config missing namespace/database\ndatasource.SurrealDB{Endpoint: \"ws://localhost:8000\"}\n// after\nerr := db.Use(ctx, \"test\", \"test\") // ensure ns/db selected before migrations\nif err != nil {\n\tlog.Fatalf(\"select ns/db: %v\", err)\n}","handlingStrategy":"try-catch","validationCode":"// pre-check SurrealDB reachability\nif err := db.Health(ctx); err != nil {\n\treturn fmt.Errorf(\"surrealdb unreachable: %w\", err)\n}","typeGuard":"if s.SurrealDB == nil {\n\treturn errors.New(\"surrealdb datasource not configured\")\n}","tryCatchPattern":"if err := surrealMigr.checkAndCreateMigrationTable(c); err != nil {\n\tif errors.Is(err, errExecuteQuery) {\n\t\t// setup-stage failure: log full error chain\n\t\tlog.Printf(\"migration table setup failed: %v\", err)\n\t}\n\treturn err\n}","preventionTips":["Select namespace and database before running migrations.","Use a SurrealDB role with table-definition permissions.","Pin and test SurrealDB server version against the driver in CI.","Smoke-test the DDL queries on a scratch instance before deploying."],"tags":["surrealdb","migration","database","gofr"],"backgroundTag":"migration-table-setup-failed","analyzedSha":"187eb24962502e91f1fee856230670958b66e89c","analyzedAt":"2026-09-01T20:34:54.554Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}