# Database storage and recovery

Source: https://frameleaf.app/docs/admin/database/

Frameleaf keeps everything it knows about your library in PostgreSQL: accounts, albums, media records, settings, search indexes and background job state. Your photo and video files stay in library storage. Back up both, and you can bring your whole library back.

:::caution[Release compatibility]
Use the Compose file and database image that come together with your release. A database folder only opens with the PostgreSQL build that made it, so move to a different build only by copying the database across: Manager does it during the update, and manual installations follow [Moving to a new database build](#moving-to-a-new-database-build).
:::

## Use the database supplied with your release

Frameleaf runs on its own PostgreSQL 19 image with pgvector, already set in the current Compose file. Use that image as it is; you don't need to enter an image digest. Keep it rather than a generic PostgreSQL image, and keep the PostgreSQL major version that created an existing database directory.

`DB_VECTOR_EXTENSION` takes `pgvector`. VectorChord and pgvecto.rs migration instructions from older deployments don't apply here.

## Choose storage

Put the database on a local disk, ideally an SSD, with room for the database, temporary migration space and backups. Keep the live database off NFS and SMB shares.

**Manager installations:** choose the **Database** folder during setup. Manager shows the drive each folder is on, suggests a fast drive with room when it finds one, and creates a fresh folder there, keeping earlier ones. It checks the location for you and won't use a network share, Docker's own storage, Docker volumes, loop-mounted images or memory-backed filesystems. To move the database to a faster drive later, see [Move the database](https://frameleaf.app/docs/admin/move-data-to-another-drive/#move-the-database). Manager also sets PostgreSQL's memory settings to suit your server's memory, and applies them again on every start.

**Manual installations:** `DB_DATA_LOCATION` names the host folder. The release mounts it at `/var/lib/postgresql`; keep the versioned directory inside it. The example uses `./postgres19`, relative to the Compose project folder.

## Connection settings

The release uses `database:5432` inside the private Compose network, so PostgreSQL stays private and isn't published to your LAN. New databases are created with data checksums turned on, so PostgreSQL notices a damaged page instead of returning it. The application receives `DB_USERNAME`, `DB_PASSWORD` and `DB_DATABASE_NAME`; Compose passes those values to PostgreSQL under its `POSTGRES_*` names.

To find the user name and password your installation uses, see [Accounts, passwords and where they're kept](https://frameleaf.app/docs/admin/credentials/#database).

To use your own database, configure `DB_HOSTNAME`, `DB_PORT` and credentials, or `DB_URL`, which overrides the separate connection values. It needs the same PostgreSQL version and extensions as the release. See [Environment variables](https://frameleaf.app/docs/admin/environment-variables/#database).

Changing a connection setting points Frameleaf at a different database; it doesn't copy or migrate your data.

## Backup and restore

[Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/) has the full procedure. To move a database between machines, use a logical backup rather than copying a live PostgreSQL directory.

1. Save a database backup and a matching media backup.
2. Preserve the installation configuration and any encryption or recovery keys.
3. Restore into a fresh destination using the matching Frameleaf release.
4. Check sign-in, albums, a few originals and background processing, then retire the old installation.

Coming from another photo application? Import its library into a fresh Frameleaf database rather than attaching its database directory. See [Bring an existing library](https://frameleaf.app/docs/migrate/from-another-library/).

## Moving to a new database build

Some releases come with a newer build of PostgreSQL that can't open the existing database folder. The new database refuses the old folder, so the database is copied across with a dump and a restore into a new, empty folder. The old folder is kept as it is, so you can go back.

**With Manager**, there's nothing to do by hand. The update review says **New database engine**, and the update copies the database into a new folder beside the current one, checks every table and starts the new version. If anything fails, Manager puts the previous version back on the old folder. Make sure the database drive has free space for a second copy. See [When an update brings a new database engine](https://frameleaf.app/docs/admin/upgrading/#when-an-update-brings-a-new-database-engine).

**With Docker Compose**, move by hand only when the new release's `docker-compose.yml` names a different `database` image from the one you run now. If it names the same image, keep your database folder and update normally.

Run these in the folder with your `docker-compose.yml` and `.env`:

1. Keep a copy of `.env` and of your current `docker-compose.yml`. While Frameleaf is still running, keep the exact images it runs under local names, so you can go back. Then stop Frameleaf, leave the database running, and save a dump outside the database folder:

   ```bash
   docker tag "$(docker compose images -q frameleaf-server)" frameleaf-server:before-move
   docker tag "$(docker compose images -q frameleaf-machine-learning)" frameleaf-machine-learning:before-move
   docker compose stop frameleaf-server frameleaf-machine-learning
   docker compose exec -T database sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' > frameleaf-move.dump &&
     docker compose down
   ```

   Leave off `-v` and `--volumes`. If the dump command fails, stop here: the database is unchanged, so start Frameleaf again with `docker compose up -d`. Check that `frameleaf-move.dump` isn't empty.

2. Replace `docker-compose.yml` with the new release's file. In `.env`, point `DB_DATA_LOCATION` at a new, empty folder, and leave the old folder untouched. Run `docker compose config` and check that the `database` service shows the new image and mounts the new folder.

3. Start only the new database, wait until it's healthy, then restore the dump:

   ```bash
   docker compose up -d --wait database
   docker compose exec -T database sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --exit-on-error --single-transaction --no-owner --no-acl' < frameleaf-move.dump
   ```

4. If the restore succeeds, start Frameleaf with `docker compose up -d` and check your library. If it fails, go back.

To go back, run `docker compose down`, put back the old `docker-compose.yml` and `.env`, point the server and machine learning services at the `before-move` images, and run `docker compose up -d --pull never`. Go back straight away, before anyone uploads or edits: anything changed on the new database after step 4 is lost when you return to the old one. Delete the old folder and the dump only once you're happy with the new release.

On Unraid with the manual templates, the steps are the same: stop the server and machine learning containers, save the dump with the same `pg_dump` command through `docker exec -i` on the database container, set that container to the new image and a new, empty folder, start it, restore the dump and start Frameleaf.

## Diagnose connection failures

For manual installations:

```bash
docker logs frameleaf_postgres
docker exec frameleaf_postgres pg_isready
docker logs frameleaf_server
```

For Manager installations, open **Services** and select **Logs** beside the affected service, or choose **Check connections** under **Troubleshooting** to test Docker, the database, machine learning and your drives in one go.

Most connection failures come down to disk space, a missing mount or the wrong database path, so check those first. Keep any failed database directory as it is until you have a verified recovery copy.
