[tripleaceme]

Description

Closes #4105.

The configuration guide and reference both described default_connection, default_test_connection and default_scheduler as "shared defaults across multiple gateways", which reads as if a gateway can inherit individual fields (like type) from them. That is not how they work. Config.get_connection returns gateway.connection or self.default_connection, and the test connection and scheduler follow the same pattern, so a default is only used when a gateway leaves the key out entirely.

Changes:

• docs/guides/configuration.md and docs/reference/configuration.md: reword the section intro and add a paragraph saying the default is a fallback for gateways that omit the key, and that fields are not merged.
• docs/reference/configuration.md: remove "Default: A DuckDB connection that creates an in-memory database" from the default_connection row. default_connection defaults to None, and a gateway with no connection fails with No connection configured for gateway '<name>'. The in-memory DuckDB default only applies to default_test_connection (Config.get_default_test_connection), so that row is unchanged.

Test Plan

Docs only. I checked both behaviours against sqlmesh 0.236.2 with a DuckDB project:

• A gateway with connection: {database: local.db} plus default_connection: {type: duckdb} fails with Missing connection type., which is the case reported in the issue.
• A gateway with no connection and no default_connection fails with No connection configured for gateway 'local'.

Checklist

• I have run make style and fixed any issues
• I have added tests for my changes (if applicable) (not applicable, docs only)
• All existing tests pass (make fast-test) (not run, no code changes)
• My commits are signed off (git commit -s) per the DCO

Summary by CodeRabbit

• Documentation
  • Clarified that default connection and scheduler settings apply only when a gateway omits the corresponding setting.
  • Explained that gateway-specific configurations are used as written and must include all required fields; they are not merged with defaults.
  • Removed the specific in-memory DuckDB default from the default_connection description.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

The configuration guide and reference now state that defaults apply only when a gateway omits the corresponding key. They clarify that explicit gateway settings are not merged with defaults. The reference also removes the documented in-memory DuckDB default for default_connection.

Changes: Gateway default settings

Layer / File(s)	Summary
Clarify gateway default behavior docs/guides/configuration.md, docs/reference/configuration.md	Both documents describe defaults as fallbacks for omitted gateway keys. They state that explicit gateway settings are used as written and are not merged with defaults. The reference no longer specifies an in-memory DuckDB default for default_connection.

Estimated code review effort: 2 (Simple) | ~5 minutes

Change: Other · Severity of issue fixed: Low

Suggested reviewers: fresioas

Merge Risk: Low · up to 136f0

The documentation may lead users to expect null to suppress a default, although SQLMesh uses the default instead. Correct the wording before relying on it.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn