[cigrainger]

Summary

Add Excel (.xlsx) read and write support via DuckDB's read_xlsx and COPY TO XLSX.

Usage

# Read
df = Dux.from_excel("sales.xlsx")
df = Dux.from_excel("data.xlsx", sheet: "Q1 2024", range: "A1:F100")
df = Dux.from_excel("messy.xlsx", all_varchar: true)

# Write
Dux.from_list([%{name: "Alice", age: 30}])
|> Dux.to_excel("/tmp/output.xlsx")

Safe defaults for messy spreadsheets

DuckDB infers Excel column types from the first data row only. A NULL or empty cell in row 1 causes the column to be inferred as DOUBLE, which fails when later rows contain strings. Two safety nets enabled by default:

• ignore_errors: true — type-cast failures become NULL instead of raising
• empty_as_varchar: true — empty/null cells infer as VARCHAR instead of DOUBLE

Together these handle the most common "messy spreadsheet" scenarios. Users who want strict type checking can pass ignore_errors: false, empty_as_varchar: false. Users who want full control use all_varchar: true.

Uses Keyword.validate! for option checking — typos like headers: instead of header: raise immediately.

Test plan

Happy path (3):

• Read basic xlsx with column names
• Read with all_varchar: true
• Read → filter pipeline composition

Happy path — writing (3):

• Write basic xlsx
• Write → read round-trip with types
• Pipeline before write

Sad path (2):

• Non-existent file raises
• Invalid write path raises

Adversarial (5):

• Special characters survive round-trip
• NULL in first row handled by ignore_errors (no crash)
• NULL in first row + all_varchar: true preserves all data
• ignore_errors: false + empty_as_varchar: false raises on type mismatch
• Empty dataframe writes valid xlsx
• 50-column wide table round-trip

Scale (1):

• 1000-row round-trip with SUM verification

🤖 Generated with Claude Code