Reference

Scope

As of version 9.96.0 (9.96.2 really, as previous versions are seriously flawed), the Confluence module can import Confluence Cloud CSV backups. This document presents their format. It is targeted at:

• technical people working on Confluence migration tools or tools involving Confluence exports
• technical people running migrations who need to deeply investigate some issues
• people curious about the Confluence export format

Introduction

In 2026, Atlassian has been phasing out Confluence XML backups on Confluence Cloud. CSV backups replace them.

Like a Confluence XML package, a Confluence CSV package is a zip file. It contains, among other things, an attachments folder and a CSV file per database table (with a csv.gz extension - mind you, that doesn't always mean they are actually gzipped, see below). While the Confluence XML backup is a hibernate dump, where what's exported is serialized java objects (more or less), CSV files are more directly what's stored in the RDBMS (so for instance if you have ever looked at a PostgresSQL instance containing Confluence server stuff, these CSV file will look quite familiar). Also contrary to Confluence XML backups, there doesn't seem to be an exportDescriptor.properties file: of course, we know where a CSV export comes from: Atlassian's Confluence Cloud.

Like for Confluence XML exports, there are two types of CSV bakups we know about:

• A space backup package, produced from the settings of a space in Confluence.
• A site backup package, produced from the global administration in Confluence. It contains all the  spaces, as well as users and groups, but it doesn't necessarily contain the attachments folder.

At the time of writing, there are a few major differences between the site export and the space export, effectively making them slightly different formats.

1. About the CSV tables:
   • In space backups, the CSV files are at the root of the ZIP archive, and despite their .csv.gz extension, are not actually gzipped, they are stored plain text! (so, on many operating systems, double clicking on them will fail, because your OS will try to gunzip it and of course it can't work.
   • In site backups, they are indeed gzipped, and they are in a data folder. WarningWhat's more, the body field in the bodycontent.csv.gz file is compressed with zstd and then base64-encoded.
2. About the attachment folder:
   • In space backups, the attachments folder is structured like in Confluence XML backups: an attachment is found at attachments/<stable page id>/<stable attachment id>/<version number>
   • In site backups, an attachment is found at attachments/<uuid> where uuid is given by the FILESTORE_ID property (provided in contentproperties.csv.gz) of the attachment revision record (defined in content.csv.gz) 
3. About the whiteboards folder: only found in site exports. We haven't looked into the whiteboards yet.
4. About the metadata.json file: only found in site exports. It's the somewhat spiritual replacement of the exportDescriptor.properties file found in XML backups. It provides a list of the .csv.gz files in the archive with their sizes in bytes, and some stuff like the backup id, account id, the cloud instance id, things probably mostly relevant to Atlassian's setup. Notably absent from this file would be a backup date. We don't currently use this file.

Description of the CSV tables

Effectively Working with CSV backups

Unfortunately, we don't have much experience in this yet. Compared to Confluence XML, there's no huge file with everything inside it unordered that can be quite challenging to work with. However, you need to deal with gzipped (or not!) CSV files, and with the body field in the bodycontent table that can base64 encoded zstd compressed stuff.

Here are some tips anyway.

Unzip the relevant files

For instance, get the bodycontent table:

From a space export (note how we drop the annoying and wrong .gz file):

unzip -l csv-export.zip bodycontent.csv.gz > bodycontent.csv

From a site export, add a call to gunzip:

unzip -l csv-export.zip bodycontent.csv.gz | gunzip > bodycontent-with-body-still-encoded.csv

To get the body column of a site export, ignore the first line (CSV header), then take the second field, base-64 decode and then decompress the resulting zstd content:

tail -n +2 bodycontent-with-body-still-encoded.csv | cut -d, -f2 | base64 -d | zstd -d > bodies.txt

Decode a unique body value:

echo "KLUv/SAMYQAAPHA+aGVsbG88L3A+" | base64 -d | zstd -d                                                                                                  <p>hello</p>

Re-encode a body value:

echo '<p>hello</p>' | zstd | base64                                                                                                                        KLUv/QRYaQAAPHA+aGVsbG88L3A+CkTGPNg=

Use SQLite to work with the CSV tables

SQLite can import and export CSV files.

Let's run sqlite3 in a folder where we have extracted a CSV backup:

$ sqlite3
SQLite version 3.53.2 2026-06-03 19:12:13
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.

We can import one or several CSV files, and they are immediately queriable, together:

sqlite> .import content.csv content
sqlite> .import bodycontent.csv bodycontent

For instance, let's imagine we have filtered contents using some criterion with something like this:

sqlite> delete from content where ...;

We only want to keep the body contents of the remaining content records:

sqlite> delete from bodycontent where contentid not in (select contentid from content);

Now, let's update bodycontent.csv. We set the output mode of SQLite to csv, and disable a limit that would silently truncate long fields, which can happen with body contents. We want headers, and we want to output to bodycontent.csv. We select everything, which will output in the CSV file. And then, we revert to stdout tabs output.

sqlite> .mode csv --charlimit 0
sqlite> .headers on
sqlite> .output bodycontent.csv
sqlite> select * from bodycontent;
sqlite> .output stdout
sqlite> .mode tabs