docs: add some notes about duckdb bundling (#646)

cc @ceholden
stac-utils · Feb 22, 2025 · e7bc2f1 · e7bc2f1
1 parent 8f34c26
commit e7bc2f1
Show file tree

Hide file tree

Showing 3 changed files with 25 additions and 1 deletion.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -56,7 +56,7 @@ jobs:
       - uses: astral-sh/setup-uv@v5
       - name: Get DuckDB
         run: |
-          wget https://github.com/duckdb/duckdb/releases/download/v1.1.3/libduckdb-linux-amd64.zip
+          wget https://github.com/duckdb/duckdb/releases/download/v1.2.0/libduckdb-linux-amd64.zip
           unzip libduckdb-linux-amd64.zip -d /opt/duckdb
       - name: Format
         run: cargo fmt --check

diff --git a/crates/cli/README.md b/crates/cli/README.md
@@ -58,6 +58,17 @@ Use the `--help` flag to see all available options for the CLI and the subcomman
 This crate has two features:
 
 - `pgstac`: enable a [pgstac](https://github.com/stac-utils/pgstac) backend for `stacrs serve` (enabled by default)
+- `duckdb-bundled`: bundle DuckDB by building it from source, instead of using a local installation (enabled by default)
+
+### DuckDB
+
+If you have DuckDB installed locally and want to use that shared library (instead of building it when you install), disable the `duckdb-bundled` feature:
+
+```shell
+cargo install stac-cli --no-default-features -F pgstac
+```
+
+This can dramatically speed up install time.
 
 ## Other info
 

diff --git a/crates/duckdb/README.md b/crates/duckdb/README.md
@@ -15,6 +15,19 @@ cargo add stac-duckdb
 
 See the [documentation](https://docs.rs/stac-duckdb) for more.
 
+## Bundling
+
+By default, DuckDB looks for its shared library on your system.
+Use `DUCKDB_LIB_DIR` and `DUCKDB_INCLUDE_DIR` to help it find those resources.
+If you want to build the DuckDB library as a part of this (or a downstream's) crate's build process, use the `bundled` feature.
+E.g. to test this crate if you don't have DuckDB locally:
+
+```shell
+cargo test -p stac-duckdb -F duckdb/bundled
+```
+
+See [the duckdb-rs docs](https://github.com/duckdb/duckdb-rs?tab=readme-ov-file#notes-on-building-duckdb-and-libduckdb-sys) for more.
+
 ## Other info
 
 This crate is part of the [stac-rs](https://github.com/stac-utils/stac-rs) monorepo, see its README for contributing and license information.