duckgo init

Author: ma6174

.github/workflows/go.yml

@@ -0,0 +1,25 @@
+name: Go
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: '1.24.4'
+        check-latest: true
+
+    - name: Test
+      run: go test -v -ldflags="-checklinkname=0" ./...
+
+    - name: Vet
+      run: go vet ./... 

.gitignore

@@ -0,0 +1,22 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Go workspace file
+go.work
+go.work.sum
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Mac files
+.DS_Store 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ma6174
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT of OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

Makefile

@@ -0,0 +1,2 @@
+test:
+	go test -cover -v -ldflags="-checklinkname=0" ./...

README.cn.md

@@ -0,0 +1,75 @@
+# DuckGo: 轻松创建 Go/XGo 版 DuckDB UDF
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/ma6174/duckgo.svg)](https://pkg.go.dev/github.com/ma6174/duckgo)
+
+`DuckGo` 是一个 Go 语言库，旨在极大地简化为 [DuckDB](https://duckdb.org/) 创建用户定义函数 (UDF) 的过程。它通过 Go 的反射机制，让您可以直接将一个普通的 Go 函数无缝转换为 DuckDB 的标量函数 (Scalar UDF)，同时通过[ixgo](https://github.com/goplus/ixgo)支持从 Go/XGo 脚本动态创建加载 UDF，无需预先编译。
+
+## 核心功能
+
+- **从原生 Go 函数创建**: 直接将你的 Go 函数（例如 `func(a, b int) int`) 转换为 DuckDB UDF。
+- **自动类型映射**: 自动处理 Go 类型与 DuckDB 类型之间的转换，支持多种数据类型。
+- **支持可变参数**: 支持 Go 的可变参数函数 (variadic functions)。
+- **动态脚本加载**: 无需编译！可以直接从 `.go`、`.xgo` 源文件动态加载函数作为 UDF。
+- **SQL 内直接加载**: 提供一个辅助函数，允许您直接在 SQL 查询中加载和注册脚本中的 UDF。
+- **错误处理**: 妥善处理 UDF 执行过程中的 `panic`，并将其转换为 DuckDB 错误返回。
+
+## 安装
+
+```bash
+go get github.com/ma6174/duckgo
+```
+
+## 重要提示：关于动态脚本功能
+
+本项目的动态脚本加载功能（由 `script` 包提供）依赖于 [ixgo](https://github.com/goplus/ixgo)。由于 `ixgo` 的工作原理，当您编译或运行任何使用了 `script` 包的代码时，**必须**添加一个特定的链接器标志来禁用符号链接检查。
+
+否则，您会遇到链接器错误。
+
+**编译时:**
+```bash
+go build -ldflags="-checklinkname=0" .
+```
+
+**运行时:**
+```bash
+go run -ldflags="-checklinkname=0" .
+```
+
+如果您在自己的项目里引用了本库的 `script` 包，请务必在您的编译和运行命令中加入此标志。
+
+## 使用方法
+
+下面是几个例子，展示了如何使用 `DuckGo`。完整的可运行示例代码存放在 [`example`](./example) 目录下。
+
+### 示例 1: 从原生 Go 函数创建 UDF
+
+这是最基本的使用方式。任何普通的 Go 函数都可以被注册。
+
+核心逻辑是使用 `udf.BuildScalarUDF` 将原生 Go 函数包装起来，然后通过 `duckdb.RegisterScalarUDF` 进行注册。
+
+**完整代码请参见: [`example/simple_udf/main.go`](./example/simple_udf/main.go)**
+
+### 示例 2: 从 Go 脚本动态加载 UDF
+
+这是 `DuckGo` 最强大的功能之一。您无需编译，可以直接将一个 Go 源文件中的函数注册为 UDF。
+
+通过 `script.AddIXGoUDFFromFile` 函数，您可以指定一个 `.go` 文件和需要加载的函数名。
+
+**完整代码请参见: [`example/script_udf/`](./example/script_udf/)**
+
+### 示例 3: 通过 SQL 直接加载脚本 UDF
+
+为了让动态加载更加灵活，您甚至可以直接在 SQL 中调用一个辅助函数来加载 UDF。
+
+首先调用 `script.EnableRegisterUDFFromSQL(db)` 启用该功能，之后就可以在 SQL 中使用 `add_ixgo_udf` 函数了。
+
+**完整代码请参见: [`example/sql_load_udf/`](./example/sql_load_udf/)**
+
+## 包概览
+
+- **`udf`**: 核心包，负责将原生的 Go 函数转换为 DuckDB UDF。
+- **`script`**: 提供从 Go/XGo 脚本动态加载 UDF 的功能。
+
+## 许可证
+
+本项目采用 [MIT](LICENSE) 许可证。

README.md

@@ -0,0 +1,75 @@
+# DuckGo: Create DuckDB UDFs in Go/XGo with Ease
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/ma6174/duckgo.svg)](https://pkg.go.dev/github.com/ma6174/duckgo)
+
+`DuckGo` is a Go library designed to dramatically simplify the process of creating User-Defined Functions (UDFs) for [DuckDB](https://duckdb.org/). It uses Go's reflection mechanism to seamlessly convert a native Go function into a DuckDB scalar UDF. Additionally, it leverages [ixgo](https://github.com/goplus/ixgo) to support dynamically loading UDFs from Go/XGo scripts without prior compilation.
+
+## Core Features
+
+- **Create from Native Go Functions**: Directly convert your Go functions (e.g., `func(a, b int) int`) into DuckDB UDFs.
+- **Automatic Type Mapping**: Automatically handles type conversions between Go and DuckDB, supporting a wide range of data types.
+- **Variadic Function Support**: Seamlessly supports Go's variadic functions.
+- **Dynamic Script Loading**: No compilation needed! Directly load functions from `.go` or `.xgo` source files as UDFs.
+- **Direct Loading from SQL**: Provides a helper function to load and register UDFs from scripts directly within SQL queries.
+- **Panic Handling**: Gracefully recovers from panics during UDF execution and converts them into DuckDB errors.
+
+## Installation
+
+```bash
+go get github.com/ma6174/duckgo
+```
+
+## Important Note: Regarding Dynamic Scripting
+
+The dynamic script loading feature (provided by the `script` package) relies on [ixgo](https://github.com/goplus/ixgo). Due to how `ixgo` works, you **must** add a specific linker flag to disable symbol name checking whenever you build or run code that uses the `script` package.
+
+Failure to do so will result in a linker error.
+
+**Build:**
+```bash
+go build -ldflags="-checklinkname=0" .
+```
+
+**Run:**
+```bash
+go run -ldflags="-checklinkname=0" .
+```
+
+If you import the `script` package in your own project, make sure to include this flag in your build and run commands.
+
+## Usage
+
+Here are a few examples of how to use `DuckGo`. For complete, runnable code, please see the [`example`](./example) directory.
+
+### Example 1: Creating a UDF from a Native Go Function
+
+This is the most basic use case. Any regular Go function can be registered.
+
+The core logic involves wrapping the native Go function with `udf.BuildScalarUDF` and then registering it using `duckdb.RegisterScalarUDF`.
+
+**For the full code, see: [`example/simple_udf/main.go`](./example/simple_udf/main.go)**
+
+### Example 2: Loading a UDF from a Go Script
+
+This is one of `DuckGo`'s most powerful features. You can register a function from a Go source file as a UDF without compiling it first.
+
+The `script.AddIXGoUDFFromFile` function allows you to specify a `.go` file and the names of the functions you want to load.
+
+**For the full code, see: [`example/script_udf/`](./example/script_udf/)**
+
+### Example 3: Loading a UDF Directly via SQL
+
+For even greater flexibility, you can call a helper function from within SQL to load UDFs.
+
+First, enable the feature by calling `script.EnableRegisterUDFFromSQL(db)`. You can then use the `add_ixgo_udf` function in your SQL queries.
+
+**For the full code, see: [`example/sql_load_udf/`](./example/sql_load_udf/)**
+
+## Package Overview
+
+- **`udf`**: The core package, responsible for converting native Go functions into DuckDB UDFs.
+- **`script`**: Provides the functionality for dynamically loading UDFs from Go/XGo scripts.
+
+## License
+
+This project is licensed under the [MIT](LICENSE) License. 

example/script_udf/README.md

@@ -0,0 +1,15 @@
+# Example: Dynamic UDF from Script
+
+This example demonstrates how to dynamically load a User-Defined Function (UDF) into DuckDB from a Go source file (`my_udfs.go`) without prior compilation.
+
+## How to Run
+
+Due to the use of `ixgo` for dynamic code interpretation, you need to provide a specific linker flag to disable symbol name checking when running this example.
+
+Use the following command from within this directory (`example/script_udf`):
+
+```bash
+go run -ldflags="-checklinkname=0" .
+```
+
+This will execute the `main.go` program, which dynamically loads the `my_multiply` function from `my_udfs.go` and then calls it from within a SQL query.

example/script_udf/main.go

@@ -0,0 +1,32 @@
+package main
+
+import (
+	"database/sql"
+	"fmt"
+	"log"
+
+	"github.com/ma6174/duckgo/script" // 导入 script 包
+	_ "github.com/marcboeker/go-duckdb/v2"
+)
+
+func main() {
+	db, err := sql.Open("duckdb", "")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer db.Close()
+
+	// 从脚本文件加载 "multiply" 函数
+	err = script.AddIXGoUDFFromFile(db, "my_udfs.go", "my_multiply")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// 在 SQL 中使用它
+	var result int
+	err = db.QueryRow("SELECT my_multiply(7, 6)").Scan(&result)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("my_multiply(7, 6) = %d\n", result)
+}

example/script_udf/my_udfs.go

@@ -0,0 +1,6 @@
+// my_udfs.go
+package main
+
+func my_multiply(a, b int) int {
+	return a * b
+}

example/simple_udf/main.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"log"
+
+	"github.com/ma6174/duckgo/udf"
+	"github.com/marcboeker/go-duckdb/v2"
+)
+
+func main() {
+	db, err := sql.Open("duckdb", "")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer db.Close()
+
+	// 1. 定义一个你想要在 SQL 中使用的 Go 函数
+	add := func(a, b int) int {
+		return a + b
+	}
+
+	// 2. 使用 udf.BuildScalarUDF 将其包装成 DuckDB UDF
+	scalarFunc, err := udf.BuildScalarUDF(add)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// 3. 获取连接并注册 UDF
+	conn, err := db.Conn(context.Background())
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer conn.Close()
+
+	err = duckdb.RegisterScalarUDF(conn, "go_add", scalarFunc)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// 4. 现在你可以在 SQL 中调用它了!
+	var result int
+	err = db.QueryRow("SELECT go_add(5, 3)").Scan(&result)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("go_add(5, 3) = %d\n", result)
+}