fix: surface migration configuration mistakes instead of ignoring them

docs/changelog.rst

@@ -9,6 +9,32 @@ important operational fixes.
 Recent Updates
 ==============
 
+Unreleased
+------------------------------------------------------------------------------
+
+**Changed:**
+
+* ``migration_config`` now rejects keys SQLSpec does not read, raising
+  :class:`~sqlspec.exceptions.ImproperConfigurationError` with the closest
+  valid key. A misspelling such as ``version_table`` instead of
+  ``version_table_name`` was previously accepted and silently ignored, leaving
+  the setting at its default. Remove or correct unrecognized keys to upgrade.
+
+**Fixed:**
+
+* Pointing ``--config`` at a module rather than a configuration object now
+  reports the ``module:attribute`` references that module exports, instead of
+  failing later with ``AttributeError: module has no attribute 'bind_key'``.
+* Configuration references that misuse ``:`` report the accepted syntax rather
+  than an import failure.
+* Errors raised while importing a configuration module keep their original type
+  and message instead of being rewrapped as an import failure.
+* The "No SQLSpec config found" help text shows the ``[tool.sqlspec]`` section
+  name, which console markup previously consumed, and no longer mangles config
+  paths that contain colons.
+* ``author`` is declared on :class:`~sqlspec.config.MigrationConfig`. The
+  migration generator already read it, but type checkers rejected it.
+
 v0.57.0
 ------------------------------------------------------------------------------
 

docs/examples/migration_quickstart_config.py

@@ -0,0 +1,7 @@
+from sqlspec.adapters.sqlite import SqliteConfig
+
+database_config = SqliteConfig(
+    bind_key="app",
+    connection_config={"database": "app.db"},
+    migration_config={"script_location": "migrations", "version_table_name": "schema_versions"},
+)

docs/examples/quickstart_migrations.py

@@ -0,0 +1,52 @@
+import sqlite3
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from sqlspec.cli import add_migration_commands
+
+__all__ = ("test_sqlite_migration_quickstart",)
+
+
+def test_sqlite_migration_quickstart(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Exercise the documented config discovery and migration workflow."""
+    config_example = Path(__file__).with_name("migration_quickstart_config.py")
+    (tmp_path / "database.py").write_text(config_example.read_text())
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("SQLSPEC_CONFIG", raising=False)
+    runner = CliRunner()
+    config_path = "database:database_config"
+
+    cli_result = runner.invoke(add_migration_commands(), ["--config", config_path, "show-config"])
+    assert cli_result.exit_code == 0, cli_result.output
+    assert "app" in cli_result.output
+
+    env_result = runner.invoke(
+        add_migration_commands(), ["show-config"], env={"SQLSPEC_CONFIG": "database.database_config"}
+    )
+    assert env_result.exit_code == 0, env_result.output
+    assert "app" in env_result.output
+
+    (tmp_path / "pyproject.toml").write_text('[tool.sqlspec]\nconfig = "database:database_config"\n')
+    pyproject_result = runner.invoke(add_migration_commands(), ["show-config"])
+    assert pyproject_result.exit_code == 0, pyproject_result.output
+    assert "Using config from pyproject.toml" in pyproject_result.output
+
+    commands = (
+        ["init", "--no-prompt"],
+        ["create-migration", "-m", "create users table", "--no-prompt"],
+        ["upgrade", "--no-prompt"],
+        ["show-current-revision"],
+    )
+    for command in commands:
+        result = runner.invoke(add_migration_commands(), ["--config", config_path, *command])
+        assert result.exit_code == 0, result.output
+
+    assert (tmp_path / "app.db").is_file()
+    assert len(list((tmp_path / "migrations").glob("*.sql"))) == 1
+    with sqlite3.connect(tmp_path / "app.db") as connection:
+        tracker_name = connection.execute(
+            "SELECT name FROM sqlite_master WHERE type = ? AND name = ?", ("table", "schema_versions")
+        ).fetchone()
+    assert tracker_name == ("schema_versions",)

docs/usage/cli.rst

@@ -4,32 +4,38 @@ Command Line Interface
 SQLSpec includes a CLI for managing migrations and inspecting configuration. Use it
 when you want a fast, explicit workflow without additional tooling.
 
-Configuration can come from ``--config``, ``SQLSPEC_CONFIG``, or
-``[tool.sqlspec]`` in ``pyproject.toml``.
+Every command needs a configuration reference. Pass it with ``--config``, set
+``SQLSPEC_CONFIG``, or record it in ``[tool.sqlspec]`` -- see
+:ref:`pointing-the-cli-at-your-configuration` for the details.
 
 Core Commands
 -------------
 
 .. code-block:: console
 
-   sqlspec init
-   sqlspec create-migration -m "add users"
-   sqlspec upgrade
-   sqlspec downgrade
+   sqlspec --config database:database_config show-config
+   sqlspec --config database:database_config init --no-prompt
+   sqlspec --config database:database_config create-migration -m "add users" --no-prompt
+   sqlspec --config database:database_config upgrade --no-prompt
+   sqlspec --config database:database_config downgrade --no-prompt
+   sqlspec --config database:database_config show-current-revision
 
 Common Options
 --------------
 
 - ``--bind-key`` targets a specific database configuration.
 - ``--no-prompt`` skips confirmation prompts.
 - ``--format`` selects SQL vs Python migration files.
+- ``--validate-config`` reports each configuration and whether it is async-capable.
 - ``--use-logger`` emits migration output via structured logger.
 - ``--no-echo`` disables console output for migration commands.
 - ``--summary`` emits a single summary log entry when logger output is enabled.
 
 Tips
 ----
 
+- ``show-config`` verifies the CLI resolved the configuration you expected
+  before you run anything that touches the database.
 - Run ``sqlspec --help`` to see global options.
 - Run ``sqlspec upgrade --help`` to see command-specific migration options.