Ir para o conteúdo principal

Postgres Pré-existente

Embora não seja oficialmente recomendado, é possível executar o Immich usando um servidor Postgres pré-existente. Para usar esta configuração, você deve ter um nível básico de familiaridade com Postgres e a linha de comando do Linux. Se você não possuir esses conhecimentos, recomendamos usar a configuração padrão com um contêiner Postgres dedicado.

Por padrão, o Immich espera permissões de superusuário no banco de dados Postgres e requer que certas extensões sejam instaladas. Este guia descreve os passos necessários para preparar um servidor Postgres pré-existente para ser usado pelo Immich.

dica

Executar com um servidor Postgres pré-existente pode desbloquear recursos administrativos poderosos, incluindo replicação lógica e backups em log de reescrita streaming usando programas como pgBackRest ou Barman.

Pré-requisitos​

Você deve instalar pgvector (>= 0.7.0, < 1.0.0), pois é um pré-requisito para o vchord. A maneira mais fácil de fazer isso no Debian/Ubuntu é adicionando o repositório Apt do PostgreSQL e então executando apt install postgresql-NN-pgvector, onde NN é sua versão do Postgres (por exemplo, 16).

Você deve instalar o VectorChord na sua instância do Postgres usando as instruções deles. Após a instalação, adicione shared_preload_libraries = 'vchord.so' ao seu postgresql.conf. Se você já tiver algumas shared_preload_libraries configuradas, pode separar cada extensão com uma vírgula. Por exemplo, shared_preload_libraries = 'pg_stat_statements, vchord.so'.

nota

O Immich é conhecido por funcionar com versões do Postgres >= 14, < 18.

Certifique-se de que a versão instalada do VectorChord é compatível com sua versão do Immich. O intervalo atual aceito para o VectorChord é >= 0.3.0, < 0.5.0.

Especificando a URL de conexão​

Você pode se conectar ao seu servidor Postgres pré-existente configurando a variável de ambiente DB_URL no arquivo .env.

DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename'

# requer uma conexão SSL com o Postgres
# DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename?sslmode=require'

# requer uma conexão SSL, mas não força a verificação do nome do certificado
# DB_URL='postgresql://immichdbusername:immichdbpassword@postgreshost:postgresport/immichdatabasename?sslmode=require&sslmode=no-verify'

Com permissão de superusuário​

Normalmente, o Immich espera permissões de superusuário no banco de dados, que você pode conceder executando ALTER USER <immichdbusername> WITH SUPERUSER; no console psql. Se preferir não conceder permissões de superusuário, siga as instruções na próxima seção.

Sem permissão de superusuário​

Este método é recomendado apenas para usuários avançados e frequentemente requer intervenção manual ao atualizar o Immich.

Atualmente, os backups automatizados exigem permissão de superusuário devido ao uso de pg_dumpall.

O Immich pode ser executado sem permissões de superusuário seguindo as instruções abaixo no prompt do psql para preparar o banco de dados.

Configurar Postgres para o Immich
CREATE DATABASE <immichdatabasename>;
\c <immichdatabasename>
BEGIN;
ALTER DATABASE <immichdatabasename> OWNER TO <immichdbusername>;
CREATE EXTENSION vchord CASCADE;
CREATE EXTENSION earthdistance CASCADE;
COMMIT;

Atualizando VectorChord​

Ao instalar uma nova versão do VectorChord, você precisará atualizar manualmente a extensão e recriar os índices conectando-se ao banco de dados Immich e executando:

ALTER EXTENSION vchord UPDATE;
REINDEX INDEX face_index;
REINDEX INDEX clip_index;

Migrando para VectorChord​

O VectorChord é a extensão sucessora do pgvecto.rs, permitindo maior desempenho, menor uso de memória e resultados de maior qualidade para pesquisa inteligente e reconhecimento facial.

Migrando de pgvecto.rs​

