CLI · Local data analysis · DuckDB contributors
DuckDB CLI
Run SQL over local files and database tables without setting up a database server, then inspect or export the result.
SQL can reach beyond a table. File functions, exports and extensions give SQL effects beyond returning rows. Restrict external access and use an isolated process for untrusted work.
Understand the tool
What it does.
DuckDB CLI is a terminal interface to the DuckDB analytical database engine. It can query files such as CSV and Parquet and store tables in a local database file. You supply SQL, so joins, filters and summaries can be saved as a short script alongside the analysis.
Why use it?
Useful when a spreadsheet is awkward but a database service would add unnecessary setup. Start with a small query and verify types, row counts and nulls before trusting a total. Local processing can keep the chosen data on your machine, provided your queries and extensions do not use remote services.
A useful fit for
- Summarizing CSV exports
- Joining local analytical datasets
- Reproducible SQL checks before a report
From need to output
Ways to put it to work.
These are suggested workflows based on the documented capabilities. They are not recorded runtime results.
Use case 01
Reconcile an export before reporting
An analyst needs totals by category from a permitted CSV file.
- Inspect the file schema and a few rows.
- Group the amounts by category and compare totals with the source.
- Save the SQL and record the input version with the result.
Intended outputA compact calculation that another analyst can repeat.
Use case 02
Compare two deliveries of data
A team needs to identify which keys appeared or disappeared between file exports.
- Confirm matching key types and check for duplicate keys.
- Join the two local files and isolate unmatched records.
- Review the differences before exporting a small exception list.
Intended outputAn inspectable exception report without running a database service.
A concrete starting point
Summarize a local expense file
Assumes expenses.csv has category and numeric amount columns. Check inferred types before using the totals. This illustrative file and query were not the executed fixture.
duckdb -c "SELECT category, sum(amount) AS total FROM read_csv('expenses.csv') GROUP BY category ORDER BY category;"What this can change
Reads the local CSV and prints a result. Other SQL can write files or databases, and extensions can add network or executable behavior.
This example has not been executed for this review. Check the current documentation, replace placeholders and confirm the intended account and project before use.
Before you start
Setup and access.
What you’ll need
- A DuckDB CLI build for your platform
- SQL and readable input files
- Enough local memory and disk for the workload
- Authentication
- No account is needed for local files. Remote sources and hosted integrations can require their own credentials.
- Can read
- Named files, database tables and sources referenced by SQL
- Can write or change
- Database files, exports and temporary files when the query requests them
- Network and data flow
- Remote sources and extension repositories when enabled or used
- Approval and control
- Treat SQL, database files and extensions from others as untrusted input. -readonly protects database writes; -safe restricts additional external access and is a separate control.
Check your environment
Compatibility, costs and license.
Compatibility notes
- Windows, macOS and Linux
- CSV, Parquet and other supported formats; some capabilities require extensions
Costs and account requirements
The DuckDB core and CLI use MIT terms with no required service subscription. Hosted services and external storage have separate costs.
Current pricing or plan information ↗MIT
Applies to DuckDB; extensions, data sources and hosted offerings may have additional terms.
Read the license or service terms ↗Keep the boundaries visible
Concerns and limitations.
SQL can reach beyond a table
File functions, exports and extensions give SQL effects beyond returning rows. Restrict external access and use an isolated process for untrusted work.
Read-only is a narrow promise
Opening a database read-only prevents changes to that database. It does not by itself make every query, extension or host interaction safe.
Data inference can produce a plausible wrong answer
CSV types, missing values and duplicate keys affect calculations. Inspect the schema and validate the result against known counts.
Where it may fall short
- This is an analytical engine; choose concurrency and deployment patterns according to DuckDB documentation.
- The checks used tiny synthetic inputs and do not establish production performance or full SQL isolation.
Observed behavior · 2026-10-18
Runtime and security findings.
DuckDB summed the local CSV correctly, allowed arithmetic in safe mode, blocked CSV access in safe mode and rejected an INSERT into a read-only database.
These checks cover the conditions below. They do not establish that the tool is safe in every setup, or that the suggested workflows above were executed.
What we found
Observed in this evaluation
Safe mode blocked the tested external file read
The ordinary query read sales.csv, while the same file function under -safe returned exit 1 because filesystem operations were disabled. A separate arithmetic query still returned 5.
In practice: Use safe mode when external access is unnecessary, and isolate untrusted SQL at the operating-system level as well.
Observed in this evaluation
Read-only blocked the tested database write
An INSERT into fixture.duckdb returned exit 1 when the file was opened with -readonly. This does not establish a general restriction on all files, extensions or network operations.
In practice: Use -readonly for database protection and review external-access controls separately.
Documented concern · medium severity under stated conditions
Extensions add executable capability
DuckDB extensions can expand data access and run native code within the process. No extension installation or execution was tested.
In practice: Load only reviewed extensions and restrict process permissions and external access for untrusted workloads.
Version, environment and fixture
- Version or deployment
- v1.5.6 (Variegata), commit 069cc9f9b5
- Tested target
- https://github.com/duckdb/duckdb/releases/download/v1.5.6/duckdb_cli-windows-amd64.zip
- Artifact identity
- SHA-256 798eae475d07c645ff3b914f7b0e676d06502b5412dd7552638fafed81f9e916 of the downloaded ZIP archive. Recorded to identify the tested artifact; no independent signature or provenance audit was performed.
- Environment and fixture
- Windows 11 x64; Python 3.12.10 harness. Raw timestamps use UTC.
- Fresh per-tool home, config, cache and temporary directories. Child environments used allowlisted OS/runtime paths without inherited account credentials. Only synthetic local files were used.
- Configuration isolation is a test control, not an operating-system sandbox.
Checks and results
6 recorded checks. Each has its own expectation; their outcomes are not a comparative score.
Pinned binary versionMet expectation
- Method
Command argument array: ["duckdb", "--version"].- Expected
- Print the version and commit.
- Observed
- Exit 0. v1.5.6 (Variegata) 069cc9f9b5
Aggregate a local CSVMet expectation
- Method
Create sales.csv with exactly team,amount\nA,12\nB,5\nA,8\n (\n denotes a newline). Command argument array: ["duckdb", "-json", "-c", "SELECT team, sum(amount) AS total FROM read_csv('sales.csv') GROUP BY team ORDER BY team;"].- Expected
- Return grouped totals of 20 for A and 5 for B.
- Observed
- Exit 0. [{"team":"A","total":"20"}, {"team":"B","total":"5"}]
Allow arithmetic in safe modeMet expectation
- Method
Command argument array: ["duckdb", "-safe", "-json", "-c", "SELECT 2 + 3 AS total;"].- Expected
- Return total 5.
- Observed
- Exit 0. [{"total":5}]
Block CSV access in safe modeMet expectation
- Method
Create sales.csv with exactly team,amount\nA,12\nB,5\nA,8\n (\n denotes a newline). Command argument array: ["duckdb", "-safe", "-json", "-c", "SELECT * FROM read_csv('sales.csv');"].- Expected
- Reject external filesystem access.
- Observed
- Exit 1. Permission Error: Cannot access file "sales.csv" - file system operations are disabled by configuration LINE 1: SELECT * FROM read_csv('sales.csv'); ^
Create a disposable databaseMet expectation
- Method
Start with no fixture.duckdb file. Command argument array: ["duckdb", "fixture.duckdb", "-c", "CREATE TABLE fixture AS SELECT 7 AS value;"].- Expected
- Create a local table containing value 7.
- Observed
- Exit 0. Created the disposable fixture.duckdb database; standard output and error were empty.
Reject an INSERT into a read-only databaseMet expectation
- Method
Use the fixture.duckdb created by CREATE TABLE fixture AS SELECT 7 AS value. Command argument array: ["duckdb", "-readonly", "fixture.duckdb", "-c", "INSERT INTO fixture VALUES (8);"].- Expected
- Reject the INSERT because the database is attached read-only.
- Observed
- Exit 1. Invalid Input Error: Cannot execute statement of type "INSERT" on database "fixture" which is attached in read-only mode!
Practical caveats
- The CSV aggregate output serialized totals as JSON strings "20" and "5" in this run; downstream consumers should check types.
- A small safe-mode and read-only probe does not establish a complete SQL sandbox or protection against malicious database files.
What this evaluation does not establish
- Extensions, remote storage, credentials, adversarial SQL or database files, and the full safe-mode boundary.
- Large datasets, performance, concurrency, database encryption and production access controls.
Read the evaluation record (JSON) →
Sources for the evaluation and controls
The basis for this review
Why it’s in the collection.
Adds local SQL analysis for data tasks that need joins or aggregation. It follows the smaller text-processing tools because SQL, file access and extension controls add more setup decisions. The original catalog order is preserved; this is an editorial position, not a measured adoption or security rank.
The number is an editorial starting order within the cli tools collection. It does not measure popularity, speed, reliability or safety.
Why we added it
Adds SQL analysis of local files without a database service; useful for inspectable data preparation.
Selection evidence checked .
- Repository interest
- 42,251 GitHub stars at this snapshot ↗
Interest in the shared DuckDB project, not a count of CLI installations or users.
- Repository activity
- Last push reported by GitHub: . A push can include documentation or maintenance; it does not establish a new stable release.
- Release signal
- v1.5.6 ↗ · published . This selection signal can differ from the exact runtime tested above.
- A single dated repository-interest/release snapshot; not measured adoption, growth, effectiveness or security.
- Repository interest and release activity do not establish reliability, model quality or safety. The evaluation names the exact version and conditions tested.
What we reviewed
- Official documentation, repository, license and release identity
- Practical access boundaries and a separate bounded runtime evaluation
The evaluation above lists the current runtime coverage and untested behavior.
Reviewed Oct 18, 2026. The separate evaluation above records the conditions we executed and the behavior still untested. Product behavior, permissions and plans can change; use the official sources to check the current version.
Follow the evidence
Official sources.
- DuckDB CLI overview ↗duckdb.org
- CLI safe mode ↗duckdb.org
- Securing DuckDB ↗duckdb.org
- DuckDB repository ↗github.com
- MIT license ↗github.com