{"record":{"id":"3c4c2a4e3ff1b176","repo":"ory/hydra","slug":"driver-t-does-not-support-online-restore","errorCode":null,"errorMessage":"driver %T does not support online restore","messagePattern":"driver %T does not support online restore","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"oryx/popx/migrator.go","lineNumber":103,"sourceCode":"// pop wraps the modernc.org/sqlite driver with otelsql for tracing; we\n// unwrap via the otelsql Raw() accessor before reaching the driver-specific\n// NewRestore method on the underlying *sqlite.conn.\nfunc restoreSQLiteOnline(ctx context.Context, db *sql.DB, srcPath string) error {\n\tconn, err := db.Conn(ctx)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"failed to acquire sql.Conn for restore\")\n\t}\n\tdefer func() { _ = conn.Close() }()\n\n\treturn conn.Raw(func(driverConn any) error {\n\t\tif w, ok := driverConn.(interface{ Raw() driver.Conn }); ok {\n\t\t\tdriverConn = w.Raw()\n\t\t}\n\t\trestorer, ok := driverConn.(interface {\n\t\t\tNewRestore(srcUri string) (*moderncsqlite.Backup, error)\n\t\t})\n\t\tif !ok {\n\t\t\treturn errors.Errorf(\"driver %T does not support online restore\", driverConn)\n\t\t}\n\t\t// See: https://sqlite.org/backup.html .\n\t\tbackup, err := restorer.NewRestore(srcPath)\n\t\tif err != nil {\n\t\t\treturn errors.Wrap(err, \"NewRestore failed\")\n\t\t}\n\t\t// Step(-1) copies all remaining pages in one call.\n\t\tfor {\n\t\t\tmore, stepErr := backup.Step(-1)\n\t\t\tif stepErr != nil {\n\t\t\t\t_ = backup.Finish()\n\t\t\t\treturn errors.Wrap(stepErr, \"backup.Step failed\")\n\t\t\t}\n\t\t\tif !more {\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t\treturn errors.Wrap(backup.Finish(), \"backup.Finish failed\")","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/ory/hydra/blob/4174065ffb052799890f7480f5360a877a67ffc1/oryx/popx/migrator.go#L85-L121","documentation":"Inside conn.Raw, the code type-asserts the unwrapped driver connection to an interface with NewRestore(srcUri string) (*moderncsqlite.Backup, error). If the concrete driver does not implement online backup, errors.Errorf produces 'driver %T does not support online restore', reporting the actual driver type.","triggerScenarios":"Running the SQLite online-restore path while connected via a driver whose connection is neither *sqlite.conn nor otherwise implementing NewRestore — e.g. a pure-Go alternative driver, a wrapped driver not unwrappable via Raw(), or mattn/go-sqlite3.","commonSituations":"Swapping the SQLite driver (cgo vs modernc), stacking extra driver wrappers that break the Raw() unwrapping chain, running migrations on a non-SQLite database that mistakenly routes into this code path.","solutions":["Use the supported modernc.org/sqlite driver (via the otelsql wrapper the library configures) for online restore","Remove or adjust extra driver wrappers so the Raw() unwrap reaches a *sqlite.conn","Fall back to file-copy restore instead of the online backup API","Guard the restore with a capability check before invoking it"],"exampleFix":"// before\nimport _ \"github.com/mattn/go-sqlite3\"\n// after\nimport _ \"modernc.org/sqlite\"","handlingStrategy":"fallback","validationCode":null,"typeGuard":"func supportsOnlineRestore(driverConn any) bool {\n  if w, ok := driverConn.(interface{ Raw() driver.Conn }); ok {\n    driverConn = w.Raw()\n  }\n  _, ok := driverConn.(interface {\n    NewRestore(srcUri string) (*moderncsqlite.Backup, error)\n  })\n  return ok\n}","tryCatchPattern":"if err := restoreSQLiteOnline(ctx, db, srcPath); err != nil {\n  if strings.Contains(err.Error(), \"does not support online restore\") {\n    // fall back to file-based restore\n    err = fileCopyRestore(db, srcPath)\n  }\n  return err\n}","preventionTips":["Standardize on modernc.org/sqlite (as wrapped by the library) for SQLite connections","Avoid stacking custom driver wrappers that break Raw() unwrapping","Document the driver requirement for online backup features","Add a capability check at startup and select a restore strategy accordingly"],"tags":["sqlite","go","driver","backup"],"backgroundTag":"unsupported-driver-capability","analyzedSha":"4174065ffb052799890f7480f5360a877a67ffc1","analyzedAt":"2026-09-03T14:52:41.581Z","contentChangedAt":"2026-09-03T14:52:41.581Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}