This documentation covers Poweradmin 4.x. Some sections are still being expanded.

Upgrading to Version 4.0.5

Overview

Version 4.0.5 is a maintenance release that focuses on bug fixes, database compatibility improvements, and a new configuration option to address performance issues.

Key Changes

  • Security: Replaced GET confirmation links with POST forms for delete operations; improved debug output escaping
  • Database Compatibility: Added primary key to records_zone_templ table for MySQL InnoDB Cluster compatibility
  • PostgreSQL Fix: Synchronized sequences to prevent duplicate key errors when adding permission templates
  • API Improvements: Fixed crash when PowerDNS API returns errors; HTTP 204 compliance; PHP 8.1 compatibility
  • Docker: Updated FrankenPHP base image to 1.10-php8.4-alpine; improved health checks
  • DNS: Allow HTML characters in TXT records; improved IDN validation
  • Performance Option: New configuration option to disable forward zone associations in reverse zone list

Breaking Changes

None - Version 4.0.5 is fully backward compatible with v4.0.0 configuration.

Upgrade Instructions

Prerequisites

  • You must be running Poweradmin v4.0.0 or later
  • If upgrading from v3.x, first upgrade to v4.0.0
  • Ensure you have a database backup before proceeding

Step 1: Backup Your Data

Always backup your database and files before upgrading.

# MySQL/MariaDB backup
mysqldump -u username -p poweradmin_db > poweradmin_backup_$(date +%Y%m%d).sql

# PostgreSQL backup
pg_dump -h localhost -U username poweradmin_db > poweradmin_backup_$(date +%Y%m%d).sql

# SQLite backup
cp /path/to/poweradmin.db /path/to/poweradmin_backup_$(date +%Y%m%d).db

Step 2: Download and Extract

  1. Download the v4.0.5 release from GitHub
  2. Extract the archive to a temporary location
  3. Replace files in your Poweradmin installation directory
cd /tmp
wget https://github.com/poweradmin/poweradmin/archive/refs/tags/v4.0.5.tar.gz
tar -xzf v4.0.5.tar.gz
rsync -av poweradmin-4.0.5/ /var/www/poweradmin/ --exclude=config/settings.php

Step 3: Run Database Updates

Version 4.0.5 includes a database schema update to add a primary key to the records_zone_templ table. This improves compatibility with MySQL InnoDB Cluster and other replication systems that require all tables to have primary keys.

For MySQL/MariaDB:

mysql -u username -p poweradmin_db < sql/poweradmin-mysql-update-to-4.0.5.sql

For PostgreSQL:

psql -h localhost -U username -d poweradmin_db -f sql/poweradmin-pgsql-update-to-4.0.5.sql

For SQLite:

sqlite3 /path/to/poweradmin.db < sql/poweradmin-sqlite-update-to-4.0.5.sql

Step 4: Clear Cache and Restart

# Restart PHP-FPM to clear opcache
sudo systemctl restart php-fpm
# or for Apache
sudo systemctl restart apache2

Step 5: Verify Upgrade

  1. Log in to Poweradmin
  2. Check that zones and records are accessible
  3. Test adding/editing records to confirm functionality

Database Schema Changes

Primary Key on records_zone_templ Table

The records_zone_templ table now has an id column as primary key. This change:

  • Enables compatibility with MySQL InnoDB Cluster (which requires all tables to have primary keys)
  • Improves compatibility with database replication systems
  • Has no impact on existing functionality

PostgreSQL Sequence Synchronization

For PostgreSQL users, this update also synchronizes the following sequences with actual data:

  • perm_items_id_seq
  • perm_templ_id_seq
  • perm_templ_items_id_seq

This prevents "duplicate key value violates unique constraint" errors when adding new permission templates or items.

New Configuration Option

show_forward_zone_associations

A new configuration option has been added to address performance issues when viewing reverse zones with many associated forward zones.

Location: config/settings.php

'interface' => [
    // ... other settings ...
    'show_forward_zone_associations' => true, // Default: true (added in 4.0.5)
],

Description: When set to true (default), the reverse zone list displays associated forward zones for each PTR record. When set to false, this lookup is disabled, which can significantly improve page load times for large installations with many reverse zones.

When to disable: If you experience Gateway Timeout errors or slow loading on the reverse zones page, set this option to false.

Bug Fixes

Zone Editing (Issue #958)

Fixed an issue where editing a DNS record would incorrectly remove the zone name from the record's name field. Previously, all occurrences of the zone name were removed; now only the trailing zone suffix is stripped as expected.

Zone Template Sync (Issues #944, #945)

Fixed errors when updating zones from templates, particularly affecting installations where zones were created before Poweradmin was installed (where zone_id differs from domain_id).

PHP 8.4 Compatibility (Issue #935)

Fixed type safety issues with getZoneTemplate() function that caused errors on PHP 8.4 when managing zones not created from templates.

SQLite Record Search (Issue #919)

Fixed "ambiguous column name: name" error when searching for records in zones using SQLite database.

SMTP Mail Configuration (Issue #861)

Fixed TLS/STARTTLS connection handling for SMTP mail transport. Email sending now works correctly with modern mail servers requiring encrypted connections.

Legacy Theme Handling (Issue #899)

Added graceful fallback when users have configured a removed legacy theme (like spark). The application now defaults to the default theme instead of throwing an error.

Microseconds Display (Issue #915)

Fixed the display of PowerDNS latency metrics to show the correct unit (microseconds/us) instead of milliseconds (ms).

HTML in TXT Records (Issue #953)

TXT records containing HTML characters (like < and >) are now accepted. Previously these were incorrectly rejected by validation.

API Crash Prevention

Fixed crash when PowerDNS API returns zone errors. The API now handles error responses gracefully.

DNSSEC Reverse Zone Detection

Added missing is_reverse_zone variable to DNSSEC controllers, fixing errors when managing DNSSEC for reverse zones.

Installation XML Extension Check

Added missing XML extension check in the requirements step of the installer.

Docker Users

If using the official Docker image, simply pull the new version:

docker pull poweradmin/poweradmin:4.0.5

The database migration will need to be run manually against your database unless using a fresh installation.

Troubleshooting

"Duplicate key value violates unique constraint" (PostgreSQL)

If you see this error when adding permission templates after upgrading, the sequence synchronization may not have run correctly. Manually run:

SELECT setval('perm_items_id_seq', (SELECT MAX(id) FROM perm_items));
SELECT setval('perm_templ_id_seq', (SELECT MAX(id) FROM perm_templ));
SELECT setval('perm_templ_items_id_seq', (SELECT MAX(id) FROM perm_templ_items));

Gateway Timeout on Reverse Zones

If the reverse zones page times out, add this to your config/settings.php:

'interface' => [
    'show_forward_zone_associations' => false,
],

Migration Script Errors

If the MySQL migration fails with "Duplicate column name 'id'", the table already has a primary key and no migration is needed. This can happen if you previously applied a fix manually or are upgrading from a development version.