How to Backup Logto Data: Complete PostgreSQL and Storage Guide

Back up Logto by dumping the PostgreSQL database with pg_dump, archiving the storage directory defined by STORAGE_DIRECTORY, and preserving your environment variables including DB_URL.

Logto stores all operational data—including tenants, users, MFA configurations, and roles—in a PostgreSQL database, with optional user-uploaded assets stored in a configurable storage backend. Understanding how to backup Logto data ensures you can recover from hardware failures or migrate to new infrastructure without losing critical authentication state. This guide covers production-ready workflows derived from the logto-io/logto source code, specifically referencing database connection patterns documented in CONTRIBUTING.md and initialization commands found in AGENTS.md.

Prerequisites

Before initiating a backup, verify you have access to the following components:

• PostgreSQL instance access – Logto persists all data in PostgreSQL (default port 5432), including MFA backup codes referenced in packages/core/CHANGELOG.md.
• pg_dump and pg_restore utilities – These PostgreSQL client tools create portable dumps and rebuild databases.
• Storage backend access – User-uploaded avatars and files reside in the filesystem path defined by STORAGE_DIRECTORY or an external object store when STORAGE_PROVIDER is configured.
• Environment variables – The DB_URL connection string and storage configuration are required for restoration.

Back Up the PostgreSQL Database

All Logto data lives in PostgreSQL. According to CONTRIBUTING.md, the DB_URL variable typically follows the format postgres://user:password@host:5432/logto.

Using Docker (Local Development)

For Docker-based deployments, run pg_dump inside the container to avoid network credential exposure:

# Identify the container (default: logto-postgres)

docker ps | grep postgres

# Create a custom-format dump inside the container

docker exec logto-postgres pg_dump -U postgres -F c -b -v -f /var/lib/postgresql/data/logto_backup.dump

# Copy the dump to your host

docker cp logto-postgres:/var/lib/postgresql/data/logto_backup.dump ./logto_backup.dump

The -F c flag creates a custom format dump compatible with pg_restore. This method captures the complete database schema defined in packages/schemas/CHANGELOG.md, including all tenant and user data structures.

Using Direct Host Access (Production)

For production servers with direct PostgreSQL access:

export PGPASSWORD=your_db_password
pg_dump -h localhost -U postgres -p 5432 -F c -b -v -f logto_backup.dump logto

Replace the host, username, and database name to match your DB_URL configuration.

Verify the Database Dump

Confirm dump integrity before relying on it for disaster recovery:

pg_restore -l logto_backup.dump

This lists all objects contained in the dump. If the command executes without errors, the backup is healthy.

Back Up Uploaded Assets

Logto stores user-uploaded content—such as avatars and custom logos—outside the database. The location depends on your STORAGE_PROVIDER setting.

For filesystem storage (STORAGE_PROVIDER=filesystem):

# Archive the storage directory (default: /var/logto/storage)

tar -czvf logto_assets.tar.gz -C /var/logto storage

For object storage (e.g., Amazon S3):

# Sync the entire bucket to local backup

aws s3 sync s3://logto-bucket ./logto_assets/

Save Environment Configuration

Preserve your runtime configuration to ensure seamless restoration:

# Create a dated backup of your environment file

cp .env .env.backup_$(date +%F)

Critical variables to secure include:

DB_URL=postgres://postgres:YOUR_PASSWORD@HOST:5432/logto
STORAGE_PROVIDER=filesystem
STORAGE_DIRECTORY=/var/logto/storage

Restore Logto from Backup

Restoration requires reversing the backup process using the files and variables you preserved.

1. Prepare the target database – Create a fresh PostgreSQL instance or drop the existing Logto database.

2. Restore the database dump:

pg_restore -h localhost -U postgres -d logto -c logto_backup.dump

The -c flag drops existing objects before recreating them, ensuring a clean restoration state.

3. Restore assets:

   • Filesystem: tar -xzvf logto_assets.tar.gz -C /
   • S3: aws s3 sync ./logto_assets/ s3://logto-bucket

4. Restart Logto with the saved environment variables (e.g., pnpm start:dev or Docker Compose).

As implemented in the packages/cli/CHANGELOG.md, the db seed and db alter CLI commands interact with this same PostgreSQL instance, confirming that a restored database will correctly support Logto's administrative operations.

Automate Periodic Backups

For production environments, schedule automated backups using cron. This example runs daily at 02:30 AM, dumping the database and syncing to S3:

30 2 * * * /usr/bin/pg_dump -h localhost -U postgres -F c -f /backups/logto_$(date +\%F).dump logto && \
    /usr/bin/aws s3 cp /backups/logto_$(date +\%F).dump s3://my-logto-backups/

Complete automation script combining database and asset backups:

#!/usr/bin/env bash
set -euo pipefail

# Database backup

export PGPASSWORD=postgres
pg_dump -h localhost -U postgres -F c -b -v -f /backups/logto_$(date +%F).dump logto

# Asset backup

tar -czvf /backups/logto_assets_$(date +%F).tar.gz -C /var/logto storage

# Remote sync

aws s3 cp /backups/logto_$(date +%F).dump s3://my-logto-backups/
aws s3 cp /backups/logto_assets_$(date +%F).tar.gz s3://my-logto-backups/

Summary

• Logto data resides in PostgreSQL – Use pg_dump -F c to create portable custom-format dumps that include all tenant, user, and MFA configuration data.
• Assets require separate backup – Filesystem storage needs tar archiving; object stores need synchronization tools like aws s3 sync.
• Environment variables are critical – Secure the DB_URL and STORAGE_DIRECTORY values to ensure successful restoration.
• Verification prevents surprises – Always run pg_restore -l to validate dump integrity before disaster strikes.
• Automation ensures consistency – Schedule cron jobs to execute pg_dump and storage syncs regularly.

Frequently Asked Questions

Does Logto provide a built-in backup command?

No, Logto does not include a native backup CLI command. According to packages/cli/CHANGELOG.md, the CLI provides db seed and db alter for database management, but backup operations rely on standard PostgreSQL tools like pg_dump and pg_restore.

What data is included in the PostgreSQL dump?

The dump captures everything stored in the database schema, including tenant configurations, user profiles, roles, MFA settings, and OAuth application data. As noted in packages/schemas/CHANGELOG.md, this schema defines all tables required for Logto's operation. However, user-uploaded files (avatars, logos) stored in the STORAGE_DIRECTORY or external object stores must be backed up separately.

How do I backup Logto when running in Docker?

Use docker exec to run pg_dump inside the PostgreSQL container, then copy the file to your host with docker cp. This approach avoids exposing database credentials over the network and works with the default development setup documented in AGENTS.md.

Can I restore a backup to a different version of Logto?

Restoration works best when the target Logto version matches the source version. Database schema changes between versions may cause compatibility issues. Check packages/core/CHANGELOG.md for migration notes before restoring to a newer version, and run pnpm cli db alter after restoration if upgrading.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}