Metadata-Version: 2.4
Name: lenzdb
Version: 0.1.5
Summary: SQL views over CSV files, with safe edits back to text.
Project-URL: Homepage, https://github.com/arel/lenzdb
Project-URL: Repository, https://github.com/arel/lenzdb
Project-URL: Issues, https://github.com/arel/lenzdb/issues
Author: Arel Cordero
Maintainer: Arel Cordero
License: MIT
License-File: LICENSE
Keywords: cli,csv,data,git,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: duckdb>=1.5.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=15.0.0
Requires-Dist: sqlglot>=30.0.0
Requires-Dist: typer>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.0; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/user-attachments/assets/72860259-5e87-41fa-b667-0e80bf75ada8)

---

## 3-Minute Demo

```bash
# 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
```

```bash
# 2) Inspect your data
lnz view tasks
```

```bash
# 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
```

```bash
# 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.

```bash
# 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

```bash
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

```bash
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

```bash
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)

```text
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
