chore: updated docs

Author: cofin

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.14.7"
+    rev: "v0.14.8"
     hooks:
       - id: ruff
         args: ["--fix"]

AGENTS.md

@@ -453,7 +453,13 @@ def command(config: str | None):
 - Walk filesystem from cwd to find config files
 - Return `None` if not found to trigger helpful error message
 
-**Reference implementation:** `sqlspec/cli.py` (lines 26-65), `sqlspec/utils/config_discovery.py`
+**Multi-config support:**
+- Split comma-separated values from CLI flag, env var, or pyproject.toml
+- Resolve each config path independently
+- Flatten results if callables return lists
+- Deduplicate by `bind_key` (later configs override earlier ones with same key)
+
+**Reference implementation:** `sqlspec/cli.py` (lines 26-110), `sqlspec/utils/config_discovery.py`
 
 ### CLI Sync/Async Dispatch Pattern
 

docs/examples/usage/usage_cli_1.py

@@ -25,6 +25,12 @@ def test_single_and_multiple_configs() -> None:
     def get_configs() -> list[AsyncpgConfig]:
         return [db_config]
 
+    # Usage with CLI:
+    # --config "myapp.config.db_config"                          # Single config
+    # --config "myapp.config.configs"                            # Config list
+    # --config "myapp.config.get_configs"                        # Callable
+    # --config "myapp.config.db_config,myapp.config.configs"     # Multiple paths (comma-separated)
+
     # end-example
     assert isinstance(db_config, AsyncpgConfig)
     assert isinstance(configs, list)

docs/usage/cli.rst

@@ -217,11 +217,14 @@ SQLSpec CLI supports three ways to specify your database configuration, in order
 2. **Environment Variable** (``SQLSPEC_CONFIG``) - Convenient for development workflows
 3. **pyproject.toml** (``[tool.sqlspec]``) - Project-wide default configuration
 
-The ``--config`` option and ``SQLSPEC_CONFIG`` environment variable accept a dotted path to either:
+The ``--config`` option and ``SQLSPEC_CONFIG`` environment variable accept:
 
 - **A single config object**: ``myapp.config.db_config``
 - **A config list**: ``myapp.config.configs``
 - **A callable function**: ``myapp.config.get_configs()``
+- **Multiple config paths (comma-separated)**: ``myapp.config.primary_config,myapp.config.analytics_config``
+
+Each config path is resolved independently, and if a callable returns a list of configs, all configs are collected.
 
 Example configuration file (``myapp/config.py``):
 
@@ -239,36 +242,36 @@ Config Discovery Methods
 
 .. code-block:: bash
 
-   sqlspec --config myapp.config:get_configs upgrade head
+   sqlspec --config myapp.config.get_configs upgrade head
 
 Use for one-off commands or to override other config sources.
 
 **Method 2: Environment Variable**
 
 .. code-block:: bash
 
-   export SQLSPEC_CONFIG=myapp.config:get_configs
+   export SQLSPEC_CONFIG=myapp.config.get_configs
    sqlspec upgrade head  # Uses environment variable
 
 Convenient for development. Add to your shell profile:
 
 .. code-block:: bash
 
    # ~/.bashrc or ~/.zshrc
-   export SQLSPEC_CONFIG=myapp.config:get_configs
+   export SQLSPEC_CONFIG=myapp.config.get_configs
 
 Multiple configs (comma-separated):
 
 .. code-block:: bash
 
-   export SQLSPEC_CONFIG="app.db:primary_config,app.db:analytics_config"
+   export SQLSPEC_CONFIG="app.db.primary_config,app.db.analytics_config"
 
 **Method 3: pyproject.toml (Project Default)**
 
 .. code-block:: toml
 
    [tool.sqlspec]
-   config = "myapp.config:get_configs"
+   config = "myapp.config.get_configs"
 
 Best for team projects - config is version controlled.
 
