jet

package module
v0.23.0-beta.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0, BSD-3-Clause, MIT Imports: 0 Imported by: 0

README

Nanostack DB

Type-safe SQL for Go: a statement builder that the compiler checks, and models and table types generated from your database. It supports PostgreSQL, CockroachDB, MySQL, MariaDB and SQLite.

stmt := SELECT(RunnerJobs.AllColumns).
	FROM(RunnerJobs).
	WHERE(RunnerJobs.ID.EQ(UUID(jobID)).AND(RunnerJobs.Status.EQ(String("queued"))))

job, err := query.One[model.RunnerJobs](ctx, db, stmt) // (functional.Option[model.RunnerJobs], error)

Origin: a fork of go-jet

Nanostack DB is a fork of go-jet by Goran Bjelanovic and its contributors. We adapted it for the Nanostack framework. go-jet's design is the reason we chose it: every column, literal and expression has a Go type, so comparing a text column with an integer, or a timestamp with a string, does not compile.

What Nanostack changed:

  • Name and module path. The library is the db module of nanostack-framework (github.com/nanostack-dev/nanostack-framework/db). Package layout and APIs stay as close to go-jet as possible, so upstream fixes can still be merged.
  • Native functional support. Generated models can use functional.Option[T] for nullable columns. Scanning, MODEL, SET and literals understand Option. Query helpers return (Option[T], error) for zero-or-one rows.
  • Tests. The integration suites run on testcontainers for every supported database, with no Makefile or docker-compose step: fetch the pinned test data once, then one go test (see tests/Readme.md). CockroachDB and MariaDB runs are compiled against the models generated from those databases.
  • Identity. jet -version reports Nanostack DB and the go-jet commit it forks. Generated files keep go-jet's Code generated by go-jet header.

Using functional.Option

Generate Option models: jet -nullable=option ... (the CLI default stays pointer, as in go-jet), or template.DefaultWith(postgres.Dialect, template.NullableOption) in a generator program. A nullable column becomes functional.Option[T]; NOT NULL columns are unchanged.

Read. qrm fills an Option[T] field exactly like a *T field, with the same conversions on every driver: NULL is None, a value is Some. A nested Option[Struct] (a LEFT JOIN, with alias:"x.*") behaves like *Struct. *Option[T], Option[*T], nested Options, Option[[]S] and []Option[T] panic with the fix in the message.

Write. An Option argument is unwrapped wherever it appears: MODEL, MODELS, VALUES, SET, Literal, Raw arguments and DebugSql. None writes NULL (never DEFAULT), like a nil pointer. A *functional.Option[T] argument or MODEL field panics, as it does when reading. Typed literals take an Option: StringOpt(o), Int32Opt(o), TimestampzOpt(o), UUIDOpt(o)... An absent one keeps the plain constructor's cast: on PostgreSQL most are typed NULLs ($1::text), but IntOpt and FloatOpt are untyped, like Int and Float; use Int64Opt or DoubleOpt where the server must infer the type. SQLite's DateOpt, TimeOpt and DateTimeOpt format the time in UTC, the instant SQLite's date functions give for a stored time.

Query helpers (db/query): One/OneMap return (functional.Option[T], error), All/AllMap return a never-nil functional.Seq[T], plus Exec and Count. sql.ErrNoRows is never returned. They take the executor explicitly (*sql.DB, *sql.Tx...).

Optional filters (db/filter): When(opt, cond), If(ok, cond), All(...) and Any(...) drop absent conditions. Do not compare a column with an XxxOpt literal: col = NULL is never true.

stmt := SELECT(Invoice.AllColumns).FROM(Invoice).WHERE(filter.All(
	Invoice.TenantID.EQ(UUID(tenant)),
	filter.When(status, func(s string) BoolExpression { return Invoice.Status.EQ(String(s)) }),
))
invoices, err := query.All[model.Invoice](ctx, db, stmt)

Search contract (db/search): the types that every layer of a search shares (Result, Pagination, Sort, Cursor), the page rule CheckPage, the limits, the errors and All. It imports the standard library only, so an API or domain package can import it with no SQL dialect. A client error (IsClientError) answers HTTP 400; ErrUnscoped, a search with no tenant scope, is a programming error and answers 500.

if err := search.CheckPage(page); err != nil { // ErrInvalidLimit, ErrInvalidOffset, ErrInvalidCursor...
	return search.Result[Invoice]{}, err
}

The complete list of changes, the upstream commit we started from, and how we merge upstream releases are in UPSTREAM.md. The go-jet README, which documents the statement builder in depth, is kept in docs/upstream/README.md; go-jet's wiki applies too, with the import path changed.

License

Apache License 2.0, the same as go-jet. See LICENSE and NOTICE. Every source file taken from go-jet carries a header that says it was modified.

Documentation

Overview

Package jet is a complete solution for efficient and high performance database access, consisting of type-safe SQL builder with code generation and automatic query result data mapping. Jet currently supports PostgreSQL, MySQL, MariaDB and SQLite. Future releases will add support for additional databases.

Installation

Use the command bellow to add jet as a dependency into go.mod project:

$ go get -u github.com/nanostack-dev/nanostack-framework/db

Jet generator can be installed in one of the following ways:

  1. (Go1.16+) Install jet generator using go install: go install github.com/nanostack-dev/nanostack-framework/db/cmd/jet@latest

  2. Install jet generator to GOPATH/bin folder: cd $GOPATH/src/ && GO111MODULE=off go get -u github.com/go-jet/jet/cmd/jet

  3. Install jet generator into specific folder: git clone https://github.com/go-jet/jet.git cd jet && go build -o dir_path ./cmd/jet

