sqlitexplorer 1.0.0__tar.gz → 1.1.2__tar.gz

sqlitexplorer-1.1.2/MANIFEST.in

@@ -0,0 +1,2 @@
+graft tests
+global-exclude __pycache__ *.py[cod]

{sqlitexplorer-1.0.0/sqlitexplorer.egg-info → sqlitexplorer-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlitexplorer
-Version: 1.0.0
+Version: 1.1.2
 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
@@ -21,6 +21,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: outfancy>=0.11
 Requires-Dist: plotille>=6
+Requires-Dist: plotilleresample>=1.0
 Requires-Dist: typer>=0.12
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
@@ -35,7 +36,8 @@ 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).
+with [plotille](https://github.com/tammoippen/plotille), resampled by
+[plotilleresample](https://github.com/carlosplanchon/plotilleresample).
 
 [![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/)
@@ -127,6 +129,8 @@ 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.
+`chart` reduces as it reads, so the memory it needs does not grow with the
+table; `chart --no-resample` is the one that holds every row.
 
 ## Queries
 
@@ -159,6 +163,14 @@ stderr. `--kind` selects `line` (default), `scatter` or `hist` (first column
 only, `--bins`). `--height`, `--width`, `--x-label`, `--y-label` and `--color`
 adjust the drawing.
 
+Line and scatter charts are reduced to what the canvas can show, keeping the
+minimum and the maximum of every column of braille dots, so spikes survive and
+the true extremes keep the X of their own row. The rows are reduced as they are
+read, in chunks, so a chart over millions of rows needs no more memory than one
+over a thousand; the reduction is reported on stderr. `--no-resample` reads and
+plots every row instead. Histograms are never reduced, since dropping rows would
+change the distribution.
+
 ## Export, import, dump and diff
 
 ```sh
@@ -170,8 +182,14 @@ sqlitexplorer diff app.db backup.db                      # exit status 1 when th
 ```
 
 `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.
+TEXT for each column; values with leading zeros and integers too large for
+SQLite stay TEXT, so codes such as `007` keep their digits. Empty CSV cells
+become NULL. The format comes from the file extension unless `--format` is
+given, and `--encoding` reads a file that is not UTF-8.
+
+`export --all` writes one file per table and view inside the directory: a name
+that would not be a valid file name is sanitised, and an object that cannot be
+read (a view over a dropped table) is skipped with a warning on stderr.
 
 ## Shell
 
@@ -204,26 +222,6 @@ 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 → sqlitexplorer-1.1.2}/README.md

@@ -6,7 +6,8 @@ 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).
+with [plotille](https://github.com/tammoippen/plotille), resampled by
+[plotilleresample](https://github.com/carlosplanchon/plotilleresample).
 
 [![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/)
@@ -98,6 +99,8 @@ 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.
+`chart` reduces as it reads, so the memory it needs does not grow with the
+table; `chart --no-resample` is the one that holds every row.
 
 ## Queries
 
@@ -130,6 +133,14 @@ stderr. `--kind` selects `line` (default), `scatter` or `hist` (first column
 only, `--bins`). `--height`, `--width`, `--x-label`, `--y-label` and `--color`
 adjust the drawing.
 
+Line and scatter charts are reduced to what the canvas can show, keeping the
+minimum and the maximum of every column of braille dots, so spikes survive and
+the true extremes keep the X of their own row. The rows are reduced as they are
+read, in chunks, so a chart over millions of rows needs no more memory than one
+over a thousand; the reduction is reported on stderr. `--no-resample` reads and
+plots every row instead. Histograms are never reduced, since dropping rows would
+change the distribution.
+
 ## Export, import, dump and diff
 
 ```sh
@@ -141,8 +152,14 @@ sqlitexplorer diff app.db backup.db                      # exit status 1 when th
 ```
 
 `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.
+TEXT for each column; values with leading zeros and integers too large for
+SQLite stay TEXT, so codes such as `007` keep their digits. Empty CSV cells
+become NULL. The format comes from the file extension unless `--format` is
+given, and `--encoding` reads a file that is not UTF-8.
+
+`export --all` writes one file per table and view inside the directory: a name
+that would not be a valid file name is sanitised, and an object that cannot be
+read (a view over a dropped table) is skipped with a warning on stderr.
 
 ## Shell
 
@@ -175,26 +192,6 @@ 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 → sqlitexplorer-1.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sqlitexplorer"
-version = "1.0.0"
+version = "1.1.2"
 description = "Explore SQLite databases from the terminal: tables, schema, stats, search, queries, charts, export/import and an interactive shell."
 readme = "README.md"
 license = "MIT"
@@ -29,6 +29,7 @@ classifiers = [
 dependencies = [
     "outfancy>=0.11",
     "plotille>=6",
+    "plotilleresample>=1.0",
     "typer>=0.12",
 ]
 

{sqlitexplorer-1.0.0 → sqlitexplorer-1.1.2}/sqlitexplorer/charts.py

@@ -12,10 +12,12 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
+from itertools import islice
 
 import plotille
+import plotilleresample
 
-from sqlitexplorer.core import ExplorerError, ResultSet
+from sqlitexplorer.core import ExplorerError, ResultSet, RowStream
 
 __all__ = [
     "ChartKind",
@@ -23,7 +25,9 @@ __all__ = [
     "histogram_values",
     "render_chart",
     "render_histogram",
+    "resample_series",
     "series_from_result",
+    "stream_series",
 ]
 
 PALETTE = ("red", "green", "yellow", "blue", "magenta", "cyan")
@@ -31,6 +35,13 @@ PALETTE = ("red", "green", "yellow", "blue", "magenta", "cyan")
 AXIS_LABEL_WIDTH = 8
 # Characters taken by the Y axis (ticks, label and separator) next to the canvas.
 AXIS_WIDTH = 12
+# A tuple, not bool | int | float: the union would be rebuilt on every call,
+# and this runs once per value of the result.
+_NUMERIC = (bool, int, float)
+# Rows read at a time when streaming, and how many reduced points may pile
+# up before they are reduced again.
+_CHUNK = 65536
+_PILE = 8
 
 
 class ChartKind(str, Enum):
@@ -47,7 +58,7 @@ class Series:
 
 
 def _number(value: object) -> float | None:
-    if isinstance(value, bool | int | float):
+    if isinstance(value, _NUMERIC):
         return float(value)
     if isinstance(value, str):
         try:
@@ -69,11 +80,13 @@ def _x_value(value: object) -> float | datetime | None:
     return None
 
 
-def series_from_result(result: ResultSet) -> tuple[list[Series], int]:
+def series_from_result(result: ResultSet, *, require_rows: bool = True) -> tuple[list[Series], int]:
     """Split *result* into one series per numeric column after the first.
 
     Rows with a NULL in the X column or in any series are skipped; the second
-    item of the returned tuple counts them.
+    item of the returned tuple counts them. With *require_rows* false an empty
+    result yields empty series instead of raising, which is what the streaming
+    reader needs for a chunk that holds nothing usable.
     """
     if len(result.columns) < 2:
         raise ExplorerError("need an X column and at least one numeric column")
@@ -82,8 +95,10 @@ def series_from_result(result: ResultSet) -> tuple[list[Series], int]:
     ys: list[list[float]] = [[] for _ in y_names]
     x_type: type | None = None
     skipped = 0
+    keep_x = xs.append
+    keep = [bucket.append for bucket in ys]
     for row in result.rows:
-        if any(value is None for value in row):
+        if None in row:
             skipped += 1
             continue
         x = _x_value(row[0])
@@ -93,26 +108,88 @@ def series_from_result(result: ResultSet) -> tuple[list[Series], int]:
             x_type = type(x)
         elif not isinstance(x, x_type):
             raise ExplorerError(f"column {x_name} mixes numbers and dates")
-        numbers = []
-        for name, value in zip(y_names, row[1:], strict=True):
+        for name, value, append in zip(y_names, row[1:], keep, strict=True):
             number = _number(value)
             if number is None:
                 raise ExplorerError(f"column {name} is not numeric: {value!r}")
-            numbers.append(number)
-        xs.append(x)
-        for bucket, number in zip(ys, numbers, strict=True):
-            bucket.append(number)
-    if not xs:
+            append(number)
+        keep_x(x)
+    if require_rows and not xs:
         raise ExplorerError("no rows to plot")
     return [
         Series(label=name, x=xs, y=bucket) for name, bucket in zip(y_names, ys, strict=True)
     ], skipped
 
 
+def resample_series(
+    series: Sequence[Series], *, kind: ChartKind, width: int, height: int
+) -> list[Series]:
+    """Reduce every series to the points the canvas can actually draw.
+
+    min/max keeps the extremes of every bucket, so spikes survive, and it only
+    indexes X, which the LTTB resamplers cannot do when X is a date.
+    """
+    budget = _canvas_width(width)
+    reduce = (
+        plotilleresample.resample_scatter
+        if kind is ChartKind.SCATTER
+        else plotilleresample.resample_plot_minmax
+    )
+    reduced = []
+    for item in series:
+        x, y = reduce(item.x, item.y, budget, height)
+        reduced.append(Series(label=item.label, x=list(x), y=list(y)))
+    return reduced
+
+
+def stream_series(
+    stream: RowStream, *, kind: ChartKind, width: int, height: int
+) -> tuple[list[Series], int, int]:
+    """Reduce *stream* to the canvas without ever holding every row.
+
+    Rows are read in chunks, each chunk is reduced on its own and the reduced
+    points are reduced again as they pile up, so the memory a chart needs stops
+    growing with the size of the table. Returns the series, how many rows were
+    skipped for their NULLs and how many were read.
+    """
+    reduced: list[Series] = []
+    x_type: type | None = None
+    skipped = rows_read = 0
+    while True:
+        rows = list(islice(stream.rows, _CHUNK))
+        if not rows:
+            break
+        rows_read += len(rows)
+        chunk, chunk_skipped = series_from_result(
+            ResultSet(columns=stream.columns, rows=rows), require_rows=False
+        )
+        skipped += chunk_skipped
+        if not chunk[0].x:
+            continue
+        if x_type is None:
+            x_type = type(chunk[0].x[0])
+        elif not isinstance(chunk[0].x[0], x_type):
+            raise ExplorerError(f"column {stream.columns[0]} mixes numbers and dates")
+        chunk = resample_series(chunk, kind=kind, width=width, height=height)
+        reduced = (
+            [
+                Series(label=old.label, x=old.x + new.x, y=old.y + new.y)
+                for old, new in zip(reduced, chunk, strict=True)
+            ]
+            if reduced
+            else chunk
+        )
+        if len(reduced[0].x) > _PILE * len(chunk[0].x):
+            reduced = resample_series(reduced, kind=kind, width=width, height=height)
+    if not reduced or not reduced[0].x:
+        raise ExplorerError("no rows to plot")
+    return resample_series(reduced, kind=kind, width=width, height=height), skipped, rows_read
+
+
 def histogram_values(result: ResultSet) -> tuple[list[float], int]:
     """Numeric values of the first column of *result*, and how many NULLs were skipped."""
     if not result.columns:
-        raise ExplorerError("no rows to plot")
+        raise ExplorerError("need a numeric column to plot")
     name = result.columns[0]
     values: list[float] = []
     skipped = 0

{sqlitexplorer-1.0.0 → sqlitexplorer-1.1.2}/sqlitexplorer/cli.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import difflib
 import functools
 import inspect
+import re
 import shutil
 import sys
 import time
@@ -28,6 +29,7 @@ from sqlitexplorer.charts import (
     render_chart,
     render_histogram,
     series_from_result,
+    stream_series,
 )
 from sqlitexplorer.completion import complete_table
 from sqlitexplorer.core import (
@@ -156,6 +158,7 @@ _EXTENSIONS = {
     OutputFormat.MARKDOWN: "md",
 }
 _FORMAT_BY_SUFFIX = {".csv": OutputFormat.CSV, ".tsv": OutputFormat.TSV, ".json": OutputFormat.JSON}
+_UNSAFE_IN_NAME = re.compile(r"[^\w.-]")
 
 
 # --- Helpers ------------------------------------------------------------------
@@ -273,11 +276,31 @@ def _attach_all(db: Explorer, values: Sequence[str] | None, *, write: bool) -> N
         db.attach(alias, path, write=write)
 
 
+def _read_text(file: Path, encoding: str) -> str:
+    """Read *file* as text, reporting a wrong encoding as a plain message."""
+    try:
+        return file.read_text(encoding=encoding)
+    except UnicodeDecodeError:
+        _fail(f"{file.name} is not valid {encoding} text")
+    except LookupError:
+        _fail(f"unknown encoding: {encoding}")
+    except OSError as error:
+        _fail(str(error))
+
+
+def _export_file_name(name: str, extension: str) -> str:
+    """A file name for *name* that cannot escape the directory it is written in."""
+    safe = _UNSAFE_IN_NAME.sub("_", name).lstrip(".")
+    return f"{safe or '_'}.{extension}"
+
+
 def _read_sql(sql: str | None, file: Path | None) -> list[str]:
-    if (sql is None) == (file is None):
+    if sql is not None and file is not None:
         _fail("give either an SQL statement or --file, not both")
+    if sql is None and file is None:
+        _fail("give an SQL statement, - to read it from stdin, or --file")
     if file is not None:
-        text = file.read_text(encoding="utf-8")
+        text = _read_text(file, "utf-8")
     elif sql == "-":
         text = sys.stdin.read()
     else:
@@ -617,7 +640,8 @@ def chart(
         str,
         typer.Argument(
             show_default=False,
-            help="Query whose first column is X and the other numeric columns are series.",
+            help="Query whose first column is X and the other numeric columns are series,"
+            " or - to read it from stdin.",
         ),
     ],
     kind: Annotated[
@@ -625,6 +649,13 @@ def chart(
     ] = ChartKind.LINE,
     height: Annotated[int, typer.Option("--height", min=3, help="Height in rows.")] = 15,
     bins: Annotated[int, typer.Option("--bins", min=1, help="Bins of a histogram.")] = 10,
+    resample: Annotated[
+        bool,
+        typer.Option(
+            "--resample/--no-resample",
+            help="Reduce the rows to the points the canvas can show (line and scatter only).",
+        ),
+    ] = True,
     x_label: Annotated[str | None, typer.Option("--x-label", help="Label of the X axis.")] = None,
     y_label: Annotated[str | None, typer.Option("--y-label", help="Label of the Y axis.")] = None,
     params: ParamOption = None,
@@ -635,12 +666,13 @@ def chart(
     parameters = _parameters(params)
     with _reporting_errors(), open_database(database) as db:
         text = sys.stdin.read() if sql == "-" else sql
-        result = db.execute(text, parameters if parameters else ())
-        if not result.returns_rows:
-            _fail("the statement returned no rows")
+        bound = parameters if parameters else ()
         use_color = resolve_color(color)
         screen = width if width is not None else shutil.get_terminal_size().columns
         if kind is ChartKind.HIST:
+            result = db.execute(text, bound)
+            if not result.returns_rows:
+                _fail("the statement returned no rows")
             values, skipped = histogram_values(result)
             drawing = render_histogram(
                 values,
@@ -652,7 +684,23 @@ def chart(
                 y_label=y_label or "count",
             )
         else:
-            series, skipped = series_from_result(result)
+            if resample:
+                # Reduces as it reads, so the rows never pile up in memory.
+                stream = db.stream(text, bound)
+                if not stream.returns_rows:
+                    _fail("the statement returned no rows")
+                columns = stream.columns
+                series, skipped, read = stream_series(
+                    stream, kind=kind, width=screen, height=height
+                )
+                if len(series[0].x) < read:
+                    typer.echo(f"resampled {read} rows to {len(series[0].x)} points", err=True)
+            else:
+                result = db.execute(text, bound)
+                if not result.returns_rows:
+                    _fail("the statement returned no rows")
+                columns = result.columns
+                series, skipped = series_from_result(result)
             default_y = series[0].label if len(series) == 1 else "value"
             drawing = render_chart(
                 series,
@@ -660,7 +708,7 @@ def chart(
                 width=screen,
                 height=height,
                 color=use_color,
-                x_label=x_label or result.columns[0],
+                x_label=x_label or columns[0],
                 y_label=y_label or default_y,
             )
         if skipped:
@@ -722,11 +770,21 @@ def export(
     with _reporting_errors(), open_database(database) as db:
         if every:
             assert output is not None
-            output.mkdir(parents=True, exist_ok=True)
+            targets: dict[str, str] = {}
             for name in db.names():
-                target = output / f"{name}.{_EXTENSIONS[output_format]}"
-                with target.open("w", encoding="utf-8") as handle:
-                    write_rows(db.stream_rows(name), options, handle)
+                file_name = _export_file_name(name, _EXTENSIONS[output_format])
+                if file_name in targets:
+                    _fail(f"{name} and {targets[file_name]} both export to {file_name}")
+                targets[file_name] = name
+            output.mkdir(parents=True, exist_ok=True)
+            for file_name, name in targets.items():
+                target = output / file_name
+                try:
+                    with target.open("w", encoding="utf-8") as handle:
+                        write_rows(db.stream_rows(name), options, handle)
+                except ExplorerError as error:
+                    target.unlink(missing_ok=True)
+                    typer.secho(f"skipped {name}: {error}", err=True, fg=typer.colors.YELLOW)
             return
         assert table is not None
         if output is None:
@@ -762,15 +820,17 @@ def import_(
     delimiter: Annotated[
         str | None, typer.Option("--delimiter", help="Field delimiter for CSV/TSV.")
     ] = None,
+    encoding: Annotated[
+        str, typer.Option("--encoding", help="Encoding of the file.")
+    ] = "utf-8-sig",
 ) -> None:
     """Load a CSV, TSV or JSON file into a table, creating it if needed."""
     input_format = output_format or _FORMAT_BY_SUFFIX.get(file.suffix.lower())
     if input_format is None:
         _fail(f"cannot tell the format of {file.name}; pass --format")
+    text = _read_text(file, encoding)
     with _reporting_errors(), open_database(database, write=True) as db:
-        headers, raw_rows = parse_rows(
-            file.read_text(encoding="utf-8-sig"), input_format, delimiter=delimiter
-        )
+        headers, raw_rows = parse_rows(text, input_format, delimiter=delimiter)
         types = infer_types(raw_rows, len(headers))
         count = db.import_rows(
             table, list(zip(headers, types, strict=True)), coerce_rows(raw_rows, types)

{sqlitexplorer-1.0.0 → sqlitexplorer-1.1.2}/sqlitexplorer/core.py

@@ -498,7 +498,10 @@ class Explorer:
             table, columns=columns, where=where, order_by=order_by, descending=descending
         )
         query = f"SELECT {selection} {source}{order} LIMIT ? OFFSET ?"
-        return self.stream(query, (-1 if limit is None else limit, offset))
+        try:
+            return self.stream(query, (-1 if limit is None else limit, offset))
+        except sqlite3.Error as error:
+            raise translate_error(error, write=self._write) from error
 
     def stats(
         self,

{sqlitexplorer-1.0.0 → sqlitexplorer-1.1.2}/sqlitexplorer/render.py

@@ -53,6 +53,11 @@ ELLIPSIS = "…"
 _ANSI = re.compile(r"\x1b\[[0-9;]*m")
 _INTEGER = re.compile(r"^[+-]?\d+$")
 _REAL = re.compile(r"^[+-]?(\d+\.\d*|\.\d+|\d+)([eE][+-]?\d+)?$")
+_LEADING_ZERO = re.compile(r"^[+-]?0\d")
+# A tuple, not bool | int: the union would be rebuilt on every call.
+_INTEGRAL = (bool, int)
+# Integers outside this range do not fit in a SQLite INTEGER column.
+_INT64 = range(-(2**63), 2**63)
 
 
 class OutputFormat(str, Enum):
@@ -262,6 +267,11 @@ def default_page_size() -> int:
     return max(1, shutil.get_terminal_size().lines - 4)
 
 
+def _page_footer(number: int, pages: int, rows: int) -> str:
+    plural = "" if rows == 1 else "s"
+    return f"page {number} of {pages} ({rows} row{plural})"
+
+
 def paginate(
     result: ResultSet, *, page: int | None = None, page_size: int | None = None
 ) -> tuple[ResultSet, str | None]:
@@ -275,7 +285,7 @@ def paginate(
         pages = max(1, -(-result.total // size))
         if number > pages:
             raise ExplorerError(f"page {number} is out of range (1-{pages})")
-        return result, f"page {number} of {pages} ({result.total} rows)"
+        return result, _page_footer(number, pages, result.total)
     pages = max(1, -(-len(result.rows) // size))
     if number > pages:
         raise ExplorerError(f"page {number} is out of range (1-{pages})")
@@ -283,7 +293,7 @@ def paginate(
     sliced = ResultSet(
         columns=result.columns, rows=result.rows[start : start + size], rowcount=result.rowcount
     )
-    return sliced, f"page {number} of {pages} ({len(result.rows)} rows)"
+    return sliced, _page_footer(number, pages, len(result.rows))
 
 
 def stdout_is_tty() -> bool:
@@ -422,15 +432,19 @@ def parse_rows(
     if fmt not in (OutputFormat.CSV, OutputFormat.TSV):
         raise ExplorerError(f"cannot import from the {fmt.value} format")
     separator = delimiter or ("\t" if fmt is OutputFormat.TSV else ",")
-    reader = csv.reader(io.StringIO(text), delimiter=separator)
+    if len(separator) != 1:
+        raise ExplorerError("the delimiter must be a single character")
     try:
-        headers = next(reader)
-    except StopIteration:
-        raise ExplorerError("empty file") from None
+        records = list(csv.reader(io.StringIO(text), delimiter=separator))
+    except csv.Error as error:
+        raise ExplorerError(f"cannot read the file: {error}") from error
+    if not records:
+        raise ExplorerError("empty file")
+    headers, *rest = records
     if not any(header.strip() for header in headers):
         raise ExplorerError("empty file")
     rows: list[list[object]] = []
-    for number, record in enumerate(reader, start=2):
+    for number, record in enumerate(rest, start=2):
         if not record:
             continue
         if len(record) > len(headers):
@@ -459,19 +473,24 @@ def _parse_json_rows(text: str) -> tuple[list[str], list[list[object]]]:
 def _plain_json_value(value: object) -> object:
     if isinstance(value, bool):
         return int(value)
+    if isinstance(value, int) and value not in _INT64:
+        return str(value)
     if isinstance(value, (dict, list)):
         return json.dumps(value, ensure_ascii=False)
     return value
 
 
 def _classify(value: object) -> str:
-    if isinstance(value, bool | int):
+    if isinstance(value, _INTEGRAL):
         return "INTEGER"
     if isinstance(value, float):
         return "REAL"
     text = str(value).strip()
+    if _LEADING_ZERO.match(text):
+        # 007 is a code, not a number: storing it as one would drop the zeros.
+        return "TEXT"
     if _INTEGER.match(text):
-        return "INTEGER"
+        return "INTEGER" if int(text) in _INT64 else "TEXT"
     if _REAL.match(text):
         return "REAL"
     return "TEXT"