@@ -278,22 +281,82 @@ Multiple configs (array):
 
    [tool.sqlspec]
    config = [
-       "myapp.config:primary_config",
-       "myapp.config:analytics_config"
+       "myapp.config.primary_config",
+       "myapp.config.analytics_config"
    ]
 
 **Precedence:** CLI flag > Environment variable > pyproject.toml
 
 If no config is found from any source, SQLSpec will show a helpful error message with examples.
 
+Multi-Config Resolution Details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When using comma-separated config paths or list format in pyproject.toml, SQLSpec:
+
+1. **Resolves each path independently**: Each dotted path is imported and resolved
+2. **Flattens callable results**: If a callable returns a list, all configs are collected
+3. **Deduplicates by bind_key**: Later configs override earlier ones with the same ``bind_key``
+4. **Validates final list**: Empty config lists result in an error
+
+**Deduplication Example:**
+
+.. code-block:: bash
+
+   # If primary_config has bind_key="db" and backup_config has bind_key="db"
+   export SQLSPEC_CONFIG="app.primary_config,app.backup_config"
+
+   # Result: Only backup_config is used (last wins)
+
+**Combined callable and list:**
+
+.. code-block:: python
+
+   # myapp/config.py
+   def get_all_configs():
+       """Returns list of configs."""
+       return [primary_config, analytics_config]
+
+   single_config = AsyncpgConfig(bind_key="backup", ...)
+
+.. code-block:: bash
+
+   # This resolves to 3 configs: primary, analytics, and backup
+   export SQLSPEC_CONFIG="myapp.config.get_all_configs,myapp.config.single_config"
+
+**Deduplication with callables:**
+
+.. code-block:: python
+
+   # myapp/config.py
+   primary = AsyncpgConfig(bind_key="db", ...)
+   updated = AsyncpgConfig(bind_key="db", ...)  # Same bind_key
+
+   def get_primary():
+       return primary
+
+   def get_updated():
+       return updated
+
+.. code-block:: bash
+
+   # Only updated config is used (last wins for bind_key="db")
+   sqlspec --config "myapp.config.get_primary,myapp.config.get_updated" upgrade
+
 Global Options
 --------------
 
 ``--config PATH``
-   Dotted path to SQLSpec config(s) or callable function. Optional when using
-   environment variable or pyproject.toml config discovery.
+   Dotted path to SQLSpec config(s) or callable function. Supports comma-separated
+   multiple paths. Optional when using environment variable or pyproject.toml config discovery.
+
+   Examples:
+
+   - Single config: ``--config myapp.config.db_config``
+   - Callable: ``--config myapp.config.get_configs``
+   - Multiple paths: ``--config "myapp.config.primary_config,myapp.config.analytics_config"``
 
-   Example: ``--config myapp.config.get_configs``
+   Configs with duplicate ``bind_key`` values are deduplicated (last wins).
 
 ``--validate-config``
    Validate configuration before executing migrations. Shows loaded configs
@@ -808,6 +871,41 @@ Multi-Config Operations
 When you have multiple database configurations, SQLSpec provides options to manage
 them collectively or selectively.
 
+Quick Reference: Multi-Config Patterns
+---------------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 35 35
+
+   * - Pattern
+     - Example
+     - Behavior
+   * - Single config
+     - ``--config "app.config.db"``
+     - Load one config
+   * - Config list
+     - ``--config "app.config.configs"``
+     - Load all configs in list
+   * - Callable returning list
+     - ``--config "app.config.get_configs"``
+     - Call function, load returned configs
+   * - Comma-separated paths
+     - ``--config "app.config.db1,app.config.db2"``
+     - Load multiple configs, deduplicate by bind_key
+   * - Env var (comma-separated)
+     - ``SQLSPEC_CONFIG="app.config.db1,app.config.db2"``
+     - Same as comma-separated CLI flag
+   * - pyproject.toml (list)
+     - ``config = ["app.config.db1", "app.config.db2"]``
+     - Load all paths in array
+   * - Mixed callables and configs
+     - ``--config "app.config.get_configs,app.config.backup"``
+     - Flatten callable results + direct configs
+   * - Duplicate bind_key
+     - ``--config "app.config.old,app.config.new"``
+     - Later config overrides (new wins)
+
 Scenario: Multiple Databases
 -----------------------------
 
