[paomian]

No description provided.

[Copilot]

🟡 Changes recommended

Critical issues can lose or corrupt rows through reused inputs, stale schema caches, and premature buffer clearing, while timestamp conversion can reject or misencode valid values.

6 open issues

• Encode generator rows before mutable values are reused · New
• Revalidate cached schema after external table changes · New
• Allow release uploads to skip existing files · New
• Treat gRPC dependency split as a breaking release · New
• Report acknowledged rows on validation failures · New
• Restore missing API and testing documentation · New

What changed in this PR

This PR separates the GreptimeDB Python client into a pure Python facade and an optional native gRPC package, and adds a PostgreSQL COPY backend.

Changes:

• Introduces backend extras, automatic backend selection, shared schema types, and compatibility imports.
• Adds batched PostgreSQL writes with validation, connection management, and offline and integration tests.
• Updates packaging, version synchronization, documentation, and CI to build, test, and publish both distributions.

File	Description
uv.lock	Records facade extras and backend dependencies.
tests/​test_types.py	Tests pure Python schema validation.
tests/​test_postgres.py	Tests COPY encoding, batching, errors, and connection lifecycle.
tests/​test_postgres_schema_compat.py	Checks schema compatibility with native types.
tests/​test_postgres_integration.py	Adds COPY round-trip and recovery tests.
tests/​test_integration.py	Skips gRPC tests when the plugin is absent.
tests/​test_convert.py	Makes native conversion tests backend-dependent.
tests/​test_backends.py	Tests backend selection and installation combinations.
scripts/​set-version.py	Synchronizes distribution versions, pins, and lockfiles.
README.zh-CN.md	Updates Chinese installation and backend examples.
README.md	Updates English installation and backend examples.
python/​greptimedb_ingester/​postgres.py	Implements the synchronous PostgreSQL COPY client.
python/​greptimedb_ingester/​grpc.py	Exposes the explicit gRPC backend.
python/​greptimedb_ingester/​_types.py	Adds schema types independent of the native plugin.
python/​greptimedb_ingester/​_native.py	Provides compatibility with the former native import path.
python/​greptimedb_ingester/​_errors.py	Shares the public error type across backends.
python/​greptimedb_ingester/​__init__.py	Selects the default backend and public exports.
pyproject.toml	Converts the root package to setuptools with optional extras.
packages/​grpc/​uv.lock	Locks native-plugin development dependencies.
packages/​grpc/​src/​types.rs	Houses native schema and write-option types.
packages/​grpc/​src/​lib.rs	Houses native module registration and runtime setup.
packages/​grpc/​src/​error.rs	Houses native error conversion.
packages/​grpc/​src/​convert.rs	Houses row conversion and request encoding.
packages/​grpc/​src/​client.rs	Houses the native gRPC client.
packages/​grpc/​src/​cell.rs	Houses Python-to-Rust value conversion.
packages/​grpc/​src/​bulk.rs	Houses native bulk buffering and writer operations.
packages/​grpc/​README.zh-CN.md	Describes the internal plugin in Chinese.
packages/​grpc/​README.md	Describes plugin packaging and platform support.
packages/​grpc/​python/​greptimedb_ingester_grpc/​__init__.py	Defines the plugin namespace and version.
packages/​grpc/​pyproject.toml	Configures the standalone maturin distribution.
packages/​grpc/​LICENSE	Includes the plugin’s Apache license.
packages/​grpc/​Cargo.toml	Updates the relocated native crate version.
packages/​grpc/​Cargo.lock	Synchronizes the native crate’s locked version.
packages/​grpc/​.python-version	Selects Python 3.10 for plugin development.
MANIFEST.in	Defines facade source-archive contents.
examples/​postgres_example.py	Demonstrates batched COPY writes.
docs/​usage.md	Documents backend extras and PostgreSQL usage.
docs/​api.md	Removes the existing API reference.
AGENTS.md	Updates contributor guidance for the package split.
.gitignore	Adds native build, macOS, and documentation ignore rules.
.github/​workflows/​wheels.yml	Adds backend installation matrices and two-distribution publishing.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The schema cache can miss table changes and corrupt writes, the patch upgrade breaks existing gRPC installations, and timestamp conversion mishandles valid dates.

3 open issues

• Revalidate cached schema after external table changes
• Treat gRPC dependency split as a breaking release
• Restore missing API and testing documentation

2 previously missed issues

In code that hasn't changed since last review

Source archive omits local gRPC dependency path

MANIFEST.in:7

The facade source archive omits packages/grpc, but its pyproject.toml still overrides the gRPC dependency with that local path. Running the documented uv sync --extra grpc from the unpacked archive therefore fails because the directory is absent. Include the local plugin, or provide an archive installation path that resolves the published plugin instead.

Row-count errors omit acknowledged rows and batch uncertainty

python/​greptimedb_ingester/​postgres.py:485

If a later COPY reports a row-count mismatch, this exception omits acknowledged_rows even though earlier batches have committed. Include affected in the error and explicitly mark the current batch as uncertain, so callers can distinguish the acknowledged prefix from writes whose outcome is unknown.

3 resolved since last review

• Encode generator rows before mutable values are reused
• Report acknowledged rows on validation failures
• Allow release uploads to skip existing files

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Stale PostgreSQL schema validation can cause data loss, and encoding failures can misreport acknowledged rows, leading to duplicate retries.

3 open issues

• Revalidate cached schema after external table changes
• Treat gRPC dependency split as a breaking release
• Restore missing API and testing documentation

_{Review effort: Balanced}