feat: map geo type to string or binary. (#767)

* feat: map geo type to string or binary.

* chore: add AGENTS.md

* update README.md.

Author: youngsofun

AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md
+
+Read this file first. Then open only the relevant file(s) under `agents/`.
+
+This repository is a Rust workspace for BendSQL plus a separate frontend, language bindings, and Docker-based integration tests.
+
+## Repo Map
+
+- `cli/`: `bendsql` CLI, REPL, output formatting, and web UI host
+- `core/`: low-level Databend REST client
+- `driver/`: public Rust driver API and query execution layer
+- `sql/`: shared SQL/value decoding and encoding logic
+- `macros/`: proc macros used by the Rust driver stack
+- `frontend/`: editable browser UI source
+- `cli/frontend/`: generated frontend assets embedded by the CLI; do not edit by hand
+- `bindings/python/`: Python client bindings
+- `bindings/nodejs/`: Node.js client bindings
+- `tests/`: Docker-based integration test harness
+- `ttc/`: tcp test container utilities
+
+## Global Rules
+
+- Prefer source edits over generated output.
+- Do not manually edit `cli/frontend`; rebuild it from `frontend/`.
+- Keep changes inside the owning subsystem unless the task clearly crosses boundaries.
+- Check for uncommitted user changes before editing and do not revert unrelated work.
+- Report the exact verification commands you ran, plus anything you skipped and why.
+
+## Task Routing
+
+- Rust behavior, CLI flags, REPL, output, or public Rust API changes: read `agents/rust-workspace.md`
+- Browser UI, embedded assets, or frontend dev/proxy flow: read `agents/frontend.md`
+- Docker integration tests, Python bindings, or Node.js bindings: read `agents/integration-and-bindings.md`
+
+Some tasks span multiple areas. In that case, read the relevant files before editing.

agents/frontend.md

@@ -0,0 +1,31 @@
+# Frontend
+
+Use this guide for work in `frontend/` and for changes that affect how the CLI serves the web UI.
+
+## Source of Truth
+
+- Edit `frontend/` for browser UI code.
+- Do not manually edit `cli/frontend`; it is generated output copied from the frontend build.
+- Touch `cli/` only when changing how the CLI serves embedded assets or proxies the dev server.
+
+## Workflow
+
+- Interactive development: run `cd frontend && pnpm run dev` in one terminal and `make dev-run` in another.
+- Production asset rebuild: run `make build-frontend`.
+- `make build` and `make run` also rebuild frontend assets before building or running the CLI.
+
+## Repo-Specific Behavior
+
+- Development proxy mode depends on `BENDSQL_DEV_MODE=1`.
+- The CLI serves generated assets from `cli/frontend` for production-style runs.
+- If a task changes both browser UI and CLI wiring, validate both sides.
+
+## Validation
+
+- At minimum, run `cd frontend && pnpm run build` for frontend changes.
+- If UI serving or proxy behavior changed, also validate the relevant CLI flow with `make dev-run` or a normal CLI run.
+
+## Response Expectations
+
+- State whether you changed source UI code, CLI embedding logic, or both.
+- Report whether you rebuilt generated assets.

agents/integration-and-bindings.md

@@ -0,0 +1,36 @@
+# Integration And Bindings
+
+Use this guide for Docker-based integration tests and for work in `bindings/python/` or `bindings/nodejs/`.
+
+## Integration Harness
+
+- Integration commands are slower and more side-effectful than unit tests.
+- `tests/Makefile` starts Docker Compose services.
+- The setup may append `127.0.0.1 minio` to `/etc/hosts` if it is missing.
+- Prefer the narrowest integration target that matches the change.
+
+## Integration Commands
+
+- `make integration-core`
+- `make integration-driver`
+- `make integration-bendsql`
+- `make integration-bindings-python`
+- `make integration-bindings-nodejs`
+- `make integration` only when multiple layers changed or broad final validation is needed
+
+## Bindings Guidance
+
+- Treat Python and Node.js bindings as separate deliverables.
+- Do not assume a Rust-layer fix is complete if the same behavior is exposed through bindings.
+- For externally visible API or type-mapping changes, inspect whether bindings need matching updates or verification.
+- After changes under `bindings/nodejs/`, run `cd bindings/nodejs && pnpm prettier --write .`.
+- After changes under `bindings/python/`, run `cd bindings/python && ruff format .`.
+- Python binding integration tests run with `behave`.
+- Node.js binding integration tests run with `pnpm run test`.
+- For local Python binding test runs, make sure the interpreter that owns `behave` is loading the current `databend_driver` build or install, not a stale site-packages copy.
+- When adjusting local binding test flow, prefer changes that keep `Makefile` targets and related helper scripts aligned with the CI workflow instead of introducing local-only behavior that can drift from CI.
+
+## Response Expectations
+
+- Call out any Docker or local-environment prerequisites for the commands you ran.
+- If integration or binding validation was skipped, say exactly what was skipped and why.

agents/rust-workspace.md

@@ -0,0 +1,43 @@
+# Rust Workspace
+
+Use this guide for work in `cli/`, `core/`, `driver/`, `sql/`, `macros/`, and `ttc/`.
+
+## Ownership
+
+- `cli/`: CLI flags, REPL behavior, output formatting, local web server wiring
+- `core/`: low-level Databend REST client behavior
+- `driver/`: public Rust driver API, query execution, parameter binding
+- `sql/`: shared SQL parsing/value decoding/encoding logic
+- `macros/`: proc-macro behavior
+- `ttc/`: test-container utilities; touch only when the task is explicitly about TTC
+
+## Change Routing
+
+- CLI UX changes usually belong in `cli/`.
+- Protocol behavior, row decoding, type mapping, and parameter binding usually belong in `driver/`, `sql/`, or `core/`.
+- Do not move reusable logic into `cli/` if bindings or driver users should share it.
+- If a change affects a public API or observable query behavior, check whether bindings or docs also need updates.
+
+## Validation
+
+- Prefer targeted Rust validation first when the scope is narrow.
+- For general Rust changes, run `make test`.
+- For broad or user-facing changes, run `make check`.
+- This repo ignores `Cargo.lock`. If local Rust results differ from CI and the change may depend on dependency resolution, check whether a stale local `Cargo.lock` is masking the issue. Regenerate or remove it only as a targeted troubleshooting step, not as a default workflow.
+
+`make check` currently runs:
+
+- `cargo fmt --all -- --check`
+- `cargo clippy --all-targets --all-features -- -D warnings`
+- `cargo deny check`
+- `cargo machete`
+- `hawkeye check`
+- `typos`
+
+If local tooling is missing, report that explicitly instead of silently skipping it.
+
+## Response Expectations
+
+- Summarize the behavior change, not just the files touched.
+- List the exact test or check commands that ran.
+- If you skipped validation, say what was skipped and why.

bindings/nodejs/Cargo.toml

@@ -15,6 +15,7 @@ doc = false
 [dependencies]
 chrono = { workspace = true }
 databend-driver = { workspace = true, features = ["rustls", "flight-sql"] }
+databend-driver-core = { workspace = true }
 env_logger = "0.11.8"
 tokio-stream = { workspace = true }
 

bindings/nodejs/README.md

@@ -98,8 +98,8 @@ await conn.close();
 | `MAP`       | `Object`          |
 | `VARIANT`   | `String / Object` |
 | `BITMAP`    | `String`          |
-| `GEOMETRY`  | `String`          |
-| `GEOGRAPHY` | `String`          |
+| `GEOMETRY`  | `String / Buffer` |
+| `GEOGRAPHY` | `String / Buffer` |
 
 Note: `VARIANT` is a json encoded string. Example:
 
@@ -117,6 +117,17 @@ const value = JSON.parse(data);
 console.log(value);
 ```
 
+`GEOMETRY` and `GEOGRAPHY` follow the current `geometry_output_format` setting. Text formats such as `GeoJSON` or `WKT` return `String`; binary formats such as `WKB` or `EWKB` return `Buffer`.
+
+For example:
+
+```javascript
+const row = await conn.queryRow(
+  "settings(geometry_output_format='WKB') SELECT st_point(60, 37)",
+);
+console.log(Buffer.isBuffer(row.values()[0]));
+```
+
 We also provide a helper function to convert `VARIANT` to `Object`:
 
 ```javascript

bindings/nodejs/src/lib.rs

@@ -371,9 +371,23 @@ impl ToNapiValue for Value<'_> {
                     String::to_napi_value(env, s.to_string())
                 }
             }
