docs: add a runnable SQLite end-to-end example by dchaudhari7177 · Pull Request #21 · Jackxiaozhiren/datasentry

dchaudhari7177 · 2026-08-29T07:03:25Z

Closes #14

examples/integrations/sqlite/ — a database, a scan, and the findings, with nothing external involved.

Every command and every block of output in the README was captured from a real run, then re-run from a clean state to confirm it reproduces. The numbers in the README are the numbers you get.

What is in it

create_database.py — builds shop.db, one orders table, 14 synthetic rows
README.md — the six steps, with real output
.gitignore — keeps shop.db and .datasentry/ out of the repository

One deliberate choice

The flaws are planted one per row rather than randomly corrupted:

Row	Flaw
9	`2026-02-30` — a date that does not exist
10	`not-an-email`
11	`quantity` of `-2`
12	`unit_price` missing
13	an exact duplicate of row 1
14	empty `country`

Two reasons. Each finding traces to one visible cause, so a reader learns what a detector is for. And the same database produces the same 15 issues and the same 94.7 on every machine, which is what makes the documented output checkable rather than illustrative.

The verified run

$ python create_database.py
wrote shop.db with 14 rows

$ datasentry scan shop.db --table orders
{ "status": "failed", "row_count": 14, "total_issues": 15,
  "issues_count": {"info":0,"low":5,"medium":9,"high":1,"critical":0},
  "detector_runs": 39, "quality_score": 94.7 }

$ datasentry score
Overall quality score: 94.7  (score_version=1)
  completeness      98.9   validity  91.0   uniqueness  93.9

$ datasentry report export latest --as html
{ "path": ".datasentry/reports/latest.html", "format": "html" }

Two things the README explains rather than glosses over, because both would otherwise read as bugs on a first run:

"status": "failed" is the gate, not a crash. The scan ran; the data did not pass. Saying so is what makes the CI use case land.
consistency, integrity and timeliness read None. Nothing in a single-table first scan can score them — they need a contract or a previous scan — and the weights renormalize across the dimensions that were scored, so an absent dimension does not quietly count as a pass.

Constraints

Synthetic data only; no network, credentials or API keys
No detector or connector changes — documentation and one fixture script
No DataSentry logic duplicated: the script writes rows and stops, everything else is the public CLI
Repairs are out, per the constraint. datasentry repair is a reviewed propose → preview → apply loop, and the README says so explicitly and links to examples/demo/ rather than silently omitting it

Linked from examples/README.md in the goal table, placed above the ecommerce row since it is the smaller starting point.

The shortest path from a database a user already has to a list of findings: build a local table, scan it, read the issues and the score. No external service, credentials, API key or LLM. create_database.py plants one flaw per row -- an impossible date, a malformed email, a negative quantity, a missing price, an exact duplicate and an empty country -- rather than corrupting rows randomly, so each finding maps to an obvious cause and the output is identical on every machine. Every command and every block of output in the README was captured from a clean run of this example. Repairs are deliberately left out and pointed at examples/demo/, since they are a reviewed step rather than a first-run one.