What is a Salesforce Org?

An org is the virtual space provided to an individual Salesforce customer. It includes all customer data and applications, and is composed of Systems of Record (SOR) that store customer data and metadata, including:

• Relational Database (DB)
• NoSQL Database (HBase)
• FileForce (Keystone)

Additional services that store org state include search indexes (Solr) and Domain Name System (DNS) for My Domains.

What is an Org Migration?

An org migration is a set of processes and technologies that move a production org from a source Salesforce instance to a target Salesforce instance. The org move is orchestrated by copying and regenerating customer data and metadata.

What Happens During an Org Migration Window?

During an org migration window, the org enters read-only mode. This is the org migration event window, required to make a consistent copy of the org's data. The org migration tool orchestrates copying data from all source Systems of Record (SOR) to the corresponding target SOR. Once all SOR data is successfully copied, the org is activated on the target instance.

Relational Database (DB)

Since Salesforce is a multi-tenant system — where multiple customers share database resources — standard database migration tools are not applicable. Salesforce uses a custom data copy tool that runs on Salesforce application servers. This tool has two stages: Copy and Validation.

Copy

Data is stored in database tables. Table copy takes place in chunks, which may be copied in parallel for performance. Each chunk is processed as follows:

1. Read data from the source pod's database using standard SQL (Structured Query Language) through JDBC (Java Database Connectivity).
2. Transport data to the target pod over HTTPS using end-to-end TLS (Transport Layer Security) encryption.
3. Insert data into the target pod's database using standard SQL through JDBC. If a chunk copy fails for any reason (source, network, or target failure), the entire chunk is retried with no retry limit.

Validation

After all table data is copied, a validation process runs on every table:

1. Run SQL queries using JDBC to collect the row count and checksum of a subset of fields on both the source and target databases.
2. Compare row counts and checksums from source and target.

If all validations complete successfully, the Relational Database copy is complete.

FileForce (Keystone)

Keystone is composed of a metadata catalog and a store for file extents. The metadata catalog is stored in the relational database. The extent store is API-driven and globally accessible — target instances can access extents on source instances.
During the migration window, Salesforce copies only the metadata catalog from source to target (using the same mechanism as the Relational Database). After migration, the metadata catalog on the target instance points to extents on the source instance until asynchronous migration of file extents is complete.
Migration of file extent data from source to target is performed asynchronously outside of the migration window to minimize org read-only downtime. This process can take up to 2 weeks after the org is activated. Users retain uninterrupted access to all FileForce data throughout this process.

NoSQL Database (HBase)

HBase migration uses a two-step approach:

1. A replication process is enabled between source and target clusters so that new data written on the source immediately flows to the target.
2. Existing data is copied from source to target in parallel with replication.

The detailed HBase migration steps are:

1. Set up cross-cluster trust so source and target cluster processes can communicate (clusters are Kerberos-secured).
2. Initiate replication so new data flows to the target cluster.
3. Initiate the copy job for existing org data.
4. Copy metadata for the org to the target cluster (required for Phoenix table views not covered by replication).
5. Confirm data copy jobs complete successfully.
6. Tear down the cross-cluster trust.

What Happens After an Org Migration?

On activation, the org accepts read-write requests on the target pod. New writes land on the target pod's SOR stores.
FileForce data migration from source to target continues asynchronously. A periodic process on the target instance scans all Keystone metadata and enqueues copy operations for all extent data for the migrated org. These operations retry until successful.
For encrypted blobs, decryption keys are stored as metadata rows and copied separately during the Relational Database copy process. Copying to target FileForce stores can take up to 2 weeks after org activation. Users have uninterrupted access to all FileForce data throughout.

Sandboxes

Sandboxes are not moved as part of an org migration. Sandboxes remain on the CS instance where they were located until refreshed. Existing sandboxes remain where they are until deleted by the customer or refreshed. Upon refresh, the new sandbox org is created in the same region as the production org. Metadata migration tools such as Change Sets and Ant continue to operate exactly as before the migration.

Search Operations

During an org migration, search data is transferred from source servers to target servers. Source servers are backed up as part of standard search backup procedures. For orgs scheduled for migration, these backups are executed with higher priority to ensure all data is current.
During migration, search data backups are restored on the target servers. No data is removed from the source, which allows Salesforce to roll back or abort operations without customer impact.
The restore process generally completes during off-business hours. For large orgs, the restore phase can take longer, which may temporarily impact search-dependent operations such as record lookup and content search. No customer action is required.

See Also

How to Prepare for an Org Migration