Instance Migrator – Perfex CRM Migration Tool

Secure, reliable, and flexible migration for Perfex CRM SaaS tenants and standalone installations.
Export, import, clone, and transfer Perfex CRM data and files between servers with automatic encryption re-keying, table-prefix remapping, and secure server-to-server transfers.

Instance Migrator makes it easy to move individual Perfex CRM SaaS tenants or standalone Perfex CRM installations without manually handling database dumps, encryption keys, table prefixes, or uploaded files.

Note: This is a module for Perfex CRM

Quick Highlights

Full Tenant Export – Export an individual SaaS tenant with its database and files
Standalone Migration – Export and import the complete database of a standalone Perfex installation
Automatic Encryption Re-keying – Keep encrypted settings and credentials readable after migration
Table Prefix Remapping – Automatically adapt tenant table prefixes during import
Server-to-Server Transfer – Securely transfer migration packages between paired servers
Flexible Import – Import database, files, or both
Manual Transfer Support – Download migration packages and transfer them manually
Complete Audit Trail – Track migration status, progress, counts, timestamps, and communication logs
Built for SaaS & Standalone – Installation type is automatically detected

Why You Need This Module

Moving a Perfex CRM installation or SaaS tenant to another server can involve much more than copying a database. Encrypted settings may no longer work with the destination encryption key, tenant table prefixes may conflict, and uploaded files can easily be missed. This module allow you to migrate or eject/ingest a tenant without revealing encryption key to either party.

Instance Migrator handles these migration tasks automatically. Export the required data, transfer the migration package, and import it into the destination installation with encryption re-keying, table-prefix remapping, and file restoration handled by the module.

Whether you are moving an individual SaaS tenant, restoring tenant data, preparing a staging/demo environment, or migrating a standalone Perfex CRM installation, Instance Migrator provides a structured and reliable migration workflow.

Key Features

Full Tenant Export

Export an individual tenant from a Perfex CRM SaaS installation
Exports tenant-scoped database tables
Exports data as a gzipped SQL dump
Includes source and destination table-prefix information in the dump header
Optionally includes the tenant’s standard Perfex upload directories
Suitable for tenant migration, cloning, staging, and restoration

Standalone Installation Export

Export the complete database of a standalone Perfex CRM installation
Optional export of standard Perfex uploaded files and media
Suitable for moving an entire standalone Perfex installation to another server
Can be transferred manually or through a paired server connection

Flexible Import

Import a database dump, file archive, or both
At least one import source is required
Files-only import restores media without modifying database data
In SaaS mode, import data into the selected tenant’s database
In standalone mode, import into the current Perfex database
Automatically handles destination table prefixes

Automatic Encryption Re-keying

Encrypted values remain readable after migration
Exported data is re-keyed using a fresh per-export encryption key
The installation’s real encryption key is never stored inside the migration package
On import, encrypted values are re-encrypted using the destination installation’s encryption key
Supports SMTP passwords and mail client secrets
Supports payment gateway encrypted credentials with automatic detection
Supports staff 2FA secrets
Supports department and lead email-integration passwords
Supports vault passwords and standard encrypted columns

Table Prefix Remapping

Automatically remaps database tables to the destination tenant prefix
Detects the source prefix directly from the migration dump header
Helps prevent accidental double-prefixing
Helps avoid table and foreign-key conflicts during tenant imports
Designed specifically for Perfex CRM SaaS tenant isolation

Secure Server-to-Server Transfer

Optional peer-to-peer server pairing
Short-lived pairing codes
Administrator confirmation required on both servers
Fresh 256-bit shared secret negotiated during pairing
HMAC-SHA256 signed API requests
Timestamp-based replay protection
Unique nonce protection for requests
Time-limited download tokens
Incoming transfers can be disabled

Manual Transfer Support

Download database dumps for manual transfer
Download file archives for manual transfer
Upload packages through the destination import interface
No direct server connection required

Complete Migration History

Track every migration operation
Record migration direction and type
Track tenant information where applicable
Migration status and progress from 0-100%
Database table counts
File counts
Migration timestamps
Detailed communication and error logs
Dedicated migration history and detail screens

What Gets Migrated

