mirror of
https://github.com/aljazceru/turso.git
synced 2025-12-31 23:14:21 +01:00
118 lines
3.4 KiB
Markdown
118 lines
3.4 KiB
Markdown
# Limbo driver for Go's `database/sql` library
|
|
|
|
**NOTE:** this is currently __heavily__ W.I.P and is not yet in a usable state.
|
|
|
|
This driver uses the awesome [purego](https://github.com/ebitengine/purego) library to call C (in this case Rust with C ABI) functions from Go without the use of `CGO`.
|
|
|
|
## Embedded Library Support
|
|
|
|
This driver includes an embedded library feature that allows you to distribute a single binary without requiring users to set environment variables. The library for your platform is automatically embedded, extracted at runtime, and loaded dynamically.
|
|
|
|
### Building from Source
|
|
|
|
To build with embedded library support, follow these steps:
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/tursodatabase/limbo
|
|
|
|
# Navigate to the Go bindings directory
|
|
cd limbo/bindings/go
|
|
|
|
# Build the library (defaults to release build)
|
|
./build_lib.sh
|
|
|
|
# Alternatively, for faster builds during development:
|
|
./build_lib.sh debug
|
|
```
|
|
|
|
### Build Options:
|
|
|
|
* Release Build (default): ./build_lib.sh or ./build_lib.sh release
|
|
|
|
- Optimized for performance and smaller binary size
|
|
- Takes longer to compile and requires more system resources
|
|
- Recommended for production use
|
|
|
|
* Debug Build: ./build_lib.sh debug
|
|
|
|
- Faster compilation times with less resource usage
|
|
- Larger binary size and slower runtime performance
|
|
- Recommended during development or if release build fails
|
|
|
|
If the embedded library cannot be found or extracted, the driver will fall back to the traditional method of finding the library in the system paths.
|
|
|
|
## To use: (_UNSTABLE_ testing or development purposes only)
|
|
|
|
### Option 1: Using the embedded library (recommended)
|
|
|
|
Build the driver with the embedded library as described above, then simply import and use. No environment variables needed!
|
|
|
|
### Option 2: Manual library setup
|
|
|
|
#### Linux | MacOS
|
|
|
|
_All commands listed are relative to the bindings/go directory in the limbo repository_
|
|
|
|
```
|
|
cargo build --package limbo-go
|
|
|
|
# Your LD_LIBRARY_PATH environment variable must include limbo's `target/debug` directory
|
|
|
|
export LD_LIBRARY_PATH="/path/to/limbo/target/debug:$LD_LIBRARY_PATH"
|
|
|
|
```
|
|
|
|
#### Windows
|
|
|
|
```
|
|
cargo build --package limbo-go
|
|
|
|
# You must add limbo's `target/debug` directory to your PATH
|
|
# or you could built + copy the .dll to a location in your PATH
|
|
# or just the CWD of your go module
|
|
|
|
cp path\to\limbo\target\debug\lib_limbo_go.dll .
|
|
|
|
go test
|
|
|
|
```
|
|
**Temporarily** you may have to clone the limbo repository and run:
|
|
|
|
`go mod edit -replace github.com/tursodatabase/limbo=/path/to/limbo/bindings/go`
|
|
|
|
```go
|
|
import (
|
|
"fmt"
|
|
"database/sql"
|
|
_"github.com/tursodatabase/limbo"
|
|
)
|
|
|
|
func main() {
|
|
conn, err := sql.Open("sqlite3", ":memory:")
|
|
if err != nil {
|
|
fmt.Printf("Error: %v\n", err)
|
|
os.Exit(1)
|
|
}
|
|
sql := "CREATE table go_limbo (foo INTEGER, bar TEXT)"
|
|
_ = conn.Exec(sql)
|
|
|
|
sql = "INSERT INTO go_limbo (foo, bar) values (?, ?)"
|
|
stmt, _ := conn.Prepare(sql)
|
|
defer stmt.Close()
|
|
_ = stmt.Exec(42, "limbo")
|
|
rows, _ := conn.Query("SELECT * from go_limbo")
|
|
defer rows.Close()
|
|
for rows.Next() {
|
|
var a int
|
|
var b string
|
|
_ = rows.Scan(&a, &b)
|
|
fmt.Printf("%d, %s", a, b)
|
|
}
|
|
}
|
|
```
|
|
|
|
## Implementation Notes
|
|
|
|
The embedded library feature was inspired by projects like [go-embed-python](https://github.com/kluctl/go-embed-python), which uses a similar approach for embedding and distributing native libraries with Go applications.
|