Upgrading to Version 4.1.0

Overview

Version 4.1.0 introduces important architectural changes with the removal of the PHP-based database migration system in favor of traditional SQL scripts. This change simplifies maintenance and improves reliability.

Key Changes

• Database migration system removed: PHP-based Phinx migrations replaced with SQL scripts
• Simplified upgrade process: Direct SQL script execution instead of migration commands
• Better compatibility: SQL scripts work across different PHP environments
• Reduced dependencies: Removal of CakePHP components and Phinx library
• New Modern Theme: Bootstrap 5 sidebar layout with mobile responsive design
• Legacy Configuration Removal: inc/config.inc.php support completely removed

Breaking Changes

Removed Features

• Migration management interface: The show_migrations configuration option has been removed
• Database migration commands: PHP-based migration tools are no longer available
• Migration status tracking: The migrations table is no longer used
• Legacy configuration support: inc/config.inc.php is no longer supported - use config/settings.php

Removed Dependencies

The following PHP packages have been removed: * robmorgan/phinx - Database migration library * cakephp/* packages - Various CakePHP components used by Phinx

Upgrade Instructions

Step 1: Backup Your Data

Always backup your database and files before upgrading.

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

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

Step 2: Download and Extract

1. Download the latest v4.1.0 release from GitHub
2. Extract the archive to a temporary location
3. Copy files to your Poweradmin installation directory

Step 3: Run Database Updates

Choose the appropriate SQL script for your database type:

For MySQL/MariaDB:

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

For PostgreSQL:

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

For SQLite:

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

Step 4: Update Configuration

Remove the show_migrations setting from your config/settings.php file if present:

// Remove this line if it exists:
'show_migrations' => true,  // ← Remove this entire line

Step 5: Clear Any Cached Data

If you have any caching enabled, clear the cache:

# Example for file-based cache
rm -rf cache/*

# Or restart your web server
sudo systemctl restart apache2
# or
sudo systemctl restart nginx

Database Schema Changes

The v4.1.0 update script performs the following changes:

• Drops the phinxlog table (migration tracking table)
• Removes migration-related database objects
• Optimizes existing table structures

Post-Upgrade Verification

After upgrading, verify your installation:

1. Check the web interface: Ensure Poweradmin loads without errors
2. Test core functionality: Try creating/editing a DNS zone
3. Verify database connectivity: Check that all data is accessible
4. Review logs: Check web server and PHP error logs for any issues

Configuration Changes

Removed Configuration Options

The following configuration options are no longer supported:

• interface.show_migrations - Migration management interface toggle

Updated Configuration Structure

No other configuration changes are required for this release.

Troubleshooting

Common Issues

Migration table still exists: If you see references to migration tables, manually remove them:

-- For all database types
DROP TABLE IF EXISTS phinxlog;

Permission errors: Ensure your web server has proper permissions:

# Example permissions setup
chown -R www-data:www-data /path/to/poweradmin
chmod -R 755 /path/to/poweradmin

Cache issues: Clear any application or web server caches after the upgrade.

Rollback Instructions

If you need to rollback to v4.0.0:

1. Restore your database backup
2. Restore your file backup
3. No additional migration commands are needed

Support

If you encounter issues during the upgrade:

1. Check the GitHub Issues page
2. Review the error logs for specific error messages
3. Ensure all prerequisites are met for v4.1.0

Next Steps

After successfully upgrading to v4.1.0:

1. Review the new streamlined upgrade process
2. Update your upgrade procedures to use SQL scripts directly
3. Consider automating future upgrades using the SQL scripts

For future upgrades, you can now apply database changes using standard SQL scripts instead of PHP migration commands.