Backup Archive Format

Filename#

Archives created by the module are named:

omeka-backup-YYYYMMDD-HHmmss-<token>.zip

<token> is 16 random hexadecimal characters, so two backups started in the same second get different names. Uploaded archives keep their original name (sanitised), with a timestamp and token appended only if that name is already taken. Archives added from the backup directory keep their name unchanged.

Layout#

omeka-backup-20260326-020000-3f9a1c7e5b2d8e04.zip
├── metadata.json        # manifest (always present)
├── db.sql               # database dump (include_db)
├── export/              # JSON-LD API export (include_api)
│   ├── items.json
│   ├── item_sets.json
│   ├── files.json
│   ├── vocabularies.json
│   ├── resource_templates.json
│   ├── properties.json
│   ├── resource_classes.json
│   └── sites.json
├── files/               # Omeka file store (include_files)
│   ├── original/
│   ├── large/
│   ├── medium/
│   ├── square/
│   └── ...
├── themes/              # OMEKA_PATH/themes (include_themes)
└── modules/             # OMEKA_PATH/modules (include_modules)

Directories are copied as-is, including hidden files and empty directories.

metadata.json#

{
    "backup_module_version": "1.4.0",
    "omeka_version": "4.2.0",
    "created_at": "2026-03-26T02:00:00+00:00",
    "includes": {
        "include_db": true,
        "include_files": true,
        "include_themes": true,
        "include_modules": true,
        "include_api": true
    }
}

metadata.json is what identifies a ZIP as a backup: uploads and archives added from the backup directory are rejected without it. omeka_version is the Omeka S version the archive was made on (Backup 1.4.0 and later); the restore preview shows it and warns when it is newer than the installation being restored. The includes block tells the restore page which components to offer. If it is missing (for example in an archive assembled by hand), the module looks for db.sql, files/, themes/, modules/ and export/ inside the archive instead.

db.sql#

The dump is plain SQL written by the module, not by mysqldump:

• A header comment with the host, database name and generation time.
• SET FOREIGN_KEY_CHECKS = 0; and SET SQL_MODE = 'NO_AUTO_VALUE_ON_ZERO';
• For every base table: DROP TABLE IF EXISTS, the CREATE TABLE statement from SHOW CREATE TABLE, then one INSERT INTO ... (columns) VALUES (...) statement per row with column names included.
• For every view: DROP VIEW IF EXISTS and the CREATE VIEW statement.
• SET FOREIGN_KEY_CHECKS = 1;

All tables in the database are included, not only Omeka's, so tables belonging to other modules and the module's own omeka_backup table are part of the dump. Rows are streamed one at a time, so memory use stays flat on large tables.

On restore the file is read line by line and each statement (ending in ; at the end of a line) is executed in order. The dump can also be loaded with the mysql client or any tool that accepts standard SQL.

export/#

Each file is a JSON array of the JSON-LD representations Omeka's API returns for that resource type, fetched 50 at a time. The export runs as the user who started the backup, so private resources are included when a global administrator creates the backup from the admin panel, and omitted from command-line runs.

files.json is always written but is empty in the current version, because Omeka's API names that resource media. Media records are still fully covered by db.sql.

The export is informational. It is never read back during a restore.

Checksums and records#

Each archive's SHA-256 digest is stored with its record as sha256:<hex>. It is verified before every restore. After unpacking, every file is also compared with the CRC-32 checksum the ZIP stores for it, and the restore stops before changing anything if one does not match. Adding an archive from the backup directory runs the same CRC-32 check before the record is marked complete. The record in the omeka_backup table holds: