How to replace all hard-coded links in Confluence after the Base URL or AppLink URL is changed

Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Summary

When changing the Base URL or an application link URL, either due to a URL change or from an export/import (e.g. Cloud to Server or Server to Server), links created as absolute links to the old URL (for example, using Insert > Link > Web Link) need to be manually changed.

Example Server to Server

Old Base URL	http://mycompany.com/confluence
New Base URL	http://confluence.mycompany.com/

Example Cloud to Server (this requires extra steps)

Old Base URL	http://mycompany.atlassian.net/wiki
New Base URL	http://confluence.mycompany.com/

Example Jira to Confluence

Old Jira URL	http://mycompany.com/jira
New Jira URL	http://mycompanynewurl.com/jira

ℹ️ this KB may be used in other types of URL changes, ⚠️ make sure you test this before on a test instance if using this procedure on cases not described here.

Please note that Cloud to Server Base URL change requires extra steps due to these known issues

What about relative links?

If a link was created as a relative link (for example, by using Edit > Insert > Link, then from "Recently Viewed" or "Search"), it will change when the base URL changes.

This document has more details: Working with Links.

Environment

Confluence Server or Data Center

Solution

Always back up your data before making any database modifications. If possible, test any alter, insert, update, or delete SQL commands on a staging server first.

Option 1: Export/Import Option using Find and Replace

This option outlines how to export your Confluence data and perform a find/replace leveraging the sed script notated below to update the link values.

1. Choose an export method and generate the export file

Option A: Generate a site XML export file

⚠️ The XML backup method can be a resource-intensive operation that can cause performance issues depending on the size of your instance. If your Confluence instance is very large, we would recommend running this operation over a maintenance window in an abundance of caution.

Full site export

Go to Administration > General Configuration > Backup & Restore
Check Back up attachments
Click Back Up
Find the XML export file (usually) in <confluence-home>/temp
Extract the entities.xml file from the XML export file
Shut down Confluence

Option B: Generate a database export file

Use a native database tool to export all the data. This requires Confluence to be shut down.

For MySQL use mysqldump
For PostgreSQL use pg_dump

2. Run the sed script against your export file to find and replace the old URL value with the new value

Run the following sed script on the export file you generated.

sed Basic Syntax Example

sed -r -e 's/oldvalue/newvalue/g' <export-file-name>

A PowerShell equivalent would be like this:

Powershell basic syntax example

Get-Content ./<export-file-name> | foreach{$_ -replace 'oldvalue','newvalue'}

As an example, the following script would be running for an instance where the old URL is http://mycompany.com/confluence and the new URL is http://confluence.mycompany.com. Note that the script contains escapes for the forward-slash characters contained in the URL. This example references an example site export file entities.xml.If you are running this against a database export, you would replace this file with your resulting export.sql file.

The examples below also place the output in a new entities_new.xml file. Be sure to use the entities.xml file name after all changes are done for the import to be successful.

Example Script with URL Values

sed -r -e 's/mycompany.com\/confluence/confluence.mycompany.com/g' entities.xml > entities_new.xml

Example Powershell script with URL values

Get-Content ./entities.xml | foreach{$_ -replace 'mycompany.com/confluence','confluence.mycompany.com'} | Out-File -path entities_new.xml

For Cloud exports only

Cloud exports will use the entities.xml file for the backup zip

For CONFSERVER-54759 - Absolute Cloud URLs are not usable in Server when migrating with simple domain name replacement
Replace all content URLs to Confluence Server format with this command (using the example URLs above)
sed example
1sed -r -e 's/mycompany\.atlassian\.net\/wiki\/spaces\/[A-Z0-9]+\/pages\/([0-9]+)\/[A-Za-z0-9+.]+/confluence.mycompany.com\/pages\/viewpage.action?pageId=\1/g' entities.xml > entities_new.xml
Powershell example
1Get-Content ./entities.xml | foreach{$_ -replace 'mycompany.atlassian.net/wiki/spaces/[A-Z0-9]+/pages/([0-9]+)/[A-Za-z0-9+.]+','confluence.mycompany.com/pages/viewpage.action?pageId=$1'} | Out-File -path entities_new.xml
ℹ️ In this example, the Powershell command will only work when using the single quotes ('), as double-quotes (") would break the ID replacement ($1).
For CONFSERVER-45919 - Server Base URL becomes N/A after restoring from a Cloud backup. (fixed in 6.8.2 and later)
Replace incorrect Base URL entry from N/A
sed example
1sed -r -e 's/<server\.base\.url>N\/A</server\.base\.url>/<server.base.url>http://confluence.mycompany.com</server.base.url>/g' entities.xml > entities_new.xml
Powershell example
1Get-Content ./entities.xml | foreach{$_ -replace '<server.base.url>N/A</server.base.url>','<server.base.url>http://confluence.mycompany.com</server.base.url>'} | Out-File -path entities_new.xml

3. Reimport the updated export file

Option A: Site XML Import

Using this option will require extra steps to re-load all the Add-ons from http://marketplace.atlassian.com/

Re-zip up the XML export file, taking care to place the files in the same location as the original export.
Go to Administration > General Configuration > Backup & Restore
Click Choose file and select the new XML backup zip file
Click Upload and Restore

Option B: Database import

Use the database tools to re-import the data.

Option 2: WebDAV option

Use the WebDAV plugin and mount the WebDAV location locally, then run a script that uses sed to replace all of the Old Base URLs. This option creates a new page version for all pages that are changed (this includes any page versions that are crawled and edited).

Option 3: Confluence Source Editor option

You can use the Confluence Source Editor app to modify content on a page-by-page basis.

Install the Confluence Source Editor app.
Open the editor on an affected page.
Click the <> button on the top right of the editor.
Replace any occurrences of the old base URL with the new base URL.
Save the page.

This technique has the benefit of being less risky than doing direct data manipulation and it's easier than manually linking the attachment through the editor interface.

Option 4: Database query

Confluence stores page content in plain text, on the 'BODYCONTENT' table. It's also possible to replace these links by replacing text on this table, with the following queries:

Starting from Confluence 7 (skip this step for older versions) we will need to set the flag on drafts to use content from pages when generating drafts instead of using Synchrony cache.

update CONTENTPROPERTIES set stringval='synchrony-recovery' where propertyname = 'sync-rev-source' and contentid in (select contentid from BODYCONTENT WHERE body LIKE '%old-URL%');

Replacing the links for all page versions (Compatible with PostgreSQL, Oracle, MySQL)

UPDATE BODYCONTENT 
SET body = replace(body,'old-URL','new-URL') 
WHERE body LIKE '%old-URL%';

# Assuming that the HTTP protocol remains the same, specify the URL without a reference to the protocol. For example:
UPDATE LINKS 
SET destpagetitle = replace(destpagetitle,'//the.old-URL.com','//my.new-URL.com') 
WHERE destpagetitle LIKE '%//the.old-URL.com%';
UPDATE LINKS 
SET lowerdestpagetitle = replace(lowerdestpagetitle,'//the.old-url.com','//my.new-url.com') 
WHERE lowerdestpagetitle LIKE '%//the.old-url.com%';

# Make sure to set the URL in the last SQL query to lowercase

Replacing the links for all page versions (Compatible with SQL Server 2017 - Microsoft Docs - ntext, text, and image (Transact-SQL))

1
2
3

UPDATE BODYCONTENT
   SET BODY = REPLACE (CONVERT(VARCHAR(MAX), BODY), 'old-URL','new-URL')
 WHERE BODY LIKE '%old-URL%';

Extra: Replacing the links for the latest versions of pages from active spaces (Compatible with PostgreSQL)

UPDATE BODYCONTENT
SET BODY = REPLACE (BODY,'old-URL','new-URL')
WHERE BODYCONTENTID IN (SELECT bc.BODYCONTENTID
                        FROM BODYCONTENT bc
                        INNER JOIN CONTENT c ON c.CONTENTID = bc.CONTENTID
                        INNER JOIN SPACES s ON s.SPACEID = c.SPACEID
                        WHERE bc.BODY LIKE '%old-URL%'
                          AND c.PREVVER is NULL
                          AND c.CONTENTTYPE ='PAGE'
                          AND c.CONTENT_STATUS = 'current'
                          AND s.SPACESTATUS = 'CURRENT');

This will replace all instances of 'old-URL' on pages, with the text from 'new-URL', automatically replacing the links on Confluence pages.

ℹ️ Restart Confluence or flush the cache in General Configuration → Cache Management to have these changes be reflected in the UI.

⚠️ Try this on a test Confluence instance beforehand, and backup the Confluence database first

Updated on April 16, 2025

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Atlassian Support

How to replace all hard-coded links in Confluence after the Base URL or AppLink URL is changed

Summary

Environment

Solution

Still need help?