feat: Add IBM Db2 engine adapter

[hdm-db2-eco-system]

Adds a IBM Db2 engine adapter for SQLMesh, including connection
configuration, Docker-based CI, integration tests, and engine-specific documentation.

CI results (stable baseline — Docker Db2 Community Edition)

81 passed · 46 skipped · 0 failed

Tested against: icr.io/db2_community/db2:latest (Db2 11.5)

---

What works

Model kinds

Kind	Status
FULL	✅ Working
INCREMENTAL_BY_TIME_RANGE	✅ Working
INCREMENTAL_BY_UNIQUE_KEY	✅ Working — MERGE INTO confirmed
INCREMENTAL_BY_PARTITION	✅ Working
INCREMENTAL_UNMANAGED	✅ Working
VIEW	✅ Working
SEED	✅ Working
SCD_TYPE_2_BY_TIME	⏭ Deferred — see below
SCD_TYPE_2_BY_COLUMN	⏭ Deferred — see below

Core engine operations

Operation	Notes
CREATE TABLE	Primary key columns get NOT NULL automatically
CTAS	Appends mandatory WITH DATA clause
MERGE INTO	TARGET/SOURCE alias substitution
CREATE INDEX	Idempotent — checks SYSCAT.INDEXES first
CREATE/DROP SCHEMA	Existence checked via SYSCAT.SCHEMATA
DROP VIEW	Existence checked via SYSCAT.VIEWS
GRANT/REVOKE	Uses SYSCAT.TABAUTH (Db2 has no INFORMATION_SCHEMA.TABLE_PRIVILEGES)
TRUNCATE	Implemented as DELETE FROM (Db2 has no native TRUNCATE)
Table/column comments	COMMENT ON TABLE / COMMENT ON COLUMN
Metadata queries	All via SYSCAT catalog views

---

What is skipped and why

All skips are in tests/core/engine_adapter/integration/test_integration.py
with documented pytest.skip() reasons. Search for if ctx.dialect == "db2"
in that file to see every skip block.

1. SCD Type 2 — 4 tests skipped

Tests: test_scd_type_2_by_time, test_scd_type_2_by_time_source_columns,
test_scd_type_2_by_column, test_scd_type_2_by_column_source_columns

Error: SQL20521N reason 7 — Db2's SQL preprocessor treats identifiers
starting with _ as conditional compilation directives.

Root cause: SQLMesh's _scd_type_2() in base.py generates _exists,
_key0, _row_number, _t as column aliases — all underscore-prefixed.
The SCD staging table also uses CTAS which Db2 does not support natively.

---

2. View comments — 3 tests skipped

Tests: test_create_view, test_create_view_source_columns,
test_get_data_objects

Error: SQL0104N — Db2 has no COMMENT ON VIEW statement.

---

3. test_sushi — 1 test skipped

Error: SQL0104N — CREATE SCHEMA IF NOT EXISTS is not valid Db2 SQL.
The before_all statements in the sushi example project emit IF NOT EXISTS
unconditionally through the db2-sqlglot-dialect generator.

---

4. ctx.create_context() tests — 6 tests skipped

Tests: test_batch_size_on_incremental_by_unique_key_model,
test_state_migrate_from_scratch, test_python_model_column_order,
test_unicode_characters, test_grants_plan,
test_incremental_by_unique_key_model_when_matched

Error: SQLMeshError: Cannot create a snapshot in a different catalog

Root cause: shared.py:346 performs a case-sensitive == comparison
between catalog_name (uppercased by Db2 normalisation, e.g. "TESTDB")
and _default_catalog (set from the config parser under duckdb dialect,
e.g. "testdb"). Db2 is the only SINGLE_CATALOG_ONLY + UPPERCASE engine,
so this case mismatch was never encountered before. This requires a framework-level
fix in shared.py which is outside the scope of this PR.

---

What is included

Core adapter — sqlmesh/core/engine_adapter/db2.py

• catalog_support = SINGLE_CATALOG_ONLY — Db2 databases are fully isolated;
  cross-database queries are not possible within a single connection
• SUPPORTED_DROP_CASCADE_OBJECT_KINDS = [] — Db2 raises SQL0104N on CASCADE
• MAX_IDENTIFIER_LENGTH = 128
• set_current_catalog() via CONNECT TO
• TIMESTAMPTZ stripped to TIMESTAMP (SQL0180N — Db2 rejects UTC offset literals)
• normalize_identifiers before quoting (SQL0204N — CTE alias case mismatch)

