Changing a WordPress site from a Pantheon development address to its final production domain requires coordinating DNS, domain attachment, SSL provisioning, and a database search-replace. These operations are related, but they are not all dependent on one another. In this deployment plan, the recommended sequence was to complete the domain and DNS cutover first, then update WordPress database references to the final domain once the new environment was serving traffic.
Issue background
A WordPress site hosted on Pantheon was preparing to replace an existing production website. The new WordPress build was available on a Pantheon development address, while the final public domain remained attached to the existing site.
The launch team needed to determine how to:
- Move the production domain to the new Pantheon environment
- Update WordPress database references from the temporary Pantheon address to the final domain
- Preserve HTTPS during the transition
- Keep downtime and broken assets to a minimum
The main concern was whether the database could be updated before the production domain was attached to the new environment.
Diagnosis
The database update and the domain attachment were separate operations. WordPress content could be searched and replaced with the final domain even though the domain itself was still being moved between environments.
However, updating the database too early could make internal links and assets point to a domain that still served the old site. For that reason, the cleaner sequence was:
- Complete the domain and DNS cutover.
- Run the WordPress database search-replace immediately afterward.
The Pantheon development address would remain available throughout the process, providing an alternate way to reach the new environment during troubleshooting.
Pantheon’s launch documentation also indicated that a short 404 period could occur while the domain was detached from the old environment and attached to the new one. The task estimated that this interruption would generally last only a few minutes when the steps were performed back to back.
SSL required additional attention. The existing certificate could continue serving while Pantheon provisioned the certificate for the new environment, but the task noted that provisioning might take up to an hour. Pantheon documentation described domain-ownership verification as a way to prepare the certificate in advance, but it was unclear whether pre-verification could be completed while the domain remained attached to the previous environment. That point needed confirmation from Pantheon support.
Resolution steps
- Inventory the current domain configuration. Record the active DNS values, the environment currently serving the domain, the new Pantheon environment, and any redirects or alternate hostnames.
- Lower DNS TTL in advance. Reduce the relevant record TTL before launch so updated DNS values propagate more quickly.
- Back up both environments. Create current database and file backups for the existing site and the new WordPress environment.
- Confirm domain ownership and SSL requirements. Ask Pantheon support whether the production domain can be pre-verified and whether the new certificate can be provisioned before detaching the domain from the existing environment.
- Prepare the database command. Build and review the exact WP-CLI search-replace command before launch. Use generic placeholders until the final values are confirmed:
wp search-replace 'https://temporary-environment.example' 'https://www.example.com' --skip-columns=guid --dry-run- Run a dry run first. Review the number of replacements and confirm that the command targets the correct database tables without changing data.
- Begin the domain cutover. Update the domain attachment and DNS records according to the Pantheon launch plan.
- Expect a possible brief 404 window. Perform the detach, attach, and DNS steps consecutively to keep any interruption as short as possible.
- Run the production search-replace. Once the final domain resolves to the new environment, run the command without
--dry-run:
wp search-replace 'https://temporary-environment.example' 'https://www.example.com' --skip-columns=guid- Flush caches. Clear Pantheon, WordPress, object, CDN, and browser caches after the database update.
- Verify HTTPS. Confirm that the certificate is valid for the production hostname and that HTTP requests redirect correctly to HTTPS.
- Test critical site paths. Review the homepage, navigation, forms, login flows, media files, downloads, redirects, and any third-party integrations.
- Check for mixed content and stale URLs. Search the page source, browser Console, and database for remaining references to the temporary environment.
- Preserve rollback options. Keep the old environment and DNS values documented until the new WordPress site has passed launch verification.
Using --skip-columns=guid avoids rewriting WordPress GUID values, which are identifiers rather than ordinary frontend URLs. A dry run is also essential because WordPress databases can contain serialized data and environment-specific references that should be reviewed before replacement.
Final outcome
The team established a clear launch sequence: perform the domain and DNS cutover first, then update the WordPress database to the final production domain. This approach allowed content references to resolve correctly as soon as the new environment began serving traffic.
The plan also accounted for a possible short 404 interval and continuous HTTPS coverage during certificate provisioning. One item remained for Pantheon support to confirm: whether ownership verification and certificate preparation could be completed on the new environment while the domain was still attached to the previous site.
The key lesson is that a Pantheon domain launch should be treated as a coordinated sequence rather than one database operation. DNS, domain attachment, SSL, search-replace, cache clearing, and launch verification each need their own preparation and rollback plan.
For help planning a Pantheon launch, changing a WordPress domain, or managing a production DNS cutover, contact Freshy.
