feat: restore database backups #23978

insertish · 2025-11-18T17:30:35Z

Maintenance mode is now its own settings page with a section for restoring database backups.
Users can now manage their backups, incl. ability to restore and delete from the settings interface.
Users can now restore a database backup from onboarding / initial instance setup.
Basic integrity/heuristic checks for the library folders (displayed during onboarding "restore from backup").
Users can upload .sql or .sql.gz database dumps to restore.
Backup creation job now uses pg_dump instead of pg_dumpall.

How Has This Been Tested?

Updated maintenance e2e tests for API & web.
Update maintenance (& worker) service tests to cover new functionality.
Added new process repository tests to ensure duplex stream functions correctly.
Updated existing CLI & backup service tests where necessary to account for changes.

Demo

restore-demo.mp4

Screenshots

Screenshot 2025-11-25 at 11-16-33 Maintenance - Immich

... non-exhaustive

API Changes

GET /admin/maintenance/status returns the current action, task, progress, error (also sent over WS as MaintenanceStatusV1)
GET /admin/maintenance/integrity generates an integrity check and heuristics report
GET /admin/maintenance/backups/list provides a list of valid backup files present
GET /admin/maintenance/backups/:filename allows a user to download a backup file
DELETE /admin/maintenance/backups/:filename deletes the backup file
POST /admin/maintenance/backups/restore starts the database restore flow (onboarding only)
POST /admin/maintenance/backups/upload allows user to upload a backup file

Checklist:

I have performed a self-review of my own code
I have made corresponding changes to the documentation if applicable
I have no unrelated changes in the PR.
I have confirmed that any new dependencies are strictly necessary.
I have written tests for new code (if applicable)
I have followed naming conventions/patterns in the surrounding code
All code in src/services/ uses repositories implementations for database calls, filesystem operations, etc.
All code in src/repositories/ is pretty basic/simple and does not have any immich specific logic (that belongs in src/services/)

Please describe to which degree, if any, an LLM was used in creating this pull request.

Implementation of Duplex stream code is derived from documentation / example code generated by Claude.
It has since been refined and thoroughly tested.

Further Work (out of scope)

The translation keys shared_link_edit_expire_after_option_[...] and shared_link_expires_[...] are too specific to their actual contents.
Ellipsis usage in source translations is inconsistent, mix of ... and …

test: update backup.service.ts tests with new util

fix: missing action in cli.service.ts

refactor: cache the secret in memory

server/src/app.module.ts

server/src/controllers/maintenance.controller.ts

jrasm91 · 2025-12-02T15:00:04Z

server/src/controllers/maintenance.controller.ts

