feat(multi-version): foundation for DuckDB v1.4.4 LTS + v1.5.x support (selector script + Makefile target + doc)

Makefile

@@ -4,6 +4,23 @@ PROJ_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
 EXT_NAME=mobilityduck
 EXT_CONFIG=${PROJ_DIR}extension_config.cmake
 
+# Multi-DuckDB-version selector (foundation; CI matrix is a follow-up).
+#
+# The committed submodule SHAs target the LTS line.  To build against
+# another supported DuckDB version, run:
+#
+#     make set-duckdb-version DUCKDB_VERSION=v1.5.2
+#
+# which delegates to scripts/select-duckdb-version.sh and switches the
+# duckdb / duckdb-spatial / extension-ci-tools submodules in lockstep.
+# Same pattern as MobilityDB-on-Postgres compiling against PG 13-18 from
+# one source tree.  See doc/multi-duckdb-version.md for the full design.
+DUCKDB_VERSION ?= v1.4.4
+
+.PHONY: set-duckdb-version
+set-duckdb-version:
+	@$(PROJ_DIR)scripts/select-duckdb-version.sh $(DUCKDB_VERSION)
+
 # Include the Makefile from extension-ci-tools
 include extension-ci-tools/makefiles/duckdb_extension.Makefile
 

README.md

@@ -99,7 +99,7 @@ MobilityDuck$ ./build/release/duckdb [name of db].db
 
 ### 3.2. DuckDB shell without built-in extension
 
