Scripts & CLI

Before the Gin server listens, cmd/main.go inspects os.Args and may execute database tasks or named scripts, then exit. This mirrors many production binaries where the same container image supports migrations and HTTP with different commands.

Entry flow

Build providers.App (DB + Gin + injector).
Call script.Commands(app) when extra arguments exist.
If the command indicates only maintenance work, the process ends without calling Run.
Otherwise start Gin (--run or implicit run path depending on your Makefile).

Read script/command.go for the authoritative list of flags — documentation can drift; the source is final.

Flag	Behaviour
`--migrate` / `--migrate:run`	Apply pending migrations forward.
`--migrate:status`	Print which migrations ran in which batch.
`--migrate:rollback [n]`	Roll back `n` batches (default behaviour when `n` omitted — verify in code).
`--migrate:rollback:all`	Roll back every recorded migration — destructive.
`--migrate:create:<name>`	Generate a skeleton migration file named `<name>`.

app.DB is passed into the script layer so migrations always hit the same DSN as the running API would.

Seeding

--seed executes database.Seeder, which in turn may call packages under database/seeders. Use seeds for:

Local demo data.
Reference data that must exist in every environment (with idempotent inserts).

Avoid destructive seeds in shared staging without coordination.

Custom scripts

--script:<name> dispatches through script/script.go. Add a case for your name and implement a small runner struct when you need:

One-off data fixes.
Backfills that are too heavy for a migration transaction.
Reporting exports.

Keep scripts idempotent where possible and log clearly.

Makefile vs raw `go run`

The Makefile wraps common invocations so newcomers do not memorise flags:

make migrate-up
make seed
make run

Open the Makefile in the starter repo — targets change over time; this docs site describes intent, not exact line numbers.

CI integration

Typical pipeline steps:

go test ./...
Build binary or image.
Run migrations against the target database before or as the new version rolls out (strategy depends on backward compatibility).
Health check HTTP endpoint.

If migrations must succeed before traffic, fail the deploy job when migrate:run exits non‑zero.

Safety checklist

Never run migrate:rollback:all on production without backups.
Prefer maintenance windows for irreversible schema shrinks.
Log migration output in CI artifacts for audits.

Next: Deployment for how the binary and container fit into environments.