+    description: 'Put Immich into maintenance mode to restore a backup (Immich must not be configured)',
+    history: new HistoryBuilder().added('v9.9.9').alpha('v9.9.9'),
+  })
+  async startRestoreFlow(


We already have an endpoint for entering maintenance mode and I find it a bit weird that we now have another place where that happens. Can we just pass the file to the startMaintenance endpoint instead? Or, can you wait in the client for maintenance to start and then request a database restore after that?

Motivation here is to have a separate route without the authentication/permission checks in favour of checking if the first admin has been created (much like the logic for the first account registration: https://github.com/immich-app/immich/blob/main/server/src/services/auth.service.ts#L167)

server/src/maintenance/maintenance-ephemeral-state.repository.ts

jrasm91 · 2025-12-02T15:02:31Z

server/src/maintenance/maintenance-worker.controller.ts

+
+  @Get('admin/maintenance/backups/list')
+  @MaintenanceRoute()
+  listBackups(): Promise<MaintenanceListBackupsResponseDto> {
+    return this.service.listBackups();
+  }
+
+  @Get('admin/maintenance/backups/:filename')
+  @MaintenanceRoute()
+  downloadBackup(@Param() { filename }: FilenameParamDto, @Res() res: Response) {
+    res.header('Content-Disposition', 'attachment');
+    res.sendFile(this.service.getBackupPath(filename));
+  }
+
+  @Delete('admin/maintenance/backups/:filename')
+  @MaintenanceRoute()
+  async deleteBackup(@Param() { filename }: FilenameParamDto): Promise<void> {
+    return this.service.deleteBackup(filename);
+  }
+
+  @Post('admin/maintenance/backups/upload')
+  @MaintenanceRoute()
+  @UseInterceptors(FileInterceptor('file'))
+  uploadBackup(


let's just make a separate controller that works in both situations.

I separated backups into their own service which, since it's being used in the usual API worker, just inherits from BaseService so cannot be used in maintenance worker. It could not inherit from BaseService but that causes other issues like needing to fundamentally change some bits about tests & how these services are mocked. (and in general I think that would cause some headaches)

We've previously set convention to just reimplement routes we need in the maintenance worker controller:

immich/server/src/maintenance/maintenance-worker.controller.ts

Lines 42 to 45 in f9d2a97

@Get('server/config')

getServerConfig(): ServerConfigDto {

return this.service.getSystemConfig();

}

Which I think is fine to do here again? i.e.

immich/server/src/maintenance/maintenance-worker.controller.ts

Lines 78 to 82 in f9d2a97

@Get('admin/database-backups')

@MaintenanceRoute()

listBackups(): Promise<MaintenanceListBackupsResponseDto> {

return this.service.listBackups();

}

jrasm91 · 2025-12-02T15:03:19Z

server/src/maintenance/maintenance-worker.service.ts

+      }
+      case MaintenanceAction.RestoreDatabase: {
+        if (!action.restoreBackupFilename) {
+          return;


This should be an error and you should validate it in the dto imo.

This is intentional behaviour to either show the restore flow or start a restore depending on if the filename is provided.

refactor: `integrityCheck` -> `detectPriorInstall` chore: add `v2.4.0` version refactor: `/backups/list` -> `/backups` refactor: use sendFile in download route refactor: use separate backups permissions chore: correct descriptions refactor: permit handler that doesn't return promise for sendfile

refactor: add active flag to maintenance status

insertish added 7 commits November 18, 2025 16:51

feat: ProcessRepository#createSpawnDuplexStream

9cea3d7

test: write tests for ProcessRepository#createSpawnDuplexStream

a6fb942

feat: StorageRepository#createGzip,createGunzip,createPlainReadStream

cc78952

feat: backups util (args, create, restore, progress)

f67153e

feat: wait on maintenance operation lock on boot

0419539

chore: use backup util from backup.service.ts

0ae03f6

test: update backup.service.ts tests with new util

feat: list/delete backups (maintenance services)

7e7d6af

immich-push-o-matic bot added the 🗄️server label Nov 18, 2025

insertish added 🖥️web changelog:feature labels Nov 18, 2025

insertish added 20 commits November 18, 2025 17:35

chore: open api

b01b63b

fix: missing action in cli.service.ts

chore: add missing repositories to MaintenanceModule

edc1333

refactor: move logSecret into module init

73ae766

feat: initialise StorageCore in maintenance mode

d040de2

feat: authenticate websocket requests in maintenance mode

c090a1a

test: add mock for new storage fns

56c93a7

feat: add MaintenanceEphemeralStateRepository

7c2e8b1

refactor: cache the secret in memory

test: update service worker tests

af741a4

feat: add external maintenance mode status

442fe6e

feat: synchronised status, restore db action

26587dd

test: backup restore service tests

31410c3

refactor: DRY end maintenance

dd1cf12

feat: list and delete backup routes

53a74a7

feat: start action on boot

31f4665

fix: should set status on restore end

f778a42

refactor: add maintenanceStore to hold writables

f69c49a

feat: sync status to web app

56a4159

feat: web impl.

2e15012

test: various utils for testings

b887d4f

test: web e2e tests

9d4ad11

insertish added 3 commits November 28, 2025 12:04

merge: remote-tracking branch 'origin/main' into feat/database-restores

db7169e

merge: remote-tracking branch 'origin/main' into feat/database-restores

a7fd19d

chore: lint

8b1ba11

alextran1502 requested a review from jrasm91 December 1, 2025 15:20

jrasm91 reviewed Dec 2, 2025

View reviewed changes

insertish added 25 commits December 2, 2025 15:25

refactor: move maintenance worker init into service

b5ff460

refactor: move status impl into service

a79b4bd

refactor: add active flag to maintenance status

refactor: split into database backup controller

9b95550

test: split api e2e tests and passing

e0428b5

fix: move end button into authed default maint page

0945e18

fix: also show in restore flow

274775d

fix: import getMaintenanceStatus

ef944c2

test: split web e2e tests

f9d2a97

refactor: ensure detect install is consistently named

305bf60

chore: ensure admin for detect install while out of maint.

20d1e61

refactor: remove state repository

17dfced

test: update maint. worker service spec

4659ceb

test: split backup service spec

fe8eb85

refactor: rename db backup routes

a63b418

refactor: instead of param, allow bulk backup deletion

207a8bc

test: update sdk use in e2e test

4296211

test: correct deleteBackup call

3019091

fix: correct type for serverinstall response dto

cf3686a

chore: validate filename for deletion

02265ba

test: wip

6b9cc85

test: backups no longer take path param

adc2d5d

refactor: scope util to database-backups instead of backups

4e2187a

fix: update worker controller with new route

0d05c0d

merge: remote-tracking branch 'immich/main' into feat/database-restores

e958516

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: restore database backups #23978

feat: restore database backups #23978

insertish commented Nov 18, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jrasm91 Dec 2, 2025

Uh oh!

insertish Dec 2, 2025

Uh oh!

Uh oh!

jrasm91 Dec 2, 2025

Uh oh!

insertish Dec 3, 2025

Uh oh!

jrasm91 Dec 2, 2025

Uh oh!

insertish Dec 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	@Get('server/config')
	getServerConfig(): ServerConfigDto {
	return this.service.getSystemConfig();
	}

	@Get('admin/database-backups')
	@MaintenanceRoute()
	listBackups(): Promise<MaintenanceListBackupsResponseDto> {
	return this.service.listBackups();
	}

Uh oh!

feat: restore database backups #23978

Are you sure you want to change the base?

feat: restore database backups #23978

Conversation

insertish commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How Has This Been Tested?

Demo

Screenshots

API Changes

Checklist:

Please describe to which degree, if any, an LLM was used in creating this pull request.

Further Work (out of scope)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jrasm91 Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

insertish Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrasm91 Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

insertish Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

jrasm91 Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

insertish Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

insertish commented Nov 18, 2025 •

edited

Loading