Upgrade Guide

How to upgrade Plausible Analytics Community Edition to newer versions

Upgrade Overview

Plausible Community Edition is released twice per year with long-term support. Staying up to date ensures you have the latest bug fixes, performance improvements, and features.

Always backup your databases before upgrading. See the Maintenance guide for backup procedures.

Release Schedule

Community Edition follows a different release schedule than Plausible Cloud:

• Frequency: Long-term releases published twice per year
• Versioning: Semantic versioning (MAJOR.MINOR.PATCH)
• Support: Community-supported through GitHub Discussions

Plausible Cloud receives continuous updates multiple times per week. CE releases bundle these changes into stable releases.

Before You Upgrade

1. Review the Changelog

   Check the CHANGELOG.md for:

   • Breaking changes
   • New features
   • Configuration changes
   • Migration requirements
2. Backup Your Data

   Create backups of both databases:

   # PostgreSQL backup
   docker compose exec plausible_db pg_dump -U postgres plausible_db > backup_postgres_$(date +%Y%m%d).sql
   
   # ClickHouse backup
   docker compose exec plausible_events_db clickhouse-client --query "BACKUP DATABASE plausible_events_db TO Disk('backups', 'backup_$(date +%Y%m%d).zip')"
   
3. Check System Requirements

   Verify your system meets requirements for the new version:

   • Docker version compatibility
   • Database version requirements
   • Available disk space
   • Memory requirements
4. Plan Downtime

   Schedule the upgrade during low-traffic periods. Typical downtime: 5-15 minutes.

Standard Upgrade Procedure

Using Docker Compose

1. Pull Latest Changes

   Update the community-edition repository:

   cd community-edition
   git pull origin master
   
2. Pull New Images

   Download the latest Docker images:

   docker compose pull
   

   This downloads:

   • Latest Plausible application image
   • Updated PostgreSQL (if version changed)
   • Updated ClickHouse (if version changed)
3. Stop Services

   Gracefully stop all running containers:

   docker compose down
   
4. Start Services

   Launch with new images:

   docker compose up -d
   
5. Run Migrations

   Apply database migrations:

   docker compose exec plausible sh -c "/app/migrate.sh"
   

   Migrations use an interweaved approach, running PostgreSQL and ClickHouse migrations in order.

6. Verify Upgrade

   Check that services are running:

   docker compose ps
   docker compose logs plausible
   

   Verify the version:

   docker compose exec plausible sh -c "/app/bin/plausible version"
   

Migration Details

Database Migrations

Plausible uses two databases that must be migrated:

PostgreSQL

Stores application data:

• User accounts
• Site configurations
• API keys
• Team memberships

Migrations are applied automatically by the migrate.sh script.

ClickHouse

Stores analytics data:

• Pageviews
• Custom events
• Session data
• Aggregated statistics

Migrations may take longer for large datasets.

Checking Migration Status

# Check pending migrations
docker compose exec plausible sh -c "/app/pending-migrations.sh"

Manual Migration Control

For advanced users:

# Run only PostgreSQL migrations
docker compose exec plausible sh -c "/app/bin/plausible eval 'Plausible.Release.migrate()'"

# Run only ClickHouse migrations
docker compose exec plausible sh -c "/app/bin/plausible eval 'Plausible.Release.clickhouse_migrate()'"

Version-Specific Upgrade Notes

Upgrading to v3.0+

Time on Page Metric Changes

Version 3.0 reworked the time-on-page metric calculation:

• Now uses engagement events from tracker
• Legacy calculation used for historical data
• Warnings shown when legacy methods are used

No action required - changes are automatic.

Filter Format Changes

Dashboard filters changed from encoded to readable format:

• Old: ?filters=((is,page,(/docs,/blog)),...)
• New: ?f=is,page,/docs,/blog&f=...

Old links continue to work automatically.

Session Tracking Updates

ClickHouse now uses VersionedCollapsingMergeTree for visit data:

• Prevents race conditions
• Improves data accuracy
• Automatic migration during upgrade

Large datasets may take longer to migrate.

Upgrading to v2.1+

Registration Default Change

Default registration mode changed to invite_only:

# Explicitly set if you want open registration
DISABLE_REGISTRATION=false

IPv6 Environment Variables

ECTO_IPV6 and ECTO_CH_IPV6 are deprecated:

• IPv6 is now automatic with IPv4 fallback
• Remove these variables from configuration
• No action needed for most deployments

Cookie Changes

Auth cookies changed to token-based with server-side expiration:

• All users will be logged out after upgrade
• No data loss
• Users just need to log in again

Upgrading to v2.0+

Configuration Consolidation

Environment variables consolidated:

Old format:

