sqlitexplorer 1.0.0__py3-none-any.whl

sqlitexplorer/shell.py

@@ -0,0 +1,254 @@
+"""Interactive shell (REPL) on top of an open :class:`Explorer`.
+
+Statements are accumulated until :func:`sqlite3.complete_statement` says they
+are complete, then executed one by one. Lines starting with a dot are shell
+commands. readline (history and Tab completion) is used when available and
+the session is interactive.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import sys
+from collections.abc import Callable
+from contextlib import suppress
+from pathlib import Path
+
+import typer
+
+from sqlitexplorer.core import Explorer, ExplorerError, split_statements, translate_error
+from sqlitexplorer.render import OutputFormat, OutputOptions, emit, emit_stream, ok_message
+
+__all__ = ["Completer", "DOT_COMMANDS", "SQL_KEYWORDS", "history_path", "run_shell"]
+
+PROMPT = "sqlitexplorer> "
+CONTINUATION = "        ...> "
+
+SQL_KEYWORDS = (
+    "ALL", "ALTER", "AND", "AS", "ASC", "ATTACH", "BEGIN", "BETWEEN", "BLOB", "BY",
+    "CASE", "COMMIT", "COUNT", "CREATE", "DATABASE", "DELETE", "DESC", "DETACH",
+    "DISTINCT", "DROP", "ELSE", "END", "EXISTS", "EXPLAIN", "FROM", "GROUP", "HAVING",
+    "IN", "INDEX", "INNER", "INSERT", "INTEGER", "INTO", "IS", "JOIN", "KEY", "LEFT",
+    "LIKE", "LIMIT", "MAX", "MIN", "NOT", "NULL", "OFFSET", "ON", "OR", "ORDER",
+    "OUTER", "PLAN", "PRAGMA", "PRIMARY", "QUERY", "REAL", "ROLLBACK", "SELECT",
+    "SET", "SUM", "TABLE", "TEXT", "THEN", "UNION", "UPDATE", "VALUES", "VIEW",
+    "WHEN", "WHERE", "WITH",
+)  # fmt: skip
+
+DOT_COMMANDS = {
+    ".tables": "list tables and views with their row counts",
+    ".schema": "[NAME]  print CREATE statements",
+    ".describe": "TABLE  show the columns of a table or view",
+    ".indexes": "[TABLE]  list indexes",
+    ".stats": "TABLE  per-column statistics",
+    ".format": "table|csv|tsv|json|markdown  change the output format",
+    ".null": "TEXT  text shown for NULL values",
+    ".truncate": "N|off  truncate long values",
+    ".help": "show this help",
+    ".quit": "leave the shell (also .exit or Ctrl-D)",
+}
+
+
+class Completer:
+    """readline completer over dot-commands, SQL keywords, table and column names."""
+
+    def __init__(self, db: Explorer) -> None:
+        self._db = db
+        self._matches: list[str] = []
+
+    def candidates(self) -> list[str]:
+        names: list[str] = []
+        try:
+            for table in self._db.names():
+                names.append(table)
+                names.extend(self._db.column_names(table))
+        except (ExplorerError, sqlite3.Error):
+            pass
+        return names
+
+    def __call__(self, text: str, state: int) -> str | None:
+        if state == 0:
+            pool = (
+                list(DOT_COMMANDS) if text.startswith(".") else [*SQL_KEYWORDS, *self.candidates()]
+            )
+            lowered = text.lower()
+            matches = {item for item in pool if item.lower().startswith(lowered)}
+            self._matches = sorted(matches, key=str.lower)
+        return self._matches[state] if state < len(self._matches) else None
+
+
+def history_path() -> Path:
+    base = os.environ.get("XDG_STATE_HOME") or str(Path.home() / ".local" / "state")
+    return Path(base) / "sqlitexplorer" / "history"
+
+
+def _setup_readline(completer: Completer) -> Callable[[], None] | None:
+    """Configure readline if available; return a function that saves the history."""
+    try:
+        import readline
+    except ImportError:
+        return None
+    readline.set_completer(completer)
+    readline.set_completer_delims(" \t\n,;()")
+    if "libedit" in (readline.__doc__ or ""):
+        readline.parse_and_bind("bind ^I rl_complete")
+    else:
+        readline.parse_and_bind("tab: complete")
+    readline.set_history_length(1000)
+    path = history_path()
+    with suppress(OSError):
+        readline.read_history_file(path)
+
+    def save() -> None:
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            readline.write_history_file(path)
+        except OSError:
+            pass
+
+    return save
+
+
+def _read_piped_line(prompt: str) -> str:
+    line = sys.stdin.readline()
+    if not line:
+        raise EOFError
+    return line.rstrip("\r\n")
+
+
+def run_shell(
+    db: Explorer,
+    *,
+    options: OutputOptions,
+    write: bool,
+    interactive: bool,
+    report_error: Callable[[ExplorerError], None],
+) -> None:
+    """Read statements and dot-commands until EOF or ``.quit``."""
+    save_history = _setup_readline(Completer(db)) if interactive else None
+    read_line = input if interactive else _read_piped_line
+    buffer = ""
+    try:
+        while True:
+            try:
+                line = read_line(CONTINUATION if buffer else PROMPT)
+            except KeyboardInterrupt:
+                if not interactive:
+                    return
+                typer.echo("")
+                buffer = ""
+                continue
+            except EOFError:
+                if buffer.strip():
+                    _run_sql(db, buffer, options=options, write=write, report_error=report_error)
+                if interactive:
+                    typer.echo("")
+                return
+            stripped = line.strip()
+            if not buffer and stripped.startswith("."):
+                if not _dot_command(db, stripped, options=options, report_error=report_error):
+                    return
+                continue
+            if not buffer and not stripped:
+                continue
+            buffer = f"{buffer}\n{line}" if buffer else line
+            if sqlite3.complete_statement(buffer):
+                _run_sql(db, buffer, options=options, write=write, report_error=report_error)
+                buffer = ""
+    finally:
+        if save_history is not None:
+            save_history()
+
+
+def _run_sql(
+    db: Explorer,
+    sql: str,
+    *,
+    options: OutputOptions,
+    write: bool,
+    report_error: Callable[[ExplorerError], None],
+) -> None:
+    for statement in split_statements(sql):
+        try:
+            stream = db.stream(statement)
+            if stream.returns_rows:
+                emit_stream(stream, options)
+            else:
+                typer.echo(ok_message(stream))
+        except ExplorerError as error:
+            report_error(error)
+        except sqlite3.Error as error:
+            if write:
+                db.rollback()
+            report_error(translate_error(error, write=write))
+            return
+        if write:
+            db.commit()
+
+
+def _dot_command(
+    db: Explorer,
+    line: str,
+    *,
+    options: OutputOptions,
+    report_error: Callable[[ExplorerError], None],
+) -> bool:
+    """Run one dot-command. Returns False when the shell should exit."""
+    command, _, argument = line.partition(" ")
+    argument = argument.strip()
+    try:
+        if command in (".quit", ".exit"):
+            return False
+        if command == ".help":
+            for name, description in DOT_COMMANDS.items():
+                typer.echo(f"{name:<11}{description}")
+        elif command == ".tables":
+            emit(db.tables(), options, empty="(no tables)")
+        elif command == ".schema":
+            statements = db.schema(argument or None)
+            typer.echo("\n\n".join(f"{s};" for s in statements) if statements else "(empty schema)")
+        elif command == ".describe":
+            emit(db.columns(_required(argument, command)), options)
+        elif command == ".indexes":
+            emit(db.indexes(argument or None), options, empty="(no indexes)")
+        elif command == ".stats":
+            emit(db.stats(_required(argument, command)).result, options)
+        elif command == ".format":
+            options.format = _parse_format(argument)
+        elif command == ".null":
+            options.null = argument
+        elif command == ".truncate":
+            options.truncate = _parse_truncate(argument)
+        else:
+            raise ExplorerError(f"unknown command {command}, try .help")
+    except ExplorerError as error:
+        report_error(error)
+    except sqlite3.Error as error:
+        report_error(translate_error(error, write=False))
+    return True
+
+
+def _required(argument: str, command: str) -> str:
+    if not argument:
+        raise ExplorerError(f"usage: {command} TABLE")
+    return argument
+
+
+def _parse_format(argument: str) -> OutputFormat:
+    try:
+        return OutputFormat(argument.lower())
+    except ValueError:
+        choices = ", ".join(fmt.value for fmt in OutputFormat)
+        raise ExplorerError(
+            f"unknown format: {argument or '(none)'}; choose from {choices}"
+        ) from None
+
+
+def _parse_truncate(argument: str) -> int | None:
+    if argument.lower() in ("", "off"):
+        return None
+    try:
+        return max(1, int(argument))
+    except ValueError:
+        raise ExplorerError("usage: .truncate N|off") from None

sqlitexplorer-1.0.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: sqlitexplorer
+Version: 1.0.0
+Summary: Explore SQLite databases from the terminal: tables, schema, stats, search, queries, charts, export/import and an interactive shell.
+Author-email: "Carlos A. Planchón" <carlosandresplanchonprestes@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/carlosplanchon/sqlitexplorer.git
+Keywords: sqlite,sqlite3,database,cli,terminal,explorer,chart,shell,repl
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: outfancy>=0.11
+Requires-Dist: plotille>=6
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# sqlitexplorer
+
+![sqlitexplorer banner](https://raw.githubusercontent.com/carlosplanchon/sqlitexplorer/master/assets/banner.jpg)
+
+A command-line explorer for SQLite databases. It lists tables, prints schemas,
+dumps rows, computes statistics, searches values, runs ad-hoc queries, draws
+charts, exports and imports data, and offers an interactive shell. Tables are
+rendered with [outfancy](https://github.com/carlosplanchon/outfancy) and charts
+with [plotille](https://github.com/tammoippen/plotille).
+
+[![CI](https://github.com/carlosplanchon/sqlitexplorer/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosplanchon/sqlitexplorer/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/sqlitexplorer.svg)](https://pypi.org/project/sqlitexplorer/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sqlitexplorer.svg)](https://pypi.org/project/sqlitexplorer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/carlosplanchon/sqlitexplorer)
+
+## Installation
+
+Requires Python 3.10 or newer.
+
+```sh
+# From a clone of this repository:
+uv tool install .
+# or with pip:
+pip install .
+```
+
+## Quick tour
+
+```sh
+sqlitexplorer tables app.db                     # tables and views with their row counts
+sqlitexplorer schema app.db [users]             # CREATE statements, in creation order
+sqlitexplorer describe app.db users             # columns: type, NOT NULL, default, primary key
+sqlitexplorer indexes app.db [users]            # indexes and the columns they cover
+sqlitexplorer foreign-keys app.db [posts]       # foreign keys
+sqlitexplorer info app.db [--check]             # size, pragmas, object counts, integrity check
+sqlitexplorer show app.db users                 # rows of a table or view
+sqlitexplorer stats app.db users                # nulls, distinct, min, max, top values per column
+sqlitexplorer search app.db "marie"             # find a text in every column of every table
+sqlitexplorer query app.db "SELECT ..."         # run SQL
+sqlitexplorer chart app.db "SELECT day, total FROM sales ORDER BY day"
+sqlitexplorer dump app.db                       # the whole database as SQL
+sqlitexplorer export app.db users -o users.csv  # rows to a file
+sqlitexplorer import app.db people people.csv   # a file into a table
+sqlitexplorer diff app.db backup.db             # compare two schemas
+sqlitexplorer shell app.db                      # interactive shell
+```
+
+Every command has `--help`. Databases are opened read-only and are never
+created; commands that change data need `--write`, except `import`, which
+always writes.
+
+## Exploring
+
+`show` accepts filters so most questions need no SQL:
+
+```sh
+sqlitexplorer show app.db users -c name,age --where "age > 18" --order-by age --desc -n 20 --offset 40
+```
+
+`--columns` and `--order-by` are validated against the table; `--where` is a
+raw SQL condition.
+
+`stats` reports, for each column, the declared type, how many NULLs, how many
+distinct values, the minimum, the maximum and the most frequent values
+(`--top N`). Everything but the frequent values comes from a single pass over
+the table; on big tables use `--top 0` to skip them, `--columns` to analyse
+only some columns, or `--sample N` to work on a random sample of N rows (the
+output then says so). Likewise `tables --no-count` skips the row counts.
+
+`search` looks for a case-insensitive substring in every non-BLOB column of
+every table (`--table` restricts it, `--limit` stops early) and prints the
+table, column, rowid and value of each match. Each table is scanned once.
+
+## Output options
+
+Every command that prints rows takes the same options:
+
+| Option | Effect |
+|---|---|
+| `--format`, `-f` | `table` (default), `csv`, `tsv`, `json` or `markdown` |
+| `--null TEXT` | text shown for NULL values (default `NULL`) |
+| `--truncate N` | cut values longer than N characters |
+| `--page N`, `--page-size M` | print only one page of the rows; the footer goes to stderr |
+| `--pager` | send the output to `$PAGER` (default `less -R`) when on a terminal |
+| `--color` / `--no-color` | force or disable ANSI colors; by default only on a terminal, never when `NO_COLOR` is set |
+| `--width N` | width to fit tables into (default: the terminal width) |
+
+`NULL` and `BLOB` values are printed as SQL literals (`NULL`, `X'0102'`). In
+the JSON format NULL becomes `null`, BLOBs are base64 strings and values are
+never truncated.
+
+When a table is wider than the terminal, the widest columns are narrowed and
+their values wrapped so that every column and label stays visible. Use
+`--width` or another format to get the values on one line.
+
+Big results do not need to fit in memory: `--page` fetches only the requested
+page (in SQL for `show`, from the cursor for `query`), and the csv, tsv, json
+and markdown formats, `export` and `dump` are written row by row. The table
+format is the exception, since it needs every row to size its columns.
+
+## Queries
+
+```sh
+sqlitexplorer query app.db "SELECT name, age FROM users WHERE age > :min" -p min=30
+sqlitexplorer query app.db --file report.sql            # several statements, one transaction
+echo "SELECT COUNT(*) FROM users" | sqlitexplorer query app.db -
+sqlitexplorer query app.db "SELECT ..." --attach old=backup.db   # then use old.users
+sqlitexplorer query app.db "SELECT ..." --explain        # EXPLAIN QUERY PLAN as a tree
+sqlitexplorer query app.db "SELECT ..." --time           # rows and elapsed time on stderr
+sqlitexplorer query app.db "SELECT COUNT(*) FROM jobs" --watch 2   # re-run every 2 s, Ctrl-C stops
+sqlitexplorer query app.db "DELETE FROM users WHERE age IS NULL" --write
+```
+
+Several statements can be given at once (separated by `;`); they run in one
+transaction that is committed at the end and rolled back on the first error.
+`--param` values that look like numbers are bound as numbers. Attached
+databases follow the read-only rule of the main one.
+
+## Charts
+
+```sh
+sqlitexplorer chart app.db "SELECT day, sales, returns FROM daily ORDER BY day"
+sqlitexplorer chart app.db "SELECT age FROM users" --kind hist --bins 20
+```
+
+The first column is the X axis (numbers or ISO dates), every other column is a
+series named after the column; rows with NULLs are skipped and counted on
+stderr. `--kind` selects `line` (default), `scatter` or `hist` (first column
+only, `--bins`). `--height`, `--width`, `--x-label`, `--y-label` and `--color`
+adjust the drawing.
+
+## Export, import, dump and diff
+
+```sh
+sqlitexplorer dump app.db -o backup.sql                  # replayable SQL, like .dump
+sqlitexplorer export app.db users -f json -o users.json
+sqlitexplorer export app.db --all -o exported/ -f csv    # one file per table and view
+sqlitexplorer import app.db people people.csv            # csv, tsv or json (list of objects)
+sqlitexplorer diff app.db backup.db                      # exit status 1 when the schemas differ
+```
+
+`import` creates the table when it does not exist, inferring INTEGER, REAL or
+TEXT for each column; empty CSV cells become NULL. The format comes from the
+file extension unless `--format` is given.
+
+## Shell
+
+```
+$ sqlitexplorer shell app.db
+sqlitexplorer> SELECT name
+        ...> FROM users;
+sqlitexplorer> .tables
+sqlitexplorer> .format json
+sqlitexplorer> .quit
+```
+
+Statements end with `;` and may span several lines. Dot-commands: `.tables`,
+`.schema [NAME]`, `.describe TABLE`, `.indexes [TABLE]`, `.stats TABLE`,
+`.format FORMAT`, `.null TEXT`, `.truncate N|off`, `.help` and `.quit`. Tab
+completes SQL keywords, table and column names; the history is kept in
+`$XDG_STATE_HOME/sqlitexplorer/history` (`~/.local/state` by default). With
+`--write` every statement is committed as soon as it succeeds. SQL can also be
+piped into the shell.
+
+Completion of the command line itself (commands, options and table names) is
+installed with `sqlitexplorer --install-completion`.
+
+## Development
+
+```sh
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest
+uv run ruff check .
+```
+
+## Releasing
+
+Releases are driven by version tags. Pushing `vX.Y.Z` runs the tests, builds
+the distributions, publishes them to PyPI with
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) and creates a
+GitHub release with the artifacts attached.
+
+```sh
+uv version 0.3.0                      # or: uv version --bump minor
+git commit -am "Release 0.3.0"
+git tag v0.3.0
+git push origin master v0.3.0
+```
+
+The tag must match the version in `pyproject.toml`; the workflow refuses to
+publish otherwise. Before the first release, register the repository as a
+trusted publisher of the project on PyPI with the workflow name `release.yml`
+and the environment `pypi`, and create that environment in the repository
+settings on GitHub.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sqlitexplorer-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sqlitexplorer/__init__.py,sha256=_QaFu1_krQMSWzZQttAjpEWD52Y0SiYESAyN9xWQNTg,314
+sqlitexplorer/__main__.py,sha256=madQt2JWvV_1Kb-gJS-WWWZ-uZ3Cb2zpNexx0NRwH_8,118
+sqlitexplorer/charts.py,sha256=Mmf1kBygFAvFDHNVisH-zxbMLa-ZQEgTvtHq8C4zicA,6046
+sqlitexplorer/cli.py,sha256=4omMBYR-Y4qLG3CnE5rrtCgnnLpQU7K5qoQNHZmC-WY,27439
+sqlitexplorer/completion.py,sha256=BDoLHWmY5hzeWe2d5S0fZ43PUrKd6n1mztLhexThUk8,650
+sqlitexplorer/core.py,sha256=KGAo8W5m9ZCJYfd6eR2Wl6u-qYp0p6kiq70jTS5aNiE,27254
+sqlitexplorer/render.py,sha256=4_vDQtp4oNZdqv7MBxibxScKEVj0UFe0ti5Xxqhg6tI,17801
+sqlitexplorer/shell.py,sha256=0-SXpehANSLRBUgFzx__nhHy6PWmh17UJ3Y6evbcuYc,8742
+sqlitexplorer-1.0.0.dist-info/licenses/LICENSE,sha256=EntRdjOkc8SHsT_IPdTQUG8tJjiCWaAL7Cck5yS0NFs,1076
+sqlitexplorer-1.0.0.dist-info/METADATA,sha256=fn2OC2VkNtyT4jqxegPf7eCYSnNkbrc5z5X1TC1sSSo,10011
+sqlitexplorer-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sqlitexplorer-1.0.0.dist-info/entry_points.txt,sha256=XIkU6hndeYcPTlR2Skaeh9Zy0TsY9Ilq3ohoZlN1FGM,57
+sqlitexplorer-1.0.0.dist-info/top_level.txt,sha256=zt1GxOE886ZUrJim00zuouBPKudZCU0Nmv6fzcyPUjw,14
+sqlitexplorer-1.0.0.dist-info/RECORD,,

sqlitexplorer-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sqlitexplorer-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sqlitexplorer = sqlitexplorer.cli:main

sqlitexplorer-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Carlos A. Planchón
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sqlitexplorer-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sqlitexplorer