DuckDB Version Mismatch
Harlequin depends on DuckDB, and installing it in an isolated environment (e.g., using
pipx or in a fresh virtual environment) will cause it to install DuckDB. If you have DuckDB installed elsewhere (e.g., if you already installed DuckDB with
pipx or Homebrew), you may want to pin the version of DuckDB that Harlequin uses. For example, attempting to open a DuckDB database file with different versions of DuckDB will result in an error that looks like this:
IO Error: Trying to read a database file with version number 64, but we can
only read version 51.
The database file was created with an newer version of DuckDB.
The storage of DuckDB is not yet stable; newer versions of DuckDB cannot
read old database files and vice versa.
The storage will be stabilized when version 1.0 releases.
For now, we recommend that you load the database file in a supported version
of DuckDB, and use the EXPORT DATABASE command followed by IMPORT DATABASE
on the current version of DuckDB.
See the storage page for more information:
Determining the Version of the DuckDB CLI on your Path
First, determine what version of DuckDB you are running outside of Harlequin, and how it was installed. You can find the path to the executable with
which duckdb on Unix systems, or
get-command duckdb in Windows Powershell. This path should give you a hint about how it was installed; you could also try
pipx list or
brew list to see if DuckDB was installed by either of those tools.
duckdb --version, which should display the version number and commit SHA, like
Alternatively, the storage page linked to in the error message provides a mapping of storage versions to DuckDB versions (e.g., we can see that storage version 64 maps to DuckDB 0.9.0, and 51 maps to DuckDB 0.8.0).
Determining the Version of DuckDB Used by Harlequin
Open Harlequin, then in the query editor, type or paste
select version(). In the Results Viewer, the version number should be displayed.
Changing the Version of DuckDB Used by Harlequin
Note: Harlequin requires DuckDB >= 0.8.0 due to changes in the Python API in that version.
You can add an explicit pin to a DuckDB version alongside Harlequin’s installation. The following examples assume you would like to pin the version to
You must “inject” the pinned dependency into the Harlequin installation with:
pipx inject harlequin duckdb==0.9.0.
With your venv activated, simply install the pinned version with
pip install duckdb==0.9.0, or add
duckdb==0.9.0 to your
pipenv add duckdb==0.9.0.
poetry add duckdb==0.9.0.