Guia do administrador do cluster de replicação HQbird: hqclusternode e hqbirdrcm (RCM). Instaladores: Download do HQbird 2027.

Conteúdo


0. Introdução

Este guia descreve como instalar e usar o cluster de replicação HQbird: os nós hqclusternode e o gerenciador de cluster hqbirdrcm (RCM).

Este é um guia para o administrador do Firebird. Partimos do princípio de que você conhece o Firebird, o gfix e o nbackup. Você não precisa conhecer o funcionamento interno de um nó.

Do que o cluster é feito

Componente Quantos Onde executa O que faz
Firebird (HQbird) uma ou mais instâncias em cada servidor de bancos armazena os bancos, grava os segmentos de replicação
fbagent um por instância do Firebird ao lado do Firebird para e inicia o Firebird a pedido de um nó
hqclusternode (nó) um por instância e papel ao lado do Firebird configura a replicação, transfere segmentos, faz a inicialização da réplica
hqbirdrcm (RCM) um por cluster em qualquer host que enxergue todos os nós interface web, comandos, alertas, estatísticas

Um nó tem um papel: master ou replica. Dois nós podem executar em uma única instância do Firebird: um nó mestre e um nó réplica. Nesse caso, alguns bancos desse Firebird são mestres e outros são réplicas.

Como funciona

  1. No mestre, o Firebird grava as alterações do banco em segmentos (arquivos de log de replicação).
  2. O nó mestre envia os segmentos ao nó réplica por um canal protegido (mTLS).
  3. O nó réplica coloca os segmentos na pasta de segmentos de entrada. O Firebird da réplica os aplica à sua cópia do banco.
  4. O próprio nó mestre transfere a primeira cópia do banco para a réplica. Isso se chama inicialização (reinit). Ela passa pelo nbackup, e o mestre continua em execução durante esse tempo.
  5. Os nós enviam estatísticas ao RCM. O RCM mostra o estado do cluster e envia comandos do operador aos nós.
Como o cluster funciona: segmentos, inicialização, estatísticas e comandos do operador
Como o cluster funciona: segmentos, inicialização, estatísticas e comandos do operador

Versões compatíveis

  • Firebird / HQbird 5.0 e 4.0 — todos os recursos.
  • HQbird 3.0 e 2.5 — replicação pelo plugin replconf. Não há publicações; o conjunto de tabelas é definido por filtros. As diferenças estão descritas nas caixas “HQbird 2.5/3.0”.

A versão principal do Firebird no mestre e na réplica precisa ser a mesma. Caso contrário, o nó réplica recusa a inicialização.

Portas

Porta Quem escuta Quem se conecta Para quê
7051 nó outros nós e o RCM API do nó, transferência de segmentos e de cópias de bancos
7443 RCM todos os nós recepção de estatísticas dos nós
7444 RCM operador interface web e API do operador. Instalação pelo RCM (capítulo 1.3): HTTPS em todos os endereços. Instalação pelo HQCenter Admin ou manual: HTTP, somente 127.0.0.1
7450–7459 fbagent, enquanto a janela de vinculação está aberta RCM vinculação de hosts (capítulo 1.3)
13050 fbagent, somente 127.0.0.1 nó no mesmo host gestão do Firebird
3050 Firebird aplicações operação normal do banco

Se houver dois nós em um host (mestre e réplica), o segundo nó tem outra porta. Na instalação pelo RCM, o segundo nó recebe a porta 7061. Nos outros casos você define a porta, por exemplo 7052.

A porta 13050 não deve ficar exposta na rede. A porta 7444 com HTTP (instalação pelo HQCenter Admin ou manual) também não: conecte-se à interface web do RCM por um túnel SSH (capítulo 1). Na instalação pelo RCM, a porta 7444 funciona em HTTPS, e o instalador a abre no firewall.

A regra principal: sem fbagent, sem alterações

Um nó altera a configuração de replicação somente pelo fbagent: ele precisa reiniciar o Firebird. Se o fbagent não estiver disponível, o nó recusa qualquer ação que altere a configuração. Ele não trabalha “pela metade”.

Termos

Termo Significado
Segmento um arquivo de log de replicação com as alterações do banco
Publicação a lista de tabelas do mestre cujas alterações entram nos segmentos (Firebird 4/5)
Inicialização (reinit) transferência de uma cópia do banco do mestre para a réplica pelo nbackup
GUID do banco o identificador do banco no Firebird; o RCM o usa para ligar o mestre e a réplica
Par nó parceiro: para um mestre, as suas réplicas
Companheiro o segundo nó na mesma instância do Firebird (mestre e réplica em um host)
Registro cadastramento dos bancos mestres no nó

Como ler o guia

Capítulo Tema
1. Instalação instalação dos nós e do RCM pelo HQCenter Admin, pelo RCM sem o HQCenter Admin e manualmente, Linux e Windows
2. Configuração do cluster vínculos mestre → réplica, configurações dos nós, usuários do RCM
3. Inclusão de um banco no mestre Registro, reinício do Firebird, verificação
4. Como tornar um banco uma réplica etapas, preparação da réplica, espaço em disco
5. Inicialização passos do reinit, impacto na operação, transações longas, velocidade, erros
6. Configuração da publicação publicação do Firebird 4/5, tabelas, tabelas novas, HQbird 2.5/3.0
7. Outras opções de replicação parâmetros do replication.conf, arquivo, transferência, alertas, pausa, logs
8. Conversão de uma réplica em um banco comum Tornar comum, Promover a mestre, novo GUID, serviços (comutação, failover), lista de verificação da comutação

Todos os capítulos usam um exemplo:

O quê Valor
node-a nó mestre, bancos em /databases/master
node-b nó réplica, bancos em /databases/replica
RCM um host separado (também pode ser um dos servidores de bancos)
banco employee.fdb

1. Instalação dos nós e do hqbirdrcm

Há três métodos de instalação:

Método Quando escolhê-lo O que você faz
Pelo HQCenter Admin (1.2) o caminho habitual: o servidor de atualização do HQCenter Admin está acessível, atualizações automáticas são necessárias você executa o script de instalação do fbagent, aprova o pedido, descreve o cluster
Pelo RCM, sem o HQCenter Admin (1.3) não há HQCenter Admin, mas você precisa de certificados, configuração e atualizações sem trabalho manual; até 3 servidores de bancos você instala o HQbird em cada host, entra no RCM e, em Configurações → Vincular hosts, informa os endereços dos hosts
Manualmente (1.4) sem acesso ao HQCenter Admin, rede fechada, requisitos especiais você instala os arquivos, cria os certificados, escreve node.json e rcm.json, registra os serviços

Pelo HQCenter Admin e pelo RCM você não instala os nós e o RCM. Eles são instalados pelo fbagent quando você o adiciona ao cluster (capítulo 2). Os certificados e a configuração também são criados automaticamente.

Linux e Windows estão descritos em um único capítulo. As diferenças do Windows estão nas caixas “No Windows”.

1.1. Requisitos

Em cada servidor de bancos:

  • Firebird / HQbird 5.0, 4.0, 3.0 ou 2.5 (2.5 — somente Linux).
  • fbagent ao lado de cada instância do Firebird. Sem o fbagent o nó não funciona.
  • Sincronização de hora (NTP, chrony, w32time) em todos os servidores e no host do RCM. Janelas de reinício e de transferência, a estimativa de atraso e a verificação “nó não responde” dependem dos relógios.
  • Espaço livre para o arquivo de segmentos e para a inicialização da réplica (capítulo 4).
  • Rede conforme a tabela de portas (capítulo 0).

Linux: privilégios de root, x86_64, systemd, curl. Compatíveis: Ubuntu 20–26, Debian 11–13, Astra, CentOS 7–10, AlmaLinux, Rocky, Oracle Linux 8–10, RED OS, openSUSE 15.6, Fedora 44+.

Windows: privilégios de administrador, x64, Windows 10 / Server 2016 ou mais novo, Windows PowerShell de 64 bits 5.1. No Windows 10 e no Server 2016–2022, o 7-Zip é necessário.

Onde o RCM vai executar. É necessário um RCM por cluster. Ele pode ser instalado em qualquer servidor que enxergue todos os nós, inclusive em um dos servidores de bancos.

1.2. Instalação pelo HQCenter Admin

Passo 1. Executar o script de instalação do fbagent

O script instala o Firebird (a compilação HQbird), o fbagent, e registra o fbagent no servidor do HQCenter Admin. Escolha o script correspondente à sua versão do Firebird: fb25, fb30, fb40, fb50.

Linux (como root):

Command
sudo sh fbagent-fb50_known.sh --goafts <HQCenter-Admin-server> --enroll --cluster

No Windows (PowerShell como administrador):

Command
powershell -NoProfile -ExecutionPolicy Bypass -File .\fbagent-fb50_known.ps1 -Enroll

Não há parâmetro -Cluster no Windows: o fbagent executa como LocalSystem e cria as pastas do cluster sozinho.

Principais parâmetros:

Linux Windows Significado
--goafts <name> -Goafts servidor do HQCenter Admin de onde baixar; o nome é fornecido pelo seu fornecedor
--enroll -Enroll registrar o fbagent no HQCenter Admin (pedido de certificado)
--cluster — criar as pastas /opt/hqclusternode e /opt/hqbirdrcm (necessário somente para o fbagent 2.55.2 e anteriores; inofensivo nas versões mais novas)
--channel -Channel canal de atualização do fbagent, stable por padrão
--token -Token token de licença: o HQCenter Admin aprova o pedido automaticamente
--port -Port porta do Firebird
--yes -Yes não fazer perguntas (necessário quando não há terminal)

A lista completa de parâmetros está no README do script de instalação do fbagent.

Passo 2. Aprovar o pedido do fbagent

Com o parâmetro --enroll, o fbagent envia um pedido de certificado (CSR) ao HQCenter Admin e espera até 30 minutos pela aprovação. Você pode aprová-lo assim:

  • automaticamente — se a instalação foi executada com um token de licença (--token) e a licença tem uma vaga livre;
  • no painel do HQCenter Admin — a seção de pedidos de CSR, o pedido deste host, o botão de aprovar e assinar;
  • pela API do HQCenter Admin — POST /v1/admin/csr-requests/{id}/approve.

Se o registro não teve sucesso (por exemplo, o tempo de espera esgotou), o fbagent ainda funciona, mas o script termina com o código 2. Execute o script de novo com os mesmos parâmetros: somente o registro será repetido.

Alguns minutos depois do registro, o fbagent instala o HQ Monitor sozinho.

Passo 3. Descrever o cluster

Os nós e o RCM aparecem quando você adiciona o fbagent ao cluster do HQCenter Admin. Como descrever o cluster está no capítulo 2.

Depois de salvar o cluster:

  1. Em até 10 minutos o fbagent recebe o cluster do HQCenter Admin (depois disso ele verifica alterações a cada 60 segundos).
  2. O fbagent no host do RCM cria a autoridade certificadora do cluster (CA) e assina os certificados de todos os nós.
  3. Cada fbagent grava node.json ou rcm.json para os membros do seu cluster.
  4. Na próxima verificação de produto (a cada 3 minutos) o fbagent instala e inicia os serviços.

O que é instalado e onde:

O quê Linux Windows
Nó mestre /opt/hqclusternode/master/, serviço hqclusternode-master-p<port> <HQbird>\hqclusternode\master\, serviço HQClusterNode-master-p<port>
Nó réplica /opt/hqclusternode/replica/, serviço hqclusternode-replica-p<port> <HQbird>\hqclusternode\replica\, serviço HQClusterNode-replica-p<port>
RCM /opt/hqbirdrcm/, serviço hqbirdrcm <HQbird>\hqbirdrcm\, serviço hqbirdrcm

<port> é a porta do Firebird, por exemplo 3050. Um único fbagent pode hospedar no máximo um nó mestre, um nó réplica, um RCM e um roteador (hqclusternode router, a partir do HQbird 2027.2.30, capítulo 8.7).

No Windows. Versões do fbagent anteriores à 2.83.0 instalavam os nós em C:\hqclusternode e o RCM em C:\hqbirdrcm. Se essas pastas existirem, o fbagent continua a usá-las.

Atualizações

  • O fbagent verifica novas versões do nó e do RCM a cada 3 minutos; o canal padrão é stable. O nó réplica é atualizado primeiro, depois o nó mestre.
  • Se, depois de uma atualização, o serviço não iniciar ou informar a versão errada, o fbagent volta à versão anterior e bloqueia a nova. A lista de bloqueios: <pasta do fbagent>/update/<product>/blocked-versions.json. Para tentar a versão de novo, apague a linha dela nesse arquivo.
  • Estado do produto: fbagent --product-status hqclusternode (ou hqbirdrcm).

1.3. Instalação pelo RCM (sem o HQCenter Admin)

O cluster é gerido pelo RCM. O fbagent de cada host recebe a descrição do cluster do RCM, o fbagent no host do RCM assina os certificados, e o nó e o RCM são atualizados a partir de versões armazenadas pelo RCM.

Limitações:

  • Um cluster por RCM.
  • No máximo 3 postos. Um posto é um host que executa um nó mestre ou réplica. Um mestre e uma réplica no mesmo host contam como um posto. Um host que executa somente o RCM não ocupa um posto. Um quarto host produz o erro seats_exceeded.
  • O RCM não atualiza o fbagent nem o Firebird. O fbagent os atualiza sozinho e não mexe em replication.conf, node.json, rcm.json nem nos certificados.

Há dois métodos:

  • Vincular hosts no RCM — o método habitual. Três ações: o instalador em cada host (RCM em um host, modo de descoberta nos outros), entrar no RCM, o formulário Vincular hosts.
  • Manualmente pela linha de comando — tokens de ingresso e fbagent --cluster-join. Necessário quando a porta 7450 está fechada entre os hosts ou a janela de pareamento já fechou.

Licença. A licença de avaliação inclui o recurso cluster. Depois do período de avaliação, o fbagent não instala um nó nem o RCM se a licença não tiver cluster. Ele nunca bloqueia atualizações de nós e do RCM já instalados. Sem o HQCenter Admin, uma licença flutuante deixa de funcionar depois de online_check_days mais os dias de tolerância. Por isso instale uma licença vinculada em cada fbagent:

Command
fbagent --license-request --out license_request.json
# send the file to the vendor and receive license.json
fbagent --license-install license.json

Sem licença, o mestre deixa de enviar segmentos (capítulo 2.8).

Portas:

Porta Onde Quem se conecta
7443 host do RCM fbagent e nós de todos os hosts do cluster
7444 host do RCM navegador do operador (console do RCM, HTTPS)
7450 (no segundo fbagent e nos seguintes — 7451…7459) host em modo de descoberta, enquanto a janela de pareamento está aberta RCM no host do RCM
7051 (segundo nó do mesmo fbagent — 7061) hosts dos nós outros nós e o RCM (1.4, passo 7)

Vincular hosts no RCM

Exemplo do zero. Dois servidores Linux, o instalador .run, vinculação, registro, publicação, inicialização e reinicialização sob carga — com capturas de tela e medições: o guia hqbird2027-linux-cluster-guide.ru.md e o runbook hqbird2027-linux-cluster-runbook.ru.md (repositório goafts, pasta de documentação).

Passo 1. Instalar o HQbird em cada host

Instale o HQbird com o instalador completo em cada servidor de bancos. Não registre no HQCenter Admin (--enroll).

Por padrão o instalador não configura um cluster. Ele coloca os programas do nó e do RCM na pasta do fbagent (update/<product>/staged/), mas não instala o RCM, não abre a janela de pareamento e não abre as portas do cluster no firewall. O cluster é ativado por dois parâmetros:

Command
sudo sh hqbird2027-fb50-linux-<version>.run --rcm on               # RCM host
sudo sh hqbird2027-fb50-linux-<version>.run --cluster-pairing on   # other hosts

--rcm on — em um host, onde o RCM do cluster vai executar. O instalador:

  1. cria o cluster deste host (fbagent --cluster-init); o nome do cluster é o nome do host;
  2. instala e inicia o RCM; o console do RCM funciona em HTTPS na porta 7444;
  3. cria o primeiro administrador do RCM rcmadmin com uma senha aleatória;
  4. abre as portas 7443, 7444 e a porta do nó 7051 no firewall.

--cluster-pairing on (modo de descoberta) — em cada outro host. O instalador abre a janela de pareamento do fbagent por 24 horas: a porta 7450 e a porta do nó 7051. Enquanto a janela está aberta, um RCM da rede pode convidar este host para o seu cluster. O fbagent começa a escutar na porta 7450 em até um minuto.

Sem esses parâmetros o instalador pergunta sozinho: na interface de texto esta é a página Cluster; com --no-tui — duas perguntas. A resposta padrão é “não”. --yes sem parâmetros de cluster também responde “não” às duas perguntas.

No fim o instalador imprime as linhas RCM: e Pairing:. No host do RCM:

text
RCM:        https://10.0.0.7:7444 (cluster db1)
CA hash:    sha256:7cfc1d4b…032d2582
Login:      rcmadmin
Password:   in /opt/hqbird/fbagent-fb50/clusterca/db1/rcm-initial-password (read it with sudo; RCM asks for a new one at the first login)
Pairing:    not needed: this agent runs the RCM; other agents link through it

Em outro host:

text
RCM:        off; turn it on in HQbird Monitor or with fbagent --cluster-init <id>
Pairing:    port 7450 open until 2026-11-17T17:49:18Z (fingerprint sha256:0439e44a…91a2f9b9); an RCM may invite this host

Não há senha na saída: ela está no arquivo da linha Password:. Anote o fingerprint de cada host em modo de descoberta.

Parâmetros de cluster no instalador Linux:

Parâmetro O que faz
--rcm on|off instala o RCM e cria um cluster neste host; padrão off
--cluster-pairing on|off modo de descoberta: abre a janela de pareamento por 24 horas; padrão off
--pairing-port N porta de pareamento do novo fbagent, 7450–7459; padrão a primeira livre
--rcm-password-file F senha do administrador do RCM a partir da primeira linha do arquivo F, em vez de aleatória
--cluster-id ID nome do cluster ID em vez do nome do host (com --rcm on)
--cluster-node on|off instala o programa do nó; padrão on
--rcm-allow A,B somente estes RCMs podem convidar este host: endereço, rede CIDR ou nome

O primeiro fbagent de um host recebe a porta de pareamento 7450 e as portas de nó 7051 e 7061. A segunda instância no mesmo host — 7451, 7052 e 7062.

O RCM e a janela de pareamento podem ser ativados depois, sem o instalador: no HQ Monitor, a página Clusters, ou com comandos como o usuário do fbagent:

Command
cd <fbagent folder>                                    # /opt/hqbird/fbagent-fb50
sudo -u firebird ./fbagent --cluster-init <name>      # RCM host; open ports 7443 and 7444 yourself
sudo -u firebird ./fbagent --cluster-pairing on      # window for 24 hours
sudo -u firebird ./fbagent --cluster-pairing off
sudo -u firebird ./fbagent --cluster-pairing status

Instaladores antigos (fbagent anterior à 3.1.0) não perguntam sobre o cluster: eles instalam o RCM em cada host e abrem a janela de pareamento em todos. Você precisa do RCM de um host; os RCMs dos outros hosts param sozinhos depois da vinculação.

