fix: surface migration configuration mistakes instead of ignoring them

[cofin]

Summary

Getting started with migrations failed in ways that gave no useful signal: a misspelled configuration key did nothing at all, pointing --config at a module crashed with an unrelated AttributeError, and the error text meant to show the pyproject.toml section name printed it as blank. This makes each of those say what is actually wrong, and reorganizes the migrations guide so the working path is the first thing you read.

What changed

• Misspelled configuration keys now fail loudly. migration_config accepted any key and ignored the ones it did not recognize, so version_table instead of version_table_name silently left the tracking table at its default name. Unknown keys now raise and name the closest valid key.
• Naming a module instead of a configuration explains the fix. sqlspec --config database used to fail with AttributeError: module 'database' has no attribute 'bind_key'. It now reports the references that module exports, such as database:database_config.
• Malformed references report the accepted syntax rather than an import failure.
• Errors from your own configuration module survive. A SQLSpec error raised while importing your config keeps its message instead of being rewrapped as "could not import".
• Two display bugs in the CLI are fixed. The "no config found" help text now shows [tool.sqlspec], which console markup was consuming, and config paths containing colons are no longer mangled.
• author is a declared migration setting. The migration generator already read it, but type checkers rejected it.

How you use it

Export a configuration and point the CLI at it with module:attribute:

# database.py
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"},
)

sqlspec --config database:database_config show-config
sqlspec --config database:database_config init --no-prompt
sqlspec --config database:database_config create-migration -m "create users table" --no-prompt
sqlspec --config database:database_config upgrade --no-prompt

Set SQLSPEC_CONFIG or [tool.sqlspec] in pyproject.toml to skip the flag; --config wins over the environment variable, which wins over pyproject.toml. Separate references with commas to manage several databases at once.

Documentation

The migrations guide now leads with a quickstart that is executed by the documentation test suite, followed by configuration, running against an existing schema, extension migrations, and output control. The adapter schema-support matrix is split into supported and unsupported tables and moved below the material most readers need. The broken workflow GIF is gone.

Upgrading

Rejecting unknown migration_config keys is a behavior change. A configuration carrying a stray key previously started and quietly ignored it; it now raises at construction with the corrected key name. Remove or fix the key to upgrade.

Closes #626.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.61017% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.28%. Comparing base (a3a3012) to head (ce75951).

Files with missing lines	Patch %	Lines
sqlspec/utils/config_tools.py	93.54%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #670      +/-   ##
==========================================
+ Coverage   77.26%   77.28%   +0.01%     
==========================================
  Files         475      475              
  Lines       67901    67949      +48     
  Branches     9335     9344       +9     
==========================================
+ Hits        52462    52511      +49     
+ Misses      12035    12032       -3     
- Partials     3404     3406       +2     

Flag	Coverage Δ
integration	60.92% <54.23%> (+0.11%)	⬆️
py3.10	75.58% <96.61%> (+<0.01%)	⬆️
py3.11	75.61% <96.61%> (+0.02%)	⬆️
py3.12	75.60% <96.61%> (+0.02%)	⬆️
py3.13	75.60% <96.61%> (+1.36%)	⬆️
py3.14	76.48% <96.55%> (+0.01%)	⬆️
unit	64.80% <96.61%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
sqlspec/cli.py	67.27% <100.00%> (+0.06%)	⬆️
sqlspec/config.py	93.39% <100.00%> (+0.16%)	⬆️
sqlspec/utils/module_loader.py	81.29% <100.00%> (+1.02%)	⬆️
sqlspec/utils/config_tools.py	92.81% <93.54%> (-0.05%)	⬇️

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.