jetadmin

jet-admin

A Django-admin-style web admin for Go applications on PostgreSQL whose schema is described by go-jet/jet generated code. Register a page per table with the builder and model Jet generated, mount one http.Handler, and your team can list, search, filter, sort, add, change and delete rows, with an audit log of who did what.

• Every statement is built with Jet's PostgreSQL DSL and run through pgx; values are always parameters.
• Pages are rendered with templ and work without JavaScript: plain links, and forms answered with 303 redirects. Datastar (embedded, served by the admin) makes the search live, the filters, sorting and paging patch in place, form errors appear without a reload, and confirmations open as dialogs.
• Database constraints are the validation: a unique, foreign key, check or not-null violation comes back on the form, on the field it is about, with the constraint's name.
• A database-backed sign-in (package auth) with bcrypt passwords, hashed session tokens and a login backoff, or your own Authenticator.
• One hand-written stylesheet, light and dark, usable on a phone.

Install

go get github.com/garden-studio/jet-admin

It needs Go 1.26 and PostgreSQL 13 or later.

Usage

1. Migrate

The admin needs three tables of its own: admin_users and admin_sessions for the auth package, admin_log for the audit log. Their DDL is jetadmin.Schema (the file schema.sql); paste it into one of your migrations, for example with goose:

-- +goose Up
-- (the contents of schema.sql)

-- +goose Down
DROP TABLE admin_log;
DROP TABLE admin_sessions;
DROP TABLE admin_users;

The tables are referenced without a schema, so they are found on your search_path.

2. Register your tables and mount the admin

table and model are your packages generated by Jet. The model can be Jet's default one or one with db:"column" tags: a column matches the field of its db tag, else the field whose name is the column in CamelCase (user_id → UserID).

package main

import (
	"context"
	"log"
	"net/http"
	"os"

	"github.com/jackc/pgx/v5/pgxpool"

	jetadmin "github.com/garden-studio/jet-admin"
	"github.com/garden-studio/jet-admin/auth"

	"example.com/app/internal/db/jet/model"
	"example.com/app/internal/db/jet/table"
)

func main() {
	ctx := context.Background()
	pool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatal(err)
	}

	signIn := auth.New(pool, auth.Options{Secure: true})
	site, err := jetadmin.New(jetadmin.Config{
		DB:       pool,
		Title:    "Sumi admin",
		BasePath: "/admin",
		Auth:     signIn,
		AuditLog: true,
	})
	if err != nil {
		log.Fatal(err)
	}

	d, a := table.Devices, table.MailAccounts
	must(jetadmin.Register(site, jetadmin.Model[model.Devices]{
		Table:        d,
		Group:        "Push",
		ListDisplay:  []jetadmin.Column{d.ID, d.Platform, d.Environment, d.CreatedAt},
		ListFilter:   []jetadmin.Column{d.Platform, d.Environment, d.CreatedAt},
		SearchFields: []jetadmin.Column{d.ID, d.Token},
		Ordering:     []jetadmin.Order{jetadmin.Desc(d.CreatedAt)},
		ReadOnly:     []jetadmin.Column{d.CreatedAt},
		Fields: []jetadmin.Field{
			{Column: d.Platform, Choices: jetadmin.Choices("ios", "macos")},
		},
		Inlines: []jetadmin.Inline{{Model: "registrations", Column: table.Registrations.DeviceID}},
		Display: func(m model.Devices) string { return m.Platform + " " + m.ID.String()[:8] },
	}))
	must(jetadmin.Register(site, jetadmin.Model[model.MailAccounts]{
		Table:  a,
		Group:  "Push",
		Hidden: []jetadmin.Column{a.SealedCredentials}, // never selected for a page, shown or written
	}))
	must(jetadmin.Register(site, jetadmin.Model[model.PushLogs]{
		Table:       table.PushLogs,
		Group:       "Push",
		Permissions: jetadmin.ViewOnly, // a log is read, not edited
	}))
	must(auth.Register(site)) // the admin users, managed in the admin itself

	mux := http.NewServeMux()
	mux.Handle("/admin/", site.Handler())
	log.Fatal(http.ListenAndServe(":8080", mux))
}

func must(err error) {
	if err != nil {
		log.Fatal(err)
	}
}

3. Create the first admin user

From your own command line (a createadmin subcommand, say):

user, err := auth.CreateUser(ctx, pool, "ivan", password)
// later: auth.SetPassword(ctx, pool, "ivan", newPassword)
//        auth.Deactivate(ctx, pool, "ivan")  // also ends their sessions

Then sign in at /admin/. Further admin users can be added from the "Admin users" page.

Try the demo

example/ is a runnable site over three related tables (a uuid key, an identity key, jsonb, a text array, a nullable timestamp, choices, a foreign key and a hidden secret):

DATABASE_URL=postgres://user:pass@localhost:5432/demo go run ./example

It creates its tables, seeds a few rows, creates the user admin with a fresh password (printed; set ADMIN_PASSWORD to choose it) and serves http://localhost:8080/admin/.

Pages

Under BasePath:

A list's whole state is in its address, so a filtered list reloads and can be shared: ?q=ann&f_plan=pro&f_created_at__since=7d&f_notes__isnull=true&o=-created_at&p=2. f_<column>=<value> matches the column's text form exactly (any column, not only the ones in ListFilter), __since takes today, 7d, 30d or year, __isnull takes true or false.

Options

jetadmin.Config:

jetadmin.Model[M], every field but Table optional:

Forms follow the model field's Go type: string is a text input (a Textarea widget on request), bool a checkbox, integers a number input, floats a number with any step, time.Time a datetime-local input in UTC (a date input for a date column), uuid.UUID a validated text input, json.RawMessage or a jsonb column read as string a textarea that must hold valid JSON, []string a textarea of one value per line, []byte a read-only "N bytes". A pointer field is nullable: an empty input is NULL. Choices make a select. On add, a column with a database default (or identity) left blank is left out of the INSERT, so the default applies; GENERATED ALWAYS columns are not on the form at all.

auth.Options: CookieName (jetadmin_session), Secure (set it behind HTTPS), SessionTTL (14 days), ClientIP (the address failed sign-ins are counted against; return the client's behind a proxy) and Logger.

Security

• Handler wraps everything in http.CrossOriginProtection: a form posted from another origin is refused.
• Session cookies are random 32-byte tokens, HttpOnly, SameSite=Lax, Secure when configured; the database keeps only their SHA-256.
• A refused sign-in always gives the same message, an unknown username takes as long as a wrong password (a dummy bcrypt comparison), and after five failures from one address or against one username sign-ins there wait, doubling up to 15 minutes. The counters are in memory, per process.
• The audit log names the fields a change touched, never their values.

Limits

• PostgreSQL only.
• Single-column primary keys of a text, integer or uuid type; a table without one cannot be registered, and composite keys are refused.
• Foreign keys and inlines are declared, not read from the database.
• One filter value per column; no custom list actions besides delete yet.
• Times are shown and entered in UTC.

License

MIT, see LICENSE. Datastar is embedded under its MIT license, see NOTICE.