No Windows. As mesmas duas escolhas existem no instalador do Windows: os parâmetros /RCM e /DISCOVERY.

Passo 2. Entrar no RCM

Abra o endereço da linha RCM: do host do RCM (https://<host>:7444). Entre com o login rcmadmin e a senha do arquivo da linha Password:. O RCM pede imediatamente uma senha nova (1.5).

Passo 3. Vincular os hosts

No RCM abra Configurações → Vincular hosts.

  1. No campo Hosts informe os endereços ou nomes dos hosts, um por linha. A primeira linha é o host do RCM; ele já está no cluster.
  2. Clique em Verificar hosts. O RCM sonda as portas de pareamento 7450–7459 de cada host e mostra a plataforma, a versão do Firebird, a impressão digital e o estado. O host do RCM não precisa de janela de pareamento. Compare as impressões digitais com a saída do instalador (a linha Pairing:).
  3. Selecione o Mestre (por padrão o primeiro host) e clique em Vincular.
Vincular hosts: resultado da verificação
Vincular hosts: resultado da verificação

O RCM pede confirmação e mostra o progresso na seção Progresso. Quando todos os nós estão em execução, ele diz “Concluído” e mostra o número de revisão do cluster:

Vincular hosts: todos os nós em execução
Vincular hosts: todos os nós em execução

O mesmo pela linha de comando:

Command
cd /opt/hqbirdrcm
export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
./hqbirdrcm cluster link -hosts db1,db2,db3 -master db1

O que acontece em seguida:

  1. O RCM envia um convite a cada host livre.
  2. O fbagent do host entra no cluster e fecha a porta de pareamento. Se o host tem o seu próprio RCM sem nós, o fbagent o para e o desativa, e move o cluster vazio para cluster/left/ na pasta do fbagent.
  3. O RCM salva o cluster: nó <host>-master no mestre, <host>-replica nos outros hosts, porta 7051, vínculos mestre → réplica.
  4. O fbagent de cada host instala e inicia o nó. O RCM espera até que todos os nós estejam em execução e mostra Em execução para cada host.

Estados do host depois de Verificar hosts:

Estado O que fazer
Pronto para vincular nada. Se abaixo disser “O RCM próprio deste host vai parar depois da vinculação” — isso é normal
No cluster o host já está neste cluster
Erro unreachable a porta 7450 está fechada: a janela de pareamento está desligada (como por padrão) ou as 24 horas passaram. Logo depois da instalação espere um minuto e clique em Verificar hosts de novo. Caso contrário abra a janela (--cluster-pairing on) e verifique o firewall
Erro in_other_cluster o host está em outro cluster
Erro claimed outro RCM está vinculando este host agora
Erro seats_exceeded mais de 3 postos

Versões. O fbagent instala o nó somente a partir do RCM. O RCM pega versões assinadas da sua pasta import/ (ao lado de rcm.json) na inicialização e a cada 5 minutos. O instalador coloca ali as versões do host do RCM, e os fbagents dos outros hosts baixam sozinhos a versão da sua plataforma. A lista de versões está no final da página Vincular hosts. Uma versão também pode ser importada manualmente (passo 5 abaixo).

Manualmente pela linha de comando

Ordem: passos 1–3 no host do RCM, passo 4 em cada outro host, passos 5–6 no RCM.

Passo 1. Instalar o HQbird com o fbagent

Instale o HQbird em cada servidor de bancos e no host do RCM com o instalador completo. No host do RCM você pode informar --rcm on logo de início (então o passo 3 não é necessário). Nos outros hosts não informe parâmetros de cluster: por padrão não há RCM nem janela de pareamento. Não registre no HQCenter Admin (--enroll).

No host do RCM o instalador deixa o programa do RCM na pasta do fbagent (update/hqbirdrcm/staged/). Sem ele o passo 3 falha com o erro no hqbirdrcm to install.

Passo 2. Instalar a licença vinculada

Como no início da seção, “Licença”.

Passo 3. Criar o cluster no host do RCM

Se o instalador já criou o cluster (--rcm on: uma linha RCM: com um endereço na saída), pule este passo.

Execute o comando como o usuário do fbagent (no Linux — firebird), não como root: caso contrário os arquivos da CA e o rcm.json ficarão com o root.

Command
cd <fbagent folder>
sudo -u firebird ./fbagent --cluster-init shop-prod --address 10.0.0.7

No Windows (PowerShell como administrador): .\fbagent.exe --cluster-init shop-prod --address 10.0.0.7

  • shop-prod — nome do cluster: letras latinas minúsculas, dígitos e -.
  • --address — o endereço do host do RCM pelo qual os outros hosts se conectam a ele. Pode ser repetido várias vezes. Sem o parâmetro, usam-se os endereços e o nome do host.

O comando:

  1. cria a CA do cluster e a CA do agente (na pasta do fbagent, clusterca/<name>/);
  2. grava o certificado do RCM, rcm.json e cluster-init.json na pasta do RCM;
  3. instala o RCM e registra o serviço hqbirdrcm. No Linux o serviço executa como um usuário separado hqbirdrcm;
  4. passa o fbagent para o RCM (cluster.source = rcm) e o reinicia;
  5. imprime o endereço do RCM e a impressão digital da CA:
Code
Cluster:    shop-prod
RCM URL:    https://10.0.0.7:7443
CA hash:    sha256:9f86d0...

Anote RCM URL e CA hash: eles são necessários nos outros hosts. Executar de novo para o mesmo cluster é seguro: a CA e as chaves permanecem as mesmas.

Entre no RCM imediatamente e altere a senha do rcmadmin (1.5).

No Linux. O usuário hqbirdrcm está no grupo do fbagent. O RCM lê rcm.json por esse grupo, mas não pode gravá-lo. Por isso Configurações → RCM não salva alterações (erro rcm_config_read_only). Edite rcm.json no host como o usuário do fbagent e reinicie o RCM.

Passo 4. Conectar os fbagents dos outros hosts

  1. No host do RCM crie um token de ingresso para cada fbagent: no RCM Configurações → Cluster, o botão Criar token de ingresso. Ou pela linha de comando:

    Command
    cd /opt/hqbirdrcm
    export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
    ./hqbirdrcm cluster join-token -note db2

    O token vale 24 horas, para um único fbagent e somente uma vez. O RCM o mostra uma vez, junto com um comando pronto.

  2. No host do nó execute este comando como o usuário do fbagent:

    Command
    cd <fbagent folder>
    sudo -u firebird ./fbagent --cluster-join https://10.0.0.7:7443 \
      --ca-hash sha256:9f86d0... --token-file token.txt

    Em vez de --token-file você pode usar --token <token>. No Windows — o mesmo com .\fbagent.exe no PowerShell como administrador.

O fbagent verifica a CA do RCM pela impressão digital. Se a impressão digital não coincidir, ele para e não grava nada. Depois o fbagent recebe o seu certificado (90 dias, renovado automaticamente) e reinicia. Um fbagent conectado aparece no RCM na tabela Agentes. Enquanto ele não tem membros, nada é instalado no host.

Passo 5. Importar versões para o RCM

O fbagent pega o nó e o RCM somente do RCM. Se a versão necessária não estiver na lista Versões no espelho (Configurações → Vincular hosts), importe cada produto (hqclusternode, hqbirdrcm) para cada plataforma dos seus hosts (linux-amd64, windows-amd64). O arquivo da versão e a assinatura .sig são fornecidos pelo fornecedor.

Command
cd /opt/hqbirdrcm
sudo -u hqbirdrcm ./hqbirdrcm release import -config rcm.json \
  -file hqclusternode-linux-amd64 -product hqclusternode \
  -platform linux-amd64 -version 2027.5.12
sudo -u hqbirdrcm ./hqbirdrcm release list -config rcm.json
  • O RCM procura a assinatura em <file>.sig, ou você a indica com -sig. Sem uma assinatura válida do fornecedor o RCM não aceita o arquivo.
  • Uma versão nova substitui a anterior. Não é necessário reiniciar o RCM.
  • O fbagent verifica novas versões a cada 3 minutos. A ordem de atualização e o bloqueio são como pelo HQCenter Admin (1.2, “Atualizações”).

Passo 6. Descrever o cluster

Defina os membros e os vínculos no RCM, Configurações → Cluster (capítulo 2.3). Depois de salvar, o fbagent instala os nós do mesmo modo que pelo HQCenter Admin (1.2, passo 3): grava certificados, node.json e rcm.json, instala e inicia os serviços.

Portas — no início da seção.

1.4. Instalação manual

Passo 1. Instalar o HQbird com o fbagent

Instale o HQbird em cada servidor de bancos (com o mesmo script, mas sem --enroll, ou com o instalador completo do HQbird). Verifique se o fbagent está em execução.

Anote três valores do agent_config.json do fbagent. Eles são necessários para o node.json:

Campo do fbagent Campo do node.json Exemplo
local_api.listen firebird.fbagent_url http://127.0.0.1:13050
local_api.token firebird.fbagent_token —
local_api.instance_id firebird.instance_id —

Verificação do fbagent (a resposta é o JSON da instância do Firebird):

Command
curl -s -H "Authorization: Bearer <token>" http://127.0.0.1:13050/v1/instances/<instance_id>

Se o host tiver várias instâncias do HQbird, deixe somente o serviço da sua instância em firebird.update.services da configuração do fbagent (veja 3.5).

Passo 2. Dispor os arquivos

Linux:

Code
/opt/hqclusternode/
  hqclusternode        # program
  node.json            # node configuration (permissions 0600)
  certs/               # ca.crt, <node_id>.crt, <node_id>.key
  work/                # working folder
/opt/hqbirdrcm/
  hqbirdrcm            # program
  rcm.json             # cluster configuration
  certs/               # ca.crt, rcm.crt, rcm.key
  rcm-data/            # state, users, audit log
Command
sudo mkdir -p /opt/hqclusternode/certs /opt/hqclusternode/work
sudo install -m 0755 hqclusternode-linux-amd64 /opt/hqclusternode/hqclusternode
# on the RCM host:
sudo mkdir -p /opt/hqbirdrcm/certs /opt/hqbirdrcm/rcm-data
sudo install -m 0755 hqbirdrcm-linux-amd64 /opt/hqbirdrcm/hqbirdrcm

No Windows. A pasta padrão é C:\hqclusternode com a mesma disposição. Um caminho com espaço é permitido.

Se um host tiver dois nós (mestre e réplica), dê a cada um a sua pasta, por exemplo /opt/hqclusternode/master e /opt/hqclusternode/replica.

Passo 3. Criar os certificados

Nós e RCM se comunicam somente por mTLS. Você precisa de uma CA e de um certificado para cada participante. Execute isto uma vez em qualquer máquina:

Command
./hqclusternode gencerts -out certs \
  -nodes 'node-a:master,node-b:replica' \
  -hosts 'localhost,127.0.0.1,<ip-node-a>,<ip-node-b>,<ip-rcm>'

O comando cria ca.crt e ca.key, node-a.crt/.key, node-b.crt/.key e rcm.crt/.key. Em -hosts, liste todos os nomes e endereços pelos quais os participantes serão acessados.

gencerts e os arquivos que ele criou
gencerts e os arquivos que ele criou

ca.key é a chave da CA. Não a copie para os hosts; guarde-a separadamente.

Um nó novo é adicionado depois com -add: ele assina o par com a mesma CA, e os outros arquivos ficam inalterados:

Command
./hqclusternode gencerts -out certs -add -nodes 'node-c:replica' -hosts '<ip-node-c>'

Os certificados valem 90 dias. gencerts -out certs -list mostra as datas de expiração, e gencerts -out certs -renew os renova com a mesma chave. Copie o novo .crt para o seu host: o nó o pega sem reinício.

Copie ca.crt e somente o próprio certificado e chave de cada host.

Passo 4. Escrever node.json

Um arquivo por nó. Exemplo para o mestre (node-a):

json
{
  "node_id": "node-a",
  "role": "master",
  "listen_addr": ":7051",
  "rcm": { "url": "https://<ip-rcm>:7443", "ca_cert": "certs/ca.crt",
           "client_cert": "certs/node-a.crt", "client_key": "certs/node-a.key" },
  "firebird": {
    "root": "/opt/firebird",
    "user": "SYSDBA",
    "password": "<SYSDBA password>",
    "port": 3050,
    "replication_conf": "/opt/firebird/replication.conf",
    "replication_log": "/opt/firebird/replication.log",
    "firebird_log": "/opt/firebird/firebird.log",
    "fbagent_url": "http://127.0.0.1:13050",
    "fbagent_token": "<local_api.token>",
    "instance_id": "<local_api.instance_id>",
    "service_name": "<Firebird service name>"
  },
  "windows": { "restart_window": "22:00-05:00", "transfer_window": "23:00-05:00" },
  "peers": [ { "node_id": "node-b", "url": "https://<ip-node-b>:7051", "compress": "zstd" } ]
}

O nó réplica (node-b) tem o mesmo arquivo, mas com "role": "replica", os seus próprios certificados, e o mestre node-a em peers.

Principais campos:

Campo Valor
node_id nome do nó; o mesmo no certificado, no rcm.json e nos peers dos outros nós
role master ou replica
listen_addr o endereço da API do nó; um segundo nó no mesmo host usa outra porta (:7052)
rcm.url o endereço para receber estatísticas do RCM; none — sem RCM
firebird.* o Firebird e o fbagent desta instância; os valores do fbagent precisam coincidir exatamente
firebird.auto_restart se o nó réplica pode reiniciar o Firebird sozinho: auto (padrão), never, always
windows.restart_window a janela de reinício do Firebird; para o mestre o padrão é 22:00-05:00, para a réplica é sempre
windows.transfer_window a janela em que a inicialização corre na velocidade máxima
peers para o mestre — as suas réplicas, para a réplica — o seu mestre
databases a pasta dos bancos; é melhor não escrevê-la à mão e defini-la pelo RCM (capítulo 3)

Os demais campos têm valores padrão. O nó não inicia se os campos do fbagent não estiverem definidos.

Proteja o arquivo: ele contém a senha e o token.

Command
chmod 600 /opt/hqclusternode/node.json

No Windows. Escreva os caminhos no formato JSON: "C:\\HQbird\\replication.conf". service_name é o nome do serviço do Windows para o Firebird.

Passo 5. Escrever rcm.json

json
{
  "ingest_addr": "0.0.0.0:7443",
  "operator_addr": "127.0.0.1:7444",
  "users_file": "rcm-data/users.json",
  "data_dir": "./rcm-data",
  "tls": { "ca_cert": "certs/ca.crt", "cert": "certs/rcm.crt", "key": "certs/rcm.key" },
  "nodes": [
    { "node_id": "node-a", "url": "https://<ip-node-a>:7051", "role": "master",  "host": "A" },
    { "node_id": "node-b", "url": "https://<ip-node-b>:7051", "role": "replica", "host": "B" }
  ]
}
  • url — o endereço do nó como visto pelo host do RCM. Somente https.
  • host — o rótulo da instância do Firebird. Um nó mestre e um nó réplica com o mesmo rótulo executam no mesmo Firebird (companheiro, necessário para promover uma réplica a mestre, capítulo 8). Um rótulo — no máximo um mestre e uma réplica.
  • Caminhos relativos são resolvidos a partir da pasta do rcm.json.

Passo 6. Registrar os serviços

Ordem de início: primeiro o RCM, depois as réplicas, depois o mestre.

RCM (Linux):

Command
cd /opt/hqbirdrcm
sudo ./hqbirdrcm svc install -config /opt/hqbirdrcm/rcm.json
sudo ./hqbirdrcm svc start

Nó (Linux):

Command
cd /opt/hqclusternode
sudo ./hqclusternode svc install -config /opt/hqclusternode/node.json -certs /opt/hqclusternode/certs
sudo ./hqclusternode svc start -config /opt/hqclusternode/node.json
systemctl status hqclusternode-master-p3050

svc install cria o serviço hqclusternode-<role>-p<port> executando como o usuário firebird. Se a pasta do Firebird pertencer ao root, o comando concede ao grupo firebird acesso de escrita a ela (com o bit sticky) e imprime cada alteração: o nó precisa substituir replication.conf.

Para svc start, svc stop e svc uninstall, indique o mesmo node.json: o nome do serviço é derivado do papel e da porta do Firebird.

No Windows (PowerShell como administrador):

Command
cd C:\hqclusternode
.\hqclusternode.exe svc install -config C:\hqclusternode\node.json -certs C:\hqclusternode\certs

O serviço HQClusterNode-<role>-p<port> executa como LocalSystem, inicia automaticamente e reinicia depois de uma falha. O serviço do nó não depende do serviço do Firebird. Se o nó foi instalado com a versão 2027.1.2–2027.1.9, remova a dependência uma vez: .\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.

svc install e svc start no Windows
svc install e svc start no Windows

Passo 7. Abrir as portas

No host do nó, permita conexões de entrada em 7051 (a porta de listen_addr) a partir dos outros nós e do RCM. No host do RCM, permita conexões de entrada em 7443 a partir de todos os nós. Não exponha as portas 7444 e 13050 externamente.

Exemplo de ufw no host do nó:

Command
sudo ufw allow from <ip-rcm> to any port 7051 proto tcp
sudo ufw allow from <ip-partner-node> to any port 7051 proto tcp

Atualização manual

Pare o serviço, substitua o programa, inicie o serviço:

Command
sudo systemctl stop hqclusternode-master-p3050
sudo install -m 0755 hqclusternode-linux-amd64 /opt/hqclusternode/hqclusternode
sudo systemctl start hqclusternode-master-p3050

A configuração e os certificados não são alterados por isso.

1.5. Primeiro login no RCM

O endereço e a senha dependem de como o RCM foi instalado.

Como o RCM foi instalado Endereço Login e senha
Pelo instalador do HQbird ou por fbagent --cluster-init (1.3) https://<host do RCM>:7444 a partir de qualquer computador rcmadmin e a senha impressa pelo instalador (ou a sua, de --rcm-password-file)
Pelo HQCenter Admin (1.2) ou manualmente (1.4) http://127.0.0.1:7444, somente no host do RCM rcmadmin, senha strong password (com um espaço)

HTTPS (1.3). O certificado do RCM é assinado pela CA do cluster, que o navegador não conhece, por isso ele avisa. Na página de login o RCM mostra a impressão digital da CA. Compare-a com o CA hash impresso pelo instalador, e importe a CA no navegador ou no sistema como raiz confiável: o link Baixar o certificado da CA na página de login (https://<host do RCM>:7444/ca.crt, arquivo hqcluster-ca.crt). Para o RCM escutar somente em localhost, defina "operator_addr": "127.0.0.1:7444" em rcm.json e reinicie o RCM.

HTTP (1.2, 1.4). De outro computador, conecte-se por um túnel SSH:

Command
ssh -L 7444:127.0.0.1:7444 <rcm-host>

Depois abra http://127.0.0.1:7444 no navegador.

Página de login do RCM
Página de login do RCM

Senha gerada. O RCM pede que você a altere no primeiro login: até você alterá-la, as outras páginas não abrem. Altere a strong password imediatamente (o link Senha no cabeçalho).

Alteração da senha no primeiro login
Alteração da senha no primeiro login

Idioma. Selecione Russo na lista de idiomas no cabeçalho da página (também disponível na página de login). Se você não selecionar um, o idioma é tomado do navegador.

Alteração de senhas e usuários novos

Cada usuário altera a própria senha: o link Senha no cabeçalho da página. Você precisa da senha atual e de uma nova com pelo menos 12 caracteres. Depois da alteração, as outras sessões desse usuário são encerradas.

Se o instalador gerou uma senha, ela é gravada no arquivo clusterca/<name>/rcm-initial-password na pasta do fbagent. Depois que a senha é alterada, o fbagent apaga esse arquivo sozinho. Não apague o arquivo initial-admin.json na pasta do RCM: ele contém somente um hash. Se o arquivo de usuários se perder e esse arquivo estiver ausente, o RCM criará um usuário com a senha padrão.

Usuários novos. Não há página de usuários na interface. Os usuários ficam no arquivo rcm-data/users.json. A senha é armazenada como um hash HA1: MD5("<name>:hqbirdrcm:<password>").

  1. Calcule o hash:

    Command
    printf '%s' 'rcmadmin:hqbirdrcm:<new password>' | md5sum
  2. Grave-o no campo ha1 do usuário em users.json. Para adicionar um usuário, acrescente outro elemento a users:

    json
    { "username": "ivanov", "ha1": "<hash>", "algo": "MD5", "created_at": "2026-11-03T00:00:00Z" }
  3. Reinicie o RCM imediatamente: ele lê o arquivo somente na inicialização. Quando uma senha é alterada na interface, o RCM reescreve o arquivo a partir da memória, e quaisquer edições que ele ainda não leu serão perdidas.

Command
chmod 600 /opt/hqbirdrcm/rcm-data/users.json
sudo systemctl restart hqbirdrcm

Sem um campo role, um usuário tem todas as permissões. A partir do HQbird 2027.2.31 existe o papel "role": "viewer": somente visualização; qualquer pedido de alteração recebe 403.

1.6. Como verificar a instalação

  • Os serviços do nó e do RCM estão em execução e não reiniciam em loop: systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.

    systemctl status do nó
    systemctl status do nó
systemctl status do RCM
systemctl status do RCM
  • O RCM responde (sem senha): curl http://127.0.0.1:7444/healthz. Quando instalado pelo RCM (1.3), o console funciona em HTTPS: curl -k https://127.0.0.1:7444/healthz.

  • No RCM, a página Visão geral mostra todos os nós, sem o marcador “não responde”.

  • Pela linha de comando no host do RCM:

    Command
    export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
    ./hqbirdrcm nodes
    ./hqbirdrcm status
  • O cluster pelo RCM: Configurações → Cluster, a seção Estado — cada membro aplicou a revisão mais recente e não informa erro. Pela linha de comando: ./hqbirdrcm cluster status.

1.7. Logs

O quê Onde
Log do nó <pasta do node.json>/logs/node-YYYYMMDD.jsonl
Saída do serviço do nó (Linux) journalctl -u hqclusternode-<role>-p<port>
Saída do serviço do RCM (Linux) journalctl -u hqbirdrcm
Log de replicação do Firebird firebird.replication_log do node.json
Logs de qualquer nó sem SSH RCM, página Logs

1.8. Erros comuns

O que você vê Causa O que fazer
O nó não inicia: um erro sobre fbagent_url, fbagent_token ou instance_id o fbagent não está em execução ou os valores não coincidem com agent_config.json verifique o fbagent com o comando curl de 1.4, passo 1
O script de instalação terminou com o código 2 o pedido do fbagent não foi aprovado a tempo aprove o pedido e execute o script de novo
Os nós não aparecem pelo HQCenter Admin o fbagent não está no cluster, ou o cluster ainda não foi obtido verifique o cluster (capítulo 2), espere até 10 minutos
O nó no RCM está “não responde” a porta 7051 está fechada, o url em rcm.json está incorreto, o endereço não está no certificado verifique as portas e o -hosts dos certificados
Sem login no RCM: “Excesso de tentativas de login malsucedidas” 10 logins malsucedidos em 5 minutos espere alguns minutos
A versão nova não se instala a versão está em blocked-versions.json remova a linha da versão do arquivo
--cluster-init: no hqbirdrcm to install o instalador não deixou o programa do RCM instale o HQbird com o instalador completo (1.3, “Manualmente”, passo 1)
--cluster-join: token_used, token_expired, token_revoked o token já foi usado, tem mais de 24 horas ou foi revogado crie um token novo (1.3, “Manualmente”, passo 4)
--cluster-join: hostname_conflict o cluster tem um fbagent com o mesmo nome de host e endereços diferentes dê nomes diferentes aos hosts
--cluster-join: this agent is in cluster … from goafts o fbagent já está no cluster do HQCenter Admin remova-o do cluster do HQCenter Admin
O nó não se instala pelo RCM o RCM não tem versão para esta plataforma hqbirdrcm release list, importe a versão (1.3, “Manualmente”, passo 5)

2. Configuração do cluster

Neste capítulo você define quais nós estão no cluster e qual mestre envia segmentos para qual réplica. Depois você configura os nós do RCM e os usuários.

Os relacionamentos são definidos de uma de três formas:

Nós instalados Onde os relacionamentos são definidos Seção
pelo HQCenter Admin no HQCenter Admin: a página Clusters do HQ Monitor ou a API do HQCenter Admin 2.2
pelo RCM, sem o HQCenter Admin no RCM: Configurações → Cluster, hqbirdrcm cluster ou a página Clusters do HQ Monitor 2.3
manualmente no RCM: Configurações → RCM e Configurações → Nós 2.3

Em nós instalados pelo HQCenter Admin ou pelo RCM, altere os relacionamentos somente na descrição do cluster. O fbagent sobrescreve node.json e rcm.json de acordo com a descrição do cluster. Editar relacionamentos em Configurações → RCM ou Configurações → Nós do RCM é recusado (409 cluster_managed). Versões anteriores do RCM aceitavam, mas isso se perdia.

2.1. Papéis e esquemas

Cada nó tem um papel: mestre ou réplica. Dois nós — um mestre e uma réplica — podem executar em uma única instância do Firebird.

Esquemas compatíveis:

Code
1 → 1        node-a (master) ──▶ node-b (replica)

1 → N        node-a ──▶ node-b
                    └─▶ node-c

N → 1        node-a ──┐
                      ├─▶ node-b    (one replica for several masters)
             node-x ──┘

Both nodes   host-1: node-1m (master) + node-1r (replica)  ← one Firebird
on a host    host-2: node-2m (master) + node-2r (replica)  ← one Firebird
             node-1m ──▶ node-2r,  node-2m ──▶ node-1r

O vínculo vai sempre do mestre para a réplica. O RCM liga o banco do mestre à sua réplica pelo GUID do banco, não pelo nome do nó.

Companheiro. Um nó mestre e um nó réplica na mesma instância do Firebird são companheiros. A promoção de uma réplica a mestre (capítulo 8) funciona somente para esse par. Em rcm.json o par é marcado por um valor idêntico de host.

2.2. Vínculos pelo HQCenter Admin

Onde descrever um cluster

  • HQ Monitor, página Clusters (somente administradores; a entrega de configuração precisa estar ativada). O modo habitual.
  • API do HQCenter Admin: POST /v1/admin/clusters e PUT /v1/admin/clusters/{id}. O painel do HQCenter Admin não tem página de clusters.

``

Passos na página Clusters

  1. Informe um Novo id do cluster (letras latinas minúsculas, dígitos e -) e clique em Criar.
  2. Adicione membros (Membros). Para cada um informe:
    • o fbagent do host;
    • o papel: master, replica ou rcm;
    • os endereços do host;
    • a porta: para um nó — 7051 (um segundo nó no mesmo host — por exemplo 7052), para o RCM — a porta de entrada de estatísticas 7443.
  3. Adicione vínculos (Vínculos de replicação) do mestre para a réplica.
  4. Clique em Validar e depois em Salvar.

Se outro administrador alterou o cluster ao mesmo tempo, a página pedirá que você recarregue o cluster e repita a alteração.

Regras

  • Um fbagent pode pertencer a somente um cluster.
  • Em um único fbagent — no máximo um mestre, uma réplica, um RCM e um roteador. O roteador (papel router, a partir do HQbird 2027.2.30) não tem vínculos e não ocupa um posto de licença (capítulo 8.7).
  • Um cluster tem exatamente um RCM. O fbagent no host do RCM executa a autoridade certificadora do cluster (CA).
  • O nome do membro (member_id) — letras latinas, dígitos, -. O nome, o fbagent e o papel de um membro não podem ser alterados. Para mover um membro para outro host, crie um membro novo com um nome novo. Não use o nome antigo de novo.
  • Toda réplica precisa ter um vínculo com o mestre.
  • O HQCenter Admin monta o endereço do nó sozinho: https://<primeiro endereço>:<porta>.
  • HQbird 2.5/3.0: defina a data replconf_valid_till do cluster (YYYY-MM-DD) — a configuração do plugin replconf vale até essa data.

Exemplo pela API

json
{"contract":1,"cluster_id":"shop-prod","name":"Shop","pki":"managed",
 "cert_validity_days":90,"renew_before_days":30,
 "members":[
  {"member_id":"db1-m","agent_id":"<fbagent of host 1>","role":"master","addresses":["db1.lan"],"listen_port":7051},
  {"member_id":"db1-rcm","agent_id":"<fbagent of host 1>","role":"rcm","addresses":["db1.lan"],"listen_port":7443},
  {"member_id":"db2-r","agent_id":"<fbagent of host 2>","role":"replica","addresses":["db2.lan"],"listen_port":7052}],
 "links":[{"from":"db1-m","to":"db2-r"}]}
  • Criar: POST /v1/admin/clusters (o documento pode ser enviado junto com os membros). Substituir o documento inteiro: PUT /v1/admin/clusters/{id}.
  • PUT exige o cabeçalho If-Match: <revision> (a revisão é fornecida por GET e ETag). Sem o cabeçalho — 428, com uma revisão antiga — 409, com um erro no documento — 422 com uma lista de erros.
  • POST /v1/admin/clusters/{id}/validate valida o documento sem salvar.
  • GET /v1/admin/clusters/{id}/status mostra o estado dos membros e as datas de expiração dos certificados.

O que acontece depois de salvar

  1. O fbagent de cada membro recebe o cluster. Dentro do cluster — uma verificação a cada 60 segundos (o fbagent no host do RCM — a cada 30 segundos). Fora de um cluster, um fbagent fica sabendo do cluster na próxima consulta de configuração. Se essa consulta não alcançar o servidor, a verificação corre a cada 10 minutos.
  2. Cada fbagent cria uma chave e envia um pedido de certificado. O fbagent no host do RCM o assina. O RCM assina o próprio certificado sem pedido.
  3. O fbagent grava em node.json: nome, papel, endereço, peers (a partir dos vínculos), o endereço do RCM, os caminhos dos certificados, os dados do Firebird e do fbagent. Em rcm.json: a lista de nós (nodes), a lista de roteadores (routers), o endereço de entrada de estatísticas e os caminhos dos certificados. O fbagent não mexe nos outros campos dos arquivos.
  4. O fbagent instala e inicia os serviços (capítulo 1).

Alteração de um cluster:

O que mudou O que o fbagent faz
somente os peers de um nó em execução passa-os ao nó sem reinício
outros campos de um nó para o nó, grava o arquivo, inicia o nó — dentro da windows.transfer_window do nó (não definida — imediatamente)
rcm.json reinicia o RCM imediatamente
certificados ou CA reinicia o serviço
um membro é removido para e remove o serviço; cluster-managed.json → cluster-removed.json, o programa → *.removed; a configuração, os certificados e os dados permanecem

Depois que um nó é removido, a seção dele # BEGIN managed-by:<name> … # END … permanece no replication.conf compartilhado. Apague-a manualmente e reinicie o Firebird pelo RCM.

Aprovação dos certificados do cluster

Por padrão o fbagent no host do RCM assina os pedidos sozinho (auto). A aprovação manual pode ser ativada. Comandos no host do RCM:

Command
fbagent --cluster-ca-approval manual     # or auto
fbagent --cluster-status                 # this fbagent's membership in the cluster (JSON)
fbagent --cluster-ca-approve <request_id>

No modo manual, um membro novo ou uma chave nova espera aprovação. A renovação de um certificado com uma chave conhecida é assinada automaticamente.

2.3. Vínculos pelo RCM

Cluster do RCM (sem o HQCenter Admin)

Se o cluster foi criado pelo instalador do HQbird ou pelo comando fbagent --cluster-init (capítulo 1.3), a descrição do cluster é armazenada pelo RCM. A forma mais fácil de adicionar hosts é na página Configurações → Vincular hosts (capítulo 1.3, “Vincular hosts no RCM”): o RCM cria os membros e os vínculos sozinho. As regras são as mesmas do HQCenter Admin (2.2, “Regras”), mais:

  • no RCM há um cluster; o membro rcm sempre existe e não pode ser excluído;
  • no máximo 3 postos (hosts com nós mestre ou réplica); caso contrário ocorre o erro seats_exceeded;
  • um membro só pode ser adicionado em um fbagent que se conectou ao RCM (capítulo 1.3: “Vincular hosts” ou “Manualmente”, passo 4).

Passos na página Configurações → Cluster:

  1. Na tabela Agentes, clique em Adicionar membro na linha do fbagent.
  2. Informe o papel (master, replica ou router), member_id, endereços e porta. A página sugere o nome <host>-<role> e a porta: 7051 para o primeiro nó do fbagent, 7061 para o segundo. Uma porta já ocupada por outro membro do host é recusada pelo RCM. Os endereços do fbagent são botões: clique para adicionar um endereço.
  3. Na seção Vínculos, clique em Adicionar vínculo do mestre para a réplica.
  4. Clique em Validar: o RCM mostrará erros e avisos.
  5. Clique em Salvar. A página mostrará a lista de alterações e pedirá confirmação. Se membros estão sendo excluídos, a janela fica vermelha.

Antes de salvar, as alterações existem somente na página (o rótulo “Não salvo”). Se alguém salvou o cluster ao mesmo tempo, a página oferecerá recarregá-lo. Se somente campos do RCM mudaram (revisão, CA, comissões), a página salvará a sua alteração sozinha.

Outras seções da página:

Seção O que há
cabeçalho nome do cluster, revisão, CA do cluster e CA do agente; o botão Exportar da CA antiga
Tokens de conexão criar um token para um fbagent novo, revogar um não usado
Documento JSON o documento inteiro em um campo de texto; Validar e Salvar o usam
Chaves e CAs comissões: chave nova de membro (rekey), CA nova do cluster (rotate_ca), CA nova do agente (rotate_agent_ca); indisponíveis quando há alterações não salvas
Estado a revisão que cada membro aplicou, expiração do certificado, serviço, último erro

Pela linha de comando no host do RCM:

Command
export RCM_USER=rcmadmin RCM_PASSWORD='<password>'
./hqbirdrcm cluster show > c.json        # document with revision
# edit c.json
./hqbirdrcm cluster validate -f c.json   # validate without saving anything
./hqbirdrcm cluster apply -f c.json      # save (If-Match = revision from the file)
./hqbirdrcm cluster agents               # connected fbagents and their members
./hqbirdrcm cluster status               # what the fbagents reported

O formato do documento é o de 2.2, “Exemplo pela API”. apply com uma revisão antiga recebe 409: execute show de novo. O RCM guarda as últimas 20 revisões em rcm-data/cluster/history/.

HQ Monitor. A página Clusters também funciona com o RCM. No host do RCM, o HQ Monitor acessa o RCM pelo fbagent desse host, com o certificado do fbagent: o usuário e a senha do RCM não são necessários. No log de auditoria do RCM essas ações são registradas como agent:<id> (<user>). Outro modo, para versões anteriores do RCM: na configuração do HQ Monitor defina rcm_admin_url (http://127.0.0.1:7444), rcm_admin_user (o usuário do RCM) e rcm_admin_password_file (um arquivo com a senha dele).

Depois de salvar, tudo segue como pelo HQCenter Admin (2.2, “O que acontece depois de salvar”). O RCM relê nodes em rcm.json sozinho, sem reinício.

Remover um fbagent do cluster: exclua os membros dele e salve, depois clique em Revogar na tabela Agentes (ou ./hqbirdrcm cluster revoke -agent <id>). Para trazê-lo de volta, é necessário um token novo. Depois da revogação o fbagent (a partir da versão 3.1.0) sai do cluster sozinho: ele para os seus nós e apaga os dados do cluster. O mesmo é feito em um host de nó pelo comando fbagent --cluster-leave. No host do RCM isso é recusado.

Instalação manual: adicionar um nó ao RCM

  1. Configurações → RCM, a tabela Nós conectados.
  2. Clique em Adicionar nó. Preencha node_id, url (https://<endereço>:7051), papel, host (rótulo da instância do Firebird), server (somente para agrupamento na tela).
  3. Clique em Validar na linha do nó: o RCM verificará a conexão e as permissões.
  4. Clique em Salvar. O RCM gravará rcm.json e salvará o arquivo antigo como rcm.json.<hora UTC>.bak (os últimos 20).
  5. Reinicie o RCM. Até o reinício a configuração antiga está em vigor; a página mostra quais campos estão esperando um reinício.
Configurações → RCM
Configurações → RCM
Command
sudo systemctl restart hqbirdrcm

Você também pode fazer isso sem a interface: edite rcm.json e reinicie o RCM.

Instalação manual: vincular mestre e réplica

O vínculo precisa ser registrado dos dois lados:

  1. Configurações → Nós, selecione o nó mestre.
  2. Na seção Pares, clique em Adicionar par: o node_id da réplica, o url dela, compressão (zstd).
  3. Clique em Salvar. O RCM mostrará a lista de alterações e pedirá confirmação. A alteração de peers entra em vigor imediatamente.
  4. Repita para o nó réplica: o par dele é o mestre.
A seção Pares do nó mestre
A seção Pares do nó mestre

Se o par não estiver registrado em um dos lados, o RCM não oferecerá esse nó réplica na inicialização do banco.

2.4. Configurações do nó

Configurações → Nós mostra as configurações de node.json que o nó permite alterar a partir do RCM. Somente os campos alterados são salvos, depois de uma janela que lista as alterações.

Configurações → Nós: seleção de um nó
Configurações → Nós: seleção de um nó
Configurações de bancos do nó com marcadores "depois da varredura"
Configurações de bancos do nó com marcadores "depois da varredura"

Cada linha é marcada com o momento em que a alteração entra em vigor:

Quando Quais configurações
Imediatamente channel_a_mbps, channel_a_burst_mbps, windows.restart_window, peers; a partir do HQbird 2027.2.24 — configurações de verificação de dados (limits.data_check_*); a partir do HQbird 2027.2.31 — advertise_addr
Depois do reinício do nó os demais limites, windows.transfer_window; a página os mostra em uma linha separada até o nó ser reiniciado
Depois da varredura databases.*, exclude_filter; se replication.conf mudou, é necessário reiniciar o Firebird (capítulo 3.5)

Somente leitura (alterados em node.json no host do nó): firebird (incluindo a senha e auto_restart), rcm, tls, segments, o endereço listen_addr.

Principais configurações:

Configuração Padrão Significado
windows.restart_window mestre 22:00-05:00, réplica — sempre quando o nó pode reiniciar o Firebird; o Firebird mestre nunca se reinicia sozinho
windows.transfer_window 23:00-05:00 a janela em que a inicialização corre na taxa reinit_window_mbps
limits.channel_a_mbps 50 taxa de transferência de segmentos, MB/s (channel_a_burst_mbps — pico de curta duração, 200)
limits.reinit_window_mbps 100 taxa de inicialização dentro da janela de transferência, MB/s
limits.reinit_day_disk_fraction 0,5 fração da velocidade de disco medida para a inicialização fora da janela
limits.retention_days 2 quantos dias manter os segmentos enviados no arquivo do mestre
limits.free_space_floor_gb 1 espaço livre mínimo, GB; abaixo disso a réplica não aceita segmentos
limits.max_concurrent_reinits 1 quantas inicializações o nó executa ao mesmo tempo

Detalhes de velocidade e retenção do arquivo estão nos capítulos 5 e 7.

firebird.auto_restart (somente em node.json) determina se um nó réplica pode reiniciar o Firebird sozinho:

Valor Comportamento
auto (padrão) pode, se este Firebird não servir bancos mestres
never nunca
always sempre, mesmo se este Firebird hospedar bancos mestres

Pelo HQCenter Admin. A windows.transfer_window do nó do fbagent também é usada como a janela para reiniciar o próprio serviço do nó quando o cluster muda. Se a janela não estiver definida em node.json, o fbagent reinicia o serviço imediatamente.

2.5. Várias instâncias do HQbird em um host

O fbagent reinicia os serviços listados em firebird.update.services da sua configuração. Uma lista vazia significa todos os serviços do HQbird no host. Deixe somente o serviço da sua própria instância na lista. O nó não vê essa configuração e grava um aviso fbagent_shared no log se o fbagent conhece mais de uma instância.

2.6. Senha do SYSDBA

O nó se conecta ao Firebird com o usuário e a senha de firebird.user e firebird.password em node.json. O fbagent guarda a própria cópia da senha. Se você alterou a senha do SYSDBA:

  1. Corrija firebird.password no node.json de cada nó desta instância (mestre e réplica).
  2. Corrija a senha na configuração do fbagent e recarregue-a (veja a documentação do fbagent).
  3. Reinicie os serviços dos nós.

Caso contrário as páginas de publicação e de verificação no RCM mostrarão um erro de login (SQLSTATE 28000).

2.7. Usuários do RCM e auditoria

  • Os usuários estão no arquivo rcm-data/users.json (capítulo 1.5). Sem um papel, um usuário tem todos os direitos; o papel viewer (a partir do HQbird 2027.2.31) — somente visualização.
  • Uma sessão dura 12 horas depois da última ação.
  • Depois de 10 logins malsucedidos em 5 minutos, o login desse usuário e endereço fica temporariamente bloqueado. Um login bem-sucedido zera o contador.
  • O log de auditoria é o arquivo rcm-data/audit.jsonl: uma linha JSON para cada alteração, login e logout. Não há log de auditoria na interface.
  • A página Comandos mostra o autor de cada comando.

2.8. Licença

Uma vez por minuto, o nó mestre lê a licença do fbagent do seu host. Se não houver licença (o período de avaliação terminou, a licença expirou ou é inválida), o nó deixa de enviar segmentos de todos os bancos do mestre. O Firebird e os bancos continuam em execução, mas as réplicas deixam de receber alterações.

O que você vê no RCM:

  • o mestre fica vermelho (NEEDS_ATTENTION), com o distintivo “sem licença: envio interrompido”;
  • não há botão Retomar: somente a licença encerra a pausa;
  • na réplica: “não recebe desde …: o mestre não tem licença”;
  • na tabela Nós, um distintivo “sem licença”; em Configurações → Nós, o bloco da licença do fbagent;
  • os alertas license_paused e license_pause_archive_released;
  • a inicialização é proibida (license_paused).
Bloco da licença do fbagent em Configurações → Nós
Bloco da licença do fbagent em Configurações → Nós

Instale a licença no fbagent. O nó encerra a pausa sozinho em até um minuto. O mestre retém o arquivo para as réplicas por limits.retention_days (2 dias por padrão) a partir do início da pausa. Se você instalar a licença mais tarde, as réplicas terão de ser inicializadas de novo.

Cluster pelo RCM, sem o HQCenter Admin. Uma licença flutuante sem o HQCenter Admin deixa de funcionar depois de online_check_days mais os dias de tolerância. Cada fbagent do cluster precisa de uma licença vinculada (fbagent --license-request, depois fbagent --license-install, capítulo 1.3, “Licença”). Depois do período de avaliação, o fbagent não adicionará um nó novo nem o RCM sem o recurso cluster na licença; ele nunca proíbe atualizações. Para o HQbird 2.5/3.0, a data replconf_valid_till no RCM não pode ser posterior ao fim da licença mais os dias de tolerância nos nós do fbagent (erro replconf_after_license).

2.9. Como verificar

  • Visão geral: todos os nós estão presentes e agrupados por servidor.

    Visão geral do cluster
    Visão geral do cluster
  • Configurações → Nós: o mestre tem uma réplica em Pares, e a réplica tem o mestre.

  • Configurações → RCM: o botão Verificar na linha de cada nó passa.

  • Relatório do cluster como um único arquivo:

    Command
    ./hqbirdrcm report -o report.json

2.10 Erros comuns

O que você vê Causa O que fazer
Edição de pares no RCM recusada (409 cluster_managed) ou perdida depois do reinício do nó o nó foi instalado pelo HQCenter Admin ou pelo RCM altere os vínculos na descrição do cluster (2.2, 2.3)
seats_exceeded ao salvar o cluster no RCM nós em um quarto host no máximo 3 hosts com nós
Configurações → RCM: rcm_config_read_only cluster pelo RCM no Linux: rcm.json pertence ao fbagent edite rcm.json como o usuário do fbagent e reinicie o RCM
Revogar agente não funciona (agent_has_members) o fbagent tem membros primeiro exclua os membros e salve
O nó réplica não é oferecido durante a inicialização o par não está registrado em um dos lados adicione o par dos dois lados (2.3)
Uma alteração em Configurações → RCM não entra em vigor o RCM não foi reiniciado reinicie o RCM
422 ao salvar o cluster no HQCenter Admin um erro no documento corrija de acordo com a lista errors, verifique por validate
409 ao salvar o cluster o cluster foi alterado por outra pessoa releia o cluster e tente de novo
Um membro novo do cluster do HQCenter Admin não recebe certificado aprovação manual no host do RCM fbagent --cluster-ca-approve <id>
Erro SQLSTATE 28000 nas páginas de publicação a senha do SYSDBA foi alterada 2.6

3. Inclusão de um banco no mestre

Neste capítulo o banco mestre passa ao controle do nó. O nó o registra em replication.conf e cria pastas para os segmentos. Depois de reiniciar o Firebird o banco fica pronto para replicação.

A criação da réplica são os passos seguintes (publicação, inicialização). Eles estão descritos nos capítulos 4–6.

Os nomes dos botões seguem a interface do RCM em russo, com os nomes em inglês entre parênteses.

3.1. Como um nó descobre os bancos

O nó mestre procura bancos em uma única pasta — a raiz dos bancos (databases.root). O que entra na gestão é decidido por regras:

Regra Campo Padrão
Pasta dos bancos root não definida
Pesquisar subpastas recursive sim
Máscara de inclusão template *.fdb
Máscara de exclusão exclude_mask nenhuma
Tamanho do arquivo, MB min_size_mb, max_size_mb sem limites (0)
Tabelas para comparação de dados sync_tables com o HQbird 2027.2.24 — tabelas da publicação do banco; se não houver — RDB$FIELDS; em 2027.5.7 — RDB$FIELDS
Lista de inclusão include_paths vazia (modo de máscara)
Lista de exclusão exclude_paths vazia

O caminho root é um caminho no host do nó, não no host do RCM. O nó aplica primeiro a máscara de inclusão, depois a de exclusão, depois o tamanho.

As regras são as mesmas para o nó inteiro. A lista sync_tables também é compartilhada: a verificação (capítulo 5.10) procura cada tabela da lista em cada banco do nó que não tem a própria lista.

Tabelas para comparação, com o HQbird 2027.2.24. Cada banco pode ter a própria lista (Tabelas de acompanhamento da sincronização). O nó a guarda em databases.sync_tables_by_db. A verificação usa a primeira lista que estiver definida:

  1. a lista própria do banco;
  2. a lista compartilhada sync_tables do nó;
  3. tabelas da publicação do banco;
  4. RDB$FIELDS.

Uma lista compartilhada salva antes tem precedência sobre a publicação: um banco sem a própria lista a usa. A página do banco do mestre mostra qual lista está em vigor (3.3).

Uma tabela ausente tanto no banco primário quanto na réplica recebe o estado “não está no banco” (absent): ela não é comparada, e a verificação não mostrará “Não ok” por causa dela. Uma tabela que falta em somente um lado é uma divergência.

RCM e nó 2027.5.7. Há uma única lista para o nó inteiro (sync_tables); sem lista a verificação usa RDB$FIELDS. Uma tabela ausente é um erro, e a verificação do banco mostrará “Não ok”.

Todas as regras ficam no node.json do nó. O nó as aplica em cada varredura.

Modo de máscara e modo de lista:

  • Modo de máscara (lista de inclusão vazia): o nó pega todos os arquivos que correspondem à máscara, exceto os excluídos. Um arquivo novo na pasta será pego pelo nó automaticamente na próxima varredura.
  • Modo de lista (lista de inclusão não vazia): o nó pega somente os arquivos da lista. Um arquivo novo não entra na gestão automaticamente — ele precisa ser adicionado.

Escolha o modo de lista se a pasta contém cópias de bancos, bancos de teste ou outros arquivos que não precisam ser replicados.

3.2. Antes de começar: verificar permissões

O usuário sob o qual o Firebird e o nó executam (firebird no Linux, LocalSystem no Windows) precisa ter permissões de leitura e escrita em:

  • a pasta raiz dos bancos e os arquivos dos bancos;
  • replication.conf e a pasta dele (o nó substitui o arquivo por um arquivo temporário);
  • as pastas de segmentos <database>.ReplLog e <database>.LogArch (o nó as cria sozinho).

O RCM verifica as permissões antes do registro (preflight). Se a verificação falhar, o comando termina com o erro preflight failed on <node> e uma lista de caminhos.

Verificação no host do nó (Linux):

Command
sudo -u firebird /opt/hqclusternode/hqclusternode checkpermissions -config /opt/hqclusternode/node.json

3.3. Página de registro de bancos

Registro de bancos: formulário e pré-visualização
Registro de bancos: formulário e pré-visualização
  1. Abra a página de registro do nó mestre. O link está disponível em dois lugares:

    • Bancos de dados → tabela Nós → coluna de ações → Registrar;
    • Visão geral → cartão do nó mestre → Registrar bancos.

    Um nó réplica não tem esta página.

  2. O formulário mostra as regras atuais do nó (o próprio nó as enviou). Se o nó não responde, os botões de pré-visualização e de registro ficam desativados: sem as regras atuais eles zerariam as listas de inclusão e exclusão.

  3. Preencha ou corrija os campos: Caminho da pasta neste servidor, recursivo, máscaras, Filtro de tamanho, Tabelas de acompanhamento da sincronização.

    O campo Tabelas de acompanhamento da sincronização:

    • com o HQbird 2027.2.24 e posteriores — a lista é por banco que esta ação vai registrar. Campo vazio: o banco usa as tabelas da própria publicação. O registro não altera a lista compartilhada do nó (sync_tables). Se ela existir, o formulário diz isso: um banco sem a própria lista a usa em vez da publicação. A lista de um banco já gerido é definida na página dele: Bancos de dados → banco mestre → bloco Tabelas de acompanhamento da sincronização. O bloco mostra qual lista está em vigor. Um campo vazio remove a lista própria do banco;
    • no RCM e no nó 2027.5.7 — uma única lista para todos os bancos do nó (sync_tables).
  4. Clique em Pré-visualizar. O nó mostrará todos os arquivos que correspondem à máscara de inclusão. Ele não altera nada.

  5. Confira a lista. Cada arquivo tem uma caixa de seleção:

    • marcada — o arquivo será gerido;
    • marcada, bloqueada, com a marca já gerido — o banco já está registrado;
    • bloqueada com um motivo — o arquivo é excluído por máscara, tamanho ou pela lista de exclusão. Para incluí-lo, altere a regra.
  6. Marque os bancos necessários e clique em Registrar os selecionados. O RCM pedirá confirmação e mostrará o número de arquivos.

Confirmação do registro
Confirmação do registro

O que este botão faz:

  • no modo de máscara — arquivos sem caixa de seleção são adicionados à lista de exclusão, arquivos com caixa de seleção são removidos dela;
  • no modo de lista — arquivos com caixa de seleção são adicionados à lista de inclusão.

O botão adiciona bancos aos que já estão na gestão. Ele não altera linhas bloqueadas. 7. O botão Registrar aplica o formulário sem alterar as listas. 8. Espere a mensagem de conclusão e o número de bancos adicionados. Se não houver resposta por muito tempo, verifique o resultado na página Comandos.

Com o HQbird 2027.2.24 e posteriores a mensagem é “Registrados: N”. Se o Firebird do mestre precisar ser reiniciado, o RCM diz qual botão pressionar (em geral Reiniciar o Firebird do mestre na linha do banco) e fornece um link para os bancos mestres. O RCM 2027.5.7 pode dizer “Nenhum banco novo adequado”, mesmo que bancos tenham sido adicionados: verifique a página Bancos de dados.

Resultado do registro
Resultado do registro

Se nenhum banco for encontrado depois do registro, mas o nó já tinha bancos, o nó recusa (409) e devolve as regras antigas. Assim um erro no caminho não desativa a replicação de todos os bancos.

O mesmo pela linha de comando

Command
hqbirdrcm enroll-databases -node node-a -root /databases/master

Nota: o comando envia somente os campos dos seus parâmetros. As demais regras (máscaras, tamanhos, listas de inclusão e exclusão, sync_tables) serão zeradas pelo nó. O comando não tem parâmetros para essas regras. Antes de executar o comando, verifique as regras atuais (hqbirdrcm getconfig -node node-a). Se elas estiverem definidas, use a página de registro.

3.4. O que acontece depois do registro

  1. O nó grava as regras em node.json.
  2. O nó varre a pasta (scansync).
  3. Para cada banco encontrado, o nó grava um bloco na própria área de replication.conf (entre as linhas # BEGIN managed-by:node-a role:master e # END …) e cria as pastas <database>.ReplLog e <database>.LogArch. O nó não modifica texto fora da própria área.
  4. Antes de fazer uma alteração, o nó salva uma cópia do arquivo: replication_YYYYMMDD_hhmmss_NNN.conf.
  5. Se replication.conf mudou, os bancos entram no estado PENDING_RESTART: o Firebird só lerá o arquivo novo depois de um reinício. Na tabela Nós isso aparece na coluna Reinício pendente.
A coluna “Reinício pendente” na tabela “Nós”
A coluna “Reinício pendente” na tabela “Nós”

Estados de um banco novo:

Estado Grupo no RCM Significado
UNCONFIGURED Pendente banco encontrado, configuração ainda não gravada
PENDING_RESTART Pendente configuração gravada, reinício do Firebird necessário
CONFIGURED Pendente Firebird reiniciado, banco pronto para publicação e inicialização

3.5. Reinício do Firebird do mestre

O nó mestre nunca reinicia o Firebird sozinho. O RCM também não. Reiniciar o mestre é decisão do operador: um reinício derruba todas as conexões de todos os bancos dessa instância do Firebird.

Escolha um horário de baixa carga e clique em um dos botões:

  • Reiniciar o Firebird do mestre — na página Bancos de dados, na linha do mestre do banco que aguarda um reinício;
  • o mesmo botão na janela Inicializar, capítulo 5;
  • Reiniciar o Firebird — na página do banco.

O RCM pedirá confirmação. Ele mostra o nome do nó e um aviso: o Firebird reiniciará imediatamente, sem janela de reinício, e todas as conexões serão derrubadas.

Confirmação do reinício do Firebird do mestre
Confirmação do reinício do Firebird do mestre

O mesmo pela linha de comando

Command
hqbirdrcm restartfirebird -node node-a

Este comando também reinicia imediatamente, sem janela de reinício.

Como o nó reinicia o Firebird:

  1. Verifica se o fbagent responde e gere a mesma instância (identificador, porta, nome do serviço de node.json). Se algum valor não coincidir, o nó recusa.
  2. Pede ao fbagent que reinicie o Firebird.
  3. Espera o Firebird responder na porta dele.
  4. Move os bancos de PENDING_RESTART para CONFIGURED.

Várias instâncias do HQbird em um host. O fbagent reinicia os serviços listados em firebird.update.services da sua configuração. Uma lista vazia significa todos os serviços do HQbird no host. Se houver duas instâncias do HQbird no host, deixe somente o serviço da sua instância na lista. Caso contrário, reiniciar um nó também parará a outra instância.

No Windows. Se replication.log cresceu até log_portion_mb ou mais, o reinício segue assim: parar o Firebird → arquivar o log → iniciar.

3.6. Um banco que já é replicado manualmente

Se a replicação já está configurada manualmente para um banco (o próprio bloco em replication.conf, publicação ativada, segmentos fluindo), ele pode entrar na gestão sem reinicializar a réplica. Para isso existe o modo detect_existing (somente mestre).

  1. Execute uma pré-visualização:

    Command
    hqbirdrcm enroll-databases -node node-a -root /databases/master -detect-existing -dry-run

    Na resposta, taken_over lista os bancos que serão migrados. Adicione -verbose para ver os bancos ignorados com o motivo.

  2. Se a lista estiver correta, execute o comando sem -dry-run.

O nó migra um bloco somente se:

  • as pastas de segmentos se chamam exatamente <database>.ReplLog e <database>.LogArch;
  • já existem segmentos no arquivo;
  • a publicação está ativada no banco.

O nó não migra um bloco com caminhos diferentes e o informa como “encontrado, mas não suportado”.

Depois da migração os bancos ficam em PENDING_RESTART, mesmo que as configurações de replicação não mudem: somente a posição do bloco no arquivo muda. Reinicie o Firebird em uma janela de manutenção.

3.7. Como verificar

  • Bancos de dados: o banco aparece na linha do nó mestre, estado CONFIGURED (depois do reinício).

  • Ao lado do banco pode haver um ícone publicação DESLIGADA: a publicação ainda não está ativada. Isso é normal; a publicação é o passo seguinte (capítulo 6).

    Banco novo na linha do mestre
    Banco novo na linha do mestre
  • No host do nó: o bloco do banco está presente em replication.conf dentro da área managed-by:node-a, e ao lado do banco há as pastas .ReplLog e .LogArch.

3.8. Remover um banco da gestão

O modo habitual é o botão. Na página Bancos de dados, marque os bancos, selecione a ação em massa Remover da gestão e clique em Aplicar aos selecionados. O RCM:

  1. adiciona os arquivos à lista de exclusão do nó;
  2. varre a pasta uma vez: os blocos dos bancos são removidos de replication.conf;
  3. apaga os registros dos bancos no nó.

Os arquivos dos bancos e as pastas de segmentos permanecem no disco. O Firebird não é reiniciado. O Firebird continua a gravar os segmentos do banco até o próximo reinício; o RCM dirá se um reinício é necessário.

O RCM recusará (has_replicas) um banco mestre que tenha uma réplica viva: caso contrário a réplica pararia em silêncio. Primeiro transforme a réplica em um banco comum ou remova-a (capítulo 8).

Não apague o bloco do banco de replication.conf manualmente: na próxima varredura o nó o gravará de novo.

Se o arquivo do banco desapareceu ou foi excluído por uma regra. Então o banco fica no estado ORPHANED (o grupo Órfão). O nó mantém o registro e o arquivo de segmentos: um banco ausente é mais vezes um engano do que uma decisão. Se o arquivo voltar, o banco volta a funcionar e o alerta é limpo. Para excluir esse banco de forma permanente, faça dois passos nesta ordem:

Command
# 1. delete the segment archive (optional)
hqbirdrcm cleanuparchive -node node-a -db <db_id> -orphaned
# 2. delete the database record
hqbirdrcm forgetdatabase -node node-a -db <db_id>

Depois de forgetdatabase o comando cleanuparchive não encontrará mais o banco. Os dois comandos funcionam somente para um banco no estado ORPHANED e não tocam no arquivo do banco.

Cuidado. Depois de promover uma réplica a mestre (capítulo 8), não execute cleanuparchive -orphaned para o registro antigo: o novo mestre usa a mesma pasta .LogArch, e o comando apagará o arquivo de trabalho dele.

3.9. Alteração da raiz dos bancos

O registro com outro caminho é permitido. O nó:

  • adiciona bancos da pasta nova;
  • move para ORPHANED os bancos da pasta antiga que não estão na nova (notificação orphaned_database) e mantém os arquivos deles.

Se você escolheu a pasta errada, registre a pasta correta de novo. Um banco com o mesmo caminho completo continuará a operar sob o mesmo db_id. Um banco em um caminho diferente é um banco novo (novo db_id); a réplica dele precisa ser inicializada de novo.

3.10. Erros comuns

O que você vê Causa O que fazer
preflight failed on node-a sem permissões nas pastas corrija as permissões, tente de novo (3.2)
409 scan_would_empty_region a pasta nova não contém bancos, mas o nó tinha alguns verifique o caminho e a máscara
A pré-visualização está vazia a máscara não corresponde ou a pasta está errada verifique o caminho, a máscara, “recursivo”
Os botões estão desativados, “Falha ao ler a configuração do nó” o nó não responde verifique o serviço do nó e a rede (capítulo 1)
O banco permanece em PENDING_RESTART por muito tempo o mestre não reinicia o Firebird sozinho reinicie o Firebird (3.5)
Reinício recusado por causa do fbagent o fbagent não está em execução ou os dados dele não coincidem com node.json capítulo 1, verificação do fbagent
O arquivo novo não apareceu o nó está no modo de lista adicione o arquivo por “Registrar os selecionados”

4. Como tornar um banco uma réplica: etapas e local no disco

Este capítulo cobre toda a jornada de um banco do primário até uma réplica em funcionamento, mais o cálculo de espaço em disco. A própria inicialização está descrita em detalhe no capítulo 5.

4.1. A regra principal

Um banco aparece em uma réplica somente pela inicialização a partir do mestre (reinit): o próprio nó mestre transfere uma cópia pelo nbackup.

Não faça uma cópia manualmente:

  • gbak cria um GUID novo de banco e zera o número do segmento. O vínculo mestre — réplica se quebra.
  • Uma cópia de arquivo de um banco em execução não é consistente, e o RCM verá dois bancos com o mesmo GUID (duplicate_guid) e proibirá a inicialização.

Uma réplica já em execução configurada manualmente pode ser tomada sob gestão sem uma cópia nova — veja 4.6.

4.2. Etapas

Nº Etapa Onde Estado do banco mestre depois da etapa
1 Registro do banco no mestre capítulo 3.3 PENDING_RESTART
2 Reinício do Firebird do mestre capítulo 3.5 CONFIGURED
3 Sincronização da publicação capítulo 6 CONFIGURED, publicação LIGADA
4 Preparação da réplica: pasta, permissões, versão do Firebird 4.3 —
5 Verificação do espaço livre no mestre e na réplica 4.4 —
6 Inicialização capítulo 5 SEEDING → IN_SYNC
7 Reinício do Firebird da réplica (se necessário) capítulo 5.6 a réplica começa a aplicar segmentos
8 Verificação dos dados capítulo 5.10 —

A etapa 3 é obrigatória para o Firebird 4/5. Sem publicação, o Firebird do mestre não grava alterações de tabelas nos segmentos, e a réplica fica silenciosamente atrás do mestre. Na página Bancos de dados esse banco é marcado com o ícone publicação DESLIGADA. Clique em Sincronizar publicação antes da inicialização.

A partir do HQbird 2027.2.24, a janela Inicializar avisa sobre isso e oferece um botão Sincronizar publicação e inicializar, enquanto o nó mestre recusa a inicialização com o erro publication_off (capítulo 5.1). O RCM e o nó 2027.5.7 não verificam a publicação.

HQbird 2.5/3.0. Não há publicações, por isso a etapa 3 é pulada. O conjunto de tabelas é definido pelos filtros do plugin replconf (capítulo 6).

Estados do banco:

Estado Grupo no RCM Significado
CONFIGURED Pendente o Firebird leu as configurações, ainda não há réplica
PUBLISHING Pendente a sincronização da publicação está em andamento
SEEDING Pendente a inicialização está em andamento
IN_SYNC Ok a réplica recebeu todos os segmentos
LAGGING Pendente a réplica está atrasada, os segmentos estão na fila
NEEDS_REINIT Erro a réplica precisa ser inicializada de novo
FAILED Erro a última inicialização falhou

4.3. Preparação da réplica

Pasta dos bancos da réplica

O nó réplica coloca cada banco na própria pasta databases.root no caminho:

Code
<databases.root>/<master node name>/<database path relative to the master root>

Exemplo: mestre node-a com raiz /databases/master e banco /databases/master/sales/employee.fdb. Na réplica node-b com raiz /databases/replica, o banco ficará aqui:

Code
/databases/replica/node-a/sales/employee.fdb

Assim, bancos com os mesmos nomes de mestres diferentes não colidem.

Ninguém cria a pasta raiz automaticamente — nem o instalador, nem o HQCenter Admin, nem o nó na inicialização. Crie-a de uma das formas seguintes:

  • na janela Inicializar: o campo Pasta da réplica, o botão Criar pasta. O botão só aparece quando a pasta não existe. Com o HQbird 2027.2.24, se o nó réplica ainda não tem databases.root, o campo já contém /databases/replica/<id do nó réplica>. Para uma réplica no Windows o campo fica vazio: informe uma pasta com letra de unidade. Cada nó réplica no mesmo host precisa da própria pasta. A pasta é criada pelo nó réplica: dono — firebird (ou o usuário do serviço do nó), permissões 2770. Se o nó não conseguir criá-la, a janela mostrará o comando para o host da réplica. Se você informar outra pasta, o RCM a gravará em databases.root do nó réplica antes da inicialização;

  • manualmente no host da réplica (Linux):

    Command
    sudo mkdir -p /databases/replica
    sudo chown firebird:firebird /databases/replica
    sudo chmod 2770 /databases/replica

    O bit setgid (2770) é necessário para que todos os arquivos internos recebam o grupo do Firebird.

Você só pode alterar a raiz da réplica enquanto ela não tem bancos: caso contrário os bancos antigos ficarão fora da varredura. Para colocar um único banco em outro local, use Mover na página do banco.

Permissões

O nó réplica e o Firebird precisam poder gravar na raiz dos bancos. O nó verifica se os arquivos colocados receberão o grupo da pasta. Se não puder — recusa com ownership_unfixable e um texto de como corrigir (em geral o serviço do nó executa com Group=root).

Com o HQbird 2027.2.24, a janela Inicializar também mostra uma pasta que existe mas na qual o serviço do nó não pode gravar: o texto do nó com o comando de correção e um botão Verificar de novo. O RCM 2027.5.7 nesse caso diz “A pasta existe”: verifique as permissões você mesmo (hqbirdrcm checkpermissions -node <replica> -root <folder>).

Versão do Firebird

A versão principal do Firebird na réplica precisa coincidir com a do mestre (5.0 → 5.0, 4.0 → 4.0). Caso contrário a réplica recusará antes de qualquer transferência de dados: incompatible_engine.

Conectividade

O nó réplica precisa ser um par do mestre, e o mestre precisa ser um par da réplica (capítulo 2). Caso contrário o RCM não oferecerá este nó na janela Inicializar.

4.4. Quanto espaço é necessário

Em resumo

Onde O quê Quanto
Mestre, volume do banco livre antes da inicialização ≥ 105 % do tamanho do banco
Réplica, volume da pasta do banco livre antes da inicialização ≥ 105 % do tamanho do banco, com o HQbird 2027.2.24 — mais free_space_floor_gb (mais o arquivo antigo, se a réplica já existia; com a caixa Remover a réplica antiga — sem ele)
Mestre, <database>.ReplLog segmentos de trabalho do Firebird até 64 segmentos × tamanho do segmento (16 MB por padrão) ≈ 1 GB por banco
Mestre, <database>.LogArch arquivo de segmentos para as réplicas alterações ao longo de retention_days (padrão 2 dias) + o que as réplicas ainda não confirmaram
Réplica, <database>.Incoming fila de segmentos a aplicar até 256 segmentos × 16 MB ≈ 4 GB por banco no pior caso
Réplica, volume inteiro margem pelo menos free_space_floor_gb (padrão 1 GB)

Verificação de espaço antes da inicialização

A inicialização verifica o espaço duas vezes e somente antes de bloquear o banco:

  1. RCM — a partir das estatísticas mais recentes do nó, antes de enviar o comando. Se o espaço for claramente insuficiente, o RCM devolve imediatamente o erro 507.
  2. Nó mestre — uma medição ao vivo no próprio volume, depois um pedido à réplica para que ela meça o dela. Se faltar em pelo menos um lado, a inicialização termina no passo VERIFICAÇÃO DE ESPAÇO com o erro insufficient disk space on master ou … on replica.

A exigência dos dois lados é 105 % do tamanho do banco mestre.

Com o HQbird 2027.2.24 o nó réplica calcula assim:

  • ele precisa de 105 % do tamanho do banco mais o free_space_floor_gb da réplica (7.3): depois da inicialização permanece no volume uma reserva para segmentos;
  • sobras de inicializações anteriores (<database>.hqcluster-part, <database>.new) contam como espaço livre: o nó as apaga antes da cópia nova;
  • o texto do erro nomeia todos os números. Ele também nomeia os arquivos <database>.pre-reinit-*.fdb e <database>.failed-seed-*.fdb com o tamanho deles. O nó nunca os apaga: apague-os você mesmo se não forem necessários.

force (forçado) pula somente a verificação no RCM. A verificação do nó não pode ser contornada: ela protege o nó de ficar sem disco no meio da cópia. Se o espaço for insuficiente somente por causa da cópia antiga da réplica, o RCM 2027.2.24 no erro 507 nomeia a caixa Remover a réplica antiga em vez de force. Para isso, os dois nós precisam ser HQbird 2027.2.24 ou mais novos. Caso contrário o erro nomeia o nó que precisa de atualização, e force.

Por que tanto

Mestre. Durante a cópia o banco é bloqueado por nbackup -L. Todas as alterações são gravadas no arquivo <database>.delta ao lado do banco. O tamanho de .delta depende da carga de escrita durante a cópia. Sob carga pesada e transferência lenta ele pode crescer bastante — acompanhe o espaço durante a primeira inicialização.

Réplica. A cópia é gravada direto no arquivo <database>.hqcluster-part ao lado do local do banco. O nó reserva o tamanho completo de antemão. O arquivo é então verificado, reparado (nbackup -FIXUP -SEQUENCE) e renomeado para o lugar. Uma segunda cópia não é necessária — o tamanho do banco é necessário uma vez, no volume do banco.

Se a réplica já existia (inicialização repetida), o arquivo antigo fica no disco até o último passo. Isso significa que o arquivo antigo e a cópia nova são necessários no volume ao mesmo tempo. O espaço livre é calculado sem o arquivo antigo — portanto a exigência é a mesma: 105 % do tamanho do banco livres.

Remover a réplica antiga (com o HQbird 2027.2.24). Se não houver espaço no volume da réplica para a cópia nova ao lado da antiga, marque esta caixa na janela de inicialização (capítulo 5.1). O nó réplica então apaga a cópia antiga e os segmentos de entrada (.Incoming) antes da transferência, e o volume tem o bastante para 105 % do tamanho do banco mais free_space_floor_gb. O nó apaga a cópia somente se todas as condições forem verdadeiras:

  • sem a exclusão não há espaço bastante, e com a exclusão há;
  • é uma cópia instalada pela inicialização deste nó: o cabeçalho é legível, o modo é réplica somente leitura;
  • o banco não foi tornado normal (não há arquivo <database>.hqcluster-normal.json, capítulo 8);
  • overwrite_non_replica não está definido (5.9).

Caso contrário o nó não apaga nada e recusa com o motivo no texto. Para apagar, o nó para o Firebird da réplica durante a exclusão (5.6).

A caixa fica desligada por padrão. Risco: enquanto a transferência está em andamento, não há cópia do banco na réplica. Se o banco tem somente uma réplica, o mestre fica desprotegido o tempo todo. Enquanto não há cópia nova, o banco na réplica está no estado NEEDS_REINIT (não FAILED e não ORPHANED), e a réplica emite o alerta replica_removed_for_reinit (warn). Quando a cópia nova está no lugar, o alerta é limpo. Se a inicialização falhar depois da exclusão, o par permanece em NEEDS_REINIT: inicie a inicialização de novo (ou a reinicialização automática a iniciará, 5.8). Uma inicialização nova transfere o banco desde o início.

Arquivo do mestre (.LogArch). O nó guarda os segmentos enviados por retention_days dias para que a réplica possa pedi-los de novo. Segmentos que a réplica ainda não aplicou são guardados por mais tempo. Se o espaço está baixo, o nó limpa o arquivo em etapas:

  1. segmentos aplicados por todas as réplicas mais antigos que retention_days;
  2. segmentos aplicados que são mais novos (quando o espaço está curto);
  3. segmentos não aplicados — somente como último recurso. Então a réplica perde os segmentos de que precisa e fica em NEEDS_REINIT.

Se uma réplica fica indisponível por muito tempo, o arquivo cresce. O volume dele = as alterações do banco ao longo do período de indisponibilidade.

Exemplo de cálculo

Banco de 100 GB. Carga — 5 GB de segmentos por dia. A inicialização corre à noite, a cópia leva 2 horas, durante as quais cerca de 2 GB vão parar em .delta.

Onde Cálculo Total livre
Mestre, volume do banco 105 GB para as verificações (inclui o crescimento de .delta) + .ReplLog 1 GB + .LogArch 2 dias × 5 GB = 10 GB ≥ 116 GB
Réplica, banco novo 105 GB + .Incoming até 4 GB + 1 GB de reserva ≥ 110 GB
Réplica, inicialização repetida arquivo antigo de 100 GB já no disco + 110 GB livres volume ≥ 210 GB
Réplica, inicialização repetida com a caixa Remover a réplica antiga (com o HQbird 2027.2.24) arquivo antigo apagado antes da transferência: 105 GB + .Incoming até 4 GB + 1 GB de reserva volume ≥ 110 GB

Acrescente uma reserva para o crescimento do banco e para a indisponibilidade da réplica (o arquivo do mestre cresce 5 GB por dia de indisponibilidade).

Segmentos em um volume separado

As pastas .ReplLog, .LogArch e .Incoming ficam por padrão ao lado do banco. Elas podem ser movidas para outro volume: o parâmetro segments.storage em node.json (com mirror_hierarchy: true o nó replica a estrutura das pastas dos bancos). Então o arquivo não tira espaço dos bancos. A verificação de 105 % continua a valer para o volume do banco.

Onde ver o espaço

  • Bancos de dados → Nós e Visão geral: o ícone de espaço livre do volume de databases.root. Amarelo — menos de 20 %, vermelho — menos de 10 %.

    Página Bancos de dados: a coluna Disco na tabela Nós
    Página Bancos de dados: a coluna Disco na tabela Nós
  • Relatório do cluster: hqbirdrcm report.

4.5. Várias réplicas de um banco

A segunda réplica e as seguintes são criadas do mesmo modo: Inicializar na linha do mestre, selecionando um nó réplica livre.

  • Enquanto uma réplica nova está sendo inicializada, o mestre não transmite este banco às réplicas já em execução. Elas alcançarão o mestre depois que a inicialização terminar. A janela de confirmação diz isso.
  • Um banco — uma inicialização de cada vez, mesmo para réplicas diferentes.
  • O espaço no mestre é verificado separadamente para cada inicialização.
Banco mestre com duas réplicas
Banco mestre com duas réplicas

4.6. Réplica configurada manualmente

Se uma réplica já está em execução a partir de um replication.conf escrito à mão, você pode tomá-la sob gestão e não copiar o banco de novo:

  1. Mestre: registre os bancos com detect_existing (capítulo 3.6).
  2. Réplica: Bancos de dados → nó réplica → Assumir, ou hqbirdrcm takeover-replica. O RCM encontrará os blocos da réplica, combinará os arquivos com os bancos mestres pelo GUID e mostrará para cada um: in_sync, resumable ou needs_reinit.
  3. Confirme as linhas. O nó moverá os blocos para a própria área de replication.conf.
  4. Reinicie o Firebird da réplica para que ele leia os blocos movidos.
  5. Inicialize somente as linhas needs_reinit: o arquivo do mestre já não contém os segmentos exigidos por essas réplicas.

4.7. Erros comuns

O que você vê Causa O que fazer
insufficient disk space on master / on replica espaço insuficiente (4.4). Na reinicialização a cópia antiga ocupa espaço até o fim (4.4) libere espaço, tente de novo. A segunda saída na réplica (a partir do HQbird 2027.2.24) é a caixa Remover a réplica antiga (4.4, 5.1)
507 do RCM imediatamente segundo as estatísticas de espaço claramente não há o bastante o mesmo. Se há espaço sem a cópia antiga, o RCM 2027.2.24 nomeia a caixa Remover a réplica antiga
incompatible_engine versões principais do Firebird diferentes atualize o Firebird da réplica
Pasta ausente no nó réplica raiz não criada Criar pasta na janela de inicialização (4.3)
A pasta existe, mas o serviço do nó não pode gravar nela (a partir do HQbird 2027.2.24) sem permissões de escrita execute o comando da janela, clique em Verificar de novo (4.3)
publication_off (a partir do HQbird 2027.2.24) a publicação do mestre está desativada ou não tem tabelas Sincronizar publicação e inicializar (5.1)
ownership_unfixable o serviço do nó tem um grupo estranho corrija o grupo do serviço como descrito no texto do erro
duplicate_guid dois bancos com o mesmo GUID (uma cópia de arquivo) remova a cópia ou dê a ela um GUID novo (nbackup -F)
Nó réplica ausente da lista Inicializar sem conexão nos pares capítulo 2
Réplica IN_SYNC, mas os dados divergem a publicação estava desativada sincronize a publicação e depois repita a inicialização

5. Inicialização (reinit)

A inicialização é a transferência de uma cópia do banco mestre para a réplica. A primeira transferência se chama inicialização (o botão Inicializar); uma transferência repetida é reinicialização (o botão Reinicializar). O mecanismo é o mesmo.

Antes de começar, conclua os passos 1–5 do capítulo 4: o banco está registrado, o Firebird do mestre foi reiniciado, a publicação está ativada, a pasta da réplica existe e há espaço bastante. Quanto espaço é necessário no mestre e na réplica está descrito no capítulo 4.4.

5.1. Como começar

Publicação primeiro. Registrar um banco não inclui a publicação. Sem publicação, a réplica não recebe alterações. Antes da inicialização, execute Sincronizar publicação (capítulo 6) ou hqbirdrcm setpublication -node <master>.

  • Com o HQbird 2027.2.24, a janela de inicialização verifica a publicação. Se ela está desligada ou não tem tabelas com chave, a janela mostra um aviso e um botão Sincronizar publicação e inicializar. O RCM sincroniza a publicação, espera o comando terminar e inicia a inicialização com a seleção da janela.
  • Um nó mestre 2027.2.24 recusa sozinho essa inicialização (e a primeira também) com o erro publication_off e emite a notificação master_publication_off (capítulo 6.1). Depois da recusa, a célula do banco volta a ter o botão Sincronizar publicação e inicializar.
  • Se o operador desligou a publicação (6.4) ou removeu dela todas as tabelas com chave (6.3), a sincronização preserva isso. O RCM não inicia a inicialização e fornece um link para a página Tabelas da publicação.
  • O RCM e o nó 2027.5.7 não verificam a publicação: a inicialização tem sucesso, o banco mostra “OK” no RCM, mas a réplica não recebe alterações. Se a publicação foi ligada depois da inicialização — reinicialize o banco.
A janela "Reinicializar o banco?"
A janela "Reinicializar o banco?"
  1. Abra Bancos de dados.
  2. Na linha do banco mestre, na coluna do nó réplica, clique em Inicializar. O nó réplica é definido pela coluna: ele não é selecionado na janela. Para um par existente — Reinit no cartão expandido do mestre.
  3. Na janela (com o HQbird 2027.2.24 o título para um par novo é “Inicializar o banco?”; no RCM 2027.5.7 — “Reinicializar o banco?” também na primeira inicialização):
    • verifique a Pasta da réplica. A janela mostra se a pasta existe. Se não existe, clique em Criar pasta: o nó réplica a criará (4.3). Se o nó não puder criá-la, a janela mostra o comando para o host da réplica. Com o HQbird 2027.2.24 a janela também mostra uma pasta na qual o serviço do nó não pode gravar: o comando de correção e um botão Verificar de novo;
    • selecione o Método de reinit: Suave (recomendado) ou Padrão (5.4). Com o HQbird 2027.2.24, se o arquivo do mestre ainda não tem segmentos (em geral antes da primeira inicialização), a janela mostra uma dica: em um banco ocupado Padrão é mais rápido;
    • se o banco mestre ainda espera um reinício do Firebird, a janela dirá isso e mostrará um botão Reiniciar o Firebird do mestre. Sem o reinício o banco não é replicado;
    • Remover a réplica antiga (com o HQbird 2027.2.24, desligada por padrão) só é necessária na reinicialização quando o volume da réplica não tem espaço para uma cópia nova ao lado da antiga (4.4). A janela mostra os números de antemão: quanto é necessário, quanto está livre, quanto a cópia antiga ocupa. Se há espaço sem a cópia antiga, a janela pede que você marque a caixa. A caixa fica inativa se o nó mestre ou réplica é uma versão antiga: a janela indica qual nó atualizar. Até a cópia nova estar pronta, a réplica não tem cópia deste banco (4.4).
  4. Confirme. O RCM informará que o banco será bloqueado no mestre e copiado para a réplica.

O progresso da inicialização é visível no cartão expandido do mestre na página Bancos de dados: passos e porcentagens. Com o HQbird 2027.2.24 o progresso também fica visível depois de atualizar a página: na primeira inicialização — na célula do nó réplica, e também na linha Progresso da reinicialização na página do banco mestre. O botão Inicializar fica inativo enquanto o nó mestre está copiando o banco. Se o RCM não está acompanhando esta inicialização (por exemplo, ela foi iniciada pela linha de comando do nó), os passos são tomados do estado do nó, sem porcentagens. No RCM 2027.5.7, depois de atualizar a página o progresso da primeira inicialização não fica visível: espere até o banco mestre sair de SEEDING.

Passos da inicialização na linha do mestre
Passos da inicialização na linha do mestre

Cada comando do RCM (inicialização, reinício do Firebird, sincronização da publicação) é registrado na página Comandos com o resultado.

A página "Comandos"
A página "Comandos"

O mesmo pela linha de comando

Command
# one database
hqbirdrcm reinit -node node-a -db <db_id> -to node-b
# all master databases
hqbirdrcm reinit -node node-a -all -to node-b

Parâmetros: -mode smooth|standard (padrão smooth), -hold=false (não reter o arquivo durante transações longas), -allow-restart (5.6), -force (5.9).

-remove-old-replica (com o HQbird 2027.2.24) — o mesmo que a caixa Excluir a réplica antiga. Somente para um banco: -db e -to são obrigatórios; com -all o comando recusa. Se o nó mestre ou réplica é uma versão antiga, o RCM recusa com node_too_old e não envia nada.

Command
hqbirdrcm reinit -node node-a -db <db_id> -to node-b -remove-old-replica

-all tenta todos os bancos e coleta os erros em vez de parar no primeiro.

5.2. Passos

Nº Passo (no RCM) O que acontece
1 VERIFICAÇÃO DE ESPAÇO verifica o espaço no mestre e na réplica (capítulo 4.4); a réplica verifica de antemão que pode aceitar o arquivo
2 BLOQUEIO nbackup -L: o arquivo do banco mestre é congelado, as alterações vão para <database>.delta
3 CÓPIA PARA O NÓ o arquivo é transferido em partes: leitura → soma de verificação → compressão → envio
4 DESBLOQUEIO nbackup -N imediatamente depois da transferência: as alterações de .delta voltam ao banco
5 SEMEADURA na réplica: verificação da soma de verificação do arquivo, nbackup -FIXUP -SEQUENCE, instalação do arquivo, gfix -replica, gravação do bloco em replication.conf
6 REINÍCIO DA RÉPLICA reinício do Firebird da réplica, se for necessário (5.6)

Depois do passo 6 o banco fica no estado IN_SYNC. O mestre continua a enviar segmentos a partir do ponto em que a cópia termina.

O que é importante saber:

  • O mestre executa o tempo todo. Os usuários gravam no banco, as alterações vão para .delta. O bloqueio é liberado imediatamente depois da transferência.
  • As transações que coincidiram com o bloqueio não se perdem. O nó encontra as transações abertas no momento de nbackup -L, e a réplica as reproduz a partir dos segmentos.
  • A transferência continua depois de uma interrupção. Se a conexão ou o nó réplica reiniciou, o mestre continuará a partir da última parte recebida. Uma transferência inacabada é guardada na réplica por 24 horas (reinit_partial_keep_hours).
  • Em um erro o nó libera o bloqueio, apaga o arquivo inacabado na réplica e coloca o banco em FAILED. A tentativa seguinte começa de um estado conhecido.
  • Com a caixa “Excluir a réplica antiga” (a partir do HQbird 2027.2.24) a réplica apaga a cópia antiga depois do passo BLOQUEIO, antes da transferência. O passo CÓPIA PARA O NÓ nesse momento mostra “removendo a cópia antiga da réplica para liberar espaço”. Um erro depois da exclusão dá ao par NEEDS_REINIT em vez de FAILED (capítulo 4.4).
  • Somente nbackup. O gbak não é usado: ele altera o GUID do banco.

5.3. Impacto na operação

O quê Impacto
Usuários do mestre continuam a trabalhar; durante a cópia .delta cresce, depois de -N as alterações são transferidas para o banco
Outras réplicas deste banco não recebem segmentos deste banco enquanto a inicialização está em andamento; elas alcançam depois
Outros bancos do mestre não são afetados
Firebird da réplica, banco novo não é parado; reinício conforme 5.6
Firebird da réplica, inicialização repetida é parado enquanto o arquivo é substituído: todos os bancos deste Firebird ficam indisponíveis por segundos
Firebird da réplica, o nó apaga a cópia antiga (caixa “Excluir a réplica antiga”, a partir do HQbird 2027.2.24) é parado mais cedo, enquanto a exclusão está em andamento, antes da transferência. O nó instala a cópia nova sem uma segunda parada se o bloco do banco em replication.conf não mudou. Se há espaço bastante e não é necessária exclusão, o nó não apaga nada, e tudo segue como em uma inicialização repetida normal
Rede e disco carga conforme os limites de velocidade (5.5)

No Windows. Um arquivo aberto pelo Firebird não pode ser substituído. Durante a inicialização repetida o nó para o Firebird da réplica pelo fbagent, instala o arquivo e inicia o Firebird de novo. No Linux o Firebird também é parado antes da substituição: caso contrário ele continuaria a trabalhar com o arquivo antigo excluído.

5.4. Métodos suave e padrão

Suave (padrão). Antes do bloqueio, o nó procura transações longas: transações de escrita do usuário que começaram antes do segmento mais antigo no arquivo do mestre. Depois da inicialização a réplica não poderá reproduzi-las e parará na primeira alteração delas (“A transação … não foi encontrada”). Transações sem alterações não são contadas.

Se essas transações existem, a inicialização não começa: o RCM mostra O reinit suave está aguardando transações longas e fornece um link Abrir a lista.

Página de transações longas: nenhuma transação longa
Página de transações longas: nenhuma transação longa

Na página Transações longas:

  • resumo: quantas transações e conexões, o segmento mais antigo;
  • 5 principais conexões com as transações mais antigas: usuário, cliente, início, idade, alterações, consulta atual;
  • Reter segmentos / Liberar a retenção — enquanto a retenção está ativada, o arquivo do mestre não é purgado e o histórico não é truncado;
  • Desconectar os selecionados e repetir o reinit — desconecta as conexões (as transações delas são desfeitas) e inicia imediatamente um reinit suave;
  • Repetir o reinit, Verificar de novo.

A retenção é ativada automaticamente quando um reinit é recusado por causa de transações longas. Ela é liberada depois de uma inicialização bem-sucedida, manualmente, ou quando o arquivo cresce até reinit_hold_max_segments (1000 segmentos por padrão, notificação retention_hold_released).

Padrão bloqueia o banco imediatamente, sem verificação. Use-o somente se você sabe que não há transações de escrita longas.

Primeira inicialização sob carga. Enquanto o arquivo do mestre está vazio, não há segmento com o qual comparar.

Com um nó mestre HQbird 2027.2.24: se o nó ativou a publicação sozinho e o arquivo não mudou desde então, o histórico começa no momento em que a publicação foi ativada. Uma transação iniciada depois entra no journal a partir da primeira alteração e não interfere no método suave. Uma transação iniciada antes não entrou no journal: o reinit espera por ela antes do bloqueio (6 tentativas a cada 10 s), e o passo locking mostra o número, a conexão e o usuário dela. Se ela não terminou, o reinit termina com o erro reinit_pre_publication_transactions: termine-a e tente de novo. A página Transações longas mostra essas transações na tabela Transações iniciadas antes de a publicação ser ativada.

Se a publicação foi ativada manualmente, não pelo nó, ou o arquivo já mudou, o início do histórico é desconhecido. Nesse caso o método suave recusa se qualquer transação de escrita está aberta, e a mensagem diz que o arquivo ainda não contém um segmento. Nesse caso o RCM 2027.2.24 não abre a lista, mas escreve o que fazer na célula do banco. Escolha Padrão ou tente de novo quando o Firebird arquivar o primeiro segmento.

Com um nó mestre 2027.5.7, o método suave recusa imediatamente na primeira inicialização de um banco que está sendo gravado: long_transactions … segment 0 (0001-01-01T00:00:00Z). Para a primeira inicialização desse banco, escolha Padrão.

Para as reinicializações seguintes o método suave funciona como de costume (o arquivo já existe).

O mesmo pela linha de comando

Command
hqbirdrcm longtx -node node-a -db <db_id>                       # list
hqbirdrcm longtx -node node-a -db <db_id> -disconnect 12,34 -retry-to node-b
hqbirdrcm longtx -node node-a -db <db_id> -hold false           # release hold

Transações mais antigas que a publicação. O Firebird não grava nos segmentos uma transação que começou antes de a publicação ser ativada. Se o nó ativou a publicação, a inicialização espera (6 tentativas a cada 10 segundos) até que essas transações terminem; caso contrário termina com o erro reinit_pre_publication_transactions listando-as. Depois de sincronizar uma publicação que adicionou tabelas, reconecte as aplicações e depois inicie a inicialização.

5.5. Velocidade

Quando Velocidade Configuração
Dentro da janela de transferência windows.transfer_window (padrão 23:00-05:00) constante limits.reinit_window_mbps, padrão 100 MB/s
Fora da janela fração da velocidade de disco medida limits.reinit_day_disk_fraction, padrão 0,5

O nó recalcula o modo a cada 30 segundos: uma inicialização iniciada de dia acelerará sozinha à noite.

O nó mede a velocidade do disco com um teste. Para repetir o teste no host do mestre:

Command
hqclusternode benchmark -config /opt/hqclusternode/master/node.json

Tempo de inicialização ≈ tamanho do banco ÷ velocidade. Exemplo: 100 GB a 100 MB/s — cerca de 17 minutos de transferência pura; na prática é limitado pela rede ou pelo disco.

5.6. Reinício do Firebird da réplica

Um banco novo na réplica. O arquivo é colocado sem parar o Firebird. O Firebird só lerá o bloco novo de replication.conf depois de um reinício. Até lá a réplica não aplica nada. O passo REINÍCIO DA RÉPLICA mostra a espera:

Rótulo O que significa
aguardando um reinício do Firebird na réplica, ele está agendado para … o nó reiniciará o Firebird sozinho depois da última inicialização (reinit_restart_delay_sec), quando as outras inicializações tiverem terminado
… a janela de reinício está fechada, a próxima abrirá em … espera da restart_window da réplica
… a última tentativa falhou, a próxima em … tentará de novo mais tarde
a réplica não pode reiniciar o Firebird sozinha: reinicie-o manualmente auto_restart: never, ou este Firebird também serve os bancos do mestre

O nó reinicia o Firebird uma vez depois de uma série de inicializações, não depois de cada banco.

Para reiniciar manualmente, clique em Reiniciar o Firebird da réplica. A espera termina depois de qualquer reinício bem-sucedido do Firebird ou quando a réplica aplicou um segmento mais novo que a cópia.

Reinicialização em um Firebird que também serve os bancos do mestre. O nó não para esse Firebird sozinho e recusa com restart_not_allowed. Inicie a inicialização de novo e marque Permitir que pare o Firebird para este reinit (-allow-restart na linha de comando) — em um momento em que as conexões deste Firebird possam ser derrubadas, inclusive as dos bancos mestres dele. Execute essas inicializações uma de cada vez por host.

Exclusão da cópia antiga (a caixa Remover a réplica antiga, com o HQbird 2027.2.24) também para o Firebird da réplica, pelas mesmas regras. Se o nó não puder parar este Firebird sozinho, ele não apaga nada e recusa com restart_not_allowed: marque também Permitir que <nó> pare o Firebird para este reinit. Se nesse momento outra inicialização está terminando na réplica ou o Firebird está reiniciando, o nó não apaga nada e recusa com engine_busy: o mestre libera o bloqueio, tente mais tarde.

5.7. Fila e inicializações simultâneas

  • Um banco — uma inicialização de cada vez (mesmo para réplicas diferentes). O botão Inicializar fica desativado enquanto uma inicialização deste banco está em andamento.
  • O nó mestre impõe limits.max_concurrent_reinits inicializações de bancos diferentes ao mesmo tempo (padrão 1). O resto espera na fila; a resposta contém a posição na fila.
  • Não execute o seu próprio nbackup -L (ou ALTER DATABASE BEGIN BACKUP) em um banco durante a inicialização dele, e não inicie uma inicialização durante esse backup: um banco só pode ter um bloqueio. A inicialização verifica isso e recusa com nbackup backup lock already active.

A fila e as transferências atuais são visíveis na página Transferência.

Página Transferência / filas
Página Transferência / filas
- Se um arquivo `.delta` permanecer depois de uma falha, certifique-se de que nenhum backup está em execução e execute `nbackup -N `. Não apague o `.delta` manualmente.

5.8. Reinicialização automática

O RCM pode reinicializar um banco no estado NEEDS_REINIT sozinho, somente dentro de uma janela configurada. Desativada por padrão.

Quando um banco entra em NEEDS_REINIT:

Causa Onde é visível
erro de aplicação irrecuperável recorrente (violação de PK, UNIQUE, FK) — 3 vezes seguidas réplica, alerta replication_unrecoverable_error
o GUID do banco mestre mudou (restauração, substituição de arquivo) réplica, alerta replication_guid_mismatch
o arquivo do mestre já não contém os segmentos de que a réplica precisa mestre
a réplica apagou a cópia antiga para a inicialização e ainda não há cópia nova (a partir do HQbird 2027.2.24) réplica, alerta replica_removed_for_reinit; mestre

Para ativar — Configurações → RCM (ou rcm.json, a seção auto_reinit):

json
"auto_reinit": {
  "enabled": true,
  "default_window": "22:30-04:00",
  "max_concurrent": 1,
  "nodes": {
    "node-a": { "window": "23:00-05:00",
                "databases": { "sales/employee.fdb": "01:00-03:00" } }
  }
}
  • Janela: por banco → por nó → global. "always" — a qualquer momento.
  • As janelas são calculadas pelo relógio do host do RCM.
  • max_concurrent — quantas inicializações (manuais e automáticas) podem estar em execução no cluster para o RCM iniciar outra automática.
  • A inicialização automática passa pelas mesmas verificações de espaço e de GUID que a inicialização manual. O autor do comando é system:autoreinit.
  • remove_old_replica_when_short (a partir do HQbird 2027.2.24, a linha Excluir a réplica antiga quando faltar espaço) — desativada por padrão. Se ativada, a inicialização automática envia a flag Excluir a réplica antiga (4.4). O RCM a envia somente se a própria réplica está em NEEDS_REINIT ou a causa NEEDS_REINIT do mestre a nomeia. Para uma réplica que está IN_SYNC ou LAGGING a flag nunca é enviada. Se o nó é uma versão mais antiga, o RCM inicia a mesma inicialização sem a flag.
  • Depois de alterar, reinicie o RCM.

Adiar no cartão do mestre desativa a inicialização automática de um único banco por 1 hora, 4 horas, 24 horas ou até ser cancelado. A inicialização manual permanece disponível.

5.9. Erros

Erro Causa O que fazer
insufficient disk space on master / on replica, 507 espaço insuficiente. Durante a reinicialização a cópia antiga ocupa espaço até o fim capítulo 4.4; na réplica (a partir do HQbird 2027.2.24) — a caixa Remover a réplica antiga (5.1)
node_too_old (a partir do HQbird 2027.2.24) a caixa Remover a réplica antiga está marcada, mas o nó mestre ou réplica é uma versão antiga atualize o nó como indicado no texto do erro ou execute sem a caixa
engine_busy, reclaim_in_progress (a partir do HQbird 2027.2.24) a réplica não pode apagar a cópia antiga agora: o Firebird ou este banco está ocupado tente mais tarde (5.6)
replica_removed_for_reinit, par NEEDS_REINIT (a partir do HQbird 2027.2.24) a réplica apagou a cópia antiga, mas a inicialização não terminou inicie a inicialização de novo (4.4)
publication_off (a partir do HQbird 2027.2.24) a publicação do mestre está desativada ou não contém tabelas com chave Sincronizar publicação e inicializar (5.1)
long_transactions, “O reinit suave está aguardando transações longas” transações de escrita longas estão abertas 5.4
long_transactions, “o arquivo do mestre ainda não contém nenhum segmento” primeira inicialização sob carga Padrão (5.4)
reinit_pre_publication_transactions transações iniciadas antes de a publicação ser ativada reconecte as aplicações, tente de novo
duplicate_guid dois bancos mestres com o mesmo GUID remova a cópia; se o passo NOVO GUID foi pulado na promoção a mestre — -force (capítulo 8.4)
license_paused o fbagent do mestre não tem licença capítulo 2.8
409 orphaned o banco está fora da varredura do mestre capítulo 3.8
incompatible_engine versões principais do Firebird diferentes capítulo 4.3
target_not_replica um banco de trabalho está no lugar da réplica (ele foi tornado normal) veja abaixo
target_other_replica (a partir do HQbird 2027.2.24) uma cópia de outro banco deste nó está no lugar da réplica veja abaixo
restart_not_allowed o Firebird da réplica também serve bancos mestres 5.6, a caixa “Permitir … parar o Firebird”
fbagent_required o fbagent não está instalado na réplica capítulo 1
nbackup backup lock already active um backup nbackup está em andamento 5.7
… -L did not finish in 2m0s and was stopped nbackup -L no mestre não terminou em 2 minutos, por isso o nó o parou tente de novo; se o erro se repetir, verifique o Firebird do mestre (firebird.log)
reinit already in progress for this database a inicialização deste banco já está em execução espere ela terminar

target_not_replica. Um banco de trabalho está no lugar da cópia: ele foi tornado normal (o arquivo <database>.hqcluster-normal.json existe) ou não está em modo réplica. O nó não sobrescreve um banco de trabalho. Se ele precisa ser substituído, um pedido à API do nó com overwrite_non_replica: true (não há botão para isso no RCM) substituirá o arquivo e guardará o antigo como <database>.pre-reinit-<hora UTC>.fdb.

target_other_replica (a partir do HQbird 2027.2.24). A réplica coloca a cópia em <databases.root>/<id do mestre>/<caminho do banco>. O id do mestre é único somente dentro do próprio cluster, por isso dois bancos podem acabar com o mesmo caminho. O nó réplica não sobrescreve uma cópia que pertence a outro dos seus bancos: o erro nomeia esse banco e o mestre dele. O nó também reconhece uma cópia cujo caminho está registrado de outro modo (um link simbólico ou junção no caminho, um nome curto de pasta do Windows). overwrite_non_replica não limpa este erro. Mova uma das cópias para outra pasta ou remova esse banco da réplica, depois inicie a inicialização de novo. O nó vê somente os próprios bancos: dois nós réplica no mesmo host precisam ter pastas de réplica diferentes (databases.root).

5.10. Como verificar o resultado

  1. Bancos de dados: o par mestre — réplica no grupo está Ok, estado IN_SYNC.

  2. Verificar no cartão do mestre: os nós contam as linhas das tabelas da lista de tabelas do banco (capítulo 3.1) no mestre e na réplica e as comparam. Verifique em horário calmo: com escritas ativas os números podem diferir.

    Com o HQbird 2027.2.24 a página de resultado nomeia a lista de cada lado (por exemplo, “a lista própria deste banco” ou “tabelas da publicação (lista não definida)”). O RCM conta a réplica usando a lista do mestre. Uma tabela ausente dos dois bancos é mostrada como “não está no banco” e não é contada como erro. Se nenhuma tabela foi comparada, o resultado é “Nenhuma tabela para comparar”, não uma divergência. Se a comparação não terminou no tempo previsto, o resultado é “Não comparado (limite de tempo)”, o que também não é uma divergência.

Resultado da verificação
Resultado da verificação
Command
hqbirdrcm verifydata -master node-a -master-db <db_id> -replica node-b -replica-db <db_id>
  1. Verificação periódica (opcional): a página Verificação de dados, Ativar em todos os nós. Com o HQbird 2027.2.24 o nó aplica as configurações imediatamente, sem reinício do serviço do nó: depois de Salvar o RCM escreve “Salvo e já em vigor”. O nó 2027.5.7 precisa que o serviço hqclusternode seja reiniciado, e o RCM 2027.2.24 diz isso. Os nós comparam as contagens de linhas sozinhos quando o mestre e a réplica estão no mesmo segmento. Uma divergência levanta o alerta data_mismatch; então execute Verificar.

Uma tabela que o operador removeu da publicação é mostrada como “não publicada”, não como uma divergência.

6. Configuração da publicação

A publicação diz ao Firebird mestre de quais tabelas gravar as alterações nos segmentos. Sem ela, a réplica não recebe nada.

6.1. O que é a publicação

No Firebird 4 e 5, as tabelas a replicar são definidas pela publicação RDB$DEFAULT:

  • Publicação ativada — em RDB$PUBLICATIONS ela tem RDB$ACTIVE_FLAG = 1 (o comando ALTER DATABASE ENABLE PUBLICATION).
  • Tabelas publicadas — a lista em RDB$PUBLICATION_TABLES.

O Firebird grava alterações nos segmentos somente para tabelas publicadas e somente quando a publicação está ativada. Registrar o banco (capítulo 3) não ativa a publicação. Ela é ativada por Sincronizar publicação (6.2).

O nó mestre verifica a publicação a cada hora (limits.publication_check_interval_sec, 3600 por padrão). Se ela está desativada, o nó a verifica a cada 2 minutos.

Na página Bancos de dados, o banco mestre tem um ícone:

Ícone Significado
publicação LIGADA publicação ativada
publicação DESLIGADA o Firebird não grava nada nos segmentos, as réplicas não recebem alterações
publicação desconhecida o nó não conseguiu ler o estado

O filtro Publicação desligada mostra bancos com publicação desativada ou desconhecida.

Se um banco com publicação desativada já tem uma réplica, o mestre levanta o alerta master_publication_off.

Com o HQbird 2027.2.24, o mestre levanta este alerta também quando recusou inicializar um banco com o erro publication_off (capítulo 5.1): a publicação está desativada ou não contém tabela com chave. O nível do alerta:

  • warn — o banco ainda não tem réplica: a inicialização espera a publicação;
  • serious — o banco já tem uma réplica;
  • info — o operador desativou a publicação.

O alerta é limpo quando a publicação é corrigida ou outra inicialização começou.

6.2. Sincronizar publicação

Linha do mestre: publicação desativada
Linha do mestre: publicação desativada

Onde clicar:

  • na linha do banco mestre na página Bancos de dados. Quando a publicação está desativada, o botão fica ao lado do ícone;
  • na página do banco;
  • para vários bancos: marque as linhas, na lista Ação selecione Sincronizar publicação. O RCM enviará um comando separado para cada banco.
Confirmação da sincronização da publicação
Confirmação da sincronização da publicação

O que o nó faz (uma única transação):

  1. Ativa a publicação. Se o operador a desativou (6.4), ele não a ativa.
  2. Adiciona à publicação todas as tabelas com chave que ainda não estão lá.
  3. Remove da publicação as tabelas sem chave e as tabelas que o operador excluiu (6.3).
  4. Desativa a adição automática de tabelas novas (EXCLUDE ALL FROM PUBLICATION, depois adiciona as tabelas necessárias). Somente o nó define a composição da publicação.
Linha do mestre depois da sincronização: publicação ativada
Linha do mestre depois da sincronização: publicação ativada

Uma tabela com chave — uma tabela permanente de usuário que tem uma chave primária ou um índice único ativo. Tabelas de sistema e temporárias não são publicadas.

A sincronização também remove da publicação tabelas sem chave que o DBA adicionou manualmente.

Se a composição já está correta, o nó não altera nada.

Quando o nó recusa:

Código Motivo
no_publications HQbird 2.5/3.0 (6.6)
not_master o nó não é o mestre
reinit_in_progress a inicialização deste banco está em andamento
orphaned, database_failed, file_missing o banco está fora da varredura, em erro, ou não tem arquivo

Todos os bancos do nó de uma vez — somente pela linha de comando. Na página Comandos o resultado é mostrado por banco: concluído, ignorado ou erro. Bancos no estado FAILED ou SEEDING e bancos sem arquivo são ignorados.

O mesmo pela linha de comando

Command
hqbirdrcm setpublication -node node-a -db <db_id>   # one database
hqbirdrcm setpublication -node node-a               # all node databases

O comando espera até 5 minutos e imprime uma linha para cada banco. Em erro o código de saída é 1. -nowait — não esperar o resultado.

6.3. Tabelas da publicação

A página “Tabelas da publicação”
A página “Tabelas da publicação”

Abra Tabelas da publicação na linha do banco mestre.

A página mostra:

  • o estado da publicação (ligada/desligada, desativada pelo operador) e os contadores;
  • cada tabela: nome, chave e estado.
Estado Significado
publicada as alterações vão para os segmentos
ainda não publicada uma tabela com chave, será adicionada na sincronização
excluída o operador a removeu da publicação
sem chave não pode ser publicada

Na coluna da chave — a chave primária ou, se não houver, o índice único com o menor número de campos.

Por que uma tabela sem chave não pode ser publicada. A réplica procura a linha para UPDATE e DELETE pela chave. Sem chave ela não encontrará a linha. Adicione uma chave primária ou um índice único, depois sincronize a publicação.

Excluir da publicação / Devolver à publicação:

  1. Marque as tabelas.
  2. Clique em Excluir da publicação ou Devolver à publicação.
  3. O nó salva a lista e sincroniza a publicação imediatamente.
Confirmação de “Excluir da publicação”
Confirmação de “Excluir da publicação”

A lista de tabelas excluídas é armazenada no nó mestre. A sincronização não a altera. Quando uma réplica é promovida a mestre (capítulo 8), a lista passa para o novo mestre.

Verificar (capítulo 5.10) mostra uma tabela excluída como “não publicada”, não como uma divergência.

6.4. Ativação e desativação da publicação

Na página Tabelas da publicação: Desativar publicação / Ativar publicação.

  • Desativar é escolha do operador. A sincronização não reativa a publicação.
  • Alterações feitas enquanto a publicação está desativada (ou enquanto uma tabela está excluída) não são enviadas à réplica, mesmo depois de ela ser ativada.
  • Depois de ativar, clique em Verificar (capítulo 5.10). Se os dados divergirem — reinicialize a réplica (capítulo 5).

6.5. Uma tabela nova

Uma tabela nova não entra na publicação sozinha: o nó desativa a adição automática.

Depois do DDL:

  1. Crie uma chave primária ou um índice único na tabela.
  2. Clique em Sincronizar publicação.
  3. Peça às aplicações que se reconectem se a reinicialização for necessária. O Firebird não grava nos segmentos transações que começaram antes de a publicação ser ativada; COMMIT RETAINING mantém essa transação aberta. A inicialização espera por essas transações e depois falha com reinit_pre_publication_transactions (capítulo 5.4).
Uma tabela nova no estado “ainda não publicada”
Uma tabela nova no estado “ainda não publicada”

Linhas gravadas na tabela nova antes da sincronização não chegarão à réplica. Se houver alguma, verifique os dados e, se necessário, reinicialize a réplica.

6.6. HQbird 2.5 e 3.0

O HQbird 2.5 e 3.0 não têm publicações. O Firebird grava segmentos se o arquivo do plugin replconf contém um bloco mestre. Os botões de publicação nesses nós ficam ocultos, e a API responde com no_publications.

O conjunto de tabelas é definido pelos parâmetros do mecanismo:

Parâmetro Significado
include_filter quais tabelas replicar: nomes ou padrões separados por vírgulas; vazio — todas
exclude_filter quais tabelas não replicar

Os parâmetros são alterados em Configurações → Parâmetros de replicação (capítulo 7.1). A página Tabelas da publicação os mostra somente leitura, com um link Alterar nas configurações do mecanismo. O Firebird lê os valores novos depois de um reinício.

Tabelas da publicação no HQbird 3.0: filtros do mecanismo
Tabelas da publicação no HQbird 3.0: filtros do mecanismo

O plugin replconf. O nó grava o próprio arquivo replconf.hqcluster.hqbird na pasta do Firebird. O Firebird o lê somente quando replconf.properties aponta para ele. O plugin precisa ser ativado uma vez:

  1. Configurações → Nós, o bloco Plugin de replicação (HQbird 2.5 / 3.0). O bloco mostra para onde replconf.properties aponta e os problemas que o nó encontrou.

Plugin não ativado: replconf.properties aponta para o arquivo do HQbird DataGuard
Plugin não ativado: replconf.properties aponta para o arquivo do HQbird DataGuard
  1. Ativar… A janela lista o que o nó fará: instalar o plugin, apontar replconf.properties para o arquivo do nó, migrar as entradas do arquivo antigo. Escolha quando: Somente dentro da janela de reinício do nó ou Agora, ignorando a janela de reinício.

Janela de ativação do plugin
Janela de ativação do plugin
  1. Depois do reinício do Firebird, o campo Ativado mostra “sim: o mecanismo lê o arquivo do nó”.

Plugin ativado
Plugin ativado

A ativação reinicia o Firebird e afeta todos os bancos deste Firebird. Faça-a em um período calmo.

7. Outras opções de replicação

7.1. Parâmetros de replicação

Configurações → Parâmetros de replicação, formulário do assistente
Configurações → Parâmetros de replicação, formulário do assistente

A página Configurações → Parâmetros de replicação altera as chaves em replication.conf para os bancos selecionados ou para o nó como um todo.

  1. Adicionar mestre e réplicas — selecione os bancos. O RCM os agrupa por versão do Firebird e papel: um formulário separado para mestres e para réplicas.

  2. Para cada parâmetro, escolha uma ação:

    Ação O que faz
    sem alterações o valor não é alterado
    definir valor um valor novo
    redefinir (para o nível acima) remover o próprio valor, tomar o valor do nível acima
    não gravar (valor do Firebird) a chave não é gravada, vale o valor do Firebird
  3. Escolha onde aplicar: Nos bancos selecionados ou Como padrão dos nós deles.

  4. Pré-visualizar — os nós verificam os valores sem alterar nada.

Pré-visualização das alterações
Pré-visualização das alterações
  1. Aplicar. O RCM envia o comando a cada nó.

De onde vem o valor (a coluna Atual):

Origem Valor
este banco definido para o banco
valor do nó definido como padrão do nó
valor interno do nó o valor do nó a partir do código
valor do Firebird a chave não é gravada
do arquivo (ainda não definido aqui) o valor de replication.conf, o RCM ainda não o alterou
definido pelo nó somente leitura (caminhos, prefixos)

Um nó que não responde mostra os bancos dele como indisponíveis para seleção. As alterações exigem o fbagent (caso contrário fbagent_required).

Quem reinicia o Firebird (o Firebird lê replication.conf somente na inicialização):

Nó Quem
mestre você o reinicia: o mestre nunca reinicia o Firebird sozinho
réplica com firebird.auto_restart: never você
réplica cujo Firebird também serve os bancos do mestre você
outras réplicas o nó o reinicia na própria janela de reinício

Para um reinício manual, a página tem um botão Reiniciar o Firebird.

7.2. Principais parâmetros

Mestre, Firebird 4/5:

Parâmetro Rótulo no RCM Valor do nó Firebird Dica
journal_archive_timeout Tempo limite do arquivo 10 s 60 s quantos segundos o Firebird espera antes de fechar um segmento incompleto. Mais baixo — a réplica fica mais perto do mestre. Precisa ser menor que limits.data_check_quiet_sec (90)
journal_segment_count Número de segmentos 64 8 quantos segmentos podem residir em .ReplLog. Precisa ser maior que limits.backlog_critical (48)
journal_segment_size Tamanho do segmento — 16 MB de 1 MB a 512 MB; o receptor não aceitará mais de 512 MB
buffer_size — 1 MB

O nó também grava log_errors = true (não pode ser alterado) e disable_on_error = true.

Réplica, Firebird 4/5:

Parâmetro Rótulo no RCM Firebird Valor
apply_idle_timeout Pausa ociosa 10 s pausa quando não há segmentos novos
apply_error_timeout Pausa após erro de aplicação 60 s pausa antes de tentar de novo depois de um erro
verbose_logging nó: true replication.log detalhado; não é recomendado desativar
skip_upddel_without_pk nó: true pular UPDATE/DELETE em tabelas sem chave

Somente Firebird 5: include_filter, exclude_filter, cascade_replication.

HQbird 2.5/3.0 — chaves log_* com o mesmo significado: log_archive_timeout, log_segment_count, log_segment_size (não menor que 2 × buffer_size). A chave alert_command é definida somente em node.json.

Uma dica para cada parâmetro está disponível no formulário do RCM.

7.3. Armazenamento do arquivo

O arquivo <database>.LogArch no mestre é limpo em etapas:

  1. Segmentos que foram aplicados por todas as réplicas e que são mais antigos que retention_days.
  2. Se o espaço livre é menor que free_space_floor_gb — segmentos aplicados mais novos que o período de retenção. Alerta disk_serious_cleanup.
  3. Se o espaço ainda está baixo — segmentos não aplicados, começando pelos mais antigos. A réplica recebe NEEDS_REINIT, alerta replication_paused_reinit_scheduled.
Parâmetro (Configurações → Nós, Armazenamento e arquivos) Padrão
limits.retention_days — Retenção do arquivo, dias 2
limits.retention_min_kept_segments — Sempre manter os últimos segmentos 0 (desativado)
limits.free_space_floor_gb — Espaço livre mínimo 1 GB
Configurações → Nós, “Armazenamento e arquivos”
Configurações → Nós, “Armazenamento e arquivos”

Limpar o arquivo manualmente:

Command
hqbirdrcm cleanuparchive -node node-a              # stages for all databases on the node
hqbirdrcm cleanuparchive -node node-a -db <db_id>  # a single database

-orphaned (somente junto com -db) apaga todos os segmentos do banco no estado ORPHANED (capítulo 3.8). Para qualquer outro banco o nó responderá not_orphaned. Nunca execute -orphaned no doador da promoção (capítulo 8.5).

7.4. Transferência: compressão, velocidade, janelas

A compressão é definida por par: Configurações → Nós → Pares, coluna compress.

Valor Significado
vazio ou none sem compressão (padrão)
zstd compressão zstd

A alteração entra em vigor imediatamente. A compressão é útil em uma rede lenta.

Velocidade de transferência de segmentos (Configurações → Nós, Transferência e reinicialização):

Parâmetro Padrão Quando entra em vigor
limits.channel_a_mbps — Velocidade de transferência de segmentos 50 MB/s imediatamente
limits.channel_a_burst_mbps — Pico de transferência de segmentos 200 MB imediatamente

A unidade é mebibyte (MiB), embora o nome diga “mbps”. O pico não pode ser menor que a velocidade.

Configurações → Nós, “Transferência e reinicialização”
Configurações → Nós, “Transferência e reinicialização”

Janelas de tempo (Janelas de tempo):

Parâmetro Padrão Quando entra em vigor O que afeta
windows.restart_window — Janela de reinício do Firebird mestre 22:00-05:00, réplica always imediatamente quando o nó réplica pode reiniciar o Firebird
windows.transfer_window — Janela de transferência 23:00-05:00 depois do reinício do nó velocidade plena de inicialização (capítulo 5.5)

O rótulo ao lado de cada campo mostra quando a alteração entra em vigor: imediatamente ou reinício do nó.

Configurações → Nós, “Janelas de tempo”
Configurações → Nós, “Janelas de tempo”

7.5. Verificação de dados

  • Verificar — uma comparação pontual da contagem de linhas no mestre e na réplica (capítulo 5.10).
  • Verificação de dados — uma comparação periódica (capítulo 5.10). O nó faz a comparação quando o mestre e a réplica estão no mesmo segmento.
  • Com o HQbird 2027.2.24, as configurações de verificação entram em vigor imediatamente depois de Salvar; não é necessário reiniciar o serviço do nó. O RCM mostra “Salvo e já em vigor”. Depois de ativar, a primeira verificação corre depois de um intervalo. Depois de desativar, uma verificação em andamento é interrompida e não grava nada. O intervalo novo é contado a partir do fim da última verificação. Manter, dias, Limite da consulta, Quieto e Gerador de progresso entram em vigor a partir da próxima verificação.
  • O nó 2027.5.7 lê essas configurações somente na inicialização: depois de Salvar, reinicie o serviço hqclusternode nesse nó. O RCM 2027.2.24 mostra “Salvo, mas ainda não em vigor” e indica o motivo.
  • Quais tabelas comparar é definido pela lista de tabelas do banco (capítulo 3.1). Com o HQbird 2027.2.24, cada banco pode ter a própria lista: o campo no registro ou o bloco Tabelas de acompanhamento da sincronização na página do banco do mestre (capítulo 3.3). A página Verificação de dados mostra qual lista foi usada, e o número de tabelas “não está no banco”. Em 2027.5.7 a lista é por nó (sync_tables).
  • Tabelas excluídas da publicação são mostradas como “não publicada” (capítulo 6.3).
Página de verificação de dados
Página de verificação de dados

7.6. Alertas

Página de alertas
Página de alertas

A página Alertas. Ações:

  • Reconhecer — o alerta permanece visível mas é marcado reconhecido;
  • Silenciar por 60 min — ocultar por uma hora;
  • Excluir / Excluir todos com este código — o RCM passa a exclusão ao nó que levantou o alerta. Se a causa permanece, o alerta aparecerá de novo.
Command
hqbirdrcm clearalerts -code backlog_warn   # also -id, -acked, -all

A partir do HQbird 2027.2.33, o RCM envia alertas para o Telegram, para um webhook (Slack, Teams, JSON) e por e-mail. Os canais são configurados na seção notify.channels do arquivo rcm.json. O bloco Canais de notificação na página Alertas mostra os canais e envia uma mensagem de teste. O RCM informa problemas de nível warn e acima: um problema apareceu, ficou mais grave, ou foi limpo. Sem canais, o RCM não envia nada. Versões anteriores não têm envio: acompanhe a página Alertas ou consulte a API do RCM.

Principais códigos:

Código Significado
backlog_warn / backlog_critical 32 / 48 segmentos não arquivados em .ReplLog
disk_serious_cleanup o arquivo está sendo limpo na etapa 2 (7.3)
replication_paused_reinit_scheduled segmentos não aplicados apagados, inicialização necessária
shipping_paused o envio ao par está suspenso (7.7)
apply_error, replication_stopped, replication_unrecoverable_error a réplica não consegue aplicar um segmento
replication_guid_mismatch o GUID do banco mestre mudou
segment_missing, segment_rejected, sequence_gap problemas na sequência de segmentos
firebird_down, firebird_log_error o Firebird não está em execução ou está registrando erros
firebird_not_answering a partir do HQbird 2027.2.30: o Firebird não respondeu a uma conexão de banco por um minuto (travamento). Isso inclui também uma conexão que não se estabeleceu por tempo esgotado; firebird_down é somente uma recusa de conexão
master_publication_off a publicação está desligada (capítulo 6); a partir do HQbird 2027.2.24 e depois de uma falha publication_off (capítulo 6.1)
replica_removed_for_reinit a partir do HQbird 2027.2.24: a réplica apagou a cópia antiga para a inicialização, e ainda não há cópia nova (capítulo 4.4)
orphaned_database banco fora da varredura (capítulo 3.8)
restart_required_after_reinit o Firebird da réplica precisa de um reinício (capítulo 5.6)
data_mismatch a verificação periódica encontrou uma divergência
license_paused o fbagent não tem licença (capítulo 2.8)

7.7. Pausa do envio

Na página Bancos de dados, na linha do mestre: Pausar o envio / Retomar o envio. Para vários bancos — pela lista Ação.

Command
hqbirdrcm pauseshipping  -node node-a -db <db_id>
hqbirdrcm resumeshipping -node node-a -db <db_id>
Confirmação de pausar o envio
Confirmação de pausar o envio
Linha do mestre durante uma pausa
Linha do mestre durante uma pausa
  • A pausa permanece em vigor até Retomar o envio ou até a inicialização.
  • O Firebird mestre continua a gravar segmentos. O arquivo .LogArch cresce: enquanto a réplica está parada, a etapa 1 (7.3) não apaga os segmentos dela.
  • Uma pausa longa pode chegar à etapa 3 e a NEEDS_REINIT. Fique de olho no espaço.
  • O botão está ausente se o banco não tem réplica ou a publicação está desativada. O ícone Pausa: sem licença significa uma pausa relacionada à licença (capítulo 2.8); ela é encerrada somente por uma licença.

7.8. Logs

Log Onde
Nó <pasta de instalação>/logs/node-YYYYMMDD.jsonl (/opt/hqclusternode ou C:\hqclusternode), 32 MB cada, 20 arquivos
replication.log e firebird.log do Firebird caminhos em node.json: firebird.replication_log, firebird.firebird_log
RCM Linux: journalctl -u hqbirdrcm
Auditoria do RCM rcm-data/audit.jsonl

Log remoto do nó — a página Logs: selecione um nó e uma fonte (replication.log, firebird.log, agente do nó).

Página de logs
Página de logs
Command
hqbirdrcm getlogs -node node-b -source replication -tail 200

8. Como passar uma réplica para um banco comum

Há dois caminhos:

Caminho Quando O que você obtém
Tornar normal, 8.1 você precisa de uma cópia de trabalho separada: relatórios, testes, uma falha sem um mestre novo um banco comum fora da replicação
Promover a mestre, 8.3 a réplica deve se tornar o novo mestre um banco gerido por um nó companheiro com o papel de mestre

Nenhum dos caminhos pode ser desfeito pela interface.

8.1. Tornar normal

Lista “Ação” da réplica: o item “Tornar normal”
Lista “Ação” da réplica: o item “Tornar normal”
  1. Bancos de dados, lado da réplica: marque as linhas da réplica.

  2. Na lista Ação, selecione Tornar normal e confirme. Não há botão separado na linha. Também não há comando de linha de comando.

Confirmação de “Tornar normal”
Confirmação de “Tornar normal”
3. O nó réplica: - executa `gfix -replica none` (HQbird 2.5/3.0: `gfix -replica {}`). Se o banco está ocupado aplicando segmentos, o nó o coloca em desligamento `single` por alguns segundos (`gfix -shut single -force 0`), limpa o modo réplica e o devolve com `gfix -online normal`. **Todas as conexões deste banco são derrubadas**; - grava o arquivo marcador `.hqcluster-normal.json` (hora, autor, db_id, GUID); - começa a limpar a fila `.Incoming` (8.2). 4. O RCM mostra o banco no grupo **Não é réplica (normal)**.
A página “Bancos de dados” depois de “Tornar normal”
A página “Bancos de dados” depois de “Tornar normal”

Depois disso, o banco está aberto para escrita.

Remova o bloco da réplica de replication.conf. O nó o remove na próxima varredura, e o Firebird lê o arquivo na inicialização:

Command
hqbirdrcm scansync -node node-b
hqbirdrcm restartfirebird -node node-b

Até lá, erros “o banco não está em modo réplica” para este banco não são levantados como alertas.

O arquivo marcador protege o banco. A inicialização não sobrescreverá esse banco: ela é recusada com target_not_replica (capítulo 5.9). Apagar somente o marcador não basta: o nó também verifica o modo réplica no cabeçalho do banco. A caixa Excluir a réplica antiga (capítulo 4.4) também não apaga esse banco.

Com o HQbird 2027.2.24, enquanto a réplica está apagando a cópia antiga deste banco para a inicialização, Tornar normal é recusado com reclaim_in_progress: tente mais tarde.

Se o banco precisa voltar a ser uma réplica — somente uma inicialização nova com sobrescrita serve. Isso é feito pela API do nó (overwrite_non_replica: true); não há esse botão no RCM. O arquivo antigo é salvo como <database>.pre-reinit-<hora UTC>.fdb, e o marcador é apagado.

8.2. O que acontece com os segmentos

  • Até o nó ter varrido os bancos, o mestre continua a enviar segmentos. A cada 30 segundos o nó réplica apaga os segmentos antigos e mantém somente os últimos 100 (keep_segments).
  • Depois da varredura, o registro do banco na réplica fica no estado ORPHANED. O nó réplica responde ao mestre com unknown_database. O mestre para de enviar segmentos a esta réplica, para de manter um arquivo para ela e a verifica de novo a cada 10 minutos.
  • As outras réplicas deste banco não são afetadas.
  • O registro ORPHANED pode ser excluído (capítulo 3.8): hqbirdrcm forgetdatabase. O próprio arquivo do banco não é excluído.

8.3. Promover a mestre

A réplica se torna o novo mestre. O arquivo dela permanece no lugar, e o controle passa ao nó companheiro.

Condições:

Condição Recusa
o banco é uma réplica bad_request
um nó com o papel de mestre — o companheiro — está em execução no mesmo host (o mesmo rótulo host em rcm.json, capítulo 2.1) no_companion
a promoção deste banco ainda não está em andamento already_running
não há inicialização para este banco nem a partir do mestre dele reinit_running

O RCM não cria o nó companheiro: instale-o de antemão (capítulo 1).

Como começar:

  • na linha da réplica, Promover a mestre, ou na lista Ação;

  • pela linha de comando:

    Command
    hqbirdrcm promotetomaster -node node-b -db <db_id>   # -timeout 10m

O RCM pedirá confirmação e nomeará o nó companheiro.

Confirmação “Promover a mestre?”
Confirmação “Promover a mestre?”

Passos (visíveis na linha da réplica, nomes em inglês):

Nº Passo O que faz
1 TURN TO NORMAL como em 8.1; pulado se o banco já é normal
2 NEW GUID um GUID novo do banco no lugar (8.4)
3 EXCLUDE ON DONOR o nó réplica (doador) exclui o arquivo da varredura dele (exclude_paths)
4 ENROLL ON o nó companheiro registra o arquivo como banco mestre
5 PUBLICATION SYNC sincronização da publicação; a lista de tabelas excluídas é trazida do mestre antigo (capítulo 6.3)
6 RESTART DONOR FIREBIRD reinício do Firebird do doador, sem esperar uma janela
7 RESTART FIREBIRD reinício do Firebird do companheiro, sem esperar uma janela
8 FINALIZE a linha do doador se torna Réplica fantasma; o mestre antigo pode se tornar Mestre degradado (8.5)
Passos da promoção na linha da réplica
Passos da promoção na linha da réplica

No HQbird 2.5 e 3.0 não há publicações: o passo PUBLICATION SYNC termina com o texto “este mecanismo não tem publicação”.

Passos da promoção no HQbird 3.0 (Windows)
Passos da promoção no HQbird 3.0 (Windows)

Se o doador e o companheiro usam o mesmo Firebird, esse Firebird é reiniciado: as conexões de todos os bancos dele são derrubadas.

Se um passo falha, o trabalho fica failed com o texto do erro. Corrija a causa e clique em Promover a mestre de novo: os passos concluídos não são repetidos. Se o RCM reinicia durante a promoção, o trabalho também ficará failed — verifique o estado dos nós e tente de novo.

Licença. Se o fbagent no host do mestre não tem licença, o mestre pausou o envio. A promoção ainda é possível. O RCM avisará: as alterações feitas depois do início da pausa serão perdidas.

8.4. GUID novo

Depois da promoção, o banco precisa receber o próprio GUID. Caso contrário o novo mestre grava segmentos sob o GUID do mestre antigo, e as réplicas dele são recusadas com duplicate_guid.

O passo NEW GUID no nó:

  1. gfix -shut single -force 0 — todas as conexões do banco são encerradas;
  2. nbackup -L, depois nbackup -F sem -SEQUENCE;
  3. apaga <database>.delta;
  4. verifica o cabeçalho: GUID novo, REPLICATION_SEQUENCE = 0;
  5. gfix -online normal.

O Firebird não é reiniciado. O método funciona em todas as versões (2.5, 3.0, 4.0, 5.0).

Se o passo foi interrompido, o nó emite o alerta newguid_interrupted. O banco pode permanecer em desligamento single. Repita Promover a mestre: o passo continuará.

O passo é pulado (o texto começa com skipped:) se o nó doador é uma versão antiga ou o arquivo já tem o próprio GUID.

Depois de um GUID novo, a cadeia antiga de nbackup deixa de servir. Faça uma cópia nbackup nova de nível 0.

Se o banco foi criado com ADD DIFFERENCE FILE, o .delta dele está em outro lugar: apague-o manualmente.

8.5. Depois da promoção

Registro do doador. No nó réplica o banco permanece ORPHANED, o caminho permanece em exclude_paths, e a pasta .Incoming e o rótulo permanecem. No RCM esta é a linha Réplica fantasma com os botões Abrir no novo mestre e Limpar.

Linha do doador: «Réplica fantasma»
Linha do doador: «Réplica fantasma»
  • Para remover a linha, clique em Limpar. Isso altera somente o RCM.
  • Para remover o registro do doador do nó réplica, execute forgetdatabase. O arquivo e a pasta .Incoming permanecem. O HQbird 2027.2.30 e mais novos não recusam o comando (mailbox_active), porque o caminho do doador está em exclude_paths. Nós de versões anteriores o recusam enquanto o arquivo e a pasta .Incoming estão presentes.
  • Nunca execute cleanuparchive -orphaned no doador. O doador e o companheiro compartilham a mesma pasta <database>.LogArch. O comando apagará o arquivo vivo do novo mestre.

Mestre antigo.

  • Se o doador era a última réplica em funcionamento dele, o RCM coloca o mestre antigo em Mestre degradado e pausa o envio ao doador (“envio pausado: … (promoção a mestre)”). Não retome o envio ao doador: ele já contém um banco de trabalho. Para limpar este estado, inicialize o banco em outra réplica.

    Mestre antigo: «Mestre degradado», envio pausado
    Mestre antigo: «Mestre degradado», envio pausado
  • A inicialização do mestre antigo para o nó doador será recusada (target_not_replica): ele já contém um banco de trabalho.
  • Se o passo NEW GUID foi pulado, o mestre antigo e o novo têm o mesmo GUID. Nesse caso a inicialização a partir do mestre antigo exige -force (capítulo 5.9).
  • Depois de uma promoção manual o RCM não transforma o mestre antigo em réplica do novo mestre. Pare as aplicações no mestre antigo e remova o banco dele da gestão (capítulo 3.8). Para um banco descrito como serviço, isso é feito pelo Reingresso (8.7).

Mestre novo. Configure uma réplica para ele: nó réplica, pares (capítulo 2), publicação (capítulo 6), inicialização (capítulo 5).

Mestre novo: banco com um GUID novo, ainda sem réplica
Mestre novo: banco com um GUID novo, ainda sem réplica

8.6. Comutação planejada: lista de verificação

Este é o procedimento de uma comutação manual. Para um banco descrito como serviço, o RCM troca o mestre sozinho (8.7). Uma promoção manual não verifica se as aplicações estão gravando no mestre antigo. Procedimento:

  1. De antemão. No host da réplica, um nó companheiro com o papel de mestre está em execução, e os dois nós têm o mesmo rótulo host (capítulo 2.1). Um nó para a réplica futura está pronto para o novo mestre.
  2. Pare as escritas das aplicações no banco do mestre antigo.
  3. Espere até a réplica ter recebido e aplicado tudo: Bancos de dados → IN_SYNC, sem fila.
  4. Verificar (capítulo 5.10): as contagens de linhas coincidem.
  5. Promover a mestre (8.3). Espere o passo FINALIZE.
  6. Verifique: o banco está na lista de mestres do companheiro, publicação ligada.
  7. Passe as aplicações para o novo mestre.
  8. Faça uma cópia nbackup de nível 0 do banco novo (8.4).
  9. Limpe o registro fantasma da linha do doador (8.5).
  10. Conecte a réplica ao novo mestre e inicialize-a (capítulo 5).
  11. Mestre antigo: remova o banco da gestão ou deixe-o como arquivo (8.5).

8.7. Serviços: comutação e failover no RCM

Com o HQbird 2027.2.30, o RCM move o mestre para outro host sozinho. Para isso, o banco é descrito como um serviço: um banco lógico em vários hosts. Em cada host do serviço há um nó mestre e um nó réplica, e o caminho do arquivo do banco é o mesmo. O serviço é criado na página Serviços (a partir do HQbird 2027.2.31) ou com o comando hqbirdrcm services put -id <id> -file <file>.json.

Ação O que faz Comandos
Comutação transferência planejada do mestre sem perda de dados. Depois o mestre antigo se torna automaticamente uma réplica do novo mestre hqbirdrcm switchover -service <id> -check, depois hqbirdrcm switchover -service <id> -to <host>
Failover o host do mestre se perdeu: o RCM promove a réplica. As alterações mais recentes do mestre podem se perder hqbirdrcm failover -service <id> -check, depois hqbirdrcm failover -service <id> -to <host> -accept-data-loss
Reingresso depois de um failover, devolve o host antigo como réplica do novo mestre hqbirdrcm rejoin -service <id>
Retomar tira o serviço do estado failed hqbirdrcm resume -service <id> -check, depois hqbirdrcm resume -service <id>

As mesmas ações estão disponíveis na página do serviço: os botões Comutação…, Failover…, Reingresso… e Retomar….

  • O failover automático fica desligado por padrão. Ele é ativado para cada serviço separadamente: hqbirdrcm policy -service <id> -auto-failover on -max-data-loss 30. Ele exige roteadores. O RCM inicia um failover somente quando o nó mestre está em silêncio, a maioria dos roteadores não enxerga o Firebird do mestre, e o atraso da réplica não passa de max_data_loss_sec.
  • Um roteador (hqclusternode router, Linux) mantém o HAProxy no mestre atual do serviço. As aplicações se conectam a <host do roteador>:<router_port> e não alteram a cadeia de conexão quando ocorre uma troca.
  • Depois de um failover, o RCM isola o mestre antigo (papel fenced) quando ele volta a responder. Traga-o de volta com o comando rejoin.