A Go ORM for TypeDB 3.x. Define your graph schema as Go structs, and get type-safe CRUD, queries, migrations, and code generation.
TypeDB has no official Go driver. This project wraps the Rust 3.x driver via CGo and layers a full ORM on top — so you can work with TypeDB entities and relations as regular Go structs instead of writing raw TypeQL.
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
employeeto a Company asemployer) - 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.
// 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.NewManager[Person](db)
persons.Insert(ctx, &Person{Name: "Alice", Email: "alice@example.com"})
results, _ := persons.Query().Filter(gotype.Eq("name", "Alice")).Execute(ctx)- 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 — chainable filters, sorting, pagination, aggregations (sum, count, min, max, mean, median, std, variance, group by)
- Schema migration — diff Go structs against a live database, apply changes, track migration state
- Code generator —
tqlgengenerates Go structs, DTOs, and a typed registry from TypeQL schema files - Rust FFI driver — wraps
typedb-driver3.x via CGo; the ORM packages compile and test without it
| Package | What it does | Needs CGo |
|---|---|---|
ast/ |
TypeQL AST nodes and compiler | No |
gotype/ |
ORM core: models, CRUD, queries, migrations | No |
tqlgen/ |
Code generator: TypeQL schema to Go structs | No |
driver/ |
Rust FFI bindings to typedb-driver 3.x |
Yes |
go get github.com/CaliLuke/go-typeql@v1.4.0The ast/, gotype/, and tqlgen/ packages work without CGo or a running database. The driver/ package requires the Rust FFI static library — you can either build it from source or use a prebuilt binary.
Each release includes prebuilt static libraries for linux-amd64, darwin-amd64, and darwin-arm64.
# Download for your platform
gh release download v1.3.1 -p 'libtypedb_go_ffi-linux-amd64.a' -R CaliLuke/go-typeql
# Option A: place in standard lib path, build with typedb_prebuilt tag
cp libtypedb_go_ffi-linux-amd64.a /usr/local/lib/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-linux-amd64.a driver/rust/target/release/libtypedb_go_ffi.a
go test -tags "cgo,typedb" ./...To build from source instead, see the Development Guide.
For a complete runnable example covering connect, schema, and CRUD, see the Getting Started walkthrough.
# Unit tests (354 tests, no database needed)
go test ./ast/... ./gotype/... ./tqlgen/...
# Integration tests (needs TypeDB on port 1729)
podman compose up -d
go test -tags "cgo,typedb,integration" ./driver/... ./gotype/...- Development Guide — building, project structure, Rust FFI, contributing
- Testing Guide — test strategy, mocks, integration test infrastructure
- API Reference — models, CRUD, queries, filters, schema, migration, code generator
- Go 1.26+
- Rust toolchain (only for the driver)
- TypeDB 3.x (only for integration tests)
MIT