Skip to content

update & expand docs for "Direct Backups"#2052

Open
brontolosone wants to merge 2 commits intogetodk:masterfrom
brontolosone:1646_db-backup-guidance
Open

update & expand docs for "Direct Backups"#2052
brontolosone wants to merge 2 commits intogetodk:masterfrom
brontolosone:1646_db-backup-guidance

Conversation

@brontolosone
Copy link
Copy Markdown
Contributor

Towards issue getodk/central#1646
Documentation part of PR getodk/central-backend#1760

What is included in this PR?

Update & expansion of the "Backing Up Central" page of the docs.

What problems did you encounter?

I've put "advanced" content inside <details> elements so that they're not visible at first sight, lest they overwhelm, but I couldn't quite work out how to make the <summary> part a proper RST section :-/

@brontolosone
Copy link
Copy Markdown
Contributor Author

CI build flips out with:

sphinx.errors.ExtensionError: Could not import extension sphinx_toolbox.collapse (exception: cannot import name 'logger' from 'sphinx.ext.autodoc' (/home/circleci/.local/lib/python3.11/site-packages/sphinx/ext/autodoc/__init__.py))

But I'm using the ::collapse I've found elsewhere in the docs, so...

@lognaturel
Copy link
Copy Markdown
Member

The issue you're seeing is an autodoc incompatibility with sphinx 9. Rebasing on master should fix it.

@brontolosone brontolosone force-pushed the 1646_db-backup-guidance branch from 6dcb207 to a0dd136 Compare April 18, 2026 02:17
Comment thread docs/central-backup.rst
Restoring a backup
------------------

Restoring a Direct Backup file to a Central instance will entirely replace all of its data with the backup. Please be very sure you are restoring to the right place with the right backup snapshot before proceeding.
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This used to be only coincidentally (sometimes) true. Now it's actually true. Restoring to a Central instance will entirely replace all of its data. (Or not, if something goes wrong. But then it doesn't leave you halfway as it's transactional now. The previous restore wasn't transactional).

Furthermore previously we asked "to make sure you're restoring to the right place" but there was not any way to find out what a particular archive's destination DB was. You just had to run the restore and see if you had any new databases in Postgres (or see if some DB had been overwritten ⚡ ), so that was an impossible task.

@brontolosone brontolosone requested a review from sadiqkhoja April 27, 2026 23:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: ✏️ in progress

Development

Successfully merging this pull request may close these issues.

2 participants