Endpoints
Frontends Postgres que suspendem em ociosidade — tipos, ciclo de vida e semântica de despertar.
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
| Tipo | Escreve? | Quando usar |
|---|---|---|
rw | Sim | O padrão — todo branch novo recebe um automaticamente. Tráfego de app, migrações, qualquer coisa que mute. Um endpoint rw por branch é suficiente para cargas típicas. |
ro | Não | Réplicas de leitura. Múltiplos endpoints ro podem anexar ao mesmo branch e compartilhar storage; seus caches locais permanecem independentes. Use para isolar tráfego de analytics do tráfego de app. |
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). Altere com
keon endpoints update <endpoint-id> --suspend-timeout <seconds>:
0 significa nunca suspender; qualquer outro valor deve ficar entre 60 e 3600.
Pela API, suspend_after_seconds em POST /v1/branches/{branchId}/endpoints
define o valor na criação. 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. Um despertar que anexa a compute pré-aquecido normalmente fica pronto em menos de 2 segundos; 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>.<region>.kisenon.com:5432/<database>?sslmode=requireO hostname é derivado do id do endpoint, não do id do projeto — cada endpoint termina TLS de forma independente. TLS é obrigatório.
O mesmo endpoint também responde em
<endpoint_id>-pooler.<region>.kisenon.com para conexões com transaction
pooling (ligado por padrão) — veja
Strings de conexão para os trade-offs
pooled-vs-direto.
Criar
Todo branch novo recebe automaticamente um endpoint rw. Para adicionar outro:
keon branches add-compute <branch-id>Flags opcionais:
--type ro|rw— o padrão éro(somente leitura).rwsubstitui o endpoint primário de leitura e escrita do branch.--min-cu <cu>/--max-cu <cu>— a janela de autoscaling.--max-cusó pode ser definido aqui; é fixo durante toda a vida do endpoint.
Para alterar a janela de suspensão depois:
keon endpoints update <endpoint-id> --suspend-timeout 600A 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.
Relacionados
- 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.