duckdb: Usage, Options & Common CI Errors
duckdb runs analytical SQL over files and an embedded database from the shell.
duckdb is the in-process analytics engine CI uses to query CSV/Parquet directly. Its quirks are an exclusive single-writer lock on the database file and memory pressure on large scans.
What it does
duckdb opens an embedded analytical database (a file or :memory:) and runs SQL, including querying CSV/Parquet/JSON files directly without importing them. Like SQLite there is no server; the CLI is the engine.
Common usage
duckdb -c "SELECT count(*) FROM read_csv_auto('data.csv')"
duckdb app.duckdb -c 'CREATE TABLE t AS SELECT * FROM read_parquet(\'f.parquet\')'
duckdb app.duckdb '.read script.sql'
duckdb -c "COPY (SELECT * FROM t) TO 'out.parquet' (FORMAT parquet)"Options
| Item | What it does |
|---|---|
| -c "SQL" | Run SQL and exit |
| <file> | Open a persistent database file |
| .read <file> | Run SQL from a file |
| read_csv_auto / read_parquet | Query files directly |
| COPY ... TO | Export query results to a file |
| -json / -csv | Set the CLI output format |
Common errors in CI
IO Error: Could not set lock on file "app.duckdb": Conflicting lock - DuckDB allows only one read-write process per file; close the other connection or open read-only (ACCESS_MODE=READ_ONLY). Out of Memory Error appears on large aggregations on small runners; set SET memory_limit='2GB' and ensure a temp directory exists for spilling. "No function matches ... read_csv_auto" means a too-old build - pin the DuckDB version since SQL surface evolves between releases.