Implementation:Duckdb Duckdb Extension Upload Test

Field	Value
source	scripts/extension-upload-test.sh, scripts/run_extension_medata_tests.sh
domains	Extension_Development, Testing
last_updated	2026-02-07

Overview

Concrete tool for verifying DuckDB extension installation and loading via SQL commands. This implementation uses shell scripts that invoke the DuckDB CLI to test that uploaded extensions can be installed, loaded, and queried, and that the embedded metadata passes validation checks.

Code Reference

Extension Loading Test

Source: scripts/extension-upload-test.sh (lines 1-64)

This script tests the end-to-end install and load flow for each extension by:

1. Starting the DuckDB CLI binary
2. Optionally setting a custom extension repository URL
3. Executing INSTALL '<extension_name>' to download and decompress the extension
4. Executing LOAD '<extension_name>' to load the extension into the runtime
5. Running a basic query to verify the extension is functional
6. Reporting pass or fail for each extension

# Simplified logic from extension-upload-test.sh
for ext in ${EXTENSIONS}; do
    echo "Testing extension: ${ext}"

    RESULT=$("${DUCKDB_BINARY}" -c "
        SET custom_extension_repository='${CUSTOM_REPO}';
        INSTALL '${ext}';
        LOAD '${ext}';
        SELECT '${ext} loaded successfully' AS status;
    " 2>&1)

    if echo "$RESULT" | grep -q "loaded successfully"; then
        echo "PASS: ${ext}"
    else
        echo "FAIL: ${ext}"
        echo "$RESULT"
        EXIT_CODE=1
    fi
done

Metadata Validation Test

Source: scripts/run_extension_medata_tests.sh (lines 1-64)

This script validates the structural integrity of the embedded metadata section:

1. Reads the metadata footer from the extension binary
2. Verifies the magic bytes are present and correct
3. Extracts and validates the platform string, version strings, and ABI type
4. Checks that the signature region is non-zero (i.e., the extension has been signed)

# Simplified logic from run_extension_medata_tests.sh
for ext_file in ${EXTENSION_FILES}; do
    echo "Validating metadata: ${ext_file}"

    # Read and verify metadata fields
    "${DUCKDB_BINARY}" -c "
        SELECT * FROM duckdb_extensions()
        WHERE extension_name = '${EXT_NAME}'
        AND installed = true;
    "

    # Verify platform matches
    # Verify version matches
    # Verify signature is present
done

I/O Contract

API

Extension loading test:

scripts/extension-upload-test.sh <duckdb_binary> <extension_list> [custom_repo_url]

Metadata validation test:

scripts/run_extension_medata_tests.sh <duckdb_binary> <extension_directory>

SQL commands used internally:

-- Install an extension from the repository
INSTALL '<extension_name>';

-- Load an installed extension into the runtime
LOAD '<extension_name>';

-- Optionally set a custom repository URL
SET custom_extension_repository = 'http://custom-repo.example.com';

Parameters

Parameter	Description	Example
DUCKDB_BINARY	Path to the DuckDB CLI binary	build/release/duckdb
Extension name	Name of the extension to test	httpfs, parquet, json
Custom repo URL	Optional custom extension repository URL	http://extensions.example.com

Inputs

• Uploaded extension on S3 (or custom repository)
• DuckDB CLI binary compiled for the target platform

Outputs

• Pass or fail status for each extension tested:
  • Pass -- the extension was successfully installed, loaded, and returned a correct query result
  • Fail -- any step in the install/load/query sequence produced an error
• Metadata validation results (platform match, version match, signature presence)

Usage Examples

Testing a single extension after upload:

# Test that httpfs can be installed and loaded
scripts/extension-upload-test.sh \
    build/release/duckdb \
    "httpfs" \
    "http://extensions.duckdb.org"

Testing all extensions:

# Test all core extensions
scripts/extension-upload-test.sh \
    build/release/duckdb \
    "httpfs parquet json tpch tpcds fts"

Testing against a custom repository (e.g., nightly bucket):

# Test extensions from the nightly S3 bucket
scripts/extension-upload-test.sh \
    build/release/duckdb \
    "httpfs parquet" \
    "http://nightly-extensions.duckdb.org"

Running metadata validation:

scripts/run_extension_medata_tests.sh \
    build/release/duckdb \
    build/release/extension/

Related Pages

• Principle:Duckdb_Duckdb_Extension_Loading_Verification
• Environment:Duckdb_Duckdb_Extension_Distribution_Env