Metadata-Version: 2.4
Name: binoc-sqlite
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Dist: binoc
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: maturin>=1.7,<2.0 ; extra == 'dev'
Requires-Dist: tomli>=2.0 ; python_full_version < '3.11' and extra == 'dev'
Provides-Extra: dev
Summary: SQLite comparator plugin for binoc
Keywords: binoc,datasets,sqlite
Home-Page: https://github.com/harvard-lil/binoc
Author: Harvard Library Innovation Lab
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/harvard-lil/binoc/tree/main/model-plugins/binoc-sqlite
Project-URL: Homepage, https://github.com/harvard-lil/binoc
Project-URL: Issues, https://github.com/harvard-lil/binoc/issues
Project-URL: Repository, https://github.com/harvard-lil/binoc

# binoc-sqlite

SQLite comparator plugin for [Binoc](https://github.com/example/binoc). Diffs `.sqlite` / `.sqlite3` / `.db` files by **schema** (tables, columns, types) and **row counts** — not row-by-row content — so you get summaries like “1 table modified”, “1 row added (1 → 2 rows)”, or “Table added (2 columns, 5 rows)” instead of a raw binary change.

## Install

From PyPI (requires Binoc and Python 3.10+):

```bash
pip install binoc binoc-sqlite
```

From the repo (when developing Binoc or this plugin):

```bash
uv run --with ./binoc-python --with ./binoc-sqlite binoc diff snapshot-a snapshot-b
```

## Example

Build two SQLite DBs and diff them (requires `sqlite3` on PATH):

```bash
mkdir -p /tmp/demo/snapshot-a /tmp/demo/snapshot-b
echo "CREATE TABLE t (id INT); INSERT INTO t VALUES (1);" | sqlite3 /tmp/demo/snapshot-a/data.sqlite
echo "CREATE TABLE t (id INT); INSERT INTO t VALUES (1); INSERT INTO t VALUES (2);" | sqlite3 /tmp/demo/snapshot-b/data.sqlite
binoc diff /tmp/demo/snapshot-a /tmp/demo/snapshot-b
```

Example output:

```markdown
# Changelog: /tmp/demo/snapshot-a → /tmp/demo/snapshot-b

## Other Changes

- **data.sqlite**: 1 table modified
- **data.sqlite/t**: 1 row added (1 → 2 rows)
```

Without the plugin, the same files would be reported as “Content changed” by the binary comparator.

## What it compares

- **Schema**: tables added/removed, columns added/removed, column type changes.
- **Row counts** per table (not cell-level diffs).

Tags emitted include `binoc-sqlite.row-addition`, `binoc-sqlite.table-addition`, `binoc-sqlite.schema-change`, etc. Configure significance (e.g. clerical vs substantive) in your dataset config; see [Writing Binoc Plugins](../docs/writing_plugins.md).

## Development

This crate is part of the Binoc workspace. From the **workspace root**:

- Run plugin tests: `cargo test -p binoc-sqlite`
- Or from this directory: `just test` (justfile runs from parent)

Test vectors live in `test-vectors/`. They use `.sqlite.d` directories of `.sql` files; the test harness builds the `.sqlite` files at test time (see `tests/test_vectors.rs`). To regenerate expected-output snapshots:

```bash
just snapshot-update
```

(Run from `binoc-sqlite/`; the justfile runs the insta update from the workspace root.)

For writing your own Binoc plugins (Rust or Python), see the main repo’s [Writing Binoc Plugins](../docs/writing_plugins.md).

