jet

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

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

Go to latest
Published: Nov 10, 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
}

Keyset pager (db/keyset): the one keyset pager (ADR 0001). A Key reads one ordering column from a row; OrderOf builds a total order (the requested sorts, then a unique tiebreak) and refuses an unknown sort with search.ErrUnknownSort. Page and PageOf count the matches and read one page through db/query, with the executor as a parameter: they never read a transaction from a context. RequireWhere refuses a page with no WHERE (search.ErrUnscoped). The pager runs on PostgreSQL, MySQL, MariaDB and SQLite with one contract: the same rows, complete walks and the same cursor tokens. Page reads the dialect from its source and writes that dialect's SQL. A key whose column type a dialect lacks (TimeKey and InetKey off PostgreSQL, MySQLTimestampKey and MariaDBTimestampKey off MySQL, RealKey on SQLite) is ErrDialect. On SQLite a time column holds text: write every row through the driver as a time.Time in UTC, or give a column that SQL fills (CURRENT_TIMESTAMP) its text form with LocalTimeKey(...).SQLiteLayout("2006-01-02 15:04:05"). A page that ends on its own cursor row is ErrNoProgress: the key does not match the stored values.

order, err := keyset.OrderOf(page.Sort, map[SortField]keyset.Key[model.Invoice]{
	SortCreatedAt: keyset.TimeKey(Invoice.CreatedAt, func(m model.Invoice) time.Time { return m.CreatedAt }),
}, keyset.StringKey(Invoice.ID, func(m model.Invoice) string { return m.ID }))
if err != nil {
	return search.Result[model.Invoice]{}, err // ErrUnknownSort
}
return keyset.Page(db, func(m model.Invoice) model.Invoice { return m }, Invoice.AllColumns).
	From(Invoice).
	Where(Invoice.TenantID.EQ(UUID(tenant))).
	RequireWhere().
	Keyset(order).
	Run(ctx, page.Pagination)

Search runtime (db/searchexec): the runtime of the searches that nanostack gen repo writes. Contains(term, exprs...) is the substring rule of every search: it trims the term, makes %, _ and ! literal, and matches without case (ILIKE on PostgreSQL, LOWER() LIKE LOWER() on MySQL and SQLite). A blank term gives TRUE, and a term that is not valid UTF-8 or holds NUL gives FALSE. Matching follows the column's collation: SQLite folds the case of ASCII letters only (load the ICU extension for Unicode), PostgreSQL on a "C" or "POSIX" column does the same, and the accent-insensitive collations of MySQL and MariaDB also ignore accents.

stmt := SELECT(Invoice.AllColumns).FROM(Invoice).WHERE(
	Invoice.TenantID.EQ(UUID(tenant)).AND(searchexec.Contains(term, Invoice.Number, Invoice.Customer)),
)

nanostack gen repo writes each declared search as a searchexec.Spec (a package variable that DefineSpec checks at package init), a builder that embeds searchexec.Query, and the repository method. The method runs it through the transactor forwarders (transactor.Search and SearchPage, in a later release), which use the context transaction and refuse a row lock. searchexec.Run and RunPage run on the executor they get: they do not read the context transaction and do not refuse a row lock. The scope is a typed value: a zero scope field (also a field that only From reads), a query of another spec and a struct literal of the builder are search.ErrUnscoped, before any statement runs. A hand-written method starts from searchexec.Resolve and gets an opaque Plan, which it can narrow but never widen. The generated searches run on PostgreSQL, MySQL, MariaDB and SQLite; any other source, and an Exists child of another dialect than the source, is keyset.ErrDialect.

Each filter of a generated builder returns a field type, and the method of the field returns the filtered copy: In (expr IN (...)), InFold (an exact match without case, expr ILIKE $1 ESCAPE '!' for each value with its wildcards escaped: the database folds both sides by the column's collation), Eq, EqIn, TimeRange (Since >=, Until <=, After >, Before <), Presence (IS NOT NULL or IS NULL), Flag (a condition, or condition IS NOT TRUE), Text (Contains, ContainsAny) and Exists (EXISTS on a child table, correlated on its link column and its tenant columns). From Go, an empty list matches no row. More than search.MaxInValues (1000) values is search.ErrTooManyValues, and a term longer than search.MaxTermLength (1000) characters is search.ErrTermTooLong: the field records the error on the query, and Resolve returns it before any statement runs. A string value that no text column can hold (not valid UTF-8, or holding NUL) matches no row. NewTimeRange takes a PostgreSQL timestamptz, and NewLocalTimeRange a timestamp without time zone (MySQL, SQLite, a PostgreSQL timestamp). A TimeRange bound moves to a whole microsecond on PostgreSQL and MySQL. On SQLite it is the time in UTC in the driver's text form, with every digit, so the rows must be written through the driver in UTC; TimeRange.SQLiteLayout gives the text form of a column that SQL fills. A bound outside 0001-01-02 to 9999-12-30 (UTC) is search.ErrInvalidTime.

q := NewWebhookRequestSearch(scope).Method().In("GET", "POST").ReceivedAt().Since(t)

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.
sqlitetime
Package sqlitetime holds the text forms of a time in a SQLite column, which keyset and searchexec share.
Package sqlitetime holds the text forms of a time in a SQLite column, which keyset and searchexec share.
Package keyset is the keyset pager of Nanostack DB (ADR 0001, ADR 0027).
Package keyset is the keyset pager of Nanostack DB (ADR 0001, ADR 0027).
Package nanorepo declares repositories for nanostack gen repo.
Package nanorepo declares repositories for nanostack 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.
Package searchexec is the runtime of the searches that nanostack gen repo writes.
Package searchexec is the runtime of the searches that nanostack gen repo writes.
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