fix(sqlalchemy): support explicit multi-row inserts (#1024)

[joe-clickhouse]

Summary

Enable SQLAlchemy multi-row insert.values(), including per-row expressions.

Closes #1024

Checklist

Delete items not relevant to your PR:

• Unit and integration tests covering the common scenarios were added
• A human-readable description of the changes was provided to include in CHANGELOG
• For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

[Copilot]

🟢 Approval recommended

The change is narrowly scoped (dialect capability flag) and is backed by both unit and integration tests plus aligned documentation and changelog coverage.

Pull request overview

This PR enables SQLAlchemy Core explicit multi-row inserts using Insert.values([...]) for the ClickHouse Connect dialect by opting the dialect into SQLAlchemy's multi-values INSERT capability, and adds coverage and documentation for the supported forms (dict rows, tuple rows, and per-row SQL expressions).

Changes:

• Enable SQLAlchemy multi-row Insert.values() support via supports_multivalues_insert = True on the dialect.
• Add unit and integration tests validating compilation and execution behavior for both client-side and server-side bind parameter modes.
• Document the supported multi-row insert forms and add a changelog entry describing the user-visible behavior.

File summaries

File	Description
tests/unit_tests/test_sqlalchemy/test_server_side_params.py	Adds compile-time coverage for multi-row inserts and a routing test to confirm explicit multi-row inserts use the text execution path while executemany uses native bulk insert.
tests/integration_tests/test_sqlalchemy/test_server_side_params.py	Adds end-to-end verification that multi-row Insert.values([...]) executes correctly for dicts, tuples, and per-row expressions in both bind modes.
docs/sqlalchemy.mdx	Documents explicit multi-row Insert.values([...]) support and guidance on when to prefer native bulk insert vs server-side params.
clickhouse_connect/cc_sqlalchemy/MIGRATING_FROM_CLICKHOUSE_SQLALCHEMY.md	Updates migration guidance to note explicit multi-row Core inserts are supported and when to use native bulk insert vs server-side params.
clickhouse_connect/cc_sqlalchemy/dialect.py	Enables SQLAlchemy multi-values INSERT capability on the dialect.
CHANGELOG.md	Adds an UNRELEASED improvements entry describing the new SQLAlchemy behavior and related Pandas to_sql(method="multi") enablement.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.