Make sure that the destination folder is added to the PATH environment variable.

Usage

Jet requires already defined database schema(with tables, enums etc), so that jet generator can generate SQL Builder and Model files. File generation is very fast, and can be added as every pre-build step. Sample command:

jet -dsn=postgresql://user:pass@localhost:5432/jetdb -schema=dvds -path=./.gen

Before we can write SQL queries in Go, we need to import generated SQL builder and model types:

import . "some_path/.gen/jetdb/dvds/table"
import "some_path/.gen/jetdb/dvds/model"

To write postgres SQL queries we import:

. "github.com/nanostack-dev/nanostack-framework/db/postgres" // Dot import is used so that Go code resemble as much as native SQL. It is not mandatory.

Then we can write the SQL query:

// sub-query
rRatingFilms :=
	SELECT(
		Film.FilmID,
		Film.Title,
		Film.Rating,
	).FROM(
		Film,
	).WHERE(
		Film.Rating.EQ(enum.FilmRating.R),
	).AsTable("rFilms")

// export column from sub-query
rFilmID := Film.FilmID.From(rRatingFilms)

// main-query
stmt :=
	SELECT(
		Actor.AllColumns,
		FilmActor.AllColumns,
		rRatingFilms.AllColumns(),
	).FROM(
		rRatingFilms.
			INNER_JOIN(FilmActor, FilmActor.FilmID.EQ(rFilmID)).
			INNER_JOIN(Actor, Actor.ActorID.EQ(FilmActor.ActorID)
	).ORDER_BY(
		rFilmID,
		Actor.ActorID,
	)

Now we can run the statement and store the result into desired destination:

var dest []struct {
	model.Film

	Actors []model.Actor
}

err := stmt.Query(db, &dest)

We can print a statement to see SQL query and arguments sent to postgres server:

fmt.Println(stmt.Sql())

Output:

SELECT "rFilms"."film.film_id" AS "film.film_id",
	 "rFilms"."film.title" AS "film.title",
	 "rFilms"."film.rating" AS "film.rating",
	 actor.actor_id AS "actor.actor_id",
	 actor.first_name AS "actor.first_name",
	 actor.last_name AS "actor.last_name",
	 actor.last_update AS "actor.last_update",
	 film_actor.actor_id AS "film_actor.actor_id",
	 film_actor.film_id AS "film_actor.film_id",
	 film_actor.last_update AS "film_actor.last_update"
FROM (
		  SELECT film.film_id AS "film.film_id",
			   film.title AS "film.title",
			   film.rating AS "film.rating"
		  FROM dvds.film
		  WHERE film.rating = 'R'
	 ) AS "rFilms"
	 INNER JOIN dvds.film_actor ON (film_actor.film_id = "rFilms"."film.film_id")
	 INNER JOIN dvds.actor ON (film_actor.actor_id = actor.actor_id)
WHERE "rFilms"."film.film_id" < $1
ORDER BY "rFilms"."film.film_id" ASC, actor.actor_id ASC;
 [50]

If we print destination as json, we'll get:

[
	{
		"FilmID": 8,
		"Title": "Airport Pollock",
		"Rating": "R",
		"Actors": [
			{
				"ActorID": 55,
				"FirstName": "Fay",
				"LastName": "Kilmer",
				"LastUpdate": "2013-05-26T14:47:57.62Z"
			},
			{
				"ActorID": 96,
				"FirstName": "Gene",
				"LastName": "Willis",
				"LastUpdate": "2013-05-26T14:47:57.62Z"
			},
			...
		]
	},
	{
		"FilmID": 17,
		"Title": "Alone Trip",
		"Actors": [
			{
				"ActorID": 3,
				"FirstName": "Ed",
				"LastName": "Chase",
				"LastUpdate": "2013-05-26T14:47:57.62Z"
			},
			{
				"ActorID": 12,
				"FirstName": "Karl",
				"LastName": "Berry",
				"LastUpdate": "2013-05-26T14:47:57.62Z"
			},
			...
	...
]

Detail info about all statements, features and use cases can be found at project wiki page - https://github.com/go-jet/jet/wiki.

Directories

Path Synopsis
cmd
jet command
Package filter builds WHERE conditions from optional inputs.
Package filter builds WHERE conditions from optional inputs.
generator
internal
jet
optional
Package optional recognises functional.Option[T] by reflection, so that qrm and the SQL builder can handle it without importing pkg/functional.
Package optional recognises functional.Option[T] by reflection, so that qrm and the SQL builder can handle it without importing pkg/functional.
Package nanorepo declares repositories for nano gen repo.
Package nanorepo declares repositories for nano gen repo.
qrm
Package query runs Nanostack DB statements and maps their results.
Package query runs Nanostack DB statements and maps their results.
Package search is the search contract of Nanostack DB: the page, sort and cursor types that every layer shares, the limits of a search, its errors, and All, which reads every page of a search.
Package search is the search contract of Nanostack DB: the page, sort and cursor types that every layer shares, the limits of a search, its errors, and All, which reads every page of a search.
tools
upstreamfmt command
Command upstreamfmt keeps `golangci-lint fmt` away from the files taken from go-jet.
Command upstreamfmt keeps `golangci-lint fmt` away from the files taken from go-jet.
upstreamsync command
Command upstreamsync compares Nanostack DB with a go-jet release and, on request, merges it.
Command upstreamsync compares Nanostack DB with a go-jet release and, on request, merges it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL