sqlseed-cli 0.2.5__tar.gz → 0.2.7__tar.gz

{sqlseed_cli-0.2.5 → sqlseed_cli-0.2.7}/.gitignore

@@ -56,9 +56,20 @@ dmypy.json
 .import_linter_cache/
 
 # sqlseed
+.release-backups/
 *.db
 *.sqlite
 *.sqlite3
+# SQLite runtime sidecars
+*.db-wal
+*.db-shm
+*.db-journal
+*.sqlite-wal
+*.sqlite-shm
+*.sqlite-journal
+*.sqlite3-wal
+*.sqlite3-shm
+*.sqlite3-journal
 .sqlseed_cache/
 snapshots/
 .env

{sqlseed_cli-0.2.5 → sqlseed_cli-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlseed-cli
-Version: 0.2.5
+Version: 0.2.7
 Summary: Command-line interface for sqlseed test data generation, preview and configuration replay
 Project-URL: Documentation, https://sunbos.github.io/sqlseed/guide/
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
@@ -29,12 +29,12 @@ configuration. This package provides the `sqlseed` command.
 
 ## Installation
 
-These instructions target version 0.2.5. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+These instructions target version 0.2.7. Check [Releases](https://github.com/sunbos/sqlseed/releases)
 for publication status; use the source installation below to test an unpublished candidate.
 Use a Python 3.10+ virtual environment:
 
 ```bash
-python -m pip install "sqlseed-cli==0.2.5"
+python -m pip install "sqlseed-cli==0.2.7"
 ```
 
 Core 0.2.4 and older lack the shared diagnostic interfaces required by this version.
@@ -76,10 +76,12 @@ sqlseed replay <cache_dir>/snapshots/YYYY-MM-DD_HHMMSS_ffffff_users.yaml
 | `init` | Write a YAML configuration template |
 | `replay` | Run a saved configuration snapshot |
 
+`init` rejects an output path that aliases its source SQLite file, including symbolic and hard links. Use a separate configuration path; replacing an existing configuration remains supported. The check covers existing ordinary local files, not concurrent path changes or custom SQLite VFS targets.
+
 For PostgreSQL, install the Core `postgres` extra and use `--url`:
 
 ```bash
-python -m pip install "sqlseed[postgres]==0.2.5" "sqlseed-cli==0.2.5"
+python -m pip install "sqlseed[postgres]==0.2.7" "sqlseed-cli==0.2.7"
 sqlseed fill --url "postgresql+psycopg://user:pass@host/db" -t users -n 1000 --provider faker --no-ai
 sqlseed inspect --url "postgresql+psycopg://user:pass@host/db"
 ```
@@ -97,17 +99,45 @@ sqlseed fill --config generate.yaml --no-ai
 override those values, including options equal to the command defaults. Without
 `--config`, the defaults are `mimesis`, `en_US`, and `5000`.
 
+If the configuration file cannot be read, parsed, or validated, `fill` reports the
+reason and exits with status 2 before generation or clearing tables. Correct the
+file path, UTF-8 YAML/JSON syntax, or reported fields and retry.
+Each invocation reads the configuration once; changes made after loading take
+effect on a later invocation.
+
+Database exceptions during direct or configuration-driven `fill` are reported as
+`Database fill failed:` with exit status 1 and URL credentials redacted, without a
+Python traceback. For a missing SQLite `mode=rw` target, no file is created;
+correct the target and retry. This diagnostic does not imply rollback of earlier
+committed batches.
+
 If any table reports generation errors, the command prints those errors and exits
 with status 1. `count` reports rows actually committed; a later batch failure can
 leave earlier commits. A snapshot retains a supplied transform script path and replay
 runs that script again; the script itself is not embedded in the snapshot.
 
+Replay matches saved table settings using SQLite's ASCII-only case-insensitive
+name rules; non-ASCII names and PostgreSQL names remain distinct. Multiple saved
+configurations matching the replay table are rejected before generation rather
+than choosing one silently. Snapshots without matching table settings retain the
+legacy defaults.
+
+Snapshots also retain `--enrich`. Enriched replay reads the current table distribution,
+not a frozen copy of the original rows. Older snapshots without this setting
+retain the default (`false`).
+
+`replay` reports missing, unreadable, or malformed snapshot files with exit status 2
+before generation starts. Check the path, read permissions, and UTF-8 YAML syntax.
+Snapshot metadata requires a nonblank string `table_name`, a positive integer
+`count`, and an integer or null `seed` (which may be omitted). Boolean values are
+not accepted as integers.
+
 The optional AI plugin registers `ai-suggest`, `ai-analyze`, and `auto-heal` through
 `sqlseed.cli_commands`. CLI does not require AI for its five base commands.
 
 ## Requirements
 
-These metadata requirements apply to version 0.2.5 and its source candidates.
+These metadata requirements apply to version 0.2.7 and its source candidates.
 Use local Core and plugins together when developing from source.
 
 - Python `>=3.10`
@@ -121,3 +151,4 @@ See the [user guide](https://sunbos.github.io/sqlseed/guide/),
 
 License: [AGPL-3.0-or-later](https://github.com/sunbos/sqlseed/blob/main/LICENSE).
 The distribution includes the full LICENSE text.
+

{sqlseed_cli-0.2.5 → sqlseed_cli-0.2.7}/README.md

@@ -6,12 +6,12 @@ configuration. This package provides the `sqlseed` command.
 
 ## Installation
 
-These instructions target version 0.2.5. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+These instructions target version 0.2.7. Check [Releases](https://github.com/sunbos/sqlseed/releases)
 for publication status; use the source installation below to test an unpublished candidate.
 Use a Python 3.10+ virtual environment:
 
 ```bash
-python -m pip install "sqlseed-cli==0.2.5"
+python -m pip install "sqlseed-cli==0.2.7"
 ```
 
 Core 0.2.4 and older lack the shared diagnostic interfaces required by this version.
@@ -53,10 +53,12 @@ sqlseed replay <cache_dir>/snapshots/YYYY-MM-DD_HHMMSS_ffffff_users.yaml
 | `init` | Write a YAML configuration template |
 | `replay` | Run a saved configuration snapshot |
 
+`init` rejects an output path that aliases its source SQLite file, including symbolic and hard links. Use a separate configuration path; replacing an existing configuration remains supported. The check covers existing ordinary local files, not concurrent path changes or custom SQLite VFS targets.
+
 For PostgreSQL, install the Core `postgres` extra and use `--url`:
 
 ```bash
-python -m pip install "sqlseed[postgres]==0.2.5" "sqlseed-cli==0.2.5"
+python -m pip install "sqlseed[postgres]==0.2.7" "sqlseed-cli==0.2.7"
 sqlseed fill --url "postgresql+psycopg://user:pass@host/db" -t users -n 1000 --provider faker --no-ai
 sqlseed inspect --url "postgresql+psycopg://user:pass@host/db"
 ```
@@ -74,17 +76,45 @@ sqlseed fill --config generate.yaml --no-ai
 override those values, including options equal to the command defaults. Without
 `--config`, the defaults are `mimesis`, `en_US`, and `5000`.
 
+If the configuration file cannot be read, parsed, or validated, `fill` reports the
+reason and exits with status 2 before generation or clearing tables. Correct the
+file path, UTF-8 YAML/JSON syntax, or reported fields and retry.
+Each invocation reads the configuration once; changes made after loading take
+effect on a later invocation.
+
+Database exceptions during direct or configuration-driven `fill` are reported as
+`Database fill failed:` with exit status 1 and URL credentials redacted, without a
+Python traceback. For a missing SQLite `mode=rw` target, no file is created;
+correct the target and retry. This diagnostic does not imply rollback of earlier
+committed batches.
+
 If any table reports generation errors, the command prints those errors and exits
 with status 1. `count` reports rows actually committed; a later batch failure can
 leave earlier commits. A snapshot retains a supplied transform script path and replay
 runs that script again; the script itself is not embedded in the snapshot.
 
+Replay matches saved table settings using SQLite's ASCII-only case-insensitive
+name rules; non-ASCII names and PostgreSQL names remain distinct. Multiple saved
+configurations matching the replay table are rejected before generation rather
+than choosing one silently. Snapshots without matching table settings retain the
+legacy defaults.
+
+Snapshots also retain `--enrich`. Enriched replay reads the current table distribution,
+not a frozen copy of the original rows. Older snapshots without this setting
+retain the default (`false`).
+
+`replay` reports missing, unreadable, or malformed snapshot files with exit status 2
+before generation starts. Check the path, read permissions, and UTF-8 YAML syntax.
+Snapshot metadata requires a nonblank string `table_name`, a positive integer
+`count`, and an integer or null `seed` (which may be omitted). Boolean values are
+not accepted as integers.
+
 The optional AI plugin registers `ai-suggest`, `ai-analyze`, and `auto-heal` through
 `sqlseed.cli_commands`. CLI does not require AI for its five base commands.
 
 ## Requirements
 
-These metadata requirements apply to version 0.2.5 and its source candidates.
+These metadata requirements apply to version 0.2.7 and its source candidates.
 Use local Core and plugins together when developing from source.
 
 - Python `>=3.10`
@@ -98,3 +128,4 @@ See the [user guide](https://sunbos.github.io/sqlseed/guide/),
 
 License: [AGPL-3.0-or-later](https://github.com/sunbos/sqlseed/blob/main/LICENSE).
 The distribution includes the full LICENSE text.
+

{sqlseed_cli-0.2.5 → sqlseed_cli-0.2.7}/src/sqlseed_cli/main.py

@@ -15,8 +15,10 @@ from typing import Any
 
 import click
 import pydantic
+import yaml
 from rich.console import Console
 from rich.table import Table as RichTable
+from sqlalchemy.exc import SQLAlchemyError
 
 from sqlseed import fill as api_fill
 from sqlseed import fill_from_config
@@ -25,10 +27,11 @@ from sqlseed._utils.logger import configure_logging, get_logger
 from sqlseed._utils.paths import get_cache_dir
 from sqlseed._utils.redaction import redact_url_credentials
 from sqlseed._version import __version__
-from sqlseed.config.loader import generate_template, load_config, save_config
+from sqlseed.config.loader import generate_template, save_config
 from sqlseed.config.models import GeneratorConfig, ProviderType, TableConfig
 from sqlseed.config.snapshot import SnapshotManager
 from sqlseed.core.orchestrator import DataOrchestrator
+from sqlseed.database._sqlite_schema import resolve_sqlite_table_name
 from sqlseed.generators import ConfigurationError
 
 CONFLICTING_DATABASE_OPTIONS = "Cannot specify both positional db_path and --url. Use one or the other."
@@ -53,14 +56,19 @@ def cli() -> None:
 
 
 def _fill_from_config_cmd(config_path: str, *, clear_before: bool = False, **kwargs: Any) -> None:
-    config = load_config(config_path)
-    table_count = len(config.tables)
-    click.echo(f"Loading config: {config_path} ({table_count} table(s))")
+    click.echo(f"Loading config: {config_path}")
+    if not clear_before:
+        click.echo(
+            "Note: Tables without clear_before=true will receive appended data. Use --clear to reset configured tables."
+        )
 
-    if not (clear_before or any(tc.clear_before for tc in config.tables)):
-        click.echo("Note: Data will be appended. Use --clear to reset tables before generation.")
+    try:
+        # Let the core API load and execute one configuration, without a separate
+        # diagnostic read that could observe a different version of the file.
+        results = fill_from_config(config_path, clear_before=clear_before, **kwargs)
+    except (OSError, TypeError, ValueError, yaml.YAMLError) as exc:
+        raise click.UsageError(_redact_credentials(f"Configuration fill failed: {exc}")) from None
 
-    results = fill_from_config(config_path, clear_before=clear_before, **kwargs)
     for result in results:
         click.echo(str(result))
         for error in result.errors:
@@ -81,6 +89,7 @@ def _save_snapshot_cmd(
     *,
     url: str | None = None,
     transform: str | None = None,
+    enrich: bool = False,
 ) -> None:
     config = GeneratorConfig(
         db_path=db_path,
@@ -95,6 +104,7 @@ def _save_snapshot_cmd(
                 clear_before=clear,
                 seed=seed,
                 transform=transform,
+                enrich=enrich,
             )
         ],
     )
@@ -275,6 +285,8 @@ def fill(**kwargs: Any) -> None:
         _execute_fill(options)
     except ConfigurationError as exc:
         raise click.UsageError(_redact_credentials(str(exc))) from None
+    except SQLAlchemyError as exc:
+        raise click.ClickException(_redact_credentials(f"Database fill failed: {exc}")) from None
 
 
 def _execute_config_fill(options: FillOptions, config_path: str) -> None:
@@ -358,6 +370,7 @@ def _execute_fill(options: FillOptions) -> None:
             clear=options.flags.clear,
             url=fill_url,
             transform=options.transform_path,
+            enrich=options.flags.enrich,
         )
 
     # Generation completed with errors: exit non-zero so callers/scripts can detect partial failure.
@@ -421,7 +434,7 @@ def preview(
         click.echo("No data generated.")
         return
 
-    console = Console()
+    console = Console(markup=False, emoji=False)
     rich_table = RichTable(title=f"Preview: {table} ({count} rows)")
 
     for col_name in rows[0]:
@@ -505,7 +518,7 @@ def inspect(db_path: str | None, table: str | None, show_mapping: bool, db_url:
         raise click.UsageError("db_path or --url is required.")
     try:
         with DataOrchestrator(target) as orch:
-            console = Console()
+            console = Console(markup=False, emoji=False)
 
             tables = [table] if table else orch.get_table_names()
 
@@ -555,20 +568,53 @@ def init(config_path: str, db: str | None, db_url: str | None) -> None:
     click.echo(f"Configuration template saved to: {config_path}")
 
 
-def _load_replay_config(snapshot_path: str) -> tuple[dict[str, Any], GeneratorConfig]:
+class _ReplayMetadata(pydantic.BaseModel):
+    """Validate the snapshot envelope before opening its configured database."""
+
+    model_config = pydantic.ConfigDict(strict=True, hide_input_in_errors=True)
+
+    table_name: str
+    count: int = pydantic.Field(gt=0)
+    seed: int | None = None
+
+    @pydantic.field_validator("table_name")
+    @classmethod
+    def nonblank_table_name(cls, value: str) -> str:
+        """Keep valid identifier spelling while rejecting empty names."""
+        if not value.strip():
+            raise ValueError("table_name must not be blank")
+        return value
+
+
+def _load_replay_config(snapshot_path: str) -> tuple[_ReplayMetadata, GeneratorConfig]:
     manager = SnapshotManager()
     try:
         data = manager.load(snapshot_path)
+        metadata = _ReplayMetadata.model_validate(data)
     except FileNotFoundError as exc:
         raise click.UsageError(f"Snapshot file not found: {snapshot_path}") from exc
-    except (ValueError, KeyError) as exc:
-        raise click.UsageError(_redact_credentials(f"Invalid snapshot file format: {exc}")) from exc
+    except OSError as exc:
+        raise click.UsageError(_redact_credentials(f"Cannot read snapshot file: {exc}")) from None
+    except (ValueError, KeyError, yaml.YAMLError) as exc:
+        raise click.UsageError(_redact_credentials(f"Invalid snapshot file format: {exc}")) from None
 
     try:
         config = GeneratorConfig(**data["config"])
     except (pydantic.ValidationError, KeyError, TypeError) as exc:
         raise click.UsageError(_redact_credentials(f"Invalid config in snapshot: {exc}")) from exc
-    return data, config
+    return metadata, config
+
+
+def _replay_table_config(config: GeneratorConfig, table_name: str, dialect_name: str) -> TableConfig | None:
+    """Select saved table settings using the connected database's name rules."""
+    matches = []
+    for table in config.tables:
+        name = resolve_sqlite_table_name(table.name, [table_name]) if dialect_name == "sqlite" else table.name
+        if name == table_name:
+            matches.append(table)
+    if len(matches) > 1:
+        raise click.UsageError("Snapshot contains multiple configurations for the replay table")
+    return matches[0] if matches else None
 
 
 @cli.command()
@@ -584,31 +630,21 @@ def replay(snapshot_path: str) -> None:
     if ".." in Path(snapshot_path).parts and not resolved_path.is_relative_to(cache_dir):
         raise click.UsageError("snapshot path must be within cache directory")
 
-    data, config = _load_replay_config(snapshot_path)
-
-    try:
-        table_name = data["table_name"]
-        count = data["count"]
-    except (KeyError, TypeError) as exc:
-        raise click.UsageError(f"Invalid snapshot file format: {exc}") from exc
-    seed = data.get("seed")
-
-    table_config = None
-    for tc in config.tables:
-        if tc.name == table_name:
-            table_config = tc
-            break
+    metadata, config = _load_replay_config(snapshot_path)
+    table_name = metadata.table_name
 
     try:
         with DataOrchestrator.from_config(config) as orch:
+            table_config = _replay_table_config(config, table_name, orch._get_dialect_name())
             result = orch.fill_table(
                 table_name=table_name,
-                count=count,
-                seed=seed,
+                count=metadata.count,
+                seed=metadata.seed,
                 batch_size=table_config.batch_size if table_config else 5000,
                 clear_before=table_config.clear_before if table_config else False,
                 column_configs=table_config.columns if table_config else None,
                 transform=table_config.transform if table_config else None,
+                enrich=table_config.enrich if table_config else False,
             )
     except (ValueError, RuntimeError, OSError, ConfigurationError) as exc:
         raise click.UsageError(_redact_credentials(str(exc))) from None

{sqlseed_cli-0.2.5 → sqlseed_cli-0.2.7}/tests/test_cli_yaml_priority.py

@@ -309,7 +309,7 @@ class TestCLIConfigPriorityIntegration:
             cli,
             ["fill", "--config", config_path, "--no-ai"],
         )
-        assert "Data will be appended" in result.output
+        assert "Tables without clear_before=true will receive appended data" in result.output
 
     def test_cli_fill_config_no_note_when_clear(self, tmp_path: Any) -> None:
         db_path = _make_db(tmp_path)
@@ -319,9 +319,9 @@ class TestCLIConfigPriorityIntegration:
             cli,
             ["fill", "--config", config_path, "--clear", "--no-ai"],
         )
-        assert "Data will be appended" not in result.output
+        assert "will receive appended data" not in result.output
 
-    def test_cli_fill_config_no_note_when_yaml_clear(self, tmp_path: Any) -> None:
+    def test_cli_fill_config_note_preserves_yaml_clear(self, tmp_path: Any) -> None:
         db_path = _make_db(tmp_path)
         config_path = _make_config(
             tmp_path,
@@ -329,8 +329,12 @@ class TestCLIConfigPriorityIntegration:
             tables=[{"name": "users", "count": 10, "clear_before": True, "columns": []}],
         )
         runner = CliRunner()
+        first = runner.invoke(cli, ["fill", "--config", config_path, "--no-ai"])
+        assert first.exit_code == 0, first.output
         result = runner.invoke(
             cli,
             ["fill", "--config", config_path, "--no-ai"],
         )
-        assert "Data will be appended" not in result.output
+        assert result.exit_code == 0, result.output
+        assert "Tables without clear_before=true will receive appended data" in result.output
+        assert _count_rows(db_path) == 10

sqlseed_cli-0.2.7/tests/test_config_load_errors.py

@@ -0,0 +1,106 @@
+"""Users can diagnose and correct configuration errors without changing data."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+import pytest
+import yaml
+from click.testing import CliRunner
+from sqlseed_cli.main import cli
+
+from tests.cli_helpers import fixed_items_config, retry_items_document
+from tests.sqlite_helpers import sqlite_connection
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+    from typing import Any
+
+
+@pytest.mark.parametrize(
+    ("filename", "contents"),
+    [
+        ("missing.yaml", None),
+        ("broken.yaml", b"tables: [\n"),
+        ("broken.json", b'{"tables": ['),
+        ("invalid.yaml", b"db_path: demo.db\ntables: wrong-type\n"),
+        ("numeric-key.yaml", b"1: value\n"),
+        ("encoding.yaml", b"db_path: \xff\n"),
+        ("tag.yaml", b"db_path: !unsupported {}\n"),
+        ("empty.yaml", b""),
+    ],
+)
+def test_config_load_error_preserves_rows_and_allows_retry(
+    tmp_path: Path, filename: str, contents: bytes | None
+) -> None:
+    database = tmp_path / "demo.db"
+    with sqlite_connection(database) as connection:
+        connection.execute("CREATE TABLE items (value INTEGER NOT NULL)")
+        connection.execute("INSERT INTO items VALUES (99)")
+    config = tmp_path / filename
+    if contents is not None:
+        config.write_bytes(contents)
+    runner = CliRunner()
+    args = ["fill", "--config", str(config), "--clear", "--no-ai"]
+
+    failed = runner.invoke(cli, args)
+
+    assert failed.exit_code == 2, repr(failed.exception)
+    assert "Configuration fill failed:" in failed.output
+    assert "Traceback" not in failed.output
+    with sqlite_connection(database) as connection:
+        assert connection.execute("SELECT value FROM items").fetchall() == [(99,)]
+
+    # Correct the file and retry through the same CLI, with real SQLite writes.
+    retry_items_document(config, fixed_items_config(database), runner, args, database)
+
+
+def test_config_directory_reports_actionable_error(tmp_path: Path) -> None:
+    result = CliRunner().invoke(cli, ["fill", "--config", str(tmp_path), "--no-ai"])
+
+    assert result.exit_code == 2, repr(result.exception)
+    assert "Configuration fill failed:" in result.output
+    assert "Traceback" not in result.output
+
+
+@pytest.mark.parametrize("change", ["replace", "remove"])
+def test_config_file_change_after_read_cannot_redirect_fill(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, change: str
+) -> None:
+    """A path replaced after its first read must not select a different database."""
+    database = tmp_path / "requested.db"
+    replacement_database = tmp_path / "replacement.db"
+    for target in (database, replacement_database):
+        with sqlite_connection(target) as connection:
+            connection.execute("CREATE TABLE items (value INTEGER NOT NULL)")
+            connection.execute("INSERT INTO items VALUES (99)")
+    document = fixed_items_config(database)
+    config = tmp_path / "generate.yaml"
+    config.write_text(yaml.safe_dump(document), encoding="utf-8")
+    original_open = open
+    changed = False
+
+    @contextmanager
+    def open_then_change(file: Any, *args: Any, **kwargs: Any) -> Iterator[Any]:
+        nonlocal changed
+        with original_open(file, *args, **kwargs) as handle:
+            yield handle
+        if file == config and not changed:
+            changed = True
+            if change == "remove":
+                config.unlink()
+            else:
+                document["db_path"] = str(replacement_database)
+                config.write_text(yaml.safe_dump(document), encoding="utf-8")
+
+    monkeypatch.setattr("builtins.open", open_then_change)
+    result = CliRunner().invoke(cli, ["fill", "--config", str(config), "--clear", "--no-ai"])
+
+    assert changed
+    assert result.exit_code == 0, result.output
+    with sqlite_connection(database) as connection:
+        assert connection.execute("SELECT value FROM items").fetchall() == [(7,), (7,)]
+    with sqlite_connection(replacement_database) as connection:
+        assert connection.execute("SELECT value FROM items").fetchall() == [(99,)]

sqlseed_cli-0.2.7/tests/test_fill_database_errors.py

@@ -0,0 +1,124 @@
+"""Database fill failures are actionable, redacted, and safe to retry."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import subprocess
+import sys
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from click.testing import CliRunner
+from sqlalchemy.exc import OperationalError
+
+from tests.sqlite_helpers import sqlite_connection
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+main = importlib.import_module("sqlseed_cli.main")
+
+
+def _args(config: bool) -> list[str]:
+    if config:
+        return ["fill", "--config", "unused.yaml", "--no-ai"]
+    return ["fill", "unused.db", "--table", "items", "--count", "2", "--provider", "base", "--no-ai"]
+
+
+def _invoke(args: list[str], root: Path) -> subprocess.CompletedProcess[str]:
+    # Invoke the actual console-script callable in a new interpreter so an
+    # uncaught exception cannot be hidden by CliRunner's exception capture.
+    return subprocess.run(
+        [sys.executable, "-c", "from sqlseed_cli.main import main; main()", *args],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        timeout=30,
+        check=False,
+    )
+
+
+@pytest.mark.parametrize("config", [False, True], ids=["direct", "config"])
+def test_missing_rw_target_reports_error_and_allows_retry(tmp_path: Path, config: bool) -> None:
+    target = tmp_path / "absent %41.db"
+    url = f"sqlite:///{target.as_uri()}?uri=true&mode=rw"
+    if config:
+        config_path = tmp_path / "generate.json"
+        config_path.write_text(
+            json.dumps({"url": url, "provider": "base", "tables": [{"name": "items", "count": 2}]}),
+            encoding="utf-8",
+        )
+        args = ["fill", "--config", str(config_path), "--no-ai"]
+    else:
+        args = ["fill", "--url", url, "--table", "items", "--count", "2", "--provider", "base", "--no-ai"]
+    before = set(tmp_path.iterdir())
+
+    failed = _invoke(args, tmp_path)
+
+    assert failed.returncode == 1, failed.stdout + failed.stderr
+    assert "Error: Database fill failed:" in failed.stderr
+    assert "unable to open database file" in failed.stderr
+    assert "Traceback" not in failed.stdout + failed.stderr
+    assert set(tmp_path.iterdir()) == before
+    assert not target.exists()
+
+    # Correct only the target and retry exactly the same command.
+    with sqlite_connection(target) as connection:
+        connection.execute("CREATE TABLE items (id INTEGER PRIMARY KEY, value INTEGER NOT NULL)")
+        connection.execute("INSERT INTO items VALUES (1, 99)")
+    recovered = _invoke(args, tmp_path)
+
+    assert recovered.returncode == 0, recovered.stdout + recovered.stderr
+    with sqlite_connection(target) as connection:
+        assert connection.execute("SELECT COUNT(*) FROM items").fetchone() == (3,)
+        assert connection.execute("SELECT value FROM items WHERE id = 1").fetchone() == (99,)
+        assert connection.execute("PRAGMA integrity_check").fetchall() == [("ok",)]
+    assert set(tmp_path.iterdir()) == before | {target}
+
+
+@pytest.mark.parametrize("config", [False, True], ids=["direct", "config"])
+def test_database_diagnostic_redacts_credentials(monkeypatch: pytest.MonkeyPatch, config: bool) -> None:
+    def fail(*args: Any, **kwargs: Any) -> None:
+        raise OperationalError(
+            None, None, Exception("failed postgresql://synthetic_user:synthetic_secret@localhost/db")
+        )
+
+    # Mock only error text; connection behavior is exercised with real SQLite above.
+    monkeypatch.setattr(main, "fill_from_config" if config else "api_fill", fail)
+    result = CliRunner().invoke(main.cli, _args(config))
+
+    assert result.exit_code == 1
+    assert "Error: Database fill failed:" in result.output
+    assert "synthetic_user" not in result.output
+    assert "synthetic_secret" not in result.output
+    assert "Traceback" not in result.output
+
+
+@pytest.mark.parametrize("config", [False, True], ids=["direct", "config"])
+@pytest.mark.parametrize("error", [RuntimeError("unrelated"), SystemExit(7), KeyboardInterrupt()])
+def test_unrelated_exceptions_are_not_database_errors(
+    monkeypatch: pytest.MonkeyPatch, config: bool, error: BaseException
+) -> None:
+    def fail(*args: Any, **kwargs: Any) -> None:
+        raise error
+
+    monkeypatch.setattr(main, "fill_from_config" if config else "api_fill", fail)
+    result = CliRunner().invoke(main.cli, _args(config))
+
+    assert "Database fill failed:" not in result.output
+    if isinstance(error, RuntimeError):
+        assert result.exception is error
+    elif isinstance(error, SystemExit):
+        assert result.exit_code == 7
+    else:
+        assert result.exit_code == 1
+        assert "Aborted!" in result.output
+
+
+def test_usage_errors_keep_exit_code_two() -> None:
+    result = CliRunner().invoke(main.cli, ["fill", "unused.db", "--table", "items", "--no-ai"])
+
+    assert result.exit_code == 2
+    assert "--count is required" in result.output
+    assert "Database fill failed:" not in result.output