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 ...By default, this calls pg_restore --create against a maintenance database on the target cluster. Postgres creates a new database with the same name as the source database, then restores all objects into it.
When you pass --created-database <name>, Walwarden first runs createdb <name> against the maintenance database, then restores into that fresh database without pg_restore --create. Use this when the source database name would collide with an existing database on providers like Neon.
When to use: Restore drills, 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 at a maintenance database on the target cluster, typically postgres. If you omit --created-database, the source database name must not already exist on the target cluster. If it does, the restore fails at the CREATE DATABASE step. Fix: rerun with --created-database <fresh-name>, 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, use a maintenance DSN such as the project's postgres database and pass --created-database <fresh-name> when the dump's source database name already exists.
Optional flag: --created-database <name> creates and restores into a fresh target database name. Names must start with a letter or underscore and contain only letters, digits, underscores, or hyphens.
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, or restore into --created-database | --clean --if-exists |
| Target database must exist | No | Yes |
| Overwrites existing data | No | Yes |
| Extra flag required | None; --created-database optional | --confirm-destructive |
| Neon first restore | Yes | No |
| Neon repeat restore | Yes, with --created-database; or 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.