Skip to content

Bind top-level Enum server parameters like their value - #1184

Merged
joe-clickhouse merged 2 commits into
ClickHouse:mainfrom
mansur-akhmadi:fix/enum-server-param
Nov 12, 2026
Merged

joe-clickhouse merged 2 commits into
ClickHouse:mainfrom
mansur-akhmadi:fix/enum-server-param

Conversation

@mansur-akhmadi

@mansur-akhmadi mansur-akhmadi commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes #1183

format_bind_value formatted an Enum member with recurse(value.value), and recurse always passes top_level=False. A top-level member with a str or date value was therefore sent as a quoted literal:

client.query("SELECT {v:String}", parameters={"v": Status.ACTIVE}).first_row
# before: ("'active'",)

This change passes the caller's top_level through, so the member formats exactly like its value. Members inside arrays, tuples and maps still format as nested literals, as before. Members of str subclasses such as class E(str, Enum) already took the str branch and do not change. A member whose value is None now binds as NULL, the same as None.

Not changed: the type-aware steps in bind_query that run before formatting, such as DateTime64 promotion, named Tuple field ordering and the _64 suffix, still see the Enum object and not its value. That was the same before this change.

Tests: a unit test in tests/unit_tests/test_driver/test_params.py covers str, int, date and tuple values at the top level and nested, and an integration test in tests/integration_tests/test_params.py binds members to String, Enum8, Int32, Date, Array(String) and Tuple(Date, Int32) through sync and async clients and compares with the plain values. Both fail on main and pass with this change.

Checklist

  • Unit and integration tests covering the common scenarios were added
  • A human-readable description of the changes was provided to include in CHANGELOG

Note

Low Risk
Narrow change to server parameter formatting for standard Enum types, with unit and integration tests; no auth or data-path impact.

Overview
Server-side parameter binding now treats a top-level enum.Enum member as its underlying value instead of always formatting through nested literal rules.

In format_bind_value, Enum handling calls format_bind_value(value.value, …, top_level) rather than recurse(value.value), so {v:String} gets user_1's without extra quotes, Date/Int32/Enum8 bindings work, and a member whose value is None binds as SQL NULL (\N) instead of the string NULL. Enum members inside arrays, tuples, and maps still use nested formatting. str subclasses such as class E(str, Enum) are unchanged because they take the str branch.

Unit and integration tests cover string, int, date, tuple, and NULL cases; the CHANGELOG documents the fix (related to [#1183]).

Reviewed by Cursor Bugbot for commit a9bfa8a. Bugbot is set up for automated code reviews on this repo. Configure here.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the Enum formatting change, though tests were not run during this review.

No open issues 🎉

What changed in this PR

Addresses #1183 in the shared parameter formatter by making top-level Enum members format like their underlying values, while preserving nested literal formatting.

Changes:

  • Preserves top_level when formatting an Enum's value, correcting quoting and NULL handling.
  • Adds unit coverage and sync/async integration tests for Enum parameter binding.
  • Documents the user-visible fix in the changelog.

No material issues were identified. Tests were not run during this review.

File Description
tests/​unit_tests/​test_driver/​test_params.py Adds scalar, nested, and NULL Enum formatting cases.
tests/​integration_tests/​test_params.py Compares Enum bindings with plain values through both HTTP clients.
clickhouse_connect/​driver/​binding.py Preserves top-level formatting when unwrapping Enum members.
CHANGELOG.md Documents corrected Enum quoting and NULL behavior.

Review effort: Balanced

@security-ai-gate-reviewer

Copy link
Copy Markdown

AI review gate — auto-approval withheld

The AI review gate is green, but the approver did not approve a9bfa8ab: it comes from a fork, not a branch in this repository: changes from outside need a maintainer's approval.

What to do: ask someone with write access who is not the PR author to approve this pull request.

@joe-clickhouse
joe-clickhouse merged commit a70ad89 into ClickHouse:main Nov 12, 2026
56 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

enum.Enum member as a server-side parameter is sent as a quoted literal

3 participants