lenzdb 0.1.5

SQL views over CSV files, with safe edits back to text.

LenzDB

SQL views over CSV files, with safe edits back to text.

LenzDB lets you define SQL views (called lenses) over CSV files, inspect them from the CLI, and safely write edits back to the source data. Everything stays as plain text, so Git works naturally.

Screen recording 2026-04-25 12.05.35 PM.webm

---

3-Minute Demo

# 1) Create a project with CSV data
mkdir demo && cd demo

cat > projects.csv <<EOF
id,name
p-1,Core Platform
p-2,Docs Refresh
EOF

cat > tasks.csv <<EOF
id,title,status,project_id
t-1,Ship CLI skeleton,todo,p-1
t-2,Write getting started docs,doing,p-2
t-3,Close phase zero,done,p-1
EOF

# tell LenzDB about the files
lnz add projects.csv
lnz add tasks.csv

# list tables LenzDB knows about
lnz list

# 2) Inspect your data
lnz view tasks

# 3) Define and register a lens (a saved SQL view)
cat > open_tasks.sql <<EOF
select
  t.id,
  t.title,
  t.status,
  p.name as project_name
from tasks t
join projects p on p.id = t.project_id
where t.status != 'done'
EOF

lnz add open_tasks.sql
lnz view open_tasks

# 4) Edit through the view
export LENZDB_EDITOR="code --wait"   # or vim/nano
lnz edit open_tasks

Make a change (e.g. update a title or status), save, and close.

# 5) Changes are written back to the source CSV
cat tasks.csv

That’s the core idea:

• Define the view you want to work with
• Edit it
• LenzDB safely writes changes back to CSV

---

Why

• Keep data in simple, diffable CSV files
• Use SQL to define the views people actually want
• Edit projections, not raw tables
• Review changes with normal Git diffs
• Avoid the overhead of a full database

---

Install

pipx install lenzdb
# or
pip install lenzdb

---

Core Concepts

• Tables → CSV files (tasks.csv)
• Lenses → SQL views (open_tasks.sql)
• lnz add → register a table or lens with a manifest in .lenzdb/schema/
• lnz view → view a table or lens, even before it is registered
• lnz edit → modify a table or lens; untracked resources are promoted on demand

---

Common Commands

lnz --help

lnz add
lnz list
lnz view tasks
lnz view open_tasks

lnz describe tasks
lnz explain open_tasks

lnz edit open_tasks
lnz edit tasks --filter "status = 'doing'"

lnz view tasks --filter "status = 'todo'"
lnz view tasks --columns id,title
lnz view tasks --order status,-title --limit 10

---

Optional: Explicit edit flow

lnz view open_tasks --format csv > /tmp/edit.csv
$EDITOR /tmp/edit.csv

lnz diff open_tasks /tmp/edit.csv
lnz plan open_tasks /tmp/edit.csv
lnz apply open_tasks /tmp/edit.csv

---

Project Structure (when you need it)

my-project/
  tasks.csv
  projects.csv
  open_tasks.sql

  .lenzdb/
    schema/

You can ignore .lenzdb/ entirely to start.

---

Notes

• CSV files are the source of truth
• Manifests in .lenzdb/schema/ register tracked tables and lenses
• Resource names are literal, so dots in filenames are part of the name
• Edits are validated before writeback
• Writable views infer safe insert defaults from exact equality filters like where status = 'doing'
• --page-size and $LENZDB_PAGE_SIZE > 0 turn on pagination and start at page 1 by default
• Keep your repo in Git for safety

---

License

MIT