From 2bdbf1bc964434a8202669ec43d2e2e2445052f4 Mon Sep 17 00:00:00 2001 From: Adegbite Ayoade Date: Thu, 24 Sep 2026 01:19:25 +0100 Subject: [PATCH] docs: clarify that default connections are not merged into gateways default_connection, default_test_connection and default_scheduler are used only when a gateway omits the matching key. A gateway that sets its own connection does not inherit fields such as type from the default. Also remove the in-memory DuckDB default listed for default_connection. Without it, a gateway with no connection fails with 'No connection configured'; the DuckDB default applies only to default_test_connection. Closes #4105 Signed-off-by: Adegbite Ayoade --- docs/guides/configuration.md | 4 +++- docs/reference/configuration.md | 6 ++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index 38f6814c8b..46c6a5da2d 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -1213,10 +1213,12 @@ Example configuration: #### Default connections/scheduler -The `default_connection`, `default_test_connection`, and `default_scheduler` keys are used to specify shared defaults across multiple gateways. +The `default_connection`, `default_test_connection`, and `default_scheduler` keys specify a connection or scheduler for gateways that do not define their own. For example, you might have a specific connection where your tests should run regardless of which gateway is being used. Instead of duplicating the test connection information in each gateway specification, specify it once in the `default_test_connection` key. +A default is only used when a gateway omits the corresponding key entirely. If a gateway specifies its own `connection`, `test_connection`, or `scheduler`, SQLMesh uses that configuration as written and ignores the default. Fields are not merged, so a gateway connection cannot inherit individual fields such as `type` from `default_connection`. Each gateway connection must be a complete connection configuration. + Example configuration specifying a Postgres default connection, in-memory DuckDB default test connection, and builtin default scheduler: === "YAML" diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index ae036a7774..84e015e0b6 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -264,13 +264,15 @@ If a configuration contains multiple gateways, SQLMesh will use the first one in ### Default connections/scheduler -The `default_connection`, `default_test_connection`, and `default_scheduler` keys are used to specify shared defaults across multiple gateways. +The `default_connection`, `default_test_connection`, and `default_scheduler` keys specify a connection or scheduler for gateways that do not define their own. For example, you might have a specific connection where your tests should run regardless of which gateway is being used. Instead of duplicating the test connection information in each gateway specification, specify it once in the `default_test_connection` key. +A default is only used when a gateway omits the corresponding key entirely. If a gateway specifies its own `connection`, `test_connection`, or `scheduler`, SQLMesh uses that configuration as written and ignores the default. Fields are not merged, so a gateway connection cannot inherit individual fields such as `type` from `default_connection`. + | Option | Description | Type | Required | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------: | :------: | -| `default_connection` | The default connection to use if one is not specified in a gateway (Default: A DuckDB connection that creates an in-memory database) | connection | N | +| `default_connection` | The connection to use for any gateway that does not specify a `connection` | connection | N | | `default_test_connection` | The default connection to use when running tests if one is not specified in a gateway (Default: A DuckDB connection that creates an in-memory database) | connection | N | | `default_scheduler` | The default scheduler configuration to use if one is not specified in a gateway (Default: built-in scheduler) | scheduler | N |