CLICKHOUSE_DATABASE_HOST=clickhouse
CLICKHOUSE_DATABASE_NAME=plausible
CLICKHOUSE_DATABASE_USER=default
CLICKHOUSE_DATABASE_PASSWORD=password

New format:

CLICKHOUSE_DATABASE_URL=http://default:password@clickhouse:8123/plausible

Update your configuration file before upgrading.

Mailer Adapter Change

Default mailer changed from Postmark to Bamboo.Mua:

# If using Postmark, explicitly set:
MAILER_ADAPTER=Bamboo.PostmarkAdapter
POSTMARK_API_KEY=your-key

Rollback Procedure

If issues occur during upgrade:

1. Stop Services

   docker compose down
   
2. Restore Database Backups

   # Restore PostgreSQL
   docker compose exec -T plausible_db psql -U postgres plausible_db < backup_postgres_YYYYMMDD.sql
   
   # Restore ClickHouse
   docker compose exec plausible_events_db clickhouse-client --query "RESTORE DATABASE plausible_events_db FROM Disk('backups', 'backup_YYYYMMDD.zip')"
   
3. Revert to Previous Version

   git checkout <previous-version-tag>
   docker compose pull
   docker compose up -d
   
4. Verify

   Check that the previous version is running correctly:

   docker compose ps
   docker compose logs plausible
   

Database migrations may not be reversible. Always maintain backups before upgrading.

Upgrading ClickHouse

ClickHouse Version Compatibility

Plausible supports ClickHouse 21.0+. To upgrade ClickHouse:

1. Check Current Version

   docker compose exec plausible_events_db clickhouse-client --query "SELECT version()"
   
2. Review ClickHouse Release Notes

   Check ClickHouse releases for breaking changes

3. Backup Data

   Create a full ClickHouse backup before proceeding

4. Update docker-compose.yml

   plausible_events_db:
     image: clickhouse/clickhouse-server:24.3-alpine
     # ... rest of config
   
5. Restart Services

   docker compose down
   docker compose up -d
   

ClickHouse upgrades are generally backward compatible, but always test in a staging environment first.

Upgrading PostgreSQL

PostgreSQL upgrades require more care:

PostgreSQL major version upgrades (e.g., 14 → 15) require a database dump and restore. This is NOT automatic.

1. Backup Current Database

   docker compose exec plausible_db pg_dumpall -U postgres > backup_full_$(date +%Y%m%d).sql
   
2. Stop All Services

   docker compose down
   
3. Update Database Volume

   For major version upgrades, you may need to remove the old volume:

   docker volume rm community-edition_db-data
   
4. Update docker-compose.yml

   plausible_db:
     image: postgres:15-alpine
     # ... rest of config
   
5. Start Database

   docker compose up -d plausible_db
   
6. Restore Backup

   docker compose exec -T plausible_db psql -U postgres < backup_full_YYYYMMDD.sql
   
7. Start Remaining Services

   docker compose up -d
   

Troubleshooting Upgrades

Migration Fails

Error: Migration script exits with error

Solutions:

1. Check logs: docker compose logs plausible
2. Verify database connectivity
3. Ensure sufficient disk space
4. Check for schema conflicts
5. Consult GitHub Discussions for specific error

If migration fails, rollback to backup and investigate.

Container Won't Start

Error: Plausible container exits immediately

Solutions:

1. Check configuration: docker compose config
2. Review environment variables
3. Check logs: docker compose logs plausible
4. Verify BASE_URL and SECRET_KEY_BASE
5. Ensure databases are accessible

Performance Degradation

Issue: Plausible is slower after upgrade

Solutions:

1. Run ClickHouse OPTIMIZE:
   docker compose exec plausible_events_db clickhouse-client --query "OPTIMIZE TABLE events_v2"
   
2. Check database sizes and consider archival
3. Review ClickHouse buffer settings
4. Monitor resource usage (CPU, RAM, disk)

Missing Data After Upgrade

Issue: Some statistics don’t appear

Solutions:

1. Check if migrations completed successfully
2. Review ClickHouse materialized views:
   docker compose exec plausible_events_db clickhouse-client --query "SHOW TABLES"
   
3. Verify ClickHouse hasn’t dropped partitions
4. Restore from backup if data loss occurred

Best Practices

Test First

Always test upgrades in a staging environment before production

Backup Everything

Maintain regular backups and verify restoration works

Read Changelogs

Review release notes for breaking changes and new features

Monitor After Upgrade

Watch logs and metrics after upgrading to catch issues early

Stay Updated

1. Watch Releases

   Star and watch the Plausible Analytics repository on GitHub

2. Join Discussions

   Participate in GitHub Discussions

3. Follow News

   Follow Plausible on Twitter/X or Mastodon

Next Steps

Maintenance

Learn about operations, backups, and monitoring

Configuration

Review configuration options after upgrade