Database

Tenant-scoped tables in SaaS mode
Core Perfex CRM tables in standalone mode
Clients and contacts
Invoices and estimates
Proposals and contracts
Subscriptions
Projects and tasks
Leads
Options and settings, including encrypted values
Custom fields
Payment gateway configurations
Lead email integration settings
Department IMAP configurations
Staff accounts and 2FA secrets
Vault entries and passwords
Other supported Perfex CRM data

Files & Media

Client files and profile images
Staff profile images
Company files
Invoice attachments
Estimate attachments
Proposal attachments
Credit note attachments
Contract files
Project files and discussions
Ticket attachments
Lead attachments
Task attachments
Expense receipts
Newsfeed uploads
Delivery note files
Purchase order files
Custom PDF files
Vault attachments
Other standard Perfex CRM upload directories

Encrypted Fields Supported

Options Table

smtp_password
microsoft_mail_client_secret
google_mail_client_secret
Payment gateway encrypted fields – automatically detected

Database Columns

tblleads_email_integration.password
tbldepartments.password
tblstaff.google_auth_secret
tblvault.password

How It Works

1. Pair Servers (Optional)

Install Instance Migrator on both Perfex CRM installations and exchange a short-lived pairing code. Both administrators confirm the connection before it becomes active. A fresh shared secret is then negotiated automatically for secure communication.

2. Export

For SaaS installations, select the individual tenant you want to migrate. For standalone installations, run a full standalone export. The module generates a gzipped SQL dump and, optionally, a media archive.

Encrypted data is re-keyed using a fresh per-export encryption key while the export is being prepared. You dont have to expose your master encryption key.

3. Transfer

Transfer the migration package using a paired server connection, receive it through the secure push flow, or download the database and file packages for manual transfer.

4. Import

Upload the database dump and/or file archive. Instance Migrator detects the source table prefix, remaps tables to the destination prefix, re-encrypts supported encrypted data using the destination encryption key, and restores files to their appropriate Perfex CRM upload paths.

Security Features

HMAC-SHA256 request signing
Timestamp-based replay protection with a 5-minute window
Unique nonce for every signed request
P2P pairing with administrator confirmation on both ends
Fresh 256-bit shared secret for paired servers
Temporary download tokens with configurable expiration
Optional incoming transfer disable switch
Per-export encryption key
Installation master encryption key is never stored inside migration packages nor exposed. You dont have to share it !
Encrypted data is automatically re-encrypted under the destination installation’s key during import

Perfect For

Perfex CRM SaaS administrators migrating individual tenants
Agencies managing multiple Perfex CRM installations
Developers moving tenants between SaaS installations
Businesses migrating standalone Perfex CRM installations
Creating tenant staging or demo environments
Restoring tenant data and media
Moving Perfex CRM to a new server or hosting provider
Transferring tenants between separate SaaS environments
Developers who need a safer alternative to manual database migration

Requirements

Perfex CRM 3.1 or higher
PDO MySQL extension for SaaS/tenant DSN imports

What’s Included

Complete Instance Migrator module source code
Step-by-step documentation
Automated CLI test suite
tests/run_tests.php test runner
No build step or container required for the test suite
Multiple language file
Migration dashboard
Server pairing interface
Tenant export interface
Standalone export interface
Import interface
Migration history and detail screens

Important Notes

In SaaS mode, Instance Migrator is designed to migrate individual tenants, not the entire SaaS installation or all tenants at once.
In standalone mode, the module can migrate the complete database of that standalone Perfex CRM installation.
Always create a backup before performing a production migration.
Test the migration process in a staging environment before migrating critical production data.
Actual migration time depends on database size, number of files, server resources, and network speed.

Questions/Support

Perfex CRM version 3.1.* to latest is required
Documentation for installation, configuration, and usage is provided
Support responses are handled within business days
Please test thoroughly before production use
Custom integrations and provider support available as paid services

Documentation

View full documentation here

Demo

View a demo of the Module in action here.

Email: admin@admin.com
Password: password

Change Log

Version 1.0.0 – 30 August 2026

Version 1.0 (Initial Release)

Instance Migrator - Perfex CRM Migration Tool