Strings de conexão

Todo endpoint do Kisenon expõe uma URI postgresql:// padrão:

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

Componentes

TLS

Endpoints terminam TLS com um certificado Let's Encrypt para *.<region>.kisenon.com, então nenhuma CA customizada é necessária.

A connection string que o Kisenon entrega — o formato Connection string do console, keon connection-string e a API — usa sslmode=require. A conexão é criptografada, mas com require a maioria dos drivers não verifica o certificado do servidor. Ela continua sendo o padrão porque é o único valor que todo driver aceita.

Verificando o certificado do servidor

Para que o seu driver verifique a cadeia de certificados e o hostname, use os parâmetros do seu driver. Os formatos por driver do console já fazem isso.

O que costuma pegar as pessoas:

• libpq anterior à 16 não entende sslrootcert=system. Use sslmode=require nesse caso como fallback deliberado: criptografado, não verificado.
• Nunca passe sslrootcert=system para um driver Node.js. pg (e o Prisma 7, que o usa) tenta ler um arquivo chamado system e falha; postgres.js envia o parâmetro ao servidor, que rejeita a conexão.
• Wheels binários do Python (psycopg[binary], psycopg2-binary) trazem o próprio OpenSSL, cujo trust store do sistema está vazio, então sslrootcert=system falha com certificate verify failed. Aponte para o bundle do seu sistema operacional com SSL_CERT_FILE — no Debian/Ubuntu, SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt. O caminho é diferente em outros sistemas.
• Windows não tem um repositório de confiança PEM, então sslrootcert=system falha com certificate verify failed em qualquer cliente baseado em libpq — psql, psycopg, a gem Ruby pg. Aponte sslrootcert para um arquivo de CA. No Python, use certifi: pip install certifi e depois sslrootcert=certifi.where() (funciona em qualquer sistema operacional; por isso os formatos Python do console o usam). Para psql ou Rails, baixe o bundle da Mozilla em https://curl.se/ca/cacert.pem e passe o caminho: sslrootcert=C:\certs\cacert.pem.
• Prisma 6 não verifica o certificado a menos que sslaccept=strict esteja definido, independentemente do que sslmode diga.
• postgres.js não verifica o certificado com sslmode=require.
• JDBC com apenas sslmode=verify-full procura ~/.postgresql/root.crt; sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory faz com que ele use o trust store da JVM.

Como o proxy roteia para o seu endpoint

O proxy do data plane decide a qual endpoint uma conexão pertence a partir de dois sinais, em ordem:

1. A startup option neon.endpoint_id, se o cliente enviar uma.
2. O hostname SNI do TLS (<endpoint_id>.<region>.kisenon.com) como fallback.

O campo de username não é consultado para roteamento — escolha qualquer role que o seu branch defina. Strings de conexão geradas pelo console carregam o endpoint no hostname, então elas roteiam via SNI automaticamente e você não precisa configurar nada extra.

Passe neon.endpoint_id explicitamente apenas quando o seu cliente não puder apresentar o endpoint no SNI — por exemplo uma stack TLS que não envia uma extensão Server Name, ou um túnel que reescreve o host. A maioria dos drivers Postgres envia SNI por padrão, então isso raramente é necessário.

Pooling de conexões

O pooling está em GA e ligado por padrão — todo endpoint tem um host pooled ao lado do direto (desde 2026-07-18).

O host pooled é <endpoint_id>-pooler.<region>.kisenon.com — o mesmo endpoint, com -pooler inserido no rótulo do host — na porta 5432 com sslmode=require:

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

O painel Connect do console e a resposta da API ambos lhe entregam um connection_uri_pooled ao lado do connection_uri direto.

O pooler roda em modo de transaction pooling (um sidecar PgBouncer por compute). Isso é ideal para muitas conexões de vida curta — funções serverless, runtimes de edge, agentes — onde cada transação pode pegar emprestada uma conexão de servidor e devolvê-la imediatamente.

Use a conexão direta (não pooled :5432) quando você precisar de:

• LISTEN / NOTIFY.
• Locks de aviso no nível de sessão.
• SET de sessão / GUCs que devem sobreviver a uma única transação.
• Prepared statements do lado do servidor.

O connection_uri direto está sempre disponível e nunca é removido, então esses continuam funcionando exatamente como antes. Um pool do lado do cliente (PgBouncer ou o pool embutido do seu driver) à frente da conexão direta também permanece válido.

Opte por retirar um endpoint do pooling com o campo pooler_enabled: false no momento da criação ou via PATCH /v1/endpoints/{endpointId}. O padrão é true.

Múltiplos endpoints

Você pode criar múltiplos endpoints no mesmo branch. Eles compartilham storage mas têm limites de conexão e caches independentes. Use-os para isolar:

• Tráfego de app vs analytics.
• Réplicas de leitura (qualquer endpoint em um branch é essencialmente uma réplica de leitura se você não escrever nele).
• Endpoints por ambiente em branches de dev.