DuckDB client (openduck extension)
  └─ ATTACH 'openduck:mydb?endpoint=...' AS cloud
       └─ gRPC + Arrow IPC
            └─ Gateway (Rust)
                 ├─ auth / routing / plan splitting
                 ├─ Worker 1 (embedded DuckDB)
                 └─ Worker N (embedded DuckDB)
                      ├─ Postgres (metadata)
                      └─ Object store (sealed layers)

crates/
  exec-gateway/     # 认证、路由、混合执行计划拆分
  exec-worker/      # 嵌入式DuckDB、Arrow IPC流处理
  exec-proto/       # protobuf/tonic代码生成
  openduck-cli/     # 统一CLI（serve|gateway|worker）
  diff-*/           # 差分存储（分层、元数据、FUSE）

extensions/
  openduck/         # DuckDB C++扩展（StorageExtension + Catalog）

clients/
  python/           # 可通过pip安装的openduck封装库

proto/
  openduck/v1/      # execution.proto

git clone https://github.com/CITGuru/openduck
cd openduck
cargo build --workspace

cd extensions/openduck
make

undefined

pip install -e clients/python

undefined

---

import openduck  # 自动从构建目录或OPENDUCK_EXTENSION_PATH检测扩展

con = openduck.connect("mydb")  # 使用OPENDUCK_TOKEN环境变量
con.sql("SELECT 1 AS x").show()
con.sql("SELECT * FROM cloud.users LIMIT 10").show()

import duckdb
import os

ext_path = os.environ["OPENDUCK_EXTENSION_PATH"]

undefined

export OPENDUCK_TOKEN=your-secret-token
export OPENDUCK_EXTENSION_PATH=extensions/openduck/build/release/extension/openduck/openduck.duckdb_extension
export OPENDUCK_ENDPOINT=http://localhost:7878   # 默认值

duckdb -unsigned -c "
  LOAD 'extensions/openduck/build/release/extension/openduck/openduck.duckdb_extension';
  ATTACH 'openduck:mydb?endpoint=http://localhost:7878&token=${OPENDUCK_TOKEN}' AS cloud;
  SHOW ALL TABLES;
  SELECT * FROM cloud.users LIMIT 5;
"

use duckdb::{Connection, Result};

fn main() -> Result<()> {
    let conn = Connection::open_in_memory()?;
    let ext_path = std::env::var("OPENDUCK_EXTENSION_PATH").unwrap();
    let token = std::env::var("OPENDUCK_TOKEN").unwrap();

    conn.execute_batch(&format!(r#"
        SET allow_unsigned_extensions = true;
        LOAD '{ext_path}';
        ATTACH 'openduck:mydb?endpoint=http://localhost:7878&token={token}' AS cloud;
    "#))?;

    let mut stmt = conn.prepare("SELECT * FROM cloud.users LIMIT 10")?;
    let rows = stmt.query_map([], |row| {
        Ok(row.get::<_, String>(0)?)
    })?;

    for row in rows {
        println!("{}", row?);
    }
    Ok(())
}

[LOCAL]  HashJoin(l.id = r.id)
  [LOCAL]  Scan(products)       ← 在本地机器运行
  [LOCAL]  Bridge(REMOTE→LOCAL)
    [REMOTE] Scan(sales)        ← 在远程工作节点运行

undefined

---

openduck:<database_name>?endpoint=<url>&token=<token>

-- 本地开发环境
ATTACH 'openduck:mydb?token=dev-token' AS cloud;

-- 远程服务器，显式指定endpoint
ATTACH 'openduck:mydb?endpoint=https://my-server.example.com&token=prod-token' AS cloud;

-- 别名：od:同样生效
ATTACH 'od:mydb?endpoint=http://localhost:7878&token=dev-token' AS cloud;

import duckdb, os

ext_path = os.environ["OPENDUCK_EXTENSION_PATH"]
token = os.environ["OPENDUCK_TOKEN"]

con = duckdb.connect(config={"allow_unsigned_extensions": "true"})
con.execute(f"LOAD '{ext_path}';")

-- 挂载由远程工作节点托管、基于DuckLake的目录
con.execute(f"ATTACH 'openduck:lakehouse?endpoint=http://localhost:7878&token={token}' AS lh;")

-- 通过OpenDuck传输层透明查询DuckLake表
con.sql("SELECT * FROM lh.events WHERE event_date = today()").show()

-- 混合查询：本地临时数据与远程DuckLake表关联
con.sql("""
    SELECT l.session_id, r.user_email
    FROM memory.sessions l
    JOIN lh.users r ON l.user_id = r.id
""").show()

-- 执行ATTACH ... AS cloud后
SHOW ALL TABLES;
SELECT table_name FROM information_schema.tables WHERE table_schema = 'cloud';

INSERT INTO cloud.events SELECT * FROM read_parquet('local_dump.parquet');

CREATE TABLE cloud.new_table AS SELECT * FROM local_csv LIMIT 0;
INSERT INTO cloud.new_table SELECT * FROM local_csv;

con.sql("SELECT * FROM cloud.large_table WHERE region = 'us-east'") \
   .write_parquet("output/us_east.parquet")

-- 加载扩展前务必设置allow_unsigned_extensions
con = duckdb.connect(config={"allow_unsigned_extensions": "true"})

duckdb -unsigned

-- 设置环境变量指向构建好的扩展路径
export OPENDUCK_EXTENSION_PATH=$(pwd)/extensions/openduck/build/release/extension/openduck/openduck.duckdb_extension
ls -la $OPENDUCK_EXTENSION_PATH   # 确认文件存在

-- 验证服务器是否运行
cargo run -p openduck-cli -- serve -d mydb -t $OPENDUCK_TOKEN
-- 默认端口为7878 — 检查防火墙/端口绑定
curl http://localhost:7878/health

-- 服务器令牌与客户端令牌必须完全一致
export OPENDUCK_TOKEN=same-value-on-both-sides
-- 服务器端：cargo run -p openduck-cli -- serve -d mydb -t $OPENDUCK_TOKEN
-- 客户端：ATTACH '...&token=same-value-on-both-sides' AS cloud;

brew install bison
export PATH="$(brew --prefix bison)/bin:$PATH"
cd extensions/openduck && make

python -c "import duckdb; print(duckdb.__version__)"
-- 确保扩展Makefile使用相同版本
-- 检查extensions/openduck/Makefile中的DUCKDB_VERSION