Skip to content

Commit

Permalink
docs: add info about postgres database checksums (#9391)
Browse files Browse the repository at this point in the history
* docs staging for next release

* linting

* newline

* remove old info
  • Loading branch information
mmomjian committed May 13, 2024
1 parent aa1dc68 commit e2a3132
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 4 deletions.
40 changes: 37 additions & 3 deletions docs/docs/FAQ.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -399,13 +399,47 @@ If it mentions SIGILL (note the lack of a K) or error code 132, it most likely m

If your version of Immich is below 1.92.0 and the crash occurs after logs about tracing or exporting a model, consider either upgrading or disabling the Tag Objects job.

### Why am I getting database errors?
## Database

### Why am I getting database ownership errors?

If you get database errors such as `FATAL: data directory "/var/lib/postgresql/data" has wrong ownership` upon database startup, this is likely due to an issue with your filesystem.
NTFS and ex/FAT/32 filesystems are not supported. See [here](/docs/install/environment-variables#supported-filesystems) for more details.

### Why does Immich log migration errors on startup?
### How can I verify the integrity of my database?

If you installed Immich using v1.104.0 or later, you likely have database checksums enabled by default. You can check this by running the following command.
A result of `on` means that checksums are enabled.

<details>
<summary>Check if checksums are enabled</summary>

```bash
docker exec -it immich_postgres psql --dbname=immich --username=<DB_USERNAME> --command="show data_checksums"
data_checksums
----------------
on
(1 row)
```

</details>

If checksums are enabled, you can check the status of the database with the following command. A normal result is all zeroes.

<details>
<summary>Check for database corruption</summary>

Sometimes Immich logs errors such as "duplicate key value violates unique constraint" or "column (...) of relation (...) already exists". Because of Immich's container structure, this error can be seen when both immich and immich-microservices start at the same time and attempt to migrate or create the database structure. Since the database migration is run sequentially and inside of transactions, this error message does not cause harm to your installation of Immich and can safely be ignored. If needed, you can manually restart Immich by running `docker restart immich immich-microservices`.
```bash
docker exec -it immich_postgres psql --dbname=immich --username=<DB_USERNAME> --command="SELECT datname, checksum_failures, checksum_last_failure FROM pg_stat_database WHERE datname IS NOT NULL"
datname | checksum_failures | checksum_last_failure
-----------+-------------------+-----------------------
postgres | 0 |
immich | 0 |
template1 | 0 |
template0 | 0 |
(4 rows)
```

</details>

[huggingface]: https://huggingface.co/immich-app
2 changes: 1 addition & 1 deletion docs/docs/administration/postgres-standalone.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ While not officially recommended, it is possible to run Immich using a pre-exist
By default, Immich expects superuser permission on the Postgres database and requires certain extensions to be installed. This guide outlines the steps required to prepare a pre-existing Postgres server to be used by Immich.

:::tip
Running with a pre-existing Postgres server can unlock powerful administrative features, including logical replication, data page checksums, and streaming write-ahead log backups using programs like pgBackRest or Barman.
Running with a pre-existing Postgres server can unlock powerful administrative features, including logical replication and streaming write-ahead log backups using programs like pgBackRest or Barman.
:::

## Prerequisites
Expand Down

0 comments on commit e2a3132

Please sign in to comment.