Answer the question first
DuckDB should not permit read‑only opening of a database that contains a newer internal format version than the binary can understand. Allowing such an open would expose the process to:
- Partial reads that could misinterpret page structures.
- Unintended writes from background processes (e.g., VACUUM, auto‑indexing) that could corrupt the file further.
- Inconsistent visibility of data, leading to incorrect results or crashes.
Therefore, the safe path is to perform a full upgrade with the exact DuckDB binary that created the file before any other binary can open it.
Why read‑only is unsafe in this scenario
DuckDB’s page format is tightly coupled to the binary version. A partially upgraded file may contain a mix of page headers, page sizes, and checksum algorithms. Even if the engine is started in read‑only mode, internal mechanisms (e.g., WAL replay, page caching, or background compaction) can still trigger writes to the file. Without a complete upgrade, those writes may corrupt the already inconsistent layout, making recovery impossible.
Recommended recovery workflow
Back up the file immediately. Copy the database file to a separate location; never modify the original until you are sure the operation is safe.
Determine the file’s internal format version. Run the current DuckDB binary with the --verbose flag to print header details:
duckdb --verbose mydb.duckdb
Look for a line like File format version: 9 or similar. If the binary refuses to start, the output may be truncated; in that case you can try a previous DuckDB release that matches the error message.
Find the matching DuckDB binary. The format version corresponds to a specific release (e.g., version 0.9.x). Download that exact binary from the official releases page.
Run a full upgrade. Start the matching binary and upgrade the file:
duckdb --upgrade mydb.duckdb
The tool rewrites all pages to the latest format. If the upgrade succeeds, the file will be fully consistent.
Verify integrity. After the upgrade, run:
duckdb mydb.duckdb -c "PRAGMA integrity_check;"
A clean result indicates the file is ready for use with newer binaries.
Open with the current binary. Now you can safely use any newer DuckDB release to read the database.
What safeguards would a future read‑only mode need?
- Strict header validation that aborts before any I/O if the format version is newer than supported.
- Disallowing background tasks (WAL replay, VACUUM, compaction) even in read‑only mode.
- Providing a diagnostic flag that lists the exact pages that are in the newer format, allowing a user to assess the extent of the partial upgrade.
Until such safeguards are proven reliable, the safest recommendation is to perform a full upgrade with the original binary rather than rely on read‑only access.
Missing diagnostic detail that could change the recommendation
If you already know the exact DuckDB version that created the file, you can skip the format‑version detection step and jump straight to the upgrade. Otherwise, please share the output of duckdb --verbose (or the error message you see) so we can pinpoint the required binary.
duckdb