Restore modes
new_database vs in_place — what each does, when to use each, and the destructive-intent guard.
The CLI's --mode flag controls how pg_restore is invoked against the target database.
new_database
walwarden restore --mode new_database ...Internally, this calls pg_restore --create against the target DSN. Postgres creates a new database with the same name as the source database, then restores all objects into it.
When to use: Test restores, cloning to a staging environment, migrations, and any case where you want the data to land in a fresh database without touching anything that already exists on the target cluster.
Target requirement: The target DSN must point to a Postgres cluster (any database on that cluster works as the connection target — postgres is conventional). The source database name must not already exist on the target cluster. If it does, the restore fails at the CREATE DATABASE step. Fix: use --mode in_place against the existing database, or drop the conflicting database first.
Neon note: Neon manages its own databases. When you restore in new_database mode to a Neon target, the new database is created inside your Neon project. If the database name already exists (because a previous restore created it), the restore fails with database already exists. Use --mode in_place --confirm-destructive for subsequent restores to the same target.
No extra flags required.
in_place
walwarden restore --mode in_place --confirm-destructive ...Internally, this calls pg_restore --clean --if-exists against the target database. All existing objects in the target database are dropped before the restore data is loaded.
When to use: Restoring into an existing database when you accept overwriting its contents. Common cases: re-running a restore drill against the same target database, recovering a production database in place, or the Neon case after the first new_database restore has already created the database.
Target requirement: The target DSN must include the database name as the path component (for example, postgresql://user:password@host:5432/target-db-name). The database must exist on the target cluster.
--confirm-destructive is required. The flag must be present or the CLI exits with code 2 before making any API call. This is a local guard; no server confirmation is needed. The flag is included automatically in the dashboard one-liner when in-place mode is selected.
Comparison
new_database | in_place | |
|---|---|---|
| pg_restore flags | --create | --clean --if-exists |
| Target database must exist | No | Yes |
| Overwrites existing data | No | Yes |
| Extra flag required | None | --confirm-destructive |
| Neon first restore | Yes | No |
| Neon repeat restore | No (use in_place) | Yes |
Choosing
Use new_database for the first restore to any target. Use in_place when the database already exists and you accept overwriting it. When in doubt, use new_database and drop the created database afterward if it was only a verification run.