Instance Migrator – Perfex CRM Migration Tool

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: [email protected]
Password: password

Change Log

Version 1.0.0 – 30 August 2026

• Version 1.0 (Initial Release)