O suporte ao pgvecto.rs será descontinuado em uma versão futura. Por isso, recomendamos que todos os usuários que atualmente usam o pgvecto.rs migrem para o VectorChord quando for conveniente. Existem duas abordagens principais para isso.

A opção mais fácil é ter ambas as extensões instaladas durante a migração:

Passos para migração (automática)
  1. Certifique-se de ainda ter o pgvecto.rs instalado
  2. Instale pgvector (>= 0.7.0, < 1.0.0). A maneira mais fácil de fazer isso no Debian/Ubuntu é adicionando o repositório Apt do PostgreSQL e então executando apt install postgresql-NN-pgvector, onde NN é sua versão do Postgres (por exemplo, 16)
  3. Instale o VectorChord
  4. Adicione shared_preload_libraries= 'vchord.so, vectors.so' ao seu postgresql.conf, certificando-se de incluir ambos vchord.so e vectors.so. Você também pode incluir outras bibliotecas aqui, se necessário
  5. Reinicie o banco de dados Postgres
  6. Se o Immich não tiver permissões de superusuário, execute o comando SQL CREATE EXTENSION vchord CASCADE; usando o psql ou o cliente de banco de dados de sua escolha
  7. Inicie o Immich e aguarde os logs Reindexed face_index e Reindexed clip_index serem exibidos
  8. Se o Immich não tiver permissões de superusuário, execute o comando SQL DROP EXTENSION vectors;
  9. Elimine o esquema antigo executando DROP SCHEMA vectors;
  10. Remova a entrada vectors.so da configuração shared_preload_libraries
  11. Reinicie o banco de dados Postgres
  12. Desinstale o pgvecto.rs (por exemplo, apt-get purge vectors-pg14 em ambientes baseados em Debian, substituindo pg14 conforme necessário). O pgvector deve permanecer instalado, pois fornece os tipos de dados usados pelo vchord

Se não for possível ter o VectorChord e o pgvecto.rs instalados ao mesmo tempo, você pode realizar a migração com mais etapas manuais:

Passos para migração (manual)
  1. Enquanto o pgvecto.rs ainda estiver instalado, execute o seguinte comando SQL usando o psql ou o cliente de banco de dados de sua escolha. Anote o número fornecido por este comando, pois você precisará dele mais tarde
SELECT atttypmod as dimsize
    FROM pg_attribute f
    JOIN pg_class c ON c.oid = f.attrelid
    WHERE c.relkind = 'r'::char
    AND f.attnum > 0
    AND c.relname = 'smart_search'::text
    AND f.attname = 'embedding'::text;
  1. Remova as referências ao pgvecto.rs usando os comandos SQL abaixo
DROP INDEX IF EXISTS clip_index;
DROP INDEX IF EXISTS face_index;
ALTER TABLE smart_search ALTER COLUMN embedding SET DATA TYPE real[];
ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE real[];
  1. Instale o VectorChord
  2. Mude as colunas de volta para os tipos de vetor apropriados, substituindo <number> pelo número da etapa 1
CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
ALTER TABLE smart_search ALTER COLUMN embedding SET DATA TYPE vector(<number>);
ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE vector(512);
  1. Inicie o Immich e deixe-o criar novos índices usando o VectorChord

Migrando de pgvector​

Passos para migração
  1. Certifique-se de ter pelo menos a versão 0.7.0 do pgvector instalada. Se for uma versão inferior, atualize e execute o comando SQL ALTER EXTENSION vector UPDATE; usando o psql ou o cliente de banco de dados de sua escolha
  2. Siga os Pré-requisitos para instalar o VectorChord
  3. Se o Immich não tiver permissões de superusuário, execute o comando SQL CREATE EXTENSION vchord CASCADE;
  4. Remova a variável ambiental DB_VECTOR_EXTENSION=pgvector, pois ela fará com que o Immich continue usando o pgvector se configurada
  5. Inicie o Immich e deixe-o criar novos índices usando o VectorChord

Observe que o próprio VectorChord usa tipos do pgvector, então você não deve desinstalar o pgvector após seguir essas etapas.