When I recently upgraded to DuckDB v1.4.0, expecting seamless access to the web-based UI extension, I was reminded of an important lesson about extension ecosystem dynamics. Here's what went wrong, what I discovered, and how to avoid similar surprises.

The Problem That Started It All

Imagine this: DuckDB v1.4.0 lands with exciting features like database encryption, a real uplift for projects with privacy constraints. I upgrade via Homebrew, launch DuckDB, and type duckdb -ui – expecting the handy web-based interface that's part of my regular workflow.

Extension Autoloading Error:
An error occurred while trying to automatically install the required extension 'ui':
Failed to download extension "ui" at URL "http://extensions.duckdb.org/v1.4.0/osx_arm64/ui.duckdb_extension.gz" (HTTP 403)
Extension "ui" is an existing extension.

The issue had been reported by others and I diligently reported as well. Actually it seems it had been reported in a few separate issues.

The ui extension, reliable since introduced with DuckDB v1.2.1, was absent from (at least) the macOS builds. Almost two days after release, still nothing. And downgrading, not as straightforward as I'd hoped.

This hiccup highlighted a key truth in extensible software: extensions don't always sync with core releases, even core releases. This may not be just annoying – it's a real business risk, causing delays, rollbacks, and potentially deferred upgrades that skip vital security fixes.

While there is not necessarily anything new to see here, its easy to overlook such "second order" dependencies. Let's break down why it happens and how to navigate it. I can also hear the "don't be an early adopter" chorus :)

Understanding the Extension Landscape

DuckDB, while exceptionally capable at its core, also thrives on its extensions – from JSON querying to geo-spatial tools and cloud storage links. But during upgrades, mismatches can cause disruptions. Here's the current state of play (late September 2025):

Core Extensions: Generally Solid, But Watch for Hitches

With 24 core extensions, mostly maintained by the DuckDB team (although with contributions from the open source community) and hosted on extensions.duckdb.org, they're built alongside releases for quick availability. Staples like json, parquet, spatial, and httpfs usually drop on day one across platforms.

But "usually" isn't "always." My ui experience showed platform-specific glitches can delay things (although I didn't explicitly test the Windows or Linux ui extensions.) In passing, the ui extension is an excellent SQL web client.

Community Extensions: Vibrant Yet Variable

Over 80 community extensions reside in the duckdb/community-extensions repo. It is certainly my expectation that these are likely to lag in compatibility as maintainers catch up with the latest release.

The upside: This ecosystem is thriving. Recent commits abound in 2025, and favourites like h3 (geo-spatial) and prql (query language) align swiftly with releases. Maintainers are quick on issues too.

Your Pre-Upgrade Toolkit

From my mishap, I crafted a checklist to assess readiness. Skip the guesswork – use these steps:

1. Inventory Your Dependencies

   Before upgrading, list what's in play:

   -- View installed extensions and versions
   SELECT extension_name, loaded, installed, version 
   FROM duckdb_extensions() 
   WHERE installed = true;
   
   -- Check specifics
   SELECT * FROM duckdb_extensions() 
   WHERE extension_name IN ('ui', 'spatial', 'h3', 'parquet');
   

   This becomes your post-upgrade benchmark.

2. Test Availability After Upgrade

   In a test environment, verify:

   -- Install keys
   INSTALL ui;
   INSTALL h3; 
   INSTALL prql;
   
   -- Load and test
   LOAD ui;
   LOAD h3;
   LOAD prql;
   

   Failures? Pause and plan.

3. Monitor Ecosystem Health

   I now automate checks for availability, repo activity, docs accuracy, and platform quirks. This would've flagged my ui issue upfront.

Rollback When Needed

Stuck? Here's how to retreat gracefully:

• Direct Binary Grab

  # Fetch from GitHub
  wget https://github.com/duckdb/duckdb/releases/download/v1.3.2/duckdb_cli-osx-universal.zip
  unzip duckdb_cli-osx-universal.zip
  

  and then "install" it whereever makes sense on your system.

• Docker for Safety

  # Pull version
  docker pull duckdb/duckdb:1.3.2
  
  # Run with data
  docker run -v /path/to/data:/data -it duckdb/duckdb:1.3.2
  

Unfortunately I downgrade using e.g. brew install duckdb@1.3.2 doesn't work.

Key Lessons and Best Practices

This experience reminded me of some hard-won wisdom:

1. Test Before Committing: Assumptions are upgrade killers. Validate in isolation first.

2. Keep Rollbacks Ready: Stock old versions via taps, binaries, or containers.

3. Mind Platforms: Availability can vary by OS and architecture – don't assume uniformity.

4. Know Your Must-Haves: Prioritise testing for critical extensions.

5. Automate Monitoring: Manual checks don't scale; build or use tools for ongoing intel.

DuckDB's ecosystem is maturing very fast, mirroring challenges already experienced for some time in Python or Node.js worlds. It's relatively young but responsive – my delay resolved in a couple of days. With growth comes complexity, so better tools for monitoring and prediction are key.

I'm tackling this with an automated solution to track much of the extension ecosystem. Curious? Dive into my follow-up: Mapping the DuckDB Extension Ecosystem: From Problem to Solution.

Wrapping Up

Upgrades should empower, not frustrate. With these strategies:

• Pre-Upgrade: Inventory, review notes, test isolates.
• During: Install/load checks, platform scans.
• Ongoing: Subscribe to announcements, watch repos, automate health checks, community chat.

This post kicks off a 2 part series on DuckDB's extensions. For the tool automating these checks, see Mapping the DuckDB Extension Ecosystem: From Problem to Solution.