Cluster e replicação HQbird Cluster

O master grava as alterações em segmentos e os envia às réplicas por um canal seguro. O próprio nó faz a cópia do banco de dados para uma nova réplica, via nbackup, enquanto os usuários trabalham. O gerenciador do cluster (RCM) mostra o atraso, as filas e os erros de todos os nós. Ele também move o master para outro host: de forma planejada, sem perda de dados, ou de emergência, quando o host do master foi perdido.

  • Firebird 2.5 · 3 · 4 · 5
  • nbackup cópia sem parar o master
  • switchover sem perda de dados
  • failover manual ou por regra
  • roteador a string de conexão não muda
  • mTLS em todos os canais

Nós · RCM · topologias

Como o cluster funciona

Ao lado de cada Firebird roda um nó. O nó tem um papel: master ou réplica. O nó do master envia segmentos, o nó da réplica os recebe, e o Firebird da réplica os aplica à sua cópia do banco de dados.

Há um RCM por cluster. Ele roda em qualquer host que alcance todos os nós. Os nós enviam estatísticas a ele, e ele repassa aos nós os comandos do operador. O RCM liga master e réplica pelo GUID do banco de dados, não pelo nome do nó.

O RCM não se instala sozinho. Ele é ligado em um host quando é preciso um cluster. Na frente das aplicações é possível colocar um roteador: ele sempre leva as aplicações ao master atual.

Diagrama do cluster: nós master enviam segmentos aos nós de réplica, o RCM vigia todos
ComponenteQuantidadeO que faz
Firebird (HQbird)em cada servidor de banco de dadosArmazena os bancos de dados e grava os segmentos de replicação.
fbagentum por instância do FirebirdPara e inicia o Firebird a pedido do nó.
hqclusternodeum por instância e papelConfigura a replicação, transfere segmentos, faz a cópia do banco de dados para a réplica.
hqbirdrcm (RCM)um por clusterInterface web, comandos, alertas, estatísticas. Conduz o switchover e o failover.
Roteador (hqclusternode router)opcional, no host das aplicações, LinuxMantém o HAProxy apontado para o master de cada serviço. As aplicações se conectam ao roteador.
  • Mesma versão principal5.0 no master, 5.0 na réplica. Caso contrário, a réplica recusa antes de transferir dados.
  • HQbird 2.5 e 3.0Replicação via plugin replconf. Filtros definem o conjunto de tabelas.
  • Pasta própria para cada masterA réplica coloca o banco de dados em uma pasta com o nome do nó master. Bancos com o mesmo nome de masters diferentes não entram em conflito.
  • Sem fbagent, sem alteraçõesSe o fbagent não está disponível, o nó recusa qualquer ação que altere a configuração. Ele não funciona “pela metade”.
  • Nó sem RCMO nó pode funcionar sozinho. O RCM é necessário para a visão geral e os comandos.
  • Compressão do canalPara rede lenta: zstd por par, vale na hora.
  • Até 3 hosts sem o HQCenterCada host com um master ou uma réplica ocupa um lugar no cluster. O RCM não aceita um quarto host.

RCM · janela de pareamento · Link hosts · slots

Como montar o cluster

A instalação do HQbird coloca os programas do cluster em cada servidor, mas não os liga. O RCM e a janela de pareamento vêm desligados por padrão. O cluster é montado em três passos: ligar o RCM em um host, abrir a janela de pareamento nos outros, vincular os hosts com um botão.

  1. 1Ligar o RCMem um host: no HQ Monitor ou com fbagent --cluster-init
  2. 2Abrir a janela de pareamentonos outros hosts, por 24 horas
  3. 3Link hostso RCM encontra os agentes, emite os certificados e inicia os nós

Passo 1. RCM em um host

No HQ Monitor, abra a seção “Cluster on this server” e ligue o RCM. Um comando no host faz o mesmo. O agente cria a CA do cluster, o certificado do RCM e o primeiro usuário. No firewall, as portas 7443 e 7444 são abertas.

fbagent --cluster-init <id>

Na instalação, a opção --rcm on (Linux) ou /RCM (Windows) faz o mesmo.

Passo 2. Janela de pareamento

Em cada host que vai entrar no cluster, o agente abre a porta de pareamento por 24 horas. A porta se fecha sozinha quando a janela termina ou quando o agente entrou no cluster.

fbagent --cluster-pairing on

Um botão no HQ Monitor faz o mesmo. Na instalação: --cluster-pairing on ou /DISCOVERY.

Passo 3. Link hosts

No RCM, abra Settings → Link hosts e digite os hosts, um por linha. O botão Check hosts lê as portas 7450–7459 de cada host. Cada agente que respondeu é uma linha da tabela.

  • A linha mostra: porta, instância, versão e porta do Firebird, porta do nó, impressão digital do certificado.
  • Marque as linhas e escolha o master. Uma linha com erro não atrapalha as outras.
  • Link emite um certificado para cada agente, cria os participantes e os vínculos master → réplica.
  • O RCM espera o certificado do agente por até 10 minutos e o início dos nós por até 20 minutos.
hqbirdrcm cluster link -hosts db1,db2,db3 -master db1

Compare a impressão digital na linha com a que o agente mostrou no seu host. Assim você sabe que vincula o servidor certo.

  • Vários agentes em um hostCada agente tem seu slot, de 0 a 9. Porta de pareamento 7450 + slot, portas dos nós 7051 + slot e 7061 + slot. A instalação escolhe o slot; a opção --pairing-port o define explicitamente.
  • Add memberA página Cluster sugere uma porta de nó livre e recusa uma porta ocupada por outro participante deste host.
  • Nomes dos participantes<nome do host>-master e <nome do host>-replica. O RCM não renomeia um participante: um novo nome é um novo participante.
  • Sem janela de pareamentoO RCM emite um token para um agente, válido por 24 horas. No novo host: fbagent --cluster-join com esse token e o hash da CA.
  • Dono do RCMO agente que ligou o RCM no host. Um segundo agente deste host recebe uma recusa. Se o dono foi removido, fbagent --cluster-init --rcm-takeover passa o RCM para outro agente. O cluster recebe uma nova CA, e os participantes precisam ser vinculados de novo.
  • Saída do clusterfbagent --cluster-leave para os nós, fecha as portas deles e apaga os certificados do cluster. As pastas dos nós ficam; --remove-data as apaga. O agente sai sozinho se o RCM o revogou ou removeu o último participante.
  • FirewallO agente abre e fecha sozinho as suas portas do cluster. Uma porta que já estava aberta antes dele, ele não fecha.
  • Remoção do HQbirdO dono do RCM não é removido enquanto outros agentes usam o seu RCM. O assistente de instalação pergunta; o modo silencioso exige --force ou /FORCE.

A página Clusters no HQ Monitor local funciona por meio do agente do host do RCM. Ela não precisa da senha do RCM. A seção “Cluster on this server” só aparece para o administrador.

Inicialização · reinit

Nova réplica sem parar o master

A réplica recebe o banco de dados só do master. O nó do master congela o arquivo com nbackup -L, envia-o em partes e remove o bloqueio logo em seguida. Os usuários do master continuam trabalhando o tempo todo: suas alterações vão para o .delta e depois voltam ao banco de dados.

gbak e cópia manual do arquivo não servem. O gbak altera o GUID do banco de dados e quebra o vínculo master–réplica. A cópia do arquivo de um banco em uso não é consistente.

    Usuários do master

    ativos

    Arquivos

    • Queda de conexãoA transferência continua a partir da última parte recebida. A cópia incompleta fica na réplica por 24 horas.
    • ErroO nó remove o bloqueio, apaga o arquivo incompleto e marca o banco de dados como FAILED. A próxima tentativa começa de um estado conhecido.
    • Transações durante o bloqueioNão se perdem. Firebird 4 e 5: o nó encontra as transações abertas no momento do nbackup -L, e a réplica as repete a partir dos segmentos. HQbird 2.5 e 3.0: o nó espera essas transações terminarem (cerca de um minuto); caso contrário, a cópia não começa.
    • Um banco de dados por vezPor padrão, o nó do master copia um banco de dados. Os outros esperam na fila.
    • Outras réplicas deste bancoDurante a cópia, não recebem segmentos deste banco de dados. Depois se atualizam.
    • Reinicialização automáticaO RCM pode copiar de novo, por conta própria, um banco de dados no estado NEEDS_REINIT, apenas em uma janela definida. Desligada por padrão.

    O modo suave espera as transações longas

    Antes do bloqueio, o nó procura transações de escrita que começaram antes do segmento mais antigo no arquivo de journals do master. Se o arquivo está vazio (primeira cópia), o limite é o momento em que o nó ligou a publicação. A réplica não consegue repetir essas transações e pararia. Por isso, a cópia não começa enquanto essas transações estiverem abertas.

    O RCM mostra as cinco conexões com as transações mais antigas: usuário, cliente, idade, consulta atual. Você pode desconectá-las e repetir a cópia na hora. Enquanto a cópia espera, o arquivo de journals do master não é limpo, mas por no máximo 1000 segmentos. Depois a limpeza continua, e o RCM gera um alerta.

    O modo normal bloqueia o banco de dados na hora, sem a verificação.

    Início da cópia. Modo (suave ou normal), pasta da réplica com verificação, permissão para parar o Firebird da réplica.

    Espaço e velocidade

    OndeO que é necessário
    Master, volume do banco de dadosLivre pelo menos 105 % do tamanho do banco de dados. Durante a cópia, o .delta cresce.
    Réplica, volume do banco de dados105 % mais a reserva do volume free_space_floor_gb (1 GB por padrão). O nó reserva o tamanho total com antecedência; uma segunda cópia não é necessária. Em uma nova cópia, o arquivo antigo fica até o fim. Se não há espaço para os dois arquivos, a opção “Remover a réplica antiga” apaga o arquivo antigo antes da transferência.
    Velocidade à noiteNa janela de transferência (por padrão 23:00–05:00) é constante, por padrão 100 MB/s.
    Velocidade de diaUma fração da velocidade medida do disco, por padrão a metade. Uma cópia iniciada de dia acelera sozinha à noite.

    O espaço é verificado duas vezes e só antes do bloqueio: primeiro pelo RCM com base nas estatísticas, depois pelos nós com medição ao vivo nos dois lados. A verificação do nó não pode ser ignorada: ela evita que o disco encha no meio da cópia.

    Firebird 4 e 5 · HQbird 2.5 e 3.0

    Publicação: quais tabelas vão para a réplica

    O Firebird 4 e 5 grava nos segmentos apenas as alterações das tabelas publicadas, e só com a publicação ligada. Sem ela, as alterações não chegam à réplica. O nó percebe isso e gera um alerta. O botão “Sincronizar publicação” a liga e monta a lista correta de tabelas.

    Tabelas da publicação. A chave de cada tabela e seu estado: publicada, ainda não publicada, retirada, sem chave.

    O que a sincronização faz

    • liga a publicação, a menos que o operador a tenha desligado por conta própria;
    • adiciona todas as tabelas com chave primária ou índice único;
    • remove as tabelas sem chave e as tabelas que o operador excluiu;
    • desliga a inclusão automática de novas tabelas.

    Sem chave, a réplica não encontra a linha para UPDATE e DELETE. Por isso, essa tabela não pode ser publicada: adicione uma chave e sincronize de novo.

    • Verificação a cada horaSe a publicação está desligada, o nó a verifica a cada 2 minutos. Para um banco de dados com réplica, isso é um alerta.
    • Lista de exclusõesFica no nó do master. Quando a réplica é promovida a master, a lista passa para o novo master.
    • Nova tabelaNão entra na publicação sozinha. Crie uma chave e clique em “Sincronizar publicação”.
    • Cópia sem publicaçãoO nó do master recusa a cópia do banco de dados se a publicação está desligada ou não tem tabelas (publication_off). A janela de inicialização oferece “Sincronizar publicação e inicializar”.
    • HQbird 2.5 e 3.0Não há publicações. Os filtros de inclusão e exclusão nas configurações de replicação definem o conjunto de tabelas.

    Alterações feitas enquanto a publicação estava desligada ou a tabela excluída não chegam à réplica, mesmo depois de ligá-la. “Verificar” compara só o número de linhas; não encontra UPDATEs perdidos. Se o banco de dados recebeu gravações com a publicação desligada, copie o banco de dados de novo.

    Atraso · arquivo · alertas · verificação de dados

    Monitoramento: a réplica não fica para trás em silêncio

    Os nós enviam estatísticas ao RCM a cada 30 segundos. Para cada par master–réplica você vê: o último segmento, quantos foram enviados, confirmados e aplicados, a fila e o atraso em segundos.

    Transferência e filas. Uma linha por caminho master → réplica: segmentos, fila e atraso.
    Estado do banco de dadosGrupo no RCMSignificado
    IN_SYNCOkA réplica recebeu todos os segmentos.
    LAGGINGPendingA réplica está atrasada, há segmentos na fila.
    SEEDINGPendingO banco de dados está sendo copiado para a réplica.
    NEEDS_REINITErrorA réplica precisa ser copiada de novo.
    FAILEDErrorA última cópia falhou.

    O arquivo de journals do master é limpo em etapas

    O master guarda os segmentos enviados para que a réplica possa pedi-los de novo. Se falta espaço, ele apaga primeiro o que com certeza não é necessário.

    1. 1Aplicados por todas, mais antigos que o prazoprazo padrão de 2 dias
    2. 2Aplicados, mas mais novos que o prazose há menos de 1 GB livre; alerta
    3. 3Ainda não aplicadospor último; a réplica precisa de uma nova cópia

    Alertas com instruções

    O RCM conhece mais de 20 tipos de alerta, e cada um tem uma instrução do que fazer. Um alerta pode ser confirmado, silenciado por 60 minutos ou removido. Se a causa continuar, o alerta aparece de novo.

    Não há e-mail nem webhook: acompanhe a página “Alertas” ou consulte a API do RCM.

    Alertas. Código, nó, mensagem e ações.
    CódigoO que aconteceu
    backlog_warn / backlog_criticalO master tem 32 / 48 segmentos não arquivados.
    apply_error, replication_stoppedA réplica não consegue aplicar um segmento.
    replication_guid_mismatchO GUID do banco de dados do master mudou: restore ou troca do arquivo.
    segment_missing, sequence_gapA sequência de segmentos está quebrada.
    firebird_down, firebird_log_errorO Firebird está parado ou registra erros.
    firebird_not_answeringA porta do Firebird está aberta, mas não é possível conectar ao banco de dados há um minuto.
    master_publication_offA publicação está desligada em um banco de dados com réplica.
    data_mismatchA verificação periódica encontrou uma diferença. A verificação é ligada à parte.
    Verificação de dados. Número de linhas de cada tabela no master e na réplica.

    Comparação entre master e réplica

    Verificar conta as linhas das tabelas escolhidas no master e na réplica e as compara. Não compara o conteúdo das linhas: não encontra linhas alteradas. Execute em um horário calmo: com gravação ativa, os números podem diferir.

    A verificação periódica vem desligada por padrão: COUNT(*) lê a tabela inteira. Ligue-a com o parâmetro do nó data_check_enabled; ela roda a cada 2 horas. Novas configurações da verificação valem na hora, sem reiniciar o nó. A verificação compara os dados quando master e réplica estão no mesmo segmento. Uma diferença gera um alerta. Uma tabela excluída da publicação aparece como “not published”, e não como erro.

    • Pausa no envioPara um ou vários bancos de dados. Depois de “Retomar”, o envio continua a partir do último segmento, sem nova cópia. O arquivo de journals cresce nesse meio-tempo.
    • Logs do nó remotoreplication.log, firebird.log e o log do nó direto no RCM, sem entrar no servidor.
    • Sem licençaO master para o envio; o Firebird e os bancos de dados continuam funcionando. Depois de instalar a licença, o envio volta sozinho em até um minuto.
    • Registro de comandosCada comando do RCM é registrado com o autor e o resultado. Relatório do cluster em um único arquivo JSON.

    Serviço · época · onde está o master

    Serviços: um banco de dados em vários hosts

    Um serviço é um banco de dados lógico em vários hosts. O master pode passar de um host para outro, mas o nome do serviço e o alias do banco de dados não mudam. As aplicações e os roteadores perguntam ao RCM onde está o master do serviço agora.

    Cada troca de master recebe o próximo número: a época. O RCM guarda o histórico das épocas: quando o master mudou e por quê. O serviço é encontrado pelo nó e pelo caminho do arquivo, não pelo GUID: no switchover o GUID do banco de dados muda, o caminho fica.

    O que o serviço descreve

    • alias — nome do banco de dados no databases.conf. O novo master o grava sozinho.
    • members — um registro por host: nó master, nó de réplica, caminho do arquivo, prioridade.
    • router_port — porta em que os roteadores recebem as aplicações deste serviço.
    • policy — regras do failover automático e o modo de fechamento do master antigo.

    Em cada host do serviço rodam dois nós no mesmo Firebird: o nó master e o nó de réplica. É a mesma topologia “Dois nós por host” do diagrama acima.

    O nó master precisa do endereço do Firebird para os clientes: o parâmetro advertise_addr. Sem ele, o RCM não diz à aplicação onde se conectar.

    Onde está o master agora

    hqbirdrcm services put -id shop -file shop.json
    hqbirdrcm services
    hqbirdrcm where -service shop
    hqbirdrcm where -db shop

    where responde: host e endereço do master, número da época, réplicas e problemas encontrados. Pela API, a aplicação pode esperar uma nova época sem consultar o RCM a cada segundo.

    A página Services do RCM mostra o mesmo para cada serviço: estado, época, master, endereço do Firebird, réplicas e problemas. O campo Find encontra o banco de dados pelo alias, pelo nome do serviço, pelo GUID ou pelo caminho.

    Serviços no navegador

    Tudo o que os comandos hqbirdrcm fazem para os serviços existe na interface web do RCM. A linha de comando não é necessária para isso.

    • Página do serviçoO estado e o seu motivo, o master, as réplicas com o atraso, os hosts e os seus papéis, os roteadores, os masters antigos na fila de fechamento, a regra do failover automático, a operação em andamento passo a passo e o histórico dos masters.
    • Botões de açãoSwitchover, Failover, Rejoin, Resume. Cada um primeiro executa uma verificação e mostra os problemas. A ação só começa depois da confirmação. Um segundo clique não inicia uma segunda operação.
    • Formulário do serviçoO botão New service cria um serviço: nome, alias, porta do roteador e uma linha para cada host. O formulário sugere os nós e os bancos de dados que eles veem. Check verifica, Save primeiro mostra a lista de alterações.
    • OperationsUma página com todos os switchovers, failovers e rejoins, os mais novos no topo. Enquanto uma operação está em andamento, o cabeçalho de cada página mostra uma marca com um link para ela.
    • Exclusão do serviçoSó o registro no RCM é excluído. A janela diz o que fica (bancos de dados, replicação, papéis dos nós, alias) e o que se perde (histórico, regra, porta nos roteadores), e pede para digitar o nome do serviço.
    • Papel viewerUm usuário com esse papel vê todas as páginas e executa verificações, mas não tem botões de ação.
    Estado do serviçoSignificadoO que fazer
    okO master funciona, a réplica em outro host o acompanha.Nada.
    rejoiningO master antigo está voltando como réplica.Esperar: o banco de dados está sendo copiado.
    degraded_no_replicaO master funciona, não há réplica. Acontece depois de um failover ou de um erro no retorno.hqbirdrcm rejoin
    failedO RCM não consegue determinar o estado, ou o Firebird do master não responde.hqbirdrcm resume após verificar

    Um serviço no estado failed não inicia nem switchover, nem failover automático. Só o operador o tira desse estado: com o comando resume, com um rejoin ou com um failover manual.

    Mudança planejada do master · sem perda de dados

    Switchover: o master passa para outro host

    O switchover move o master do serviço para outro host sem perda de dados. O RCM para as gravações no master antigo, espera a réplica aplicar o último segmento e a torna master. Depois, o master antigo volta ao cluster como réplica do novo, no mesmo caminho.

    Ele serve para trabalhos planejados: atualização do sistema operacional, troca de discos, mudança da carga para outro servidor. Primeiro a verificação, depois a execução:

    hqbirdrcm switchover -service shop -check   # só verifica, não altera nada
    hqbirdrcm switchover -service shop -to db2  # move o master para db2

    O comando conduz a operação até o fim e imprime cada passo. Código de saída 0 é sucesso. O botão Switchover na página do serviço no RCM faz o mesmo: primeiro a verificação, depois a confirmação, depois os passos da operação na tela.

      Aplicações

      funcionam

      Hosts e serviço

      O que é verificado antes do início

      • O serviço está no estado ok, o master é conhecido.
      • A réplica de destino está no estado IN_SYNC.
      • Os quatro nós dos dois hosts respondem.
      • A réplica de destino não está em pausa por causa da licença.
      • Nesses nós não há cópia do banco de dados ou promoção em andamento.

      Se algo está errado, o RCM recusa e informa o motivo com um código. Até esse momento, nada mudou.

      Se algo deu errado

      • Antes do ponto sem retorno. Um erro, um timeout ou um cancelamento colocam o master antigo de volta online. O serviço continua ok no host antigo. Se o master antigo não voltar online, o serviço fica failed: coloque o banco online com gfix -online normal e execute resume.
      • Depois do ponto sem retorno. Não é possível cancelar. Um erro coloca o serviço em failed.
      • Erro no retorno. O novo master funciona, não há réplica: degraded_no_replica. Execute hqbirdrcm rejoin -service shop.
      hqbirdrcm operations show -id <id>
      hqbirdrcm operations cancel -id <id>

      No navegador, é a página Operations e o botão Cancel na página do serviço.

      • Parada das gravaçõesO master antigo entra em shutdown completo. O nó espera as conexões terminarem: por padrão 120 segundos, no máximo 900. A opção -force N derruba as conexões após N segundos.
      • Aplicação finalA cada segundo, o RCM pergunta à réplica se ela aplicou o último segmento. Limite padrão de 300 segundos.
      • Um reinício do FirebirdNo novo master, sem esperar a janela. No retorno, o Firebird do host antigo é reiniciado só se o nó de réplica precisar.
      • O retorno é uma cópia do banco de dadosO novo master copia o banco de dados para o host antigo via nbackup. Para um banco grande isso demora, por isso o comando espera a operação por até 2 horas.
      • O RCM reiniciouCada passo é gravado em disco antes da chamada ao nó. Depois do reinício, o RCM continua a operação a partir do passo atual.
      • Bloqueio do serviçoEnquanto o switchover ou o retorno estão em andamento, o RCM recusa outras alterações nesses nós: configurações, reinício do Firebird, cópia, pausa no envio.

      As conexões com o master antigo são fechadas no passo de parada das gravações. A aplicação precisa se conectar de novo. Com roteador, a string de conexão continua a mesma. Sem roteador, a aplicação vai para o endereço do novo master: ele é informado por hqbirdrcm where -service shop.

      HAProxy · Linux · uma única string de conexão

      Roteadores: as aplicações não mudam o endereço

      O roteador fica no host das aplicações e mantém o HAProxy apontado para o master de cada serviço. As aplicações se conectam a <host do roteador>:<porta do serviço>. Depois de um switchover ou failover, a string de conexão continua a mesma.

      Diagrama do roteador: antes da troca de época, as aplicações vão pelo roteador para db1; depois da troca, para db2 época 4 · master em db1 Aplicações router:3051 Roteador HAProxy db1 master db2 réplica época 5 · master em db2 Aplicações router:3051 Roteador HAProxy db1 fechado (fenced) db2 master
      Troca de época. O roteador fecha na hora as sessões do master antigo e abre o novo quando ele responde “pronto”. O endereço e a porta para as aplicações não mudam.

      Como o roteador escolhe o host

      • Recebe do RCM a tabela de serviços: época, host do master, endereços do Firebird.
      • A cada 2 segundos, pergunta ao nó master: “você é o master desta época e o banco de dados está online?”
      • Resposta “sim”: o host aceita conexões.
      • Resposta “não”: não há novas conexões, as abertas continuam.
      • Nova época: as sessões do master antigo são fechadas na hora.

      Se o RCM não está disponível, o roteador trabalha com a última tabela. Ela fica guardada no disco do roteador.

      Como adicionar um roteador

      O roteador é um participante do cluster com o papel router. Adicione-o na página Cluster, como um master ou uma réplica. O fbagent desse host recebe um certificado, grava a configuração e registra o serviço do sistema. O HAProxy precisa estar instalado no host.

      A porta do serviço é definida por router_port na descrição do serviço. Pode haver vários roteadores: um em cada host de aplicações.

      A página Settings → Routers do RCM mostra os roteadores e os seus relatórios: qual época o roteador aplicou e para qual host ele aponta.

      • As conexões caemNa troca de master, as conexões abertas são fechadas. A aplicação precisa se conectar de novo, no mesmo endereço.
      • Endereço do clienteO Firebird vê o endereço do HAProxy, e não o da aplicação. Regras de acesso pelo IP do cliente não funcionam atrás do roteador.
      • Só LinuxO roteador funciona no Linux. Os servidores de banco de dados podem ser Windows e Linux.
      • TestemunhasOs roteadores informam ao RCM se veem a porta do Firebird do master. Sem eles, o failover automático não liga.

      Host do master perdido · manual ou por regra

      Failover: a réplica assume o papel de master

      O failover é necessário quando o host do master não responde. A réplica vira master com os segmentos que conseguiu receber. O que o master não enviou se perde. Por isso, o operador precisa aceitar a perda de forma explícita.

      hqbirdrcm failover -service shop -check                       # o que será perdido
      hqbirdrcm failover -service shop -to db2 -accept-data-loss  # execução

      Sem a opção -accept-data-loss, o comando só verifica e mostra a estimativa de perda: o último segmento do master, quantos a réplica recebeu e aplicou, quantos segmentos foram perdidos no mínimo.

      No navegador, é o botão Failover na página do serviço. Ele só inicia a operação quando o operador marca a caixa de seleção sobre a perda de dados e digita o nome do serviço.

      1. 1Verificaçãoo master não responde, a réplica tem uma cópia válida
      2. 2Aplicação finala réplica aplica tudo o que recebeu; limite de 60 s
      3. 3Promoçãoponto sem retorno: novo GUID, reinício do Firebird
      4. 4Nova épocaa réplica é master; o master antigo espera o fechamento
      • O master ainda respondeO RCM recusa: master_reachable. Execute um switchover ou pare primeiro o nó master.
      • Réplica atrasadaO estado LAGGING é aceito. Uma réplica que precisa de uma nova cópia não serve.
      • Várias réplicasPor padrão, o RCM escolhe a que aplicou mais segmentos, depois a que tem prioridade maior.
      • Depois do failoverO serviço fica no estado degraded_no_replica: o master funciona, não há réplica. Não há retorno enquanto o host antigo não voltar.
      • Serviço no estado failedO failover manual funciona também nesse caso. É a saída quando o Firebird do master travou e não é possível reiniciá-lo rápido.
      • Tabelas excluídasO RCM pega a lista delas da réplica ou das últimas estatísticas do master antigo. Se não há lista, defina as tabelas na página de publicação do novo master.
      • Limite da aplicação finalOpção -apply-timeout, por padrão 60 segundos, no máximo 3600.

      Failover automático opcional

      O RCM pode iniciar o failover sozinho. Por padrão isso está desligado. A regra é ligada para cada serviço separadamente: na página do serviço no navegador ou por comando.

      hqbirdrcm policy -service shop                                     # mostrar a regra
      hqbirdrcm policy -service shop -auto-failover on -max-data-loss 30

      O RCM verifica as condições a cada 10 segundos e só inicia o failover quando todas são atendidas.

      CondiçãoPara quê
      O nó master está em silêncio há 90 segundosO master não envia estatísticas.
      A chamada direta do RCM ao nó master falha (5 segundos)Não são apenas estatísticas atrasadas.
      Mais da metade dos roteadores não vê a porta do Firebird do masterAs aplicações também não conseguem se conectar.
      O nó de réplica não vê o master há 90 segundosTerceira testemunha.
      O atraso da réplica não passa de 30 segundosLimite de perda de dados.
      Passou uma hora desde o último failover automáticoO master não fica pulando entre hosts.
      O RCM está rodando há mais de 90 segundosDepois de um reinício, o RCM não tem dados recentes.
      Serviço ok, sem cópia ou promoção nos nósSem conflito com trabalho em andamento.
      • Roteadores são necessáriosA regra precisa de roteadores e da porta de serviço. Se faltar um deles, ela não liga: no_witnesses. Coloque os roteadores de forma que a maioria não fique no host do master.
      • Uma vezDepois de um failover automático, a regra se desliga. Só o operador a liga de novo.
      • Por que não começouO RCM guarda o motivo da espera junto com a regra do serviço e grava cada novo motivo no seu log uma única vez.
      • LogA operação roda em nome de system:autofailover. O primeiro registro diz o que as testemunhas viram.

      O limite de 30 segundos restringe só a fila que a réplica recebeu e ainda não aplicou. Os segmentos que o master gravou, mas não enviou, não entram nela. O relatório da operação mostra quantos são.

      Fence · rejoin · master travado · resume

      Retorno e recuperação

      Depois de um failover, o cluster tem dois arquivos que já foram master. O antigo precisa ser fechado, para não aceitar gravações, e voltar como réplica. O RCM faz o primeiro sozinho, e o segundo por comando do operador.

      Fechamento do master antigo (fence)

      O RCM tenta fechar o master antigo a cada 10 segundos. Quando o nó dele responde, recebe o papel “fechado” e para de enviar segmentos. Cada fechamento é gravado no log de auditoria.

      • Modo route (padrão). O banco de dados do master antigo continua online. Os roteadores já não o usam.
      • Modo shutdown. O RCM primeiro para o banco de dados. As conexões são fechadas após 5 segundos.
      hqbirdrcm policy -service shop -fence-mode shutdown

      Retorno do master antigo (rejoin)

      Quando o host antigo volta a funcionar, inicie o retorno. Primeiro o RCM fecha o master antigo, se isso ainda não foi feito. Depois o novo master copia o seu banco de dados para o host antigo, no mesmo caminho.

      hqbirdrcm rejoin -service shop

      O arquivo antigo não é apagado. Ele fica ao lado como <nome>.pre-reinit-<hora>.fdb. Nele e no arquivo de journals do master antigo estão as alterações que o novo master não tem.

      No modo route, as aplicações que se conectam ao host antigo diretamente, e não pelo roteador, ainda podem gravar no banco de dados antigo. Essas alterações não chegam ao novo master. Se parte das aplicações funciona sem roteador, ligue o modo shutdown.

      Master travado

      O Firebird pode travar de forma que a porta fica aberta, mas não é possível conectar ao banco de dados. A verificação da porta não vê isso. Por isso, o nó se conecta ao banco de dados sozinho a cada minuto, com limite de 10 segundos.

      • Um minuto sem resposta: alerta grave firebird_not_answering.
      • O RCM coloca o serviço em failed e grava o motivo: nó, host, hora.
      • Nesse estado, o failover automático não começa.

      O que fazer: salve as pilhas das threads do Firebird e o firebird.log, reinicie o Firebird no host do master e depois execute resume. Se não é possível reiniciar rápido, pare o nó master e inicie o failover.

      Saída do estado failed

      hqbirdrcm resume -service shop -check
      hqbirdrcm resume -service shop

      O RCM pergunta diretamente ao nó master e verifica:

      • não há operação em andamento no serviço;
      • o nó master responde;
      • o Firebird dele aceita conexões;
      • o host é o master da época atual, e o banco de dados está online.

      O serviço passa para ok se a réplica do outro host acompanha o master. Caso contrário, para degraded_no_replica: então execute rejoin.

      Tornar normal · promover a master

      Promoção manual da réplica: passo a passo

      Para um banco de dados que faz parte de um serviço, use o switchover e o failover: eles mesmos fazem todos os passos abaixo. O caminho manual fica para bancos de dados sem serviço. “Tornar normal” transforma a réplica em um banco de dados independente, pronto para uso: para relatórios, testes ou uma falha. “Promover a master” torna a réplica o novo master.

      A promoção funciona para um par de nós companheiros: um nó de réplica e um nó master na mesma instância do Firebird. O arquivo do banco de dados fica no lugar; o controle passa ao companheiro. Cada passo aparece na linha do banco de dados. Se um passo foi interrompido, clique no botão de novo: passos concluídos não se repetem.

        Conexões

        mantidas

        O que o RCM mostra

        Passos na linha do banco de dados. Passos concluídos em verde, o atual em vermelho, os próximos em cinza.

        Por que um novo GUID

        Sem ele, o novo master gravaria segmentos com o GUID do master antigo, e suas réplicas os recusariam. O nó dá ao banco de dados um novo GUID no lugar, via nbackup, sem reiniciar o Firebird. Funciona em 2.5, 3.0, 4.0 e 5.0.

        Depois do novo GUID, a cadeia antiga do nbackup não serve mais. Faça uma nova cópia de nível 0.

        Troca manual sem serviço

        1. Pare as gravações das aplicações no master antigo.
        2. Aguarde IN_SYNC e a fila vazia.
        3. Clique em “Verificar”: os números de linhas coincidem. Esta verificação é só do número de linhas.
        4. “Promover a master”, aguarde o passo FINALIZE.
        5. Aponte as aplicações para o novo master.
        6. Faça uma cópia nbackup de nível 0 e conecte uma nova réplica.

        A promoção manual não verifica se as aplicações gravam no master antigo e não traz o master antigo de volta como réplica. Pare as gravações você mesmo primeiro. O switchover faz os dois passos por você: para as gravações e traz o master antigo de volta.

        Reinicialização · parâmetros · certificados

        Configurações e segurança

        O Firebird lê as configurações de replicação só na inicialização. Por isso importa quem o reinicia e quando. A regra é simples: o Firebird do master nunca é reiniciado automaticamente. Há uma exceção: o switchover e o failover. Neles, o reinício faz parte de uma operação que o operador iniciou, ou de uma regra que ele ligou.

        NóQuem reinicia o Firebird
        MasterSó você. O nó do master não reinicia o Firebird sozinho.
        Réplica, o mesmo Firebird tem bancos masterVocê. A permissão na janela de cópia deixa o nó apenas parar o Firebird para trocar ou apagar o arquivo antigo da réplica.
        Réplica, reinício automático proibidoVocê.
        Demais réplicasO nó, na sua janela de reinicialização. Uma vez após uma série de cópias, e não após cada banco de dados.

        Parâmetros de replicação para vários bancos de dados

        Escolha os bancos de dados: o RCM os agrupa por versão do Firebird e papel. Para cada parâmetro, escolha uma ação: manter, definir, voltar ao nível acima ou não gravar. Você vê de onde vem o valor atual: do banco de dados, do nó ou do Firebird.

        A pré-visualização verifica os valores nos nós e não altera nada. Ela também mostra quem vai reiniciar o Firebird e quantos bancos de dados isso afeta.

        Parâmetros de replicação. Dica para cada chave, valores do nó e do Firebird, pré-visualização: “você reinicia”.
        • Janelas de tempoReinicialização do master solicitada por você: 22:00–05:00. Réplica: a qualquer hora. A promoção manual a master reinicia os dois Firebird na hora, sem janela. O switchover reinicia um Firebird: no novo master. Velocidade total de cópia: 23:00–05:00.
        • Velocidade dos segmentosPor padrão 50 MB/s, pico curto de 200 MB. Muda na hora, sem reiniciar.
        • Mover o arquivo da réplicaPara outra subpasta sem nova cópia; reversão em caso de erro.
        • Réplica configurada manualmentePode passar a ser gerenciada sem nova cópia. O RCM associa os arquivos pelo GUID.
        • Linha de comandoCópia, verificação, pausa, promoção e outros comandos do RCM também estão no hqbirdrcm. Switchover, failover e a regra do serviço estão disponíveis de três formas: no navegador, por comando e pela API.
        • Papel viewerUm usuário do RCM com o papel viewer vê tudo e executa verificações. Qualquer alteração é proibida para ele.
        • 6 idiomasInterface do RCM. As instruções dos alertas são em inglês.
        Descrição do cluster no HQ Monitor (modo demo). Participantes e papéis, vínculos master → réplica, validade do certificado de cada participante.

        Um único documento descreve o cluster

        Participantes, seus papéis e vínculos master → réplica são definidos na página Clusters do HQ Monitor ou no RCM. O fbagent de cada host recebe a descrição, instala e configura os nós sozinho. Sem o HQCenter, o RCM gerencia um cluster de até 3 hosts.

        mTLS e certificados

        Todos os canais do cluster são protegidos por mTLS com uma CA comum. A chave é criada no host do participante e não sai dele: só a solicitação de certificado é enviada. O certificado vale 90 dias e se renova sozinho 30 dias antes de vencer. Nova chave e nova CA são emitidas por comando do administrador.

        A interface web do RCM funciona via HTTPS na porta 7444. O agente abre essa porta no firewall quando o RCM é ligado no host. O login é com usuário e senha; a primeira senha precisa ser trocada. Ela fica no arquivo rcm-initial-password no host do RCM e não aparece na tela. Depois da troca da senha, o agente apaga esse arquivo. A página de login mostra o hash da CA do cluster: compare-o com a linha “CA hash” no resumo da instalação no host do RCM. Cada alteração e cada login são gravados no log de auditoria.

        Comandos · timeouts · portas · códigos de recusa

        Referência

        Comandos

        TarefaComando
        Ligar o RCM no hostfbagent --cluster-init <id>
        Abrir ou fechar a janela de pareamentofbagent --cluster-pairing on|off
        Vincular os hostshqbirdrcm cluster link -hosts db1,db2 -master db1
        Token para um host sem janela de pareamentohqbirdrcm cluster join-token -note db2
        Sair do clusterfbagent --cluster-leave
        Descrever um serviçohqbirdrcm services put -id shop -file shop.json
        Onde está o masterhqbirdrcm where -service shop
        Mudança planejada do masterhqbirdrcm switchover -service shop [-to db2] [-check]
        Mudança de emergênciahqbirdrcm failover -service shop -accept-data-loss
        Trazer o master antigo de volta como réplicahqbirdrcm rejoin -service shop
        Sair do estado failedhqbirdrcm resume -service shop [-check]
        Regra do failover automáticohqbirdrcm policy -service shop -auto-failover on|off
        Andamento e cancelamento de uma operaçãohqbirdrcm operations show|cancel -id <id>

        Timeouts e intervalos

        O quêPadrãoComo alterar
        Switchover: espera do fim das conexões120 s, no máximo 900 s-quiesce-timeout
        Switchover: a réplica aplica o último segmento300 s-apply-timeout
        Switchover: o comando espera o fim da operação2 horas-timeout
        Failover: a réplica aplica o que recebeu60 s, no máximo 3600 s-apply-timeout
        Failover automático: o master está em silêncio90 s-failover-delay
        Failover automático: limite de atraso30 s-max-data-loss
        Failover automático: intervalo entre dois1 hora-min-interval
        Verificação das condições de failover e do fechamento do master antigoa cada 10 snão muda
        Firebird travado: teste de conexãouma vez por minuto, limite de 10 snão muda
        Roteador: consulta ao nó mastera cada 2 snão muda
        Janela de pareamento, token de entrada24 horasjanela: número de horas na solicitação
        Link hosts: certificado do agente, início dos nósaté 10 minutos, até 20 minutosnão muda

        Portas

        PortaPara quê
        7443RCM: nós, agentes e roteadores, mTLS.
        7444RCM: interface web e comandos do operador, HTTPS.
        7450–7459Janela de pareamento do agente: 7450 + slot.
        7051–7060Primeiro nó do agente: 7051 + slot.
        7061–7070Segundo nó do agente: 7061 + slot.
        router_portPorta do serviço no roteador, por exemplo 3051.

        Códigos de recusa

        CódigoSignificado
        not_in_syncA réplica de destino está atrasada: o switchover não começa.
        busyHá cópia do banco de dados ou promoção em andamento nos nós.
        service_busyJá há uma operação em andamento no serviço.
        master_reachableO master responde: o failover não é necessário.
        replica_unusableA réplica não tem uma cópia válida do banco de dados.
        data_loss_not_acceptedFailover sem a opção -accept-data-loss.
        past_no_returnCancelamento depois do ponto sem retorno.
        no_witnessesFailover automático sem roteadores.
        node_port_clashA porta do nó está ocupada por outro participante do host.
        seats_exceededO cluster já tem 3 hosts.

        O principal em poucas palavras

        Perguntas frequentes

        Qual a diferença entre switchover e failover?

        O switchover é planejado: os dois hosts funcionam, os dados não se perdem, o master antigo volta sozinho como réplica. O failover é de emergência: o host do master foi perdido, perde-se o que o master não conseguiu enviar, e o master antigo volta com um comando separado.

        O que a aplicação vê durante o switchover?

        As conexões com o master antigo são fechadas quando o RCM para as gravações. Enquanto a réplica não vira master, não há onde gravar. Depois da nova época, a aplicação se conecta de novo: no mesmo endereço do roteador ou no endereço do novo master.

        Quanto tempo dura o switchover?

        A pausa nas gravações tem três partes: espera do fim das conexões (até 120 segundos por padrão), aplicação final do último segmento e um reinício do Firebird no novo master. O retorno do master antigo vem depois disso, em segundo plano. O tempo dele é o tempo da cópia do banco de dados.

        É possível trabalhar sem roteador?

        Sim. O switchover e o failover manual funcionam sem roteadores. A aplicação então descobre sozinha o endereço do master no RCM. O failover automático não liga sem roteadores: os roteadores são as testemunhas dele.

        Quantos dados podem ser perdidos no failover automático?

        A regra não dispara se a réplica está mais de 30 segundos atrasada. Mas os segmentos que o master gravou e não conseguiu enviar se perdem. O relatório da operação mostra quantos são. O arquivo antigo do banco de dados é mantido: essas alterações ficam nele e no arquivo de journals do master antigo.

        O serviço está no estado failed. O que fazer?

        Veja o motivo na página Services. Se o Firebird do master travou, reinicie-o. Depois, hqbirdrcm resume -service <id> -check mostra o que impede, e resume sem a opção coloca o serviço de volta em funcionamento.

        Quanto espaço é preciso para o retorno do master antigo?

        O retorno é uma nova cópia do banco de dados. Valem as mesmas regras de qualquer cópia: 105 % do tamanho do banco de dados. Depois do failover, o arquivo antigo fica ao lado, por isso o host antigo precisa de espaço para os dois arquivos.

        Funciona no Windows?

        Os nós e o RCM funcionam no Windows e no Linux. O roteador funciona só no Linux.

        ← Voltar à visão geral do HQbird 2027