> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Database

> Database management — check health, run migrations, and execute SQL queries via pgserve

# Database Commands

The `genie db` command group manages the embedded PostgreSQL instance (pgserve) that backs Genie's task store, agent registry, schedules, and more.

<Note>
  Genie requires pgserve >=1.1.10 (bumped 2026-04-20).
</Note>

## `genie db status`

Show pgserve health, port, data directory, and table counts.

```bash theme={"dark"}
genie db status
```

Outputs connection info, running state, and a summary of how many rows exist in each core table.

## `genie db migrate`

Run pending database migrations.

```bash theme={"dark"}
genie db migrate
```

Applies any unapplied migrations in order. Safe to run multiple times — already-applied migrations are skipped.

## `genie db query`

Execute arbitrary SQL and print results.

```bash theme={"dark"}
genie db query <sql>
```

```bash theme={"dark"}
# Count tasks by stage
genie db query "SELECT stage, count(*) FROM tasks GROUP BY stage"

# Check recent schedule runs
genie db query "SELECT * FROM schedule_triggers ORDER BY created_at DESC LIMIT 5"

# Inspect app store
genie db query "SELECT name, item_type, version FROM app_store"
```

<Warning>
  This runs raw SQL against the Genie database. Write queries (`INSERT`, `UPDATE`, `DELETE`) will modify data directly — use with care.
</Warning>

## `genie db backup`

Dump the database to a compressed snapshot file.

```bash theme={"dark"}
genie db backup
```

Creates a backup at `~/.genie/snapshot.sql.gz`.

```bash theme={"dark"}
$ genie db backup
Dumping database to ~/.genie/snapshot.sql.gz...
  ✅ Backup complete (2.3 MB)
```

## `genie db restore`

Restore the database from a backup snapshot.

```bash theme={"dark"}
genie db restore [file] [--yes]
```

| Option  | Description              |
| ------- | ------------------------ |
| `--yes` | Skip confirmation prompt |

If no file is specified, restores from the default `~/.genie/snapshot.sql.gz`.

```bash theme={"dark"}
# Restore from default snapshot
genie db restore

# Restore from a specific file
genie db restore ~/backups/genie-2026-03-30.sql.gz
```

<Warning>
  This replaces the current database contents with the snapshot data. Make sure to back up first if you have unsaved state.
</Warning>

## `genie db url`

Print the PostgreSQL connection URL for direct access with external tools.

```bash theme={"dark"}
genie db url [options]
```

| Option    | Description                                 |
| --------- | ------------------------------------------- |
| `--quiet` | Print only the URL with no extra formatting |

```bash theme={"dark"}
$ genie db url
postgresql://genie:genie@localhost:19642/genie

# Use with psql
psql $(genie db url)
```

## Danger zone

### `genie-wipe`

Fresh-start local Genie state — wipes the embedded PostgreSQL data directory (and optionally worktrees, teams, state, logs, wishes, brainstorms, and/or user config) to emulate a new-user experience.

`genie-wipe` is a repo-local script, not a top-level `genie` subcommand. Invoke it with `bun` from a Genie checkout:

```bash theme={"dark"}
bun scripts/genie-wipe.ts [--apply] [--full] [--config]
```

<Warning>
  This is destructive. Running with `--apply` permanently deletes `~/.genie/data/pgserve` — the full database — and anything else covered by the flags you pass. There is no undo. Back up first with `genie db backup` if you need to preserve state.
</Warning>

| Flag           | Description                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------- |
| *(none)*       | Dry-run (default). Prints the wipe manifest with sizes; no writes.                              |
| `--apply`      | Actually wipe. Requires typing the interlock phrase `I UNDERSTAND FRESH INSTALL` at the prompt. |
| `--full`       | Also wipe `~/.genie/{worktrees,teams,state,spawn-scripts,logs,wishes,brainstorms}`.             |
| `--config`     | Also wipe `~/.genie/config.json`, `pgserve.port`, `serve.pid`, and `brain-version-check.json`.  |
| `--help`, `-h` | Show the built-in help.                                                                         |

**What gets wiped**

* Always: `~/.genie/data/pgserve` (full DB reset — migrations re-run on next connect).
* With `--full`: `~/.genie/worktrees`, `teams`, `state`, `spawn-scripts`, `logs`, `wishes`, `brainstorms`.
* With `--config`: `~/.genie/config.json`, `pgserve.port`, `serve.pid`, `brain-version-check.json`.

**What is preserved** (unless `--config` is passed): `~/.genie/config.json`, `tmux.conf`, installer-owned scripts, shell history, and any repos outside `~/.genie/worktrees`.

```bash theme={"dark"}
# Preview what would be wiped (DB only)
bun scripts/genie-wipe.ts

# Preview a full wipe (everything except config)
bun scripts/genie-wipe.ts --full

# Wipe just the database
bun scripts/genie-wipe.ts --apply

# Nuke everything back to post-install defaults
bun scripts/genie-wipe.ts --apply --full --config
```

**Recovery:** the script itself does not restart anything. The next `genie <verb>` call (e.g. `genie serve start`) auto-starts a fresh `pgserve` and re-runs all migrations. If `--full` was used, `genie team ls` and `genie task list` will come up empty — you are effectively a new user.