Backup discourse from the command line

Documentation Self-Hosting
,
43

With the help of some AI, here is a comprehensive list of subcommands for the discourse command.
The discourse CLI (implemented via script/discourse using the Thor gem) provides 13 core subcommands categorized into Backups & Restores, Site Management & Modes, Database Utilities, and Data Migration (Import/Export).

Command Quick Reference

Category Subcommand Primary Function
Backup & Restore backup Generates a full or database-only backup archive.
restore Restores a .tar.gz backup file into the instance.
enable_restore Grants permission to execute restore commands.
disable_restore Revokes permission to perform restores.
rollback Reverts database state after a failed restore.
Site Modes enable_readonly Toggles temporary read-only mode across the site.
disable_readonly Removes read-only mode to restore normal site writes.
request_refresh Triggers a browser refresh prompt to all active connected clients.
Database Ops remap Performs global text search-and-replace across database tables.
Data Migration export_category Exports a single category, its topics, and associated users.
import_category Imports a category archive into the current forum.
export_topics Exports specific topics by ID and their author/replier accounts.
import_topics Imports a topic archive into the current forum.

Detailed Subcommand Documentation

1. Backup & Restore Commands

discourse backup [FILENAME]

  • Description: Creates a complete backup of the forum database and assets.

  • Flags:

  • --sql-only: (Boolean, Default: false) Dumps only the PostgreSQL database, skipping local uploaded files.

  • --s3-uploads: (Boolean, Default: false) Forces inclusion of S3-stored assets into the backup archive (ignored when --sql-only is set).

  • Example:

discourse backup
discourse backup --sql-only

discourse restore [FILENAME]

  • Description: Restores a forum backup from a local .tar.gz archive located in /var/www/discourse/public/backups/default.
  • Prerequisite: Requires running discourse enable_restore first.
  • Example:
discourse restore discourse-2026-07-22-120000-v2026xxxx.tar.gz

discourse enable_restore & discourse disable_restore

  • Description: Toggles the application flag that allows or restricts console/web-based restore tasks.
  • Usage Sequence:
discourse enable_restore
discourse restore <filename>
discourse disable_restore

discourse rollback

  • Description: Rolls back the database schema and state to the point prior to a failed restore execution.

2. Site State & Client Controls

discourse enable_readonly & discourse disable_readonly

  • Description: Sets or clears the READONLY_MODE_KEY in Redis.
  • Details:
  • Freezes database writes while keeping the site readable for users.
  • Uses a short time-to-live (TTL) loop refreshed while active, preventing the site from remaining locked permanently if a terminal session crashes.

discourse request_refresh

  • Description: Dispatches a system message via MessageBus instructing all online web sessions to reload the web page. Useful after deploying asset updates or global theme changes.

3. Database Remapping

discourse remap [OPTIONS] FROM TO

  • Description: Performs a direct string search-and-replace across text columns in the database. Crucial when updating domain names, CDN paths, or image upload prefixes.

  • Flags:

  • --global: (Boolean) Scans and remaps across all tables rather than standard content tables.

  • --regex: (Boolean) Evaluates the FROM parameter as a regular expression rather than a literal string.

  • Example:

discourse remap "old-domain.com" "new-domain.com"
discourse remap --global "/uploads/default/" "/cdn-uploads/"

4. Selective Data Import & Export

discourse export_category [CATEGORY_ID]

  • Description: Serializes a single category, including all nested topics, posts, and participating user profiles, into a JSON archive file.

discourse import_category [FILE_PATH]

  • Description: Reads an archive created by export_category and merges the category data into the target instance.

discourse export_topics [TOPIC_IDS...]

  • Description: Takes one or more space-separated topic IDs and exports the topics, posts, and relevant user accounts.
  • Example:
discourse export_topics 102 105 210

discourse import_topics [FILE_PATH]

  • Description: Imports a JSON archive created by export_topics into the destination Discourse instance.
1 Like