gotypeql

go-typeql

A Go ORM for TypeDB 3.x. It maps a graph schema to Go structs. It provides type-safe CRUD, queries, migrations, and code generation.

Why

TypeDB has no official Go driver. This project wraps the Rust 3.x driver through CGo. Its ORM maps TypeDB entities and relations to Go structs. You do not have to write raw TypeQL.

TypeDB in 30 seconds

TypeDB is a strongly-typed database that organizes data into three primitives:

• Entities — independent objects (Person, Company, Document)
• Relations — typed connections between entities with named roles (Employment connects a Person as employee to a Company as employer)
• Attributes — typed values owned by entities or relations (name, email, age)

TypeDB uses its own query language, TypeQL. go-typeql generates TypeQL for you from Go structs, so you rarely need to write it by hand.

Example

// Define models with struct tags
type Person struct {
    gotype.BaseEntity
    Name  string `typedb:"name,key"`
    Email string `typedb:"email,unique"`
    Age   *int   `typedb:"age"`
}

type Company struct {
    gotype.BaseEntity
    Name string `typedb:"name,key"`
}

type Employment struct {
    gotype.BaseRelation
    Employee *Person  `typedb:"role:employee"`
    Employer *Company `typedb:"role:employer"`
}

// Register, connect, go
gotype.Register[Person]()
gotype.Register[Company]()
gotype.Register[Employment]()

db := gotype.NewDatabase(conn, "my_db")
persons := gotype.MustNewManager[Person](db)

persons.Insert(ctx, &Person{Name: "Alice", Email: "alice@example.com"})

results, _ := persons.Query().Filter(gotype.Eq("name", "Alice")).Execute(ctx)

Features

• Struct-tag models — entities and relations map to Go structs with typedb:"..." tags
• Generic CRUD — Manager[T] for Insert, Get, Update, Delete, Put (upsert), plus batch variants
• Query builder — filters, sorting, pagination, aggregations, selected-field reads, typed callbacks, and count-free mutations
• Schema migration — diff Go structs against a live database, apply changes, track migration state
• Code generator — tqlgen generates Go structs, DTOs, and a typed registry from TypeQL schema files
• Rust FFI driver — wraps typedb-driver 3.x through CGo. The ORM packages compile without it. Their tests also run without it.

Packages

Getting started

Install

The latest stable release is v3.2.1, for TypeDB 3.14.2.

go get github.com/CaliLuke/go-typeql/v3@v3.2.1

Version 3 uses the /v3 import path, a sealed Filter interface, and typed Computed expressions. See Upgrading to v3 for the migration steps. For v1 to v2, see Upgrading to v2.

The ast/, given/, gotype/, and tqlgen/ packages work without CGo or a running database. The driver/ package targets TypeDB 3.14.2. It uses the typedb-driver 3.14.0 and typeql 3.14.0 Rust crates. The built-in function expressions (Abs, Length, and the others) emit fully qualified names such as std::math::abs. These names need TypeDB server 3.13.6 or later. If you use TypeDB 3.10.x, use go-typeql v1.10.x.

The driver/ package requires the static library for the Rust FFI. go get downloads only the source tree. It does not build or install libtypedb_go_ffi.a.

Before you build code that imports driver/, choose one method:

• Build the Rust library from source in the repository.
• Install a prebuilt archive.

Prebuilt FFI library

Each release includes prebuilt static libraries for:

• linux-amd64
• linux-arm64
• darwin-amd64
• darwin-arm64

platform="$(go env GOOS)-$(go env GOARCH)"

# Download for your platform
gh release download v3.2.1 -p "libtypedb_go_ffi-${platform}.a" -R CaliLuke/go-typeql

# Option A: place in standard lib path, build with typedb_prebuilt tag
libdir=/usr/local/lib
if [ "$(go env GOOS)-$(go env GOARCH)" = "darwin-arm64" ]; then libdir=/opt/homebrew/lib; fi
cp "libtypedb_go_ffi-${platform}.a" "${libdir}/libtypedb_go_ffi.a"
go test -tags "cgo,typedb,typedb_prebuilt" ./...

# Option B: place in source tree (no extra build tag needed)
mkdir -p driver/rust/target/release
cp "libtypedb_go_ffi-${platform}.a" driver/rust/target/release/libtypedb_go_ffi.a
go test -tags "cgo,typedb" ./...

On Apple Silicon with Homebrew, typedb_prebuilt also searches /opt/homebrew/lib. If you do not want to install into a linker search path, use Option B instead.

If your platform has no published archive, clone the repository. Then run make build-rust before go build or go test -tags "cgo,typedb" ....

NOTE: go get does not generate the Rust archive. This restriction also applies to modules from the Go proxy or module cache.

The Getting Started walkthrough is a complete runnable example. It covers connection, schema definition, and CRUD operations.

Running tests

# Unit tests (738 tests, no database needed)
go test ./ast/... ./given/... ./gotype/... ./tqlgen/...

# Integration tests (with the repo compose file, TypeDB is exposed on host port 1730)
docker compose up -d
TEST_DB_ADDRESS=localhost:1730 TYPEDB_GO_COMPOSE_PORT_MAP=1 go test -tags "cgo,typedb,integration" ./driver/... ./gotype/...

Debugging hangs

See the dedicated guide: Debugging Hangs.

Docs

• Development Guide — building, project structure, Rust FFI, contributing

• Testing Guide — test strategy, mocks, integration test infrastructure

• Debugging Hangs — debug flags, log keys, startup-hang diagnostics

• API Reference — models, CRUD, queries, filters, schema, migration, code generator

• TypeQL agent skill — The TypeQL team maintains the skill in the typedb/typeql-evals repository. This repository does not vendor it.

  Use typeql-check to make sure that TypeQL syntax is correct.

Requirements

• The project requires Go 1.27 or later. Darwin also requires macOS 13 or later.
• Building the driver from source needs Rust 1.97 or later. The repository pins Rust 1.98.1.
• Integration tests require TypeDB 3.x.

License

MIT