Skip to content

Upgrading Poweradmin

General Upgrade Instructions

When upgrading Poweradmin from any version to a newer one, follow these general steps:

  1. Backup your database - This is critical before any upgrade
  2. Backup your existing files - Make a complete backup of your current installation
  3. Replace files - Replace all files with the new version's files
  4. Restore configuration - Depending on your version:
  5. For versions < 4.x: Restore inc/config.inc.php from your backup
  6. For versions ≥ 4.x: Restore config/settings.php from your backup
  7. Update database structure - If required by the specific version upgrade
  8. Test functionality - Verify all features work correctly after upgrade

Patch Version Upgrades (e.g., 4.0.x → 4.0.y)

For patch releases within the same minor version (e.g., 4.0.0 → 4.0.3, or 4.0.3 → 4.0.4), the upgrade process is straightforward:

  1. Backup your database and files - Always a good practice
  2. Replace all application files - Extract the new release over your existing installation
  3. Preserve your configuration - Your config/settings.php (or inc/config.inc.php for older versions) remains unchanged
  4. Check release notes for SQL updates - Only run database migration scripts if explicitly mentioned in the release notes for that version

  5. Clear PHP opcache - If your environment uses opcache, restart PHP-FPM or your web server to clear cached bytecode:

    sudo systemctl restart php-fpm
# or
sudo systemctl restart apache2

  6. Verify functionality - Test login and basic operations

Key points for patch releases:

  • Patch releases maintain backward compatibility - no breaking changes
  • Configuration format remains the same
  • Database schema changes are rare in patch releases (but always check release notes)
  • The same file replacement process applies as major upgrades

Alternative: Symlink Strategy

For easier rollbacks, consider using symlinks:

# Extract new version to versioned directory
tar -xzf poweradmin-4.0.4.tar.gz -C /var/www/

# Update symlink to point to new version
ln -sfn /var/www/poweradmin-4.0.4 /var/www/poweradmin

# Keep config outside versioned directories
ln -s /etc/poweradmin/settings.php /var/www/poweradmin/config/settings.php

This allows quick rollback by simply changing the symlink back to the previous version.

Upgrading a Docker or Docker Compose Deployment

The official image does not migrate an existing database. On startup the entrypoint loads the Poweradmin schema only into an empty database; a database created by an older version is left as it is. Upgrading a container therefore means: back up, switch the image tag, restart, and run the release's migration script yourself. The image ships the sql/ directory together with the psql, mysql and sqlite3 clients, and the DB_* variables are already in the container's environment, so the script can be run from inside the new container.

The examples below assume the Compose service names poweradmin and postgres (or mysql) and an upgrade from 4.3.x to 4.4.1. Adjust the names and the script version to your setup.

  1. Back up the database:

    # PostgreSQL
docker compose exec postgres pg_dump -U poweradmin poweradmin > poweradmin-before-4.4.sql

# MySQL / MariaDB
docker compose exec mysql mysqldump -u poweradmin -p poweradmin > poweradmin-before-4.4.sql

  2. Switch the image tag in your Compose file (for example poweradmin/poweradmin:4.4.1), then pull and recreate only the application container:

    docker compose pull poweradmin
docker compose up -d poweradmin

  3. Run the migration script from inside the new container:

    # PostgreSQL
docker compose exec poweradmin sh -c 'PGPASSWORD="$DB_PASS" psql -h "$DB_HOST" ${DB_PORT:+-p "$DB_PORT"} -U "$DB_USER" -d "$DB_NAME" -v ON_ERROR_STOP=1 -f /app/sql/poweradmin-pgsql-update-to-4.4.0.sql'

# MySQL / MariaDB
docker compose exec poweradmin sh -c 'mysql -h "$DB_HOST" ${DB_PORT:+-P "$DB_PORT"} -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" < /app/sql/poweradmin-mysql-update-to-4.4.0.sql'

# SQLite (database file on the volume)
docker compose exec poweradmin sh -c 'sqlite3 "${DB_FILE:-/db/pdns.db}" < /app/sql/poweradmin-sqlite-update-to-4.4.0.sql'

    If the password is supplied through a Docker secret (DB_PASS__FILE), $DB_PASS is not set in the exec shell; use $(cat "$DB_PASS__FILE") in its place.

  4. Check the application - log in and open the zone templates and add zone pages.