-            databend_driver::Value::Geometry(s) => String::to_napi_value(env, s.to_string()),
+            databend_driver::Value::Geometry(s) => match s {
+                databend_driver_core::value::GeoValue::String(s) => {
+                    String::to_napi_value(env, s.to_string())
+                }
+                databend_driver_core::value::GeoValue::Binary(b) => {
+                    Buffer::to_napi_value(env, Buffer::from(b.as_slice()))
+                }
+            },
             databend_driver::Value::Interval(s) => String::to_napi_value(env, s.to_string()),
-            databend_driver::Value::Geography(s) => String::to_napi_value(env, s.to_string()),
+            databend_driver::Value::Geography(s) => match s {
+                databend_driver_core::value::GeoValue::String(s) => {
+                    String::to_napi_value(env, s.to_string())
+                }
+                databend_driver_core::value::GeoValue::Binary(b) => {
+                    Buffer::to_napi_value(env, Buffer::from(b.as_slice()))
+                }
+            },
             databend_driver::Value::Vector(inner) => {
                 let mut arr = ctx.create_array(inner.len() as u32)?;
                 for (i, v) in inner.iter().enumerate() {

bindings/nodejs/tests/binding.js

@@ -45,6 +45,10 @@ const dsn = process.env.TEST_DATABEND_DSN
   ? process.env.TEST_DATABEND_DSN
   : "databend://root:@localhost:8000/default?sslmode=disable";
 
+const POINT_GEOJSON = '{"type": "Point", "coordinates": [60,37]}';
+const POINT_WKT = "POINT(60 37)";
+const POINT_WKB = Buffer.from("01010000000000000000004E400000000000804240", "hex");
+
 Given("A new Databend Driver Client", async function () {
   this.client = new Client(dsn);
   const conn = await this.client.getConn();
@@ -226,6 +230,23 @@ Then("Select types should be expected native types", async function () {
     const row = await this.conn.queryRow(`SELECT to_datetime_tz('2024-04-16 12:34:56.789 +0800'))`);
     assert.deepEqual(row.values(), [new Date("2024-04-16 04:34:56.789Z")]);
   }
+
+  if (DRIVER_VERSION > [0, 31, 0] && DB_VERSION > [1, 2, 894]) {
+    {
+      const row = await this.conn.queryRow("SELECT st_point(60,37)");
+      assert.deepEqual(row.values(), [POINT_GEOJSON]);
+    }
+
+    {
+      const row = await this.conn.queryRow("settings(geometry_output_format='WKT') SELECT st_point(60,37)");
+      assert.deepEqual(row.values(), [POINT_WKT]);
+    }
+
+    {
+      const row = await this.conn.queryRow("settings(geometry_output_format='WKB') SELECT st_point(60,37)");
+      assert.deepEqual(row.values(), [POINT_WKB]);
+    }
+  }
 });
 
 Then("Select numbers should iterate all rows", async function () {

bindings/python/README.md

@@ -151,15 +151,15 @@ except Exception as e:
 
 ### Semi-Structured Data Types
 
-| Databend    | Python  |
-| ----------- | ------- |
-| `ARRAY`     | `list`  |
-| `TUPLE`     | `tuple` |
-| `MAP`       | `dict`  |
-| `VARIANT`   | `str`   |
-| `BITMAP`    | `str`   |
-| `GEOMETRY`  | `str`   |
-| `GEOGRAPHY` | `str`   |
+| Databend    | Python        |
+| ----------- | ------------- |
+| `ARRAY`     | `list`        |
+| `TUPLE`     | `tuple`       |
+| `MAP`       | `dict`        |
+| `VARIANT`   | `str`         |
+| `BITMAP`    | `str`         |
+| `GEOMETRY`  | `str / bytes` |
+| `GEOGRAPHY` | `str / bytes` |
 
 Note: `VARIANT` is a json encoded string. Example:
 
@@ -177,6 +177,15 @@ value = json.loads(data)
 print(value)
 ```
 
+`GEOMETRY` and `GEOGRAPHY` follow the current `geometry_output_format` setting. Text formats such as `GeoJSON` or `WKT` return `str`; binary formats such as `WKB` or `EWKB` return `bytes`.
+
+For example:
+
+```python
+row = await conn.query_row("settings(geometry_output_format='WKB') SELECT st_point(60, 37)")
+assert isinstance(row.values()[0], bytes)
+```
+
 ## APIs
 
 ### Exception Classes (PEP 249 Compliant)

bindings/python/src/types.rs

@@ -33,6 +33,7 @@ use crate::exceptions::map_error_to_exception;
 use crate::utils::wait_for_future;
 #[cfg(feature = "cp38")]
 use databend_driver::{self, zoned_to_chrono_datetime, zoned_to_chrono_fixed_offset};
+use databend_driver_core::value::GeoValue;
 
 pub static VERSION: Lazy<String> = Lazy::new(|| {
     let version = option_env!("CARGO_PKG_VERSION").unwrap_or("unknown");
@@ -129,8 +130,20 @@ impl<'py> IntoPyObject<'py> for Value {
             }
             databend_driver::Value::Bitmap(s) => s.into_bound_py_any(py)?,
             databend_driver::Value::Variant(s) => s.into_bound_py_any(py)?,
-            databend_driver::Value::Geometry(s) => s.into_bound_py_any(py)?,
-            databend_driver::Value::Geography(s) => s.into_bound_py_any(py)?,
+            databend_driver::Value::Geometry(s) => match s {
+                GeoValue::String(s) => s.into_bound_py_any(py)?,
+                GeoValue::Binary(b) => {
+                    let buf = PyBytes::new(py, &b);
+                    buf.into_bound_py_any(py)?
+                }
+            },
+            databend_driver::Value::Geography(s) => match s {
+                GeoValue::String(s) => s.into_bound_py_any(py)?,
+                GeoValue::Binary(b) => {
+                    let buf = PyBytes::new(py, &b);
+                    buf.into_bound_py_any(py)?
+                }
+            },
             databend_driver::Value::Interval(s) => {
                 let value = databend_driver::Interval::from_string(&s).unwrap();
                 let total_micros = (value.months as i64) * 30 * 86400000000