gotypeql

README

go-typeql

A Go ORM for TypeDB 3.x. Define your graph schema as Go structs, and get type-safe CRUD, queries, migrations, and code generation.

Why

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 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.

What it looks like

// 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)

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 — 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 — tqlgen generates Go structs, DTOs, and a typed registry from TypeQL schema files
• Rust FFI driver — wraps typedb-driver 3.x via CGo; the ORM packages compile and test without it

Packages

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

Getting started

Install

go get github.com/CaliLuke/go-typeql@v1.4.0

The 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.

Prebuilt FFI library

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.

Running tests

# 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/...

Docs

• 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

Requirements

• Go 1.26+
• Rust toolchain (only for the driver)
• TypeDB 3.x (only for integration tests)

License

MIT

Documentation

Overview

Package gotypeql provides a Go ORM for TypeDB 3.x.

Define your graph schema as Go structs with struct tags, and get type-safe CRUD operations, a chainable query builder, schema migrations, and code generation — all without writing raw TypeQL.

The module is organized into four packages:

• github.com/CaliLuke/go-typeql/ast — TypeQL AST nodes and compiler
• github.com/CaliLuke/go-typeql/gotype — ORM core: models, CRUD, queries, migrations
• github.com/CaliLuke/go-typeql/tqlgen — Code generator: TypeQL schema to Go structs
• github.com/CaliLuke/go-typeql/driver — Rust FFI bindings to typedb-driver 3.x (requires CGo)

The ast, gotype, and tqlgen packages compile and test without CGo or a running database. Only the driver package requires the Rust FFI library.