Connection config — sqlmesh/core/config/connection.py

• Db2ConnectionConfig with host, port, database, username, password,
  db2_schema, and SSL options
• get_catalog() returns .upper() to match Db2 UPPERCASE identifier normalisation
• Excluded from FORBIDDEN_STATE_SYNC_ENGINES — Db2 rejects table names starting
  with _; SQLMesh state tables (_snapshots, _environments, etc.) would fail.
  Users must set state_connection: duckdb

Framework integration

• sqlmesh/core/engine_adapter/__init__.py — import guarded by
  Python >= 3.10 AND find_spec('db2_sqlglot') to prevent a crash in environments
  without the db2 extra (e.g. dbt 1.6 test runs)
• sqlmesh/utils/migration.py — db2 added to MAX_TEXT_INDEX_LENGTH (255)
  and blob_text_type() returns VARCHAR(32000)

CI / infrastructure

• .github/workflows/pr.yaml — db2 added to engine-tests-docker matrix
• .github/scripts/install-prerequisites.sh — db2 case installs libxml2-dev build-essential
• .github/scripts/wait-for-db.sh — db2_ready() probe: port check + db2 connect loop
• tests/.../docker/compose.db2.yaml — IBM Db2 Community Edition container
• Makefile — db2-test target; db2 added to install-dev
• pyproject.toml — db2 optional extra (ibm_db + db2-sqlglot-dialect) + pytest marker

Tests

• tests/core/engine_adapter/test_db2.py — 22 unit tests, all passing
• tests/core/engine_adapter/integration/test_integration_db2.py — 18 Db2-specific integration tests
• tests/core/engine_adapter/integration/__init__.py — SYSCAT comment queries,
  role-based grant test infrastructure for Db2
• tests/core/engine_adapter/integration/config.yaml — inttest_db2 gateway
  with state_connection: duckdb

Documentation

• docs/integrations/engines/db2.md — connection options, state connection
  guidance, limitations, example config
• docs/integrations/overview.md, docs/guides/connections.md, mkdocs.yml — Db2 entries added

---

Checklist

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

[StuffbyYuki]

@hdm-db2-eco-system Hey would you mind resolving the conflict?

[hdm-db2-eco-system]

Hi @StuffbyYuki, the conflict has been resolved.

[cmgoffena13]

Looks like the comment doesn't match the code? If db2 is excluded for state, it should be in the set here.

[hdm-db2-eco-system]

Hi @cmgoffena13 fixed in 462c797 — "db2" is now added to FORBIDDEN_STATE_SYNC_ENGINES with the reason in an inline comment.

[cmgoffena13]

Hey @hdm-db2-eco-system -- so this PR introduces a unique situation due to its dependency on a SQLGlot plugin. So for instance, if we decide to upgrade SQLMesh's SQLGlot version, and the plugin has not caught up to the version, sqlmesh[db2] pip install would fail and cause the entire CI to fail here. Due to this unique dependency, I suggest:

1. Remove the db2 install from the make command install-dev
2. In the Action workflow, remove it from the engine-tests-docker matrix
3. Add a separate workflow that runs and calls the make db2-test command if any of the relevant db2 files change. From what I see:

• sqlmesh/core/engine_adapter/db2.py
• tests/core/engine_adapter/test_db2.py
• tests/core/engine_adapter/integration/test_integration_db2.py
• tests/core/engine_adapter/integration/docker/compose.db2.yaml

We'll try and keep in mind we have a separate plugin that will need to keep up if we upgrade SQLGlot, but these changes will help protect the repo as a whole. Let me know your thoughts.

[hdm-db2-eco-system]

Thanks for the guidance @cmgoffena13 — isolating the Db2 CI to prevent upstream SQLGlot version conflicts makes total sense!

I have updated the PR in a190479:

Makefile: Removed db2 from make install-dev so standard contributor setup is unaffected.
.github/workflows/pr.yaml: Removed db2 from the global engine-tests-docker matrix.
.github/workflows/db2.yaml: Added a dedicated workflow running make db2-test whenever Db2 adapter/test files are modified.
Could you please review these changes and let me know if any further adjustments are needed?