tracks db
Manage database migrations for Tracks applications.
Usage
tracks db <command> [flags]
These commands must be run from within a Tracks project directory (where .tracks.yaml exists). They read database configuration from environment variables, typically loaded from your .env file.
Subcommands
| Command | Description |
|---|---|
migrate | Apply pending migrations |
rollback | Roll back last migration |
status | Show migration status |
reset | Reset database |
tracks db migrate
Apply all pending database migrations in order. Migrations are SQL files in internal/db/migrations/ that define schema changes.
tracks db migrate [--dry-run]
| Flag | Description |
|---|---|
--dry-run | Preview migrations without applying |
Use --dry-run to see what would run before making changes:
tracks db migrate --dry-run
tracks db rollback
Roll back the most recently applied migration. Useful for undoing a migration during development or fixing issues.
tracks db rollback
tracks db status
Show which migrations have been applied and which are pending. Helpful for debugging migration issues or verifying deployment state.
tracks db status
tracks db reset
Reset the database by rolling back all migrations then reapplying them. This destroys all data - use with caution.
tracks db reset [--force]
| Flag | Description |
|---|---|
--force | Skip confirmation prompt |
In CI or scripts, use --force to skip the interactive confirmation:
tracks db reset --force
Supported Drivers
| Driver | Status |
|---|---|
postgres | Supported |
sqlite3 | Use make migrate-* targets |
go-libsql | Use make migrate-* targets |
For SQLite and go-libsql projects, use the generated Makefile targets instead:
make migrate-up
make migrate-down
make migrate-status
Environment
| Variable | Description |
|---|---|
APP_DATABASE_URL | Database connection string (required) |
The command loads .env automatically, or you can set the variable directly:
APP_DATABASE_URL=postgres://localhost/myapp tracks db migrate
Common Errors
Not in a project: Run from your project root where .tracks.yaml exists.
Error: not in a Tracks project directory (missing .tracks.yaml)
Missing database URL: Create a .env file or set the variable.
Error: APP_DATABASE_URL environment variable is not set
Connection failed: Check that your database is running and the URL is correct.
Error: failed to connect to database: connection refused
See Also
- Database Setup - Configuration and drivers
- Migrations Guide - Writing migration files