-If DuckDB is available on your machine ([installed independently](https://duckdb.org/install/), unrelated to MobilityDuck) and can be called by ```duckdb```, the MobilityDuck extension binary can be loaded later. **Prerequisite**: the independent DuckDB version and the DuckDB version of the build must be identical. The latest version of MobilityDuck is built with DuckDB v1.4.4 (long-term support), the binaries for which can be obtained from [the v1.4.4 release](https://github.com/duckdb/duckdb/releases/tag/v1.4.4).
+If DuckDB is available on your machine ([installed independently](https://duckdb.org/install/), unrelated to MobilityDuck) and can be called by ```duckdb```, the MobilityDuck extension binary can be loaded later. **Prerequisite**: the independent DuckDB version and the DuckDB version of the build must be identical. The latest version of MobilityDuck is built against DuckDB v1.4.4 (LTS, the ecosystem alignment target) by default; v1.5.2 is also supported as an opt-in track. See [`doc/multi-duckdb-version.md`](doc/multi-duckdb-version.md) for the per-version manifest and how to switch the working tree. The DuckDB v1.4.4 binaries are available at [the v1.4.4 release](https://github.com/duckdb/duckdb/releases/tag/v1.4.4).
 
 If you build MobilityDuck from source code, the loadable extension binary is available at ```./build/release/extension/mobilityduck/mobilityduck.duckdb_extension```.
 

doc/multi-duckdb-version.md

@@ -0,0 +1,98 @@
+# Multi-DuckDB-version support
+
+MobilityDuck targets multiple upstream DuckDB versions from one source tree, mirroring how MobilityDB-on-Postgres supports PG 13-18 from one source. This document explains the model, the per-version manifest, and how to add a new supported version.
+
+## Supported versions
+
+| DuckDB version | Track | DuckDB-spatial branch | extension-ci-tools branch | Notes |
+|---|---|---|---|---|
+| **v1.4.4** | LTS (default) | `v1.4-andium` | `v1.4.4` | The ecosystem alignment target. Full GeoArrow / GeoParquet 1.1 spatial surface in the bundled `spatial` extension. |
+| **v1.5.2** | Latest 1.5.x | `v1.5-variegata` | `v1.5-variegata` | Opt-in. Bundled `spatial` has a reduced function surface in this series; row-group pruning still works via the MVB v3 scalar-AND-chain recipe on `covering.bbox` struct leaves. |
+
+The committed submodule SHAs in `main` target v1.4.4. Switching to a different supported version is a working-tree operation: the submodules move, the source code does not.
+
+## How a build picks the version
+
+DuckDB extension ABI is version-specific — a binary built against v1.4.4 cannot load into v1.5.2 and vice versa. MobilityDuck therefore produces a separate binary per supported version (one extension build per `(duckdb_version, platform)`).
+
+Selection is driven by a single source: the SHAs that the three submodules — `duckdb`, `duckdb-spatial`, `extension-ci-tools` — point at when the build runs:
+
+```
+   ┌──────────────────────────────────────────────────────────┐
+   │              MobilityDuck source (.cpp + .hpp)           │
+   │   ──────────────────────────────────────────────────     │
+   │      #if DUCKDB_VERSION_NUM >= 010500                    │
+   │        … 1.5.x API call shape …                          │
+   │      #else                                               │
+   │        … 1.4.x API call shape …                          │
+   │      #endif                                              │
+   └─────────────────────────┬────────────────────────────────┘
+                             │ same source for every version
+                             ▼
+   ┌──────────────────────────────────────────────────────────┐
+   │   Submodules (parameterised by DUCKDB_VERSION)           │
+   │                                                          │
+   │   duckdb              → tag matching the chosen version  │
+   │   duckdb-spatial      → matching v<series>-<codename>    │
+   │   extension-ci-tools  → matching ci-tools tag/branch     │
+   └─────────────────────────┬────────────────────────────────┘
+                             │
+                             ▼
+   ┌──────────────────────────────────────────────────────────┐
+   │   One binary per (duckdb_version, platform):             │
+   │     extensions.duckdb.org/v1.4.4/linux_amd64/            │
+   │       mobilityduck.duckdb_extension                      │
+   │     extensions.duckdb.org/v1.5.2/linux_amd64/            │
+   │       mobilityduck.duckdb_extension                      │
+   │   `INSTALL mobilityduck FROM community;` resolves to     │
+   │   the right artefact automatically — the community       │
+   │   repository keys on `<duckdb_version>/<platform>/`.     │
+   └──────────────────────────────────────────────────────────┘
+```
+
+## Switching the working tree to a different version
+
+```bash
+# Switch to v1.5.2 (downloads + checks out the matching submodule SHAs)
+make set-duckdb-version DUCKDB_VERSION=v1.5.2
+
+# Then the normal build flow targets that version
+make release
+```
+
+Under the hood `make set-duckdb-version` calls `scripts/select-duckdb-version.sh`, which looks up the requested version in its per-version manifest and runs `git checkout <ref>` inside each submodule. The script does not modify `.gitmodules`; the change is per-checkout. To make the chosen version the new committed default for the parent repository, `git add` each submodule path and commit.
+
+To return to the committed default:
+
+```bash
+git submodule update --recursive
+```
+
+## Adding a new supported version
+
+Edit two files:
+
+1. `scripts/select-duckdb-version.sh` — add a `case` arm with the DuckDB tag and matching `duckdb-spatial` / `extension-ci-tools` refs.
+2. `doc/multi-duckdb-version.md` (this file) — add the row to the "Supported versions" table.
+
+A new version typically also requires:
+
+- One or more `#if DUCKDB_VERSION_NUM >= …` conditionals in the source where the new DuckDB release broke ABI (the `ExtensionUtil` → `ExtensionLoader` rename between 1.4 and 1.5 is one example; the spatial-function surface reshuffle is another).
+- Per-version expected-output variants in `test/sql/*.test` for any case where DuckDB's own behaviour changed (timezone, casting, etc.) — same pattern as MobilityDB's per-PG expected files.
+
+These per-version source / test deltas are deliberately out of scope for the foundation PR; they land as the version is brought up.
+
+## Relationship to the CI pipeline
+
+The CI workflow (`.github/workflows/MainDistributionPipeline.yml`) currently builds for a single `duckdb_version: v1.4.4`. The matrix expansion to multiple DuckDB versions — calling the foundation script per row — is a separate PR stacked on this one.
+
+## Adopter install
+
+Once the multi-version matrix is published, the adopter side is unchanged:
+
+```sql
+INSTALL mobilityduck FROM community;
+LOAD mobilityduck;
+```
+
+DuckDB's community-extension repository resolves the right binary for the running DuckDB version. Adopters on v1.4.4 LTS get the v1.4.4 build; adopters on v1.5.x get the v1.5.x build; the same MobilityDuck source produced both.

scripts/select-duckdb-version.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Switch the MobilityDuck submodules (duckdb, duckdb-spatial, extension-ci-tools)
+# to the set that targets a given DuckDB upstream version.
+#
+# This is the foundation for multi-DuckDB-version support — same pattern as
+# MobilityDB-on-Postgres compiling against PG 13-18 from one source. After
+# running this script, the `make release` / `make debug` flow builds the
+# MobilityDuck extension binary for the selected DuckDB version. The
+# committed default in the repository targets the LTS release; CI matrix
+# expansion (a follow-up PR) builds every supported version in parallel.
+#
+# Usage:
+#   scripts/select-duckdb-version.sh v1.4.4
+#   scripts/select-duckdb-version.sh v1.5.2
+#
+# The script:
+#   1. Maps the requested DuckDB version to matching `duckdb-spatial` and
+#      `extension-ci-tools` refs that target that DuckDB ABI.
+#   2. Updates each submodule's tracked branch and fetches the new tip.
+#   3. Reports the resulting SHAs so the caller can pin them if needed.
+#
+# It does NOT modify .gitmodules; the change is per-checkout only. Commit
+# the resulting submodule SHA bump (in the parent repository) if you want
+# the chosen version to be the new committed default.
+
+set -eu -o pipefail
+
+VERSION="${1:-}"
+if [[ -z "$VERSION" ]]; then
+    cat <<EOF >&2
+Usage: $0 <duckdb-version>
+
+Supported versions:
+  v1.4.4   (LTS, ecosystem alignment target)
+  v1.5.2   (latest 1.5.x line, opt-in)
+
+The chosen version pins:
+  duckdb              -> the matching DuckDB tag
+  duckdb-spatial      -> the matching v<series>-<codename> branch HEAD
+  extension-ci-tools  -> the matching v<series>-<codename> branch HEAD
+
+For full context see doc/multi-duckdb-version.md.
+EOF
+    exit 2
+fi
+
+# Per-version manifest. Add a row to extend the supported set.
+case "$VERSION" in
+    v1.4.4)
+        DUCKDB_REF="v1.4.4"
+        SPATIAL_REF="v1.4-andium"
+        CI_TOOLS_REF="v1.4.4"
+        ;;
+    v1.5.2)
+        DUCKDB_REF="v1.5.2"
+        SPATIAL_REF="v1.5-variegata"
+        CI_TOOLS_REF="v1.5-variegata"
+        ;;
+    *)
+        echo "Unsupported DuckDB version: $VERSION" >&2
+        echo "Edit scripts/select-duckdb-version.sh to add a manifest row." >&2
+        exit 2
+        ;;
+esac
+
+cd "$(git rev-parse --show-toplevel)"
+
+echo "[select-duckdb-version] target = DuckDB $VERSION"
+echo "[select-duckdb-version]   duckdb              -> $DUCKDB_REF"
+echo "[select-duckdb-version]   duckdb-spatial      -> $SPATIAL_REF"
+echo "[select-duckdb-version]   extension-ci-tools  -> $CI_TOOLS_REF"
+
+switch_submodule() {
+    local path="$1" ref="$2"
+    if [[ ! -d "$path/.git" && ! -f "$path/.git" ]]; then
+        git submodule update --init "$path"
+    fi
+    (
+        cd "$path"
+        git fetch --tags origin "$ref"
+        git checkout "$ref"
+    )
+}
+
+switch_submodule duckdb              "$DUCKDB_REF"
+switch_submodule duckdb-spatial      "$SPATIAL_REF"
+switch_submodule extension-ci-tools  "$CI_TOOLS_REF"
+
+echo
+echo "[select-duckdb-version] resulting submodule SHAs:"
+git submodule status
+echo
+echo "[select-duckdb-version] To make this the committed default for the parent"
+echo "  repository, 'git add' each submodule path and commit."

vcpkg_ports/meos/portfile.cmake

@@ -1,8 +1,8 @@
 vcpkg_from_github(
     OUT_SOURCE_PATH SOURCE_PATH
     REPO estebanzimanyi/MobilityDB
-    REF a8178dc9d56d841d0eb5025a7e8717c8d25a1d0f
-    SHA512 030a144bb3247695702dd2de11f4c389ed28c6eb0186e6988a489e2b00e9801179ba8f27bcbcd81ae89e398a7277ed7f9ff7058dbf15f5db322ae4644365c560
+    REF 3db47f887c61f049a6a03db55c48bedf6d10eee4
+    SHA512 b73123bca036813c43937f90f0d0ce45af5cb9e39d6a597304199d21ae854212319a3a7b58ecd075eb5678d89d6d5990b9faf63dd29bd8c9a4e2ed83282b94c5
 )
 
 vcpkg_replace_string(