# How to Backup Logto Data: Complete PostgreSQL and Storage Guide

> Learn how to backup Logto data. This guide covers PostgreSQL dumps, archiving storage directories, and preserving essential environment variables for data recovery.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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](https://github.com/logto-io/logto/blob/master/.github/CONTRIBUTING.md) and initialization commands found in [AGENTS.md](https://github.com/logto-io/logto/blob/master/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](https://github.com/logto-io/logto/blob/master/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](https://github.com/logto-io/logto/blob/master/.github/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:

```bash

# 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](https://github.com/logto-io/logto/blob/master/packages/schemas/CHANGELOG.md), including all tenant and user data structures.

### Using Direct Host Access (Production)

For production servers with direct PostgreSQL access:

```bash
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:

```bash
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`):

```bash

# 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):

```bash

# 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:

```bash

# Create a dated backup of your environment file

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

```

Critical variables to secure include:

```dotenv
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**:

```bash
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](https://github.com/logto-io/logto/blob/master/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:

```cron
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:

```bash
#!/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](https://github.com/logto-io/logto/blob/master/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](https://github.com/logto-io/logto/blob/master/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](https://github.com/logto-io/logto/blob/master/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](https://github.com/logto-io/logto/blob/master/packages/core/CHANGELOG.md) for migration notes before restoring to a newer version, and run `pnpm cli db alter` after restoration if upgrading.