duckdb-sandbox

A minimal, containerized sandbox for experimenting with DuckDB from Python. No local Python or DuckDB install required — everything runs inside Docker, with the repo bind-mounted into the container so edits on the host apply live.

Requirements

• Docker with Compose (docker compose)

Quick start

# Build the image (python:3.12-slim + duckdb)
docker compose build

Usage

# open a duckdb console for a specific duckdb database
docker compose run --rm duckdb duckdb data/scratch.duckdb

# or just start a duckdb console with an inmemory database
docker compose run --rm duckdb duckdb

Layout

Path	Purpose
data/	Persistent DuckDB database files. *.duckdb / *.duckdb.wal / *.tmp are gitignored; connect here so state survives across container runs.
test-data/sample.csv	Committed 100k-row × 50-column fixture for load/query experiments.
test-data/generate_sample.py	Regenerates sample.csv.
Dockerfile / docker-compose.yml	Container definition.

Sample data

test-data/sample.csv is a 100,000-row × 50-column CSV. Columns cycle through five types by index (col_idx % 5) — int, float, category, ISO date, bool — so loading it exercises a spread of DuckDB column types. Regenerate it with:

python test-data/generate_sample.py          # deterministic (random.seed(42))

Example Duckdb commands

-- create OR replace a table from a sample csv, 100k records
CREATE OR REPLACE TABLE test AS SELECT * FROM 'test-data/sample.csv';

select count(*) from test;

select * from test limit 5;

DESCRIBE test;

SHOW TABLES;

Load the same file in another 9 times .. 1 Million records

INSERT INTO test SELECT s.* FROM 'test-data/sample.csv' AS s, range(9);

select count(*) from test ;
┌────────────────┐
│  count_star()  │
│     int64      │
├────────────────┤
│    1000000     │
│  (1 million)   │
└────────────────┘

Dump to Parquet

-- dump to parquet
COPY test TO 'test-data/test-1mil.parquet' (FORMAT parquet);

-- get file size .. for our test 1 Million records, 42 mb
SELECT filename, size / 1024.0 / 1024.0 AS size_mb FROM read_blob('data/test.parquet');