PXM runs under a dedicated, unprivileged account. The supported release targets are Ubuntu 22.04, 24.04 and 26.04 on ARM64 and x86_64. Its databases listen on localhost. Your application connects locally, or through a separately configured secure tunnel. PXM does not open firewall ports or expose database listeners publicly.
Install the verified release executable in a directory owned by this account, such as ~/.local/bin/pxm. The executable and its directory must have no group or other write permission. Keep the whole downloaded archive if you need its release receipt and third-party license notices. An executable directory writable by your account allows pxm self-update to install future signed releases without root access.
First setup
pxm doctor pxm license activate pxm startup enable pxm service add mysql --name database pxm service start database pxm services pxm service env database
license activate reads the key privately. service env intentionally prints the generated connection credentials. Do not put that output into a public log. MySQL uses port 3306, PostgreSQL 5432, and Redis 6379. Set --port for an additional instance. An occupied port is reported without stopping its current owner.
For production applications, use the administrator connection to create an application-specific database account with the permissions it needs. Keep PXM's management credentials separate from the application's configuration. Backups and compatible updates preserve existing application accounts and grants.
Adding a service downloads and verifies its engine, creates private data, and installs authentication before registering it. Start it when you are ready to connect. New services default to autostart on subsequent PXM starts; disable that with --autostart off or pxm service autostart database off.
Boot, logout and shutdown
pxm startup enable installs the account's systemd user unit and enables lingering so PXM starts at boot without an interactive login. An administrator password may be needed for that one account policy change. It does not make PXM or its databases run as root.
pxm startup status --json pxm daemon restart pxm startup disable
Disabling startup cleanly stops PXM and its services. It retains their data and leaves the account's shared lingering policy alone. startup enable --session-only leaves that existing policy unchanged. On an account that already has lingering enabled, this option can still start PXM at boot.
PXM waits for clean database shutdown. A slow checkpoint is allowed to finish. There is no timeout that force-kills a database. If PXM itself crashes, its database children receive their clean shutdown signal and systemd restarts the manager. Existing services can start and recover when licensing or downloads are unavailable. Creating a new service or installing an engine update requires an active Pro license.
If an individual database crashes while PXM remains running, PXM retries that same data generation with increasing delays, up to five attempts in ten minutes. service info reports the failure, pending retry and attempt count. An intentional stop or maintenance operation cancels automatic retries. If an earlier PXM process is still finishing a slow checkpoint, the replacement manager waits for that verified process in the background while other services remain usable. An unrelated process is never stopped or adopted automatically.
Database durability still depends on the engine and storage. Redis uses AOF with its standard appendfsync everysec policy, so abrupt host power loss can lose the most recent second of writes. PXM's recovery journal protects generation selection; it does not turn an engine's asynchronous durability policy into synchronous storage.
Readiness and recovery limits
A database must pass its authenticated readiness check within five minutes. Returning to the original generation after a backup or a failure before commit has a two-minute recovery budget. If readiness times out, PXM requests a clean shutdown and waits for it to finish. It never force-kills the database to meet that deadline.
Inspect pxm service info database --json, pxm service logs database and the daemon log. If recoveryRequired is true, run pxm service recover database. Otherwise, address the reported error before retrying pxm service start database. Failed boot autostart is reported in the daemon log rather than retried indefinitely.
Failed replacement validation preserves the original generation. Recovery after a committed update keeps the replacement and its acknowledged writes. Workloads whose normal startup exceeds these budgets need additional qualification and are outside this release's readiness guarantee.
Backups
pxm service backup database pxm service backups database install -d -m 700 "$HOME/backups" pxm service backup-export database BACKUP_ID "$HOME/backups/database-export"
A backup briefly stops that service cleanly, copies and hashes its data and credentials, then returns it to its previous running or stopped state. Other databases keep running. Backup files and the original data are retained. This is a consistent physical snapshot, so the pause depends on the size of the database and storage speed. It is not a zero-downtime backup.
backup-export writes a new private directory outside the PXM data root. Its parent must already exist, belong to your account, and have no group or other write permission. The command above creates a suitable private parent. The export includes the snapshot, credentials, signed package receipt and exact engine binaries. Copy the entire directory to your private backup storage, preserving its private permissions. The bundle contains passwords and database contents; encrypt it when your storage or transfer policy requires encryption. A backup on the same disk cannot protect against losing that disk.
PXM never deletes old backups automatically. Monitor free space and keep enough capacity for the current data, the snapshot and a replacement generation during an update or restore. Incomplete copies are not presented as valid backups. Backups refuse external tablespaces, symbolic links and hardlinked data rather than silently omitting them.
Schedule this command with your server's job scheduler during a suitable maintenance window. Check its exit status and periodically rehearse a restore on a separate instance. Keep an exported backup before removing any old data or changing the host.
Restore on the same machine
pxm service restore database BACKUP_ID --yes
Restore replaces the service's current data with the selected snapshot. It first saves the current state, validates the replacement with its exact engine on an isolated port, then switches the registered generation. The existing service keeps its name and port. The previous data remains available for recovery.
--yes explicitly confirms the data replacement. Writes made after the selected backup are not merged into it.
Recovery on another machine
Use the same CPU architecture and a supported Ubuntu release. Physical bundles are not a cross-architecture migration format.
pxm daemon start pxm service backup-import "$HOME/backups/database-export" --name restored pxm service start restored pxm service env restored
Import verifies the complete bundle and its signed engine, restores the original credentials, and registers a new stopped service with autostart off. Its original port is kept unless you supply --port. The source bundle remains untouched. Recovery works without a license receipt or network access. To make the recovered instance start at boot, run pxm service autostart restored on and pxm startup enable.
Engine updates and rollback
pxm service update-check database pxm service update database pxm service info database
PXM checks the signed Cloudflare catalog and only offers a newer compatible release in the same supported line. MySQL and Redis retain their major and minor line; PostgreSQL retains its major line. Major migrations are refused instead of upgrading a live data directory implicitly.
The update downloads and verifies the new engine first. It then cleanly stops the selected database, creates a verified backup, copies a replacement generation and validates it on an isolated port. The port and credentials stay the same. The new generation is committed durably before it accepts connections on the normal port.
If the operation fails before that commit, PXM returns to the original generation. After the commit, recovery keeps the new generation, including writes it has accepted. It does not silently discard those writes by returning to an older snapshot.
pxm service recover database pxm service rollback database --yes
Use recover when an interrupted operation needs attention. An explicit rollback restores the previous snapshot with its previous engine. It also retains the current state first. A rollback does not merge post-update writes, so review the backup and application state before confirming it.
PXM updates and logs
pxm self-update --check pxm self-update pxm daemon restart pxm service logs database journalctl --user -u pxm.service
The CLI updater verifies the signed stable feed, exact archive checksum and CPU architecture, then replaces the executable atomically. Installing it leaves running services alone. Restart the manager during your maintenance window to apply the new executable to service management. The restart cleanly stops owned databases and starts those whose autostart is enabled. Services with autostart disabled stay stopped until explicitly started. The separate website router and site workers are not restarted by this command.
The default data root is ~/.local/share/pxm-server. PXM_HOME can select a separate absolute private root before setup. The startup unit is bound to that exact root and refuses to take over another workspace. Do not rename or copy live data directories manually.
PXM 0.4 adds managed websites, automatic HTTPS and Node.js. Its database importer copies selected MySQL and PostgreSQL databases into a new verified service while leaving the source untouched. Pause application writes for the copy, then verify the application before switching traffic. The importer does not take over foreign data directories or silently copy privileged source accounts. MariaDB and automatic container adoption remain outside the qualified scope.