Skip to main content

​
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:
Stores application data:
  • User accounts
  • Site configurations
  • API keys
  • Team memberships
Migrations are applied automatically by the migrate.sh script.

​
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+

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.
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.
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+

Default registration mode changed to invite_only:
# Explicitly set if you want open registration
DISABLE_REGISTRATION=false
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

​
Upgrading to v2.0+

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.
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

Error: Migration script exits with errorSolutions:
  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.
Error: Plausible container exits immediatelySolutions:
  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
Issue: Plausible is slower after upgradeSolutions:
  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)
Issue: Some statistics don’t appearSolutions:
  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

Build docs developers (and LLMs) love

Get started for freeTalk to us