Notes:

  • Run one script per version, in order, and never skip a version. Coming from 4.2.x, run the 4.3.0 script before the 4.4.0 one.
  • Between the container restart and the migration, pages that read the new schema fail with "An error occurred while processing the request" (on 4.4.x: zone templates and add zone). The rest of the application keeps working, so the window is short but real; run the script right after the restart.
  • Run each script once. The scripts are not idempotent: a second run stops with an error such as column "is_default" of relation "zone_templ" already exists, which is harmless but means the script was already applied.
  • Patch releases (4.4.0 to 4.4.1) need no script unless their release notes say otherwise; switching the tag and restarting is enough.
  • A volume-mounted config/settings.php is left untouched. Check the release notes for new settings or container variables you may want to set.

Important Considerations

  • Always read the release notes for the version you're upgrading to and any intermediate versions
  • Neglecting to follow proper upgrade procedures may result in a non-functioning installation
  • It's recommended to perform upgrades in a test environment first before applying to production
  • After upgrading, check the system for any warnings or errors
  • Verify that zones and records remain accessible and editable
  • Report any bugs or issues you encounter during the upgrade process

Upgrade Path

If you're upgrading across multiple major versions, it's often safest to upgrade incrementally through each major version rather than jumping directly to the latest version.

If you're upgrading from a very old version (e.g., 2.0.0) to the latest release, 4.4.0, we recommend the following path:

  1. 2.0.0 → 2.1.4 (Important database structure changes)
  2. 2.1.4 → 2.2.2 (API integration changes)
  3. 2.2.2 → 3.2.0 (DNSSEC implementation)
  4. 3.2.0 → 3.9.3 (Security improvements)
  5. 3.9.3 → 4.0.0 (Complete architecture overhaul)
  6. 4.0.0 → 4.1.0 (OIDC/SAML authentication, DNS wizards, permission improvements)
  7. 4.1.0 → 4.2.0 (PHP 8.2 minimum, groups support, bulk record operations)
  8. 4.2.0 → 4.3.0 (PowerDNS API backend mode, zone metadata editor, separate API log table)
  9. 4.3.0 → 4.4.0 (Default zone template, PowerDNS capability detection, Views & Networks)

Critical Versions with SQL Migrations

The following versions include important database structure changes:

  • v2.1.4 - Added supermasters and domainmetadata tables
  • v3.0.0 - Added cryptokeys table for DNSSEC
  • v3.2.0 - Schema updates for PowerDNS API integration
  • v3.4.0 - Added tsigkeys table
  • v3.9.7 - Performance indexes on zones table
  • v4.0.0 - Complete schema overhaul, including user management
  • v4.0.5 - Primary key on records_zone_templ, PostgreSQL sequence fixes
  • v4.1.0 - OIDC/SAML authentication, DNS wizards, zone deletion permissions, permission templates
  • v4.2.0 - PHP 8.2 minimum, groups support, bulk record operations
  • v4.3.0 - PowerDNS API backend mode, zone metadata editor, separate API log table
  • v4.4.0 - Default zone template (zone_templ.is_default), PowerDNS capability detection, Views & Networks for PowerDNS 5.0
  • v4.5.0 (unreleased - complete on the master branch, awaiting its tag) - Serial policies (SOA-EDIT), record change log, granular API keys, log/metadata/ownership view permissions

Recent Patch Releases

The following releases are bug fix updates. Unless marked otherwise, no special upgrade steps are required - simply replace files and preserve your configuration. Releases marked requires SQL migration need their sql/ update script run first:

v4.4.x Series:

  • v4.4.1 (Sep 2026) - Same fixes as v4.3.5 for the 4.4.x line, plus dynamic DNS routing each myip address to its own record family, bulk record paths matched before single-record lookup, the PowerDNS metrics URL derived from pdns_api.url, and container variables for the 4.4.0 settings. No database migration

