Add patch-release mode to upgrade script (#767)

With the new `--patch` option, `upgrade.sh` will now increment only the
duckdb-rs crate patch version and leave DuckDB sources, generated
bindings, and DuckDB download tags unchanged. Handy for Rust-only patch
releases.

Author: mlafeldt

CONTRIBUTING.md

@@ -141,14 +141,30 @@ cd ~/github/duckdb-rs
 ASAN_OPTIONS=detect_leaks=1 ASAN_SYMBOLIZER_PATH=/usr/local/opt/llvm/bin/llvm-symbolizer cargo test --features bundled -- --nocapture
 ```
 
-### Update to new version
+### Update to a new version
 
-Everytime duckdb release to a new version, we also need to release a new version.
+When DuckDB releases a new version, duckdb-rs needs a matching release.
+
+Use the top-level upgrade script for DuckDB version updates:
 
-We can use the scripts to do the upgrades:
 ```shell
 ./upgrade.sh
 ```
-Which use sed to update the version number and then call `./libduckdb-sys/upgrade.sh` to generated new bindings.
 
-We may need to fix any error as duckdb's c-api may have breaking changes occasionally.
+This updates the workspace crate version, the exact workspace dependency pins
+that keep sibling crates in lockstep, README `Cargo.toml` examples, and DuckDB
+version references such as workflow tags and README download URLs. It then calls
+`./crates/libduckdb-sys/upgrade.sh` to regenerate bindings.
+
+DuckDB's C API may occasionally have breaking changes, so version updates may
+also require code fixes.
+
+For a duckdb-rs patch release that does not change the bundled DuckDB version:
+
+```shell
+./upgrade.sh --patch
+```
+
+Patch releases only update crate versions, exact workspace dependency pins,
+README `Cargo.toml` examples, and `Cargo.lock`. They do not update the DuckDB
+submodule, generated bindings, or DuckDB download tags.

README.md

@@ -136,6 +136,7 @@ These extensions are only available through the CMake build backend and imply `b
 
 Starting with DuckDB `v1.5.0`, the duckdb-rs version encodes the DuckDB version in its second semver component.
 The format is `1.MAJOR_MINOR_PATCH.x`, e.g., DuckDB `v1.5.0` maps to duckdb-rs `1.10500.x`.
+Use a tilde requirement to receive duckdb-rs patch releases without automatically moving to a different bundled DuckDB version.
 
 ### Using stable releases from crates.io
 
@@ -149,7 +150,7 @@ Or manually add it to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-duckdb = { version = "=1.10503.0", features = ["bundled"] }
+duckdb = { version = "~1.10503.0", features = ["bundled"] }
 ```
 
 ### Using the development version from git
@@ -188,7 +189,7 @@ You can adjust this behavior in a number of ways:
 
    ```toml
    [dependencies]
-   duckdb = { version = "1.10503.0", features = ["bundled"] }
+   duckdb = { version = "~1.10503.0", features = ["bundled"] }
    ```
 
 2. If you use the `bundled-cmake` feature, `libduckdb-sys` will build DuckDB from the local checkout in `crates/libduckdb-sys/duckdb-sources` using upstream CMake. This keeps plain `bundled` unchanged while allowing CMake-only extensions such as `icu`.

upgrade.sh

@@ -15,6 +15,20 @@ get_latest_release() {
     gh api "repos/$REPO/releases/latest" --jq '.tag_name'
 }
 
+usage() {
+    cat <<'EOF'
+Usage:
+  ./upgrade.sh [DUCKDB_VERSION]
+  ./upgrade.sh --patch
+
+Without arguments, upgrade to the latest DuckDB release.
+With DUCKDB_VERSION, upgrade bundled DuckDB and reset the crate patch to 0.
+Full upgrades also update workflow and README download URLs and regenerate
+bindings. With --patch, increment only the duckdb-rs crate patch version and
+leave DuckDB sources, generated bindings, and DuckDB download tags unchanged.
+EOF
+}
+
 current_workspace_version() {
     grep '^version = "' Cargo.toml | head -n1 | sed -E 's/version = "([^"]+)"/\1/'
 }
@@ -37,15 +51,93 @@ duckdb_version_to_crate_version() {
     printf '%s.%d%02d%02d.0' "$CRATE_MAJOR" "$DUCKDB_MAJOR" "$DUCKDB_MINOR" "$DUCKDB_PATCH"
 }
 
-DUCKDB_VERSION=${1:-$(get_latest_release "duckdb/duckdb")}
-DUCKDB_VERSION="v${DUCKDB_VERSION#v}"
+valid_duckdb_version() {
+    local DUCKDB_VERSION=${1#v}
+    [[ "$DUCKDB_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+}
+
+next_crate_patch_version() {
+    local CRATE_VERSION=$1
+    local MAJOR ENCODED PATCH
+    IFS=. read -r MAJOR ENCODED PATCH <<<"$CRATE_VERSION"
+    if [[ ! "$MAJOR" =~ ^[0-9]+$ || ! "$ENCODED" =~ ^[0-9]+$ || ! "$PATCH" =~ ^[0-9]+$ ]]; then
+        echo "Invalid current crate version: $CRATE_VERSION" >&2
+        exit 1
+    fi
+    printf '%s.%s.%s' "$MAJOR" "$ENCODED" "$((10#$PATCH + 1))"
+}
+
+update_crate_versions() {
+    cargo metadata --format-version 1 >/dev/null
+
+    sed_inplace "s!$CURRENT_CRATE_VERSION_PATTERN!$TARGET_CRATE_VERSION!g" \
+        Cargo.toml \
+        crates/duckdb/Cargo.toml \
+        crates/libduckdb-sys/Cargo.toml \
+        crates/duckdb-loadable-macros/Cargo.toml
+
+    # Update README Cargo.toml examples, not prose/history.
+    sed_inplace "/version = \"/s!$CURRENT_CRATE_VERSION_PATTERN!$TARGET_CRATE_VERSION!g" README.md
+
+    local UPDATED_CRATE_VERSION
+    UPDATED_CRATE_VERSION=$(current_workspace_version)
+    if [ "$UPDATED_CRATE_VERSION" != "$TARGET_CRATE_VERSION" ]; then
+        echo "Expected workspace version $TARGET_CRATE_VERSION, found $UPDATED_CRATE_VERSION" >&2
+        exit 1
+    fi
+
+    # Let Cargo rewrite Cargo.lock from the updated manifests instead of editing it as text.
+    cargo metadata --format-version 1 >/dev/null
+}
+
+PATCH_MODE=0
+
+case "${1:-}" in
+    -h|--help)
+        usage
+        exit 0
+        ;;
+    --patch)
+        PATCH_MODE=1
+        if [ $# -ne 1 ]; then
+            usage >&2
+            exit 1
+        fi
+        ;;
+    -*)
+        usage >&2
+        exit 1
+        ;;
+esac
+
+if [ "$PATCH_MODE" -eq 0 ] && [ $# -gt 1 ]; then
+    usage >&2
+    exit 1
+fi
+
 CURRENT_CRATE_VERSION=$(current_workspace_version)
 CURRENT_DUCKDB_VERSION=$(crate_version_to_duckdb_version "$CURRENT_CRATE_VERSION")
 CRATE_MAJOR=$(echo "$CURRENT_CRATE_VERSION" | cut -d. -f1)
-TARGET_CRATE_VERSION=$(duckdb_version_to_crate_version "$DUCKDB_VERSION" "$CRATE_MAJOR")
 CURRENT_CRATE_VERSION_PATTERN=${CURRENT_CRATE_VERSION//./\\.}
 CURRENT_DUCKDB_VERSION_PATTERN=${CURRENT_DUCKDB_VERSION//./\\.}
 
+if [ "$PATCH_MODE" -eq 1 ]; then
+    TARGET_CRATE_VERSION=$(next_crate_patch_version "$CURRENT_CRATE_VERSION")
+    echo "Start crate patch release for DuckDB $CURRENT_DUCKDB_VERSION"
+    echo "Update crate version from $CURRENT_CRATE_VERSION to $TARGET_CRATE_VERSION"
+    update_crate_versions
+    exit 0
+fi
+
+DUCKDB_VERSION=${1:-$(get_latest_release "duckdb/duckdb")}
+if ! valid_duckdb_version "$DUCKDB_VERSION"; then
+    echo "Invalid DuckDB version: $DUCKDB_VERSION" >&2
+    usage >&2
+    exit 1
+fi
+DUCKDB_VERSION="v${DUCKDB_VERSION#v}"
+TARGET_CRATE_VERSION=$(duckdb_version_to_crate_version "$DUCKDB_VERSION" "$CRATE_MAJOR")
+
 if [ "$DUCKDB_VERSION" = "$CURRENT_DUCKDB_VERSION" ]; then
     echo "Already up to date, latest DuckDB version is $DUCKDB_VERSION and workspace version is $CURRENT_CRATE_VERSION"
     exit 0
@@ -54,20 +146,12 @@ fi
 echo "Start to upgrade DuckDB from $CURRENT_DUCKDB_VERSION to $DUCKDB_VERSION"
 echo "Update crate version from $CURRENT_CRATE_VERSION to $TARGET_CRATE_VERSION"
 
-sed_inplace "s!$CURRENT_CRATE_VERSION_PATTERN!$TARGET_CRATE_VERSION!g" \
-    Cargo.toml \
-    crates/duckdb/Cargo.toml \
-    crates/libduckdb-sys/Cargo.toml \
-    crates/duckdb-loadable-macros/Cargo.toml
+update_crate_versions
 
 sed_inplace "s!$CURRENT_DUCKDB_VERSION_PATTERN!$DUCKDB_VERSION!g" \
     .github/workflows/rust.yaml
 
-# Update README: only Cargo.toml examples and download URLs, not prose/history.
-sed_inplace "/version = \"/s!$CURRENT_CRATE_VERSION_PATTERN!$TARGET_CRATE_VERSION!g" README.md
+# Update README download URLs, not prose/history.
 sed_inplace "/releases\/download/s!$CURRENT_DUCKDB_VERSION_PATTERN!$DUCKDB_VERSION!g" README.md
 
-# Let Cargo rewrite Cargo.lock from the updated manifests instead of editing it as text.
-cargo metadata --format-version 1 >/dev/null
-
 exec ./crates/libduckdb-sys/upgrade.sh "$DUCKDB_VERSION"