Database Development Tools#

This page covers the day-to-day database tools available after sourcing the virtual environment.

Snapshots#

Save a snapshot#

db snapshot <name>

Dumps the current database contents to a file in database/snapshots/. Useful when iterating on migrations or sharing a particular database state with another developer.

Restore a snapshot#

db restore <name>

Restores the database to a previously saved snapshot. Works with short alias names when there is only one snapshot with that name. You can also use relative or absolute paths to snapshot files in database/snapshots/.

Destroy the Database#

db destroy

Completely removes the database container. The data is not backed up beforehand. Use this only when you need to start fresh.

Migration Workflow#

When iterating on a new migration, use snapshots to make the process safe and repeatable:

Snapshot the current state before applying your new migration:
```
db snapshot before-my-migration
```
Add your new migration file to database/migrations/ and apply it:
```
db migrate
```
Verify the result — inspect database/schema.sql, open a REPL, or test in the application:
```
db repl
```
If the migration looks correct, you're done. If not, restore and try again:
```
db restore before-my-migration
```

Application REPL#

app-repl

Opens an interactive Node.js REPL with the full application context. The service locator is created based on the environment, and all registered services are available directly in the REPL:

app > await db.query('SELECT NOW() as time')
Result {
  command: 'SELECT',
  rowCount: 1,
  rows: [ { time: 2025-03-26T10:23:38.410Z } ],
}

Features:

Top-level await — query the database or call async service methods directly.
Last-value shortcut — the return value of the previous expression is available as _:
```
app > _.rows[0].time
2025-03-26T10:23:38.410Z
```
Persistent history — outside of production, command history is saved to a file in your repository. Use arrow keys to navigate or Ctrl+R to search.