v4.3.x Series:

  • v4.3.5 (Sep 2026) - Same fixes as v4.2.6 for the 4.3.x line, plus LUA records restricted for client-level editors on every surface, one canonical zone id in API backend mode, and container config generation that escapes secrets and emits valid booleans. No database migration
  • v4.3.4 (Jul 2026) - User management and SSO account hardening, max_input_vars form fixes for large zones and groups, record/log/template binding fixes, MariaDB 11.6+ record search fix, per-zone logs button (requires MySQL migration; PostgreSQL/SQLite unaffected)
  • v4.3.3 (Jun 2026) - Permission and authorization hardening across API and DNSSEC, API-backend mode polish (record ordering, dashboard resilience), template sync correctness, Docker schema initialization
  • v4.3.2 (May 2026) - API-mode zone handling (reverse zone owner display, DNSSEC status on forward zones, record counts from PowerDNS, zone kind sync), template fixes (correct sync column, preserved spaces, API-mode safe), X-Forwarded-For header trust scoped to private peers, group-owned zone control visibility, DNSSEC sign events in activity feed
  • v4.3.1 (Apr 2026) - Patch release for 4.3.x line

v4.2.x Series:

  • v4.2.6 (Sep 2026) - interface.application_url required for OIDC, SAML and password reset; Docker containers with SSO enabled refuse to start without a URL source; API user creation without perm_templ no longer yields an administrator; deactivating a user revokes their API keys; zone template records validated on save; five confirmation flows moved to POST (re-sync forked themes). No database migration
  • v4.2.5 (Jul 2026) - Same fixes as v4.3.4 for the 4.2.x line (requires MySQL migration; PostgreSQL/SQLite unaffected)
  • v4.2.4 (Jun 2026) - Same fixes as v4.3.3 for the 4.2.x line
  • v4.2.3 (May 2026) - X-Forwarded-For header trust scoped to private peers, group-owned zone control visibility, PostgreSQL record_comment_links strict-typing fix, bulk record CSV escaping, CNAME validator accepts numeric-string IDs, API record edits honor zone_content_edit_own_as_client, Users API auth_method/use_ldap sync, zone template column and content-listing fixes
  • v4.2.2 (Apr 2026) - Patch release for 4.2.x line
  • v4.2.1 (Apr 2026) - Patch release for 4.2.x line

v4.1.x Series:

  • v4.1.4 (May 2026) - Record search fix for an ambiguous ORDER BY column
  • v4.1.3 (Apr 2026) - Duplicate SOA serial increment on inline record add, comment search query referencing a non-existent table, plural-form headers and missing format specifiers in several locales
  • v4.1.2 (Mar 2026) - xmlseclibs updated to 3.1.5 (CVE-2026-32313), SSO fixes (default permission template applied to new users only, auth_method preserved on edit, OIDC groups read from the ID token), Docker entrypoint fixes for PA_LOGGING_* and volume-mounted config
  • v4.1.1 (Feb 2026) - DNSSEC fix for RFC 2317 reverse zones, login routing fix, IPv6 supermaster validation, LUA record handling, CSRF token fix, zone apex (@) symbol fix in multi-record form

v4.0.x Series:

  • v4.0.11 (May 2026) - Record search fix for an ambiguous ORDER BY column
  • v4.0.10 (Apr 2026) - Duplicate SOA serial increment on inline record add, format specifiers and plural headers across all locales
  • v4.0.9 (Mar 2026) - Zone creation API validates the template as a numeric ID, sign-zone button separated from the edit form to prevent accidental signing, Docker entrypoint fixes for volume-mounted config, light theme gradient fix
  • v4.0.7 (Feb 2026) - CSRF token fix for DNSSEC key deletion, MFA TOTP secret reuse fix, IPv6 supermaster validation, LUA record handling, zone apex (@) symbol fix
  • v4.0.6 (Jan 2026) - Zone deletion fixes, IPv6 PTR handling, MySQL SSL disabled by default for backwards compatibility
  • v4.0.5 (Jan 2026) - Database compatibility (primary key fix), PostgreSQL sequence sync, PHP 8.4 fixes, new show_forward_zone_associations option (requires SQL migration)
  • v4.0.4 (Nov 2025) - LDAP+MFA fixes, automatic TXT record splitting, DNSSEC zone signing fixes
  • v4.0.3 (Oct 2025) - SOA serial updates on record operations, API pagination, dark mode fixes
  • v4.0.2 (Sep 2025) - MySQL strict mode compatibility, SPF validation, SMTP fixes
  • v4.0.1 (Aug 2025) - Docker MySQL config, v3.9.2→v4.0.0 migration fixes, LDAP form restoration

