Skip to content

Commit 3743392

Browse files
author
Lukas Geiger
committed
docs: improve SQLiteViewer discoverability
1 parent ee415cc commit 3743392

3 files changed

Lines changed: 138 additions & 172 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
## [Unreleased]
44

55
### Added
6+
- `llms.txt` with canonical repository, use cases, key files, discovery phrases, and boundaries for LLM/search crawlers.
67
- Local release bundle workflow documented for the ignored `releases/` workspace; public source files stay lightweight.
78
- Application icon support in the Tk window.
89
- Optional startup argument for opening a database file directly.
@@ -14,6 +15,7 @@
1415
- Local WACK notes remain in the ignored `releases/windowsstore/` workspace; public root docs now describe only the source-controlled workflow.
1516

1617
### Changed
18+
- README is now English-first with a Start Here table, clearer local-first positioning, search/disambiguation context, and repaired German umlauts.
1719
- README now embeds the existing GUI screenshot from `README/screenshots/main.png`.
1820
- Repository URLs and community health files now point to `file-bricks/SQLiteViewer`.
1921
- `START.bat` now forwards command-line arguments and reports missing Python cleanly.

‎README.md‎

Lines changed: 93 additions & 172 deletions
Original file line numberDiff line numberDiff line change
@@ -1,190 +1,85 @@
1-
# SQLite Viewer Pro
1+
# SQLiteViewer
22

3-
Ein leichtgewichtiger, schneller SQLite-Datenbank-Browser mit Python und Tkinter. Öffne, durchsuche und analysiere jede SQLite-Datenbank -- ohne SQL-Kenntnisse.
3+
Local-first SQLite database browser for Windows, Linux, and macOS. Open a `.db`, `.sqlite`, or `.sqlite3` file, inspect tables, search rows, run SQL, and export CSV or JSON without sending database content anywhere.
44

