Database storage and recovery
Back up Frameleaf: database snapshots, your photo files and restoring Watch on YouTube
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.
Use the database supplied with your release
Section titled “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
Section titled “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. 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
Section titled “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.
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.
Changing a connection setting points Frameleaf at a different database; it doesn’t copy or migrate your data.
Backup and restore
Section titled “Backup and restore”Backup and restore has the full procedure. To move a database between machines, use a logical backup rather than copying a live PostgreSQL directory.
- Save a database backup and a matching media backup.
- Preserve the installation configuration and any encryption or recovery keys.
- Restore into a fresh destination using the matching Frameleaf release.
- 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.
Moving to a new database build
Section titled “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.
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:
-
Keep a copy of
.envand of your currentdocker-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:Terminal window docker tag "$(docker compose images -q frameleaf-server)" frameleaf-server:before-movedocker tag "$(docker compose images -q frameleaf-machine-learning)" frameleaf-machine-learning:before-movedocker compose stop frameleaf-server frameleaf-machine-learningdocker compose exec -T database sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' > frameleaf-move.dump &&docker compose downLeave off
-vand--volumes. If the dump command fails, stop here: the database is unchanged, so start Frameleaf again withdocker compose up -d. Check thatframeleaf-move.dumpisn’t empty. -
Replace
docker-compose.ymlwith the new release’s file. In.env, pointDB_DATA_LOCATIONat a new, empty folder, and leave the old folder untouched. Rundocker compose configand check that thedatabaseservice shows the new image and mounts the new folder. -
Start only the new database, wait until it’s healthy, then restore the dump:
Terminal window docker compose up -d --wait databasedocker 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 -
If the restore succeeds, start Frameleaf with
docker compose up -dand 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
Section titled “Diagnose connection failures”For manual installations:
docker logs frameleaf_postgresdocker exec frameleaf_postgres pg_isreadydocker logs frameleaf_serverFor 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.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.