v3.9.x Series (LTS):

  • v3.9.12 (Sep 2026) - Permission checks on template, user and zone changes; template, supermaster and DNSSEC key changes require a confirmed POST; login timing equalised; session key warning distinguishes the shipped default; log and error output escaped; public suffix and TLD data refreshed. No database migration
  • v3.9.11 (Jul 2026) - Record edits and log entries bound to the record's real zone, duplicate email rejection, dependency updates
  • v3.9.10 (Mar 2026) - Translation updates for all locales
  • v3.9.9 (Jan 2026) - Allow HTML characters in TXT records, fix record name handling
  • v3.9.8 (Jan 2026) - CSRF protection, PostgreSQL fixes, API error handling improvements
  • v3.9.6 (Oct 2025) - CAA record validation support
  • v3.9.5 (Jul 2025) - MySQL ONLY_FULL_GROUP_BY compatibility fix
  • v3.9.4 (Jul 2025) - Configurable pagination rows per page

Long-Term Support (LTS)

3.x LTS Branch

Starting with version 3.9.8, the 3.x branch has entered Long-Term Support (LTS) status. This means:

  • Security updates and bug fixes until December 2027
  • No new features - only maintenance and critical fixes
  • Stable API - no breaking changes to existing functionality
  • PHP compatibility - supports PHP 8.1, 8.2, 8.3, 8.4, and 8.5

Who should use 3.x LTS?

  • Organizations that prefer stability over new features
  • Environments where upgrading to 4.x requires significant planning
  • Users who want to migrate to 4.x at their own pace while maintaining security coverage

When to upgrade to 4.x?

The 4.x series offers significant improvements including:

  • Modern architecture with Domain-Driven Design
  • RESTful API for automation and integration
  • Enhanced security features (MFA, API keys)
  • Improved UI with better accessibility
  • Docker support with FrankenPHP

We recommend planning your migration to 4.x when your schedule allows, while the 3.x LTS branch keeps your current installation secure.

Version Support Timeline

Branch Status PHP Versions
4.4.x Current feature line (4.4.1, Sep 2026) on release/4.4.x 8.2 - 8.5
4.3.x Current stable line (recommended for production) 8.2 - 8.5
4.2.x Maintenance - security fixes only; 4.2.6 is expected to be the last release 8.2 - 8.5
4.1.x End of support - upgrade to 4.3.x 8.1 - 8.5
4.0.x End of support - upgrade to 4.3.x 8.1 - 8.5
3.9.x LTS 8.1 - 8.5
3.8.x and older EOL -

PHP 8.1 Deprecation Notice: Version 4.1.x is the last release to support PHP 8.1. Starting with 4.2.x, the minimum required PHP version is 8.2. If you are running PHP 8.1, plan your PHP upgrade before moving to 4.2.x or newer.

Troubleshooting

If you encounter issues during or after an upgrade:

  1. Check the PHP and web server error logs
  2. Verify database connectivity and permissions
  3. Ensure file permissions are set correctly
  4. Review the specific upgrade instructions for the version you're upgrading to

Which update scripts have already run?

Poweradmin does not record the schema version in the database (the migrations table that some scripts create is never written to), so on an inherited or long-neglected installation you have to work it out from what each script adds. Check the markers below from the top; the first one that is missing tells you which script to run first. Then run every later script in order.

Script Marker that shows it has run
2.1.5 column zones.zone_templ_id
2.1.7 table records_zone_templ, column users.use_ldap
3.2.0 tables log_users, log_zones
3.9.0 none (widens a column type only; safe to re-run)
4.0.0 tables user_mfa, api_keys, login_attempts, column zone_templ.created_by
4.0.2 none (changes a column type only; safe to re-run)
4.1.0 column users.auth_method, tables oidc_user_links, saml_user_links
4.2.0 tables user_groups, zones_groups, column perm_templ.template_type
4.3.0 columns zones.zone_name, zones.zone_type, users.perm_templ_source, table log_api
4.4.0 column zone_templ.is_default
4.5.0 columns api_keys.is_readonly, login_attempts.attempt_type, table log_record_changes

To check a column or table:

-- MySQL/MariaDB
SHOW COLUMNS FROM zones LIKE 'zone_name';
SHOW TABLES LIKE 'log_api';

-- PostgreSQL (psql)
\d zones
\dt log_api

-- SQLite
PRAGMA table_info(zones);
.tables log_api

Do not re-run a script whose marker is already present. Scripts up to 4.0.0 have no IF NOT EXISTS guards and stop at the first duplicate column or table, which can leave the rest of that script unapplied. Take a dump before you start.