55
![Python](https://img.shields.io/badge/Python-3.10+-blue)
66
![License](https://img.shields.io/badge/License-MIT-green)
77
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)
88

9-
## Funktionen
9+
## Start Here
1010

11-
- **Tabellen-Browser** - Listet alle Tabellen mit sortierbarem Datenraster auf
12-
- **Schema-Ansicht** - CREATE TABLE Statements mit Syntax-Highlighting anzeigen
13-
- **SQL-Editor** - Eigene Abfragen mit Syntax-Highlighting und Ergebnisansicht ausführen
14-
- **Volltextsuche** - Echtzeit-Suche über alle Spalten
15-
- **CSV-Export** - Tabellen oder Abfrageergebnisse als CSV exportieren
16-
- **JSON-Export** - Sichtbare Ergebnisse optional als `sqliteviewer-export-v1.json` mit Metadaten exportieren
17-
- **Sortierung** - Spaltenköpfe anklicken für auf-/absteigende Sortierung
18-
- **Tastenkürzel** - Ctrl+O (Öffnen), Ctrl+F (Suche), Ctrl+E (Export), F5 (Aktualisieren), F9 (SQL ausführen)
19-
- **Direktstart mit Datei** - Optional eine Datenbankdatei beim Start übergeben
11+
| Need | Start with |
12+
|---|---|
13+
| Browse a local SQLite database | `python SQLiteViewer.py path/to/database.sqlite` |
14+
| Inspect tables and schema | Data and Schema tabs |
15+
| Run a custom query | SQL Editor tab, then `F9` |
16+
| Export visible data | `File > Export as CSV` or `File > Export as JSON` |
17+
| Build a Windows package | `SQLiteViewer.spec`, `build_exe.bat`, and `STORE_LISTING.md` |
18+
| Machine-readable project summary | [`llms.txt`](llms.txt) |
2019

21-
## Screenshots
20+
## Screenshot
2221

23-
![SQLite Viewer Pro - Hauptfenster](README/screenshots/main.png)
22+
![SQLiteViewer main window](README/screenshots/main.png)
2423

25-
Die aktuelle Aufnahme zeigt den Daten-Browser mit den integrierten Tabs für Schema-Ansicht und SQL-Editor.
24+
The screenshot shows the table browser with the integrated schema and SQL workflow tabs.
2625

27-
### Daten-Browser
28-
Öffne beliebige `.db`-, `.sqlite`- oder `.sqlite3`-Dateien und durchsuche Tabellen sofort.
26+
## Why This Exists
2927

30-
### Schema-Ansicht
31-
Tabellenstrukturen mit syntaxhervorgehobenen CREATE TABLE Statements anzeigen.
28+
SQLiteViewer is meant for quick local inspection of small and medium SQLite files: app databases, exported research data, test fixtures, prototype storage, and support/debugging snapshots. It stays intentionally small and portable:
3229

33-
### SQL-Editor
34-
SQL-Abfragen mit Echtzeit-Syntax-Highlighting schreiben und ausführen.
30+
- **Local-first**: database files remain on your machine.
31+
- **No service account**: no hosted backend, telemetry, or cloud sync.
32+
- **No heavyweight install**: Python standard library plus Tkinter.
33+
- **Readable export**: CSV for spreadsheets, JSON for companion workflows.
34+
- **Simple handoff**: a single source file plus documented Store packaging assets.
3535

36-
## Installation
36+
## Features
3737

38-
### Voraussetzungen
38+
- **Table browser**: list tables and browse rows in a sortable grid.
39+
- **Schema view**: inspect `CREATE TABLE` statements with syntax highlighting.
40+
- **SQL editor**: run custom queries and view result sets.
41+
- **Search**: filter visible table rows across columns.
42+
- **CSV export**: export selected table or query output.
43+
- **JSON export**: write `sqliteviewer-export-v1.json` with source metadata and rows.
44+
- **Direct file launch**: pass a database path when starting the app.
45+
- **Keyboard shortcuts**: `Ctrl+O`, `Ctrl+F`, `Ctrl+E`, `F5`, and `F9`.
3946

40-
- Python 3.10 oder höher
41-
- Tkinter (bei den meisten Python-Installationen enthalten)
47+
## Install And Run
4248

43-
Keine zusätzlichen Abhängigkeiten -- nutzt ausschließlich die Python-Standardbibliothek.
49+
Requirements:
4450

45-
### Aus dem Quellcode starten
51+
- Python 3.10 or newer
52+
- Tkinter, included with most Python distributions
4653

47-
```bash
48-
git clone https://github.com/file-bricks/SQLiteViewer.git
49-
cd SQLiteViewer
50-
python SQLiteViewer.py
51-
```
52-
53-
### Windows
54-
55-
Doppelklick auf `START.bat` oder:
56-
57-
```cmd
58-
python SQLiteViewer.py
59-
```
60-
61-
Eine Datenbank kann direkt beim Start geöffnet werden:
62-
63-
```cmd
64-
python SQLiteViewer.py pfad\zur\datenbank.sqlite
65-
```
66-
67-
## Verwendung
68-
69-
1. **Datenbank öffnen**: `File > Open Database`, `Ctrl+O` oder per Startargument
70-
2. **Tabellen durchsuchen**: Tabelle aus dem Dropdown wählen
71-
3. **Suchen**: Im Suchfeld tippen, um Zeilen zu filtern
72-
4. **Schema ansehen**: Zum Schema-Tab wechseln
73-
5. **SQL ausführen**: Zum SQL-Editor-Tab wechseln, Abfrage schreiben, `F9` drücken
74-
6. **Exportieren**: `File > Export as CSV`, `Ctrl+E` oder `File > Export as JSON`
75-
76-
## Tastenkürzel
77-
78-
| Kürzel | Aktion |
79-
|---------|--------|
80-
| `Ctrl+O` | Datenbank öffnen |
81-
| `Ctrl+Q` | Beenden |
82-
| `Ctrl+E` | CSV exportieren |
83-
| `Ctrl+F` | Suchfeld fokussieren |
84-
| `Ctrl+A` | Alle Zeilen markieren |
85-
| `F5` | Tabelle aktualisieren |
86-
| `F9` | SQL-Abfrage ausführen |
87-
88-
Der JSON-Export ist bewusst additiv gehalten: CSV bleibt der schnellste Standardpfad, während `sqliteviewer-export-v1.json` die aktuelle Ansicht inklusive Metadaten für Companion-Workflows festhält. Details stehen in `EXPORTFORMAT.md`.
89-
90-
## Vergleich
91-
92-
| Funktion | SQLite Viewer Pro | DB Browser | DBeaver |
93-
|----------|:-----------------:|:----------:|:-------:|
94-
| Sofortiger Start | Ja | Langsam | Langsam |
95-
| SQL-Abfragen | Ja | Ja | Ja |
96-
| Tabellen durchsuchen | Ja | Ja | Ja |
97-
| Schema-Ansicht | Ja | Ja | Ja |
98-
| CSV-Export | Ja | Ja | Ja |
99-
| Volltextsuche | Ja | Eingeschränkt | Ja |
100-
| Portabel | Ja | Teilweise | Nein |
101-
| Leichtgewichtig | Ja | Nein | Nein |
102-
| Keine Installation | Ja | Nein | Nein |
103-
104-
## Technische Details
105-
106-
- **Framework**: Tkinter + ttk
107-
- **Datenbank**: sqlite3 (stdlib)
108-
- **Abhängigkeiten**: Keine (reines Python stdlib)
109-
- **Einzelne Datei**: ~780 Zeilen Python
110-
111-
---
112-
113-
## English
114-
115-
A lightweight, fast SQLite database browser built with Python and Tkinter. Open, browse, search and query any SQLite database without SQL knowledge.
116-
117-
### Features
118-
119-
- **Table Browser** - Automatically lists all tables with sortable data grid
120-
- **Schema View** - Inspect CREATE TABLE statements with syntax highlighting
121-
- **SQL Editor** - Execute custom queries with syntax highlighting and result view
122-
- **Full-Text Search** - Search across all columns in real-time
123-
- **CSV Export** - Export any table or query result to CSV
124-
- **JSON Export** - Optionally export the visible result set as `sqliteviewer-export-v1.json` with metadata
125-
- **Sorting** - Click column headers to sort ascending/descending
126-
- **Keyboard Shortcuts** - Ctrl+O (open), Ctrl+F (search), Ctrl+E (export), F5 (refresh), F9 (execute SQL)
127-
- **Direct file launch** - Optionally pass a database file when starting the app
128-
129-
### Screenshots
130-
131-
![SQLite Viewer Pro - Main Window](README/screenshots/main.png)
132-
133-
The current screenshot shows the data browser together with the integrated schema and SQL workflow tabs.
134-
135-
#### Data Browser
136-
Open any `.db`, `.sqlite`, or `.sqlite3` file and browse tables instantly.
137-
138-
#### Schema View
139-
View table definitions with syntax-highlighted CREATE TABLE statements.
140-
141-
#### SQL Editor
142-
Write and execute SQL queries with real-time syntax highlighting.
143-
144-
### Installation
145-
146-
#### Requirements
147-
148-
- Python 3.10 or higher
149-
- Tkinter (included with most Python installations)
150-
151-
No additional dependencies required - uses only Python standard library.
152-
153-
#### Run from Source
54+
Run from source:
15455

15556
```bash
15657
git clone https://github.com/file-bricks/SQLiteViewer.git
15758
cd SQLiteViewer
15859
python SQLiteViewer.py
15960
```
16061

161-
#### Windows
162-
163-
Double-click `START.bat` or run:
62+
Open a database directly:
16463

165-
```cmd
166-
python SQLiteViewer.py
64+
```bash
65+
python SQLiteViewer.py path/to/database.sqlite
16766
```
16867

169-
You can open a database directly at startup:
68+
On Windows you can also double-click `START.bat`.
17069

171-
```cmd
172-
python SQLiteViewer.py path\to\database.sqlite
173-
```
70+
## Usage
17471

175-
### Usage
72+
1. Open a database with `File > Open Database`, `Ctrl+O`, or a startup argument.
73+
2. Select a table from the dropdown.
74+
3. Type into the search field to filter visible rows.
75+
4. Switch to the Schema tab to inspect table definitions.
76+
5. Switch to the SQL Editor tab, write a query, and press `F9`.
77+
6. Export via `File > Export as CSV` or `File > Export as JSON`.
17678

177-
1. **Open a database**: `File > Open Database`, `Ctrl+O`, or a startup argument
178-
2. **Browse tables**: Select a table from the dropdown
179-
3. **Search**: Type in the search field to filter rows
180-
4. **View schema**: Switch to the Schema tab
181-
5. **Run SQL**: Switch to the SQL Editor tab, write a query, press `F9`
182-
6. **Export**: `File > Export as CSV`, `Ctrl+E`, or `File > Export as JSON`
183-
184-
### Keyboard Shortcuts
79+
## Keyboard Shortcuts
18580

18681
| Shortcut | Action |
187-
|----------|--------|
82+
|---|---|
18883
| `Ctrl+O` | Open database |
18984
| `Ctrl+Q` | Quit |
19085
| `Ctrl+E` | Export CSV |
@@ -193,40 +88,66 @@ python SQLiteViewer.py path\to\database.sqlite
19388
| `F5` | Refresh table |
19489
| `F9` | Execute SQL query |
19590

196-
The JSON export stays intentionally additive: CSV remains the default fast path, while `sqliteviewer-export-v1.json` captures the current visible result plus metadata for companion workflows. See `EXPORTFORMAT.md` for details.
91+
## Export Format
92+
93+
CSV remains the fastest default export path. The JSON export is additive and intended for companion tools, reproducible support handoffs, or LLM-assisted inspection where metadata matters.
94+
95+
See [`EXPORTFORMAT.md`](EXPORTFORMAT.md) for the `sqliteviewer-export-v1.json` contract.
96+
97+
## Search Context
19798

198-
### Comparison
99+
This repository is `file-bricks/SQLiteViewer`: a Python/Tkinter desktop SQLite viewer. It is different from DB Browser for SQLite, DBeaver, Android SQLite viewer apps, iOS debug libraries, and web-based database admin panels. Useful search phrases include:
199100

200-
| Feature | SQLite Viewer Pro | DB Browser | DBeaver |
201-
|---------|:-----------------:|:----------:|:-------:|
202-
| Instant startup | Yes | Slow | Slow |
101+
- `file-bricks SQLiteViewer`
102+
- `local-first SQLite viewer Python Tkinter`
103+
- `portable SQLite database browser with CSV JSON export`
104+
- `offline SQLite browser for Windows Python`
105+
- `SQLite table browser SQL editor Tkinter`
106+
107+
## Comparison
108+
109+
| Feature | SQLiteViewer | DB Browser for SQLite | DBeaver |
110+
|---|:---:|:---:|:---:|
111+
| Local file browsing | Yes | Yes | Yes |
203112
| SQL queries | Yes | Yes | Yes |
204-
| Browse tables | Yes | Yes | Yes |
205113
| Schema view | Yes | Yes | Yes |
206114
| CSV export | Yes | Yes | Yes |
207-
| Full-text search | Yes | Limited | Yes |
208-
| Portable | Yes | Partial | No |
209-
| Lightweight | Yes | No | No |
210-
| No install needed | Yes | No | No |
115+
| JSON companion export | Yes | No | Partial |
116+
| Python standard library core | Yes | No | No |
117+
| Lightweight source checkout | Yes | Partial | No |
118+
| No account or backend | Yes | Yes | Yes |
119+
120+
## Technical Details
211121

212-
### Technical Details
122+
- **Framework**: Tkinter and ttk
123+
- **Database access**: Python `sqlite3`
124+
- **Runtime dependencies**: Python standard library
125+
- **Primary entrypoint**: `SQLiteViewer.py`
126+
- **Packaging**: `SQLiteViewer.spec`, `build_exe.bat`, `store_package.json`
127+
- **License**: MIT
213128

214-
- **Framework**: Tkinter + ttk
215-
- **Database**: sqlite3 (stdlib)
216-
- **Dependencies**: None (pure Python stdlib)
217-
- **Single file**: ~780 lines of Python
129+
## Deutsch
130+
131+
SQLiteViewer ist ein lokaler SQLite-Datenbank-Browser für Windows, Linux und macOS. Datenbankdateien bleiben auf deinem Rechner; es gibt keinen Cloud-Dienst, keine Telemetrie und kein Konto.
132+
133+
Kurzer Einstieg:
134+
135+
- Datenbank öffnen: `python SQLiteViewer.py pfad/zur/datenbank.sqlite`
136+
- Tabellen durchsuchen: Data-Tab und Suchfeld
137+
- Schema ansehen: Schema-Tab
138+
- SQL ausführen: SQL-Editor, dann `F9`
139+
- Exportieren: CSV oder `sqliteviewer-export-v1.json`
140+
141+
Die wichtigsten deutschen Endnutzertexte verwenden echte Umlaute. Falls du neue deutschsprachige Texte ergänzt, bitte keine Ersatzschreibweisen wie `ae`, `oe` oder `ue` verwenden, sofern echte Umlaute gemeint sind.
218142

219143
## License
220144

221145
[MIT](LICENSE)
222146

223-
---
224-
225147
## Haftung / Liability
226148

227-
Dieses Projekt ist eine **unentgeltliche Open-Source-Schenkung** im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß **§ 521 BGB** auf **Vorsatz und grobe Fahrlässigkeit** beschränkt. Ergänzend gilt der Haftungsausschluss der MIT-Lizenz.
149+
Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß § 521 BGB auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gilt der Haftungsausschluss der MIT-Lizenz.
228150

229151
Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.
230152

231153
This project is an unpaid open-source donation. Liability is limited to intent and gross negligence (§ 521 German Civil Code). Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.
232-

‎llms.txt‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# SQLiteViewer
2+
3+
Canonical repository: https://github.com/file-bricks/SQLiteViewer
4+
5+
SQLiteViewer is a local-first Python/Tkinter desktop application for opening, browsing, searching, querying, and exporting SQLite database files. It is maintained under the `file-bricks` GitHub organization.
6+
7+
## Primary Use Cases
8+
9+
- Inspect `.db`, `.sqlite`, and `.sqlite3` files locally.
10+
- Browse tables and schema without a hosted backend.
11+
- Run custom SQL queries in a lightweight desktop UI.
12+
- Export visible rows to CSV or `sqliteviewer-export-v1.json`.
13+
- Package a simple Windows desktop release from source.
14+
15+
## Key Files
16+
17+
- `SQLiteViewer.py`: main desktop application.
18+
- `README.md`: user-facing landing page and quickstart.
19+
- `README/screenshots/main.png`: current UI screenshot.
20+
- `EXPORTFORMAT.md`: JSON companion export contract.
21+
- `CHANGELOG.md`: project history.
22+
- `STORE_LISTING.md`: Windows Store-style listing text.
23+
- `SQLiteViewer.spec`: PyInstaller build specification.
24+
- `build_exe.bat`: Windows build helper.
25+
- `tests/`: regression tests for SQL execution and screenshot tooling.
26+
27+
## Discovery Phrases
28+
29+
- file-bricks SQLiteViewer
30+
- local-first SQLite viewer Python Tkinter
31+
- portable SQLite database browser with CSV JSON export
32+
- offline SQLite browser for Windows Python
33+
- SQLite table browser SQL editor Tkinter
34+
35+
## Boundaries
36+
37+
- SQLiteViewer is not DB Browser for SQLite, DBeaver, an Android SQLite viewer, an iOS debug library, or a web database admin panel.
38+
- It is local-first and does not upload database content.
39+
- It is a lightweight desktop utility, not a multi-user database management system.
40+
41+
## License
42+
43+
MIT.

0 commit comments

Comments
 (0)