@@ -954,6 +1052,38 @@ Best Practices
 
       sqlspec --config myapp.config upgrade --dry-run
 
+7. **Use Unique bind_key for Multi-Config**
+
+   When managing multiple databases, always specify unique ``bind_key`` values:
+
+   .. code-block:: python
+
+      # Good - unique bind_keys
+      configs = [
+          AsyncpgConfig(bind_key="primary", ...),
+          AsyncpgConfig(bind_key="analytics", ...),
+      ]
+
+      # Problematic - configs will overwrite each other
+      configs = [
+          AsyncpgConfig(bind_key="db", ...),  # Same key
+          AsyncmyConfig(bind_key="db", ...),  # Will override above
+      ]
+
+8. **Prefer pyproject.toml for Team Projects**
+
+   Store config paths in version control for consistency:
+
+   .. code-block:: toml
+
+      [tool.sqlspec]
+      config = [
+          "myapp.config.primary_db",
+          "myapp.config.analytics_db"
+      ]
+
+   Team members automatically use the same config without manual setup.
+
 Framework Integration
 =====================
 

sqlspec/cli.py

@@ -82,9 +82,7 @@ def sqlspec_group(ctx: "click.Context", config: str | None, validate_config: boo
                 if isinstance(config_result, Sequence) and not isinstance(config_result, str):
                     all_configs.extend(config_result)
                 else:
-                    all_configs.append(
-                        cast("AsyncDatabaseConfig[Any, Any, Any] | SyncDatabaseConfig[Any, Any, Any]", config_result)
-                    )
+                    all_configs.append(config_result)  # pyright: ignore
 
             # Deduplicate by bind_key (later configs override earlier ones)
             configs_by_key: dict[

tests/integration/test_cli_config_discovery.py

@@ -88,7 +88,9 @@ def test_cli_with_pyproject(tmp_path: "Path", monkeypatch: "pytest.MonkeyPatch",
     assert "Successfully loaded 1 config(s)" in result.output
 
 
-def test_cli_flag_overrides_env(tmp_path: "Path", monkeypatch: "pytest.MonkeyPatch", mock_config_module: "Path") -> None:
+def test_cli_flag_overrides_env(
+    tmp_path: "Path", monkeypatch: "pytest.MonkeyPatch", mock_config_module: "Path"
+) -> None:
     """Test --config flag overrides SQLSPEC_CONFIG."""
     monkeypatch.chdir(tmp_path)
 
@@ -145,9 +147,7 @@ def test_cli_flag_overrides_pyproject(
     runner = CliRunner()
     cli = get_cli_with_commands()
 
-    result = runner.invoke(
-        cli, ["--config", "test_config.config.get_test_config", "--validate-config", "show-config"]
-    )
+    result = runner.invoke(cli, ["--config", "test_config.config.get_test_config", "--validate-config", "show-config"])
 
     assert result.exit_code == 0, f"Output: {result.output}"
     assert "Successfully loaded 1 config(s)" in result.output
@@ -338,9 +338,7 @@ def get_multiple_configs():
         cli = get_cli_with_commands()
 
         result = runner.invoke(
-            cli,
-            ["--validate-config", "show-config"],
-            env={"SQLSPEC_CONFIG": "multiconf2.config.get_multiple_configs"},
+            cli, ["--validate-config", "show-config"], env={"SQLSPEC_CONFIG": "multiconf2.config.get_multiple_configs"}
         )
 
         assert result.exit_code == 0, f"Output: {result.output}"
@@ -350,7 +348,9 @@ def get_multiple_configs():
             sys.path.remove(str(tmp_path))
 
 
-def test_cli_config_with_bind_key(tmp_path: "Path", monkeypatch: "pytest.MonkeyPatch", mock_config_module: "Path") -> None:
+def test_cli_config_with_bind_key(
+    tmp_path: "Path", monkeypatch: "pytest.MonkeyPatch", mock_config_module: "Path"
+) -> None:
     """Test config with bind_key is displayed correctly."""
     monkeypatch.chdir(tmp_path)