Skip to content

fix(dbapi): add PEP 249 Binary; bind Time as integer seconds - #922

Closed
sankalpsthakur wants to merge 1 commit into
ClickHouse:mainfrom
sankalpsthakur:fix/919-dbapi-binary-time
Closed

fix(dbapi): add PEP 249 Binary; bind Time as integer seconds#922
sankalpsthakur wants to merge 1 commit into
ClickHouse:mainfrom
sankalpsthakur:fix/919-dbapi-binary-time

Conversation

@sankalpsthakur

@sankalpsthakur sankalpsthakur commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Fixes #919.

Two DB-API / SQLAlchemy Core bind gaps:

  1. Binary missing — SQLAlchemy LargeBinary calls dialect.dbapi.Binary(value) and raised AttributeError because clickhouse_connect.dbapi did not define it. Add Binary = bytes plus the other standard PEP 249 constructors (Date, Time, Timestamp, *FromTicks).

  2. Time binds as HH:MM:SS — ClickHouse Time/Time64 store integer ticks (seconds for Time). format_query_value / format_bind_value left datetime.time and timedelta as bare string forms that the server rejects for Int32/Int64. Convert them to integer seconds so inserts and binds succeed.

Checklist

  • 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

Tests

  • tests/unit_tests/test_driver/test_dbapi_types.pyBinary / PEP 249 constructors
  • tests/unit_tests/test_driver/test_params.py — time/timedelta format_query_value, format_bind_value, finalize_query, server-side bind
pytest tests/unit_tests/test_driver/test_params.py \
       tests/unit_tests/test_driver/test_dbapi_types.py \
       tests/unit_tests/test_driver/test_temporal.py \
       tests/unit_tests/test_driver/test_binding.py -q
# 138 passed

AI disclosure

This change was implemented with AI assistance (Grok). I reviewed the diff, aligned it with the issue suggestions and existing bind/temporal conventions, and ran the focused unit suite above.

AI/LLM disclosure

  • AI coding tools (including Grok and/or Codex agent-assisted editing) were used to help draft or modify code and this PR description.
  • I reviewed the complete change, understand the reasoning, and ran the reported local tests before submitting.
  • This submission is original work of authorship under the project CLA / contributor terms; AI output was not pasted unreviewed.

SQLAlchemy LargeBinary calls dialect.dbapi.Binary; expose Binary=bytes
and the other PEP 249 type constructors on clickhouse_connect.dbapi.

datetime.time and timedelta query/bind parameters were stringified as
HH:MM:SS, which ClickHouse Time/Time64 reject (they store integer ticks).
Format them as seconds since midnight / total seconds instead.

Fixes ClickHouse#919
@sankalpsthakur
sankalpsthakur force-pushed the fix/919-dbapi-binary-time branch from 457a509 to 7cd8803 Compare August 1, 2026 08:37
@joe-clickhouse

Copy link
Copy Markdown
Contributor

Hi @sankalpsthakur, thanks for the work here but I am closing this PR because it combines two unrelated changes. The DB API constructor fix has been re-authored as a single PR with tests and a changelog entry. The time and timedelta binding changes are excluded because they corrupt Time64 values and break working server-side binds. That work will be handled separately.

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.

Two Core types cannot be bound through the DBAPI: LargeBinary (no PEP 249 Binary constructor) and Time

2 participants