Support writing an in-memory DataFrame to ClickHouse via to_clickhouse

[wudidapaopao]

What

DataStore.to_clickhouse() now accepts a pure in-memory pandas DataFrame (source_type == "dataframe") as the source, when an explicit target host is given. Previously this was rejected even with a host.

import pandas as pd
from datastore import DataStore

df = pd.DataFrame({"city": ["Beijing", "Shanghai"], "amount": [100.0, 300.0]})

DataStore(df).to_clickhouse(
    "analytics.sales",
    host="myorg.region.aws.clickhouse.cloud",   # *.clickhouse.cloud / :9440 auto-enables TLS
    user="default", password="...",
    order_by="city",
)

Why

The DataFrame-upload path (_execute() locally → DESCRIBE Python(df) → INSERT … FROM Python(df)) never needed a ClickHouse source — it already runs for ClickHouse-sourced stores whose pipeline has Pandas-only ops. A pure-DataFrame store was blocked only by two couplings keyed on the source type rather than the target:

1. the _require_clickhouse_for_writeback guard (rejects source_type != clickhouse), and
2. _get_adapter() (no adapter for "dataframe").

The host= parameter sets where to write but didn't change either decision, so an explicit ClickHouse target was ignored. This is a guard/adapter coupling, not a technical limit.

How

to_clickhouse() detects a pure-DataFrame source and, when an explicit host is given, runs the existing DataFrame-upload path with the target treated as ClickHouse — via a scoped source_type override in _target_server_context that is restored even on exception. An explicit, non-empty host is required (a df has no source server to default to); omitting it raises a clear DataStoreError.

Scope is deliberately narrow:

• create_view / create_materialized_view / save() still reject a pure df — they need a server-side SQL source a local df cannot provide (a VIEW stores a query, an MV is an insert-trigger on a server-side table; Python(df) is local-only and can't be persisted into a server-side definition).
• non-ClickHouse sources (mysql/postgresql) remain rejected by _require_clickhouse_for_writeback.

Tests

New TestToClickHouseLocalDataFrame (+ a cross-server case), all asserting exact values and row order per the repo's testing principles:

• fail / replace (new + refuse-existing) / append, with value + order checks
• engine / order_by (list) / partition_by
• index=True + index_label
• a Pandas transform on a local df
• no-host and empty-host guard → DataStoreError
• source_type restored after success and after a raised exception
• scope-boundary: create_view / create_materialized_view (with explicit host) and save(view/MV) still reject a local df
• cross-server: the table lands on the target server only (not the source)

Verified locally against the .github/ci/clickhouse-pair.yml pair: full test_writeback.py = 73 passed (60 existing + 13 new), no regressions.

🤖 Generated with Claude Code

[wudidapaopao]

@chibugai, review this PR.

[chibugai]

Reviewed (OCR opus-4-8, --max-tools 40, + manual read of the diff). No blocking correctness or safety issues found — advisory only, not approving/requesting changes.

What I checked on the two files (datastore/core.py, datastore/tests/test_writeback.py):

• Exception safety of the temporary override — _target_server_context now also swaps source_type to "clickhouse" when as_clickhouse_target=True, and restores both _remote_params and source_type in the finally. test_replace_new_creates_then_refuses_existing and test_source_type_restored_and_store_still_usable confirm the override doesn't leak after a raise. Good.
• Scope containment — the relaxation is to_clickhouse-only. create_view / create_materialized_view / save(type=view|materialized_view) on a pure-df store stay rejected even with an explicit host, and _require_clickhouse_for_writeback still blocks mysql/postgresql sources. The three scope-guard tests lock this in.
• No new injection / type-mapping surface — uploads route through the existing Python(df) table-function path; no identifier/value handling is changed by this PR.
• not host vs is None — intentional, so a blank host string gets the clear DataStoreError up front rather than a generic failure deeper in the upload path; test_requires_explicit_host exercises both.

Test coverage is thorough (fail/replace/append, engine+partition, index_label, transform-flow-through, cross-server isolation). LGTM from my side.