Endpoints

Um endpoint é o processo Postgres que aceita conexões de clientes. Endpoints são efêmeros: eles suspendem quando ociosos, despertam no primeiro pacote, e rodam na camada de storage separada do projeto. Pague apenas pelos segundos em que o compute está de fato rodando.

Tipos

Ambos os tipos anexam a exatamente um branch. Um endpoint não pode mudar para um branch diferente; crie um novo endpoint no branch de destino em vez disso.

Suspender em ociosidade

Endpoints suspendem após uma janela configurável sem atividade de cliente. O padrão é 300 segundos (5 minutos). Defina suspend_after_seconds no momento da criação para sobrescrever; a nova janela entra em vigor no próximo período ocioso do endpoint.

Enquanto suspenso:

• O pod de compute foi embora. Sem CPU, sem memória cobrada.
• O storage não é afetado — seus dados estão duráveis no pageserver.
• O id do endpoint e a string de conexão permanecem válidos.

Despertar

Enviar um pacote para um endpoint suspenso o desperta. A latência de cold-start é tipicamente 300–500 ms uma vez que o cluster tem o cache de pageserver aquecido; o primeiríssimo despertar após uma longa ociosidade (ou após um projeto recém-criado) pode levar 10–30 segundos enquanto o cache de páginas do pageserver aquece. Drivers Postgres padrão não veem isso como um timeout em configurações típicas — veja Solução de problemas se você vir.

Despertares de rotina são rápidos porque a plataforma mantém um pool de compute pré-aquecido à frente da demanda: um despertar geralmente anexa a compute já em execução em vez de iniciá-lo do zero. Você não gerencia nem paga pelo pool — ele apenas afeta a rapidez com que o seu endpoint volta.

Máquina de estados

Um endpoint transita por:

Pending → Starting → Running → Stopping → Stopped → (Failed)

• Pending — o control plane aceitou a requisição de criação e está agendando o pod de compute. Se você vir um endpoint preso aqui por mais que alguns segundos, veja Solução de problemas.
• Starting — o pod de compute está de pé; o Postgres está inicializando e reproduzindo o WAL até o HEAD do branch.
• Running — aceitando conexões de clientes.
• Stopping — janela ociosa expirou; drenando conexões e fazendo flush do estado local.
• Stopped — suspenso. Aguardando o próximo pacote para despertar.
• Failed — erro terminal. O card do endpoint expõe o motivo; raro, mas acontece quando o agendamento falha ou a imagem de compute não inicia.

URI de conexão

O formato de fio está documentado em Strings de conexão:

postgresql://<role>:<pwd>@<endpoint_id>.kisenon.com:5432/<database>?sslmode=require

O hostname é derivado do id do endpoint, não do id do projeto — cada endpoint termina TLS de forma independente. TLS é obrigatório.

Criar

keon endpoints create --branch <branch-id> --type rw

Flags opcionais:

• --suspend-after-seconds <n> para sobrescrever a janela de suspensão padrão.
• --type ro para um endpoint somente leitura.

A CLI retorna o id do endpoint e a string de conexão. O endpoint fica Running e pronto para aceitar conexões em poucos segundos do retorno da chamada.

Excluir

keon endpoints delete <endpoint-id>

Conexões de cliente abertas são derrubadas. O id do endpoint é aposentado e seu hostname DNS para de resolver. O branch e seus dados não são afetados.

Relacionado

• Branches — ao que um endpoint anexa.
• Strings de conexão — detalhe do formato de fio.
• Solução de problemas — estados presos, timeouts de cold-start e afins.