db

README

cmd/db

cmd/db manages persisted server configuration and database bootstrap tasks.

For the project overview, prerequisites, and high-level startup flow, see ../../README.md. For the runtime server entrypoint, see ../server/README.md.

Commands

init-config

Writes the JSON config file used by cmd/server.

go run ./cmd/db init-config \
  --config data/var/hoboapp/server.json \
  --database-url "$DATABASE_URL" \
  --data-dir data/var/hoboapp/data

Useful flags:

• --app-addr
• --database-url
• --data-dir
• --jwt-access-ttl
• --jwt-refresh-ttl
• --cookie-secure
• --force

The command creates the config directory and data directory if needed.

seed-admin

Creates or updates the bootstrap administrator through internal/service.UserService.

go run ./cmd/db seed-admin \
  --config data/var/hoboapp/server.json \
  --handle admin \
  --email admin@example.com \
  --password 'change-me-now'

This reuses the same normalization, uniqueness, password hashing, and role rules as the web app.

jwt-key create

Creates a new active signing key for a token type.

go run ./cmd/db jwt-key create --config data/var/hoboapp/server.json --type access
go run ./cmd/db jwt-key create --config data/var/hoboapp/server.json --type refresh

Behavior:

• Generates a random 32-byte HMAC secret.
• Inserts a new active key for the requested token type.
• Retires the previous active key of that type, if one exists.
• Defaults the previous key's verification grace period to the configured token TTL.

Optional flag:

• --verify-old-for

jwt-key expire

Retires a specific key by ID and optionally allows it to keep verifying tokens for a short grace period.

go run ./cmd/db jwt-key expire \
  --config data/var/hoboapp/server.json \
  --id <key-uuid> \
  --verify-for 10m

jwt-key delete

Deletes a non-active key.

go run ./cmd/db jwt-key delete \
  --config data/var/hoboapp/server.json \
  --id <key-uuid>

Active keys cannot be deleted directly. Rotate or expire them first.

Typical Bootstrap Sequence

atlas migrate apply --dir file://db/migrations --url "$DATABASE_URL"
go run ./cmd/db init-config --database-url "$DATABASE_URL"
go run ./cmd/db jwt-key create --type access
go run ./cmd/db jwt-key create --type refresh
go run ./cmd/db seed-admin --handle admin --email admin@example.com --password 'change-me-now'

Using a Dedicated Postgres Schema

If you want all application tables to live outside public, create a dedicated role, database, and schema first:

CREATE ROLE hoboapp_dev_user WITH LOGIN PASSWORD 'strong-password-here';
CREATE DATABASE hoboapp_dev OWNER hoboapp_dev_user;
\c hoboapp_dev
CREATE SCHEMA hoboapp_dev AUTHORIZATION hoboapp_dev_user;
ALTER ROLE hoboapp_dev_user IN DATABASE hoboapp_dev SET search_path TO hoboapp_dev, public;
GRANT ALL ON SCHEMA hoboapp_dev TO hoboapp_dev_user;

With that in place, use a database URL that connects as hoboapp_dev_user. The role-level search_path ensures the unqualified tables in db/schema.sql land in hoboapp_dev instead of public.

For the first Atlas migration apply against this database, use:

export DATABASE_URL='postgres://hoboapp_dev_user:strong-password-here@localhost:5432/hoboapp_dev?sslmode=disable'

atlas migrate apply \
  --allow-dirty \
  --dir file://db/migrations \
  --revisions-schema atlas_schema_revisions \
  --url "$DATABASE_URL"

The extra flags matter:

• --allow-dirty is required because the dedicated hoboapp_dev schema already exists before Atlas applies the first migration.
• --revisions-schema atlas_schema_revisions keeps Atlas bookkeeping out of the application schema and out of public.

For future migration generation, override the checked-in atlas.hcl defaults and use a schema-aware dev database:

atlas migrate diff <name> \
  --dir file://db/migrations \
  --to file://db/schema.sql \
  --dev-url 'postgres://hoboapp_atlas_user:strong-password-here@localhost:5432/hoboapp_atlas?sslmode=disable' \
  --schema hoboapp_dev

Using --schema hoboapp_dev plus a search_path of hoboapp_dev,public keeps the managed objects in the application schema while still allowing references to extension objects such as pgcrypto.

First-Run Example

export DATABASE_URL='postgres://hoboapp_dev_user:strong-password-here@localhost:5432/hoboapp_dev?sslmode=disable'

atlas migrate apply --allow-dirty --dir file://db/migrations --url "$DATABASE_URL"

go run ./cmd/db init-config \
  --config data/var/hoboapp/server.json \
  --database-url "$DATABASE_URL" \
  --data-dir data/var/hoboapp/data

go run ./cmd/db jwt-key create --config data/var/hoboapp/server.json --type access
go run ./cmd/db jwt-key create --config data/var/hoboapp/server.json --type refresh

go run ./cmd/db seed-admin \
  --config data/var/hoboapp/server.json \
  --handle admin \
  --email admin@example.com \
  --password 'password123'

Operational Notes

• The command reads the same config file format as cmd/server.
• jwt-key create and jwt-key expire keep old keys available for verification during a configurable grace window.
• JWT secrets live in PostgreSQL, not in environment variables.
• The server expects at least one active key for each token type before startup.