Skip to main content
Kysely é um query builder SQL com tipagem segura para TypeScript. Neste guia, você vai conectar o Kysely ao ClickHouse Managed Postgres por meio do driver pg com TLS verificado, criar uma tabela usando as migrations do Kysely e servir uma pequena API de lista de tarefas com Node.js.

Pré-requisitos

  • Node.js 22.18 ou posterior, que executa arquivos TypeScript diretamente, sem etapa de compilação. Os arquivos deste guia usam a extensão .mts, então o Node.js os trata como módulos ES tanto em projetos CommonJS quanto em projetos de módulos ES.
  • Uma conta do ClickHouse Cloud.
  • psql, para criar o banco de dados. Você também pode executar a instrução CREATE DATABASE no SQL Console.
  • curl, para chamar a API.
Este guia foi testado com Node.js 24.21, Kysely 0.29.6, pg 8.23.1, TypeScript 7.0.2 e PostgreSQL 18.

Crie um serviço ClickHouse Managed Postgres

No console do ClickHouse Cloud, clique em New service e selecione Postgres. A instância fica pronta em poucos minutos. Para um passo a passo completo, consulte o guia de início rápido.

Obtenha os detalhes de conexão

Clique em Connect na barra lateral esquerda do seu serviço. Mantenha Directly selecionado e ative Use SSL: a string de conexão url passará a terminar com sslmode=verify-full&sslrootcert=.... Clique em Download CA certificate para baixar o certificado de CA do seu serviço, chamado <service-name>-ca-certificate.pem, e copie a string de conexão. Este guia se conecta diretamente ao Postgres na porta 5432, por dois motivos:
  • Um servidor Node.js é um processo de longa duração. O Pool do pg já mantém um pequeno conjunto de conexões abertas e as reutiliza, então um pooler do lado do servidor traz pouco benefício.
  • O Migrator do Kysely mantém um advisory lock em nível de sessão (pg_advisory_lock) enquanto executa as migrations. O PgBouncer opera no modo de pooling por transação, então a obtenção do bloqueio, a execução das migrations e a liberação do bloqueio podem acabar, cada uma, em uma conexão de backend diferente. Via PgBouncer, o bloqueio pode continuar retido em uma conexão do pool, e as execuções seguintes de migrations ficam bloqueadas esperando por ele.
Se futuramente você executar muitas instâncias da aplicação ou funções serverless, poderá apontar a string de conexão da aplicação para o PgBouncer (porta 6432, mesmo host). O Kysely com pg funciona no modo de pooling por transação porque o pg usa prepared statements sem nome por padrão. Continue executando as migrations na porta 5432. Consulte Pooling de conexões com PgBouncer.

Configure o projeto

Crie um projeto e instale o Kysely, o driver pg e o TypeScript:
Vai adicionar a um aplicativo existente?Ignore os comandos mkdir kysely-todo && cd kysely-todo e npm init -y. No seu projeto, execute os comandos a seguir, que adicionam os scripts migrate e typecheck sem alterar o seu script start, e depois siga para Configure a conexão.

Configure a conexão

Mova o certificado da CA que você baixou para o diretório do seu projeto e renomeie-o para ca-certificate.pem. Em seguida, crie um banco de dados para o aplicativo:
Adicione a string de conexão que você copiou a um arquivo .env ou ao seu .env já existente. Substitua <PASSWORD> pela sua senha e o nome do banco de dados por guide_kysely, e defina sslrootcert como ca-certificate.pem:
.env
O pg lê sslmode e sslrootcert da string de conexão: verify-full faz com que ele verifique se o certificado do servidor foi assinado pela CA do seu serviço e se corresponde ao hostname. O sslrootcert é resolvido em relação ao diretório de trabalho, que é a raiz do projeto quando você usa npm run.
Mantenha sslmode=verify-full na URL. Sem sslmode, o pg não usa TLS nem verifica o servidor. Não passe também um objeto ssl para Pool: quando a URL contém sslmode, as configurações da URL substituem o seu objeto ssl. Se você precisar carregar a CA de outro lugar que não seja um arquivo, remova sslmode e sslrootcert da URL e passe ssl: { ca } para Pool.
Adicione um tsconfig.json para que o tsc verifique os tipos dos mesmos arquivos que o Node.js executa. Se a sua aplicação já tiver um tsconfig.json, mescle nele estas compilerOptions e a pasta migrations:
tsconfig.json

Defina a interface do banco de dados

O Kysely tipa cada consulta com base em uma interface que descreve suas tabelas. Crie src/db.mts com a interface e uma instância de Kysely que use PostgresDialect com um Pool do pg:
src/db.mts
Generated indica as colunas que o banco de dados preenche automaticamente, por isso elas são opcionais no insert.

Criar e executar uma migration

Este guia usa o Migrator nativo do Kysely com o FileMigrationProvider, que faz parte do pacote principal kysely. A CLI kysely-ctl, distribuída separadamente, é opcional e encapsula o mesmo Migrator. Crie um arquivo de migration. O Kysely executa as migrations em ordem alfanumérica pelo nome do arquivo, então use uma data como prefixo:
migrations/2026-09-30_create_todo.mts
Crie src/migrate.mts para aplicar todas as migrations pendentes. No Kysely 0.29, importe Migrator e FileMigrationProvider de kysely/migration:
src/migrate.mts
Execute a migration:
O Kysely registra as migrations aplicadas na tabela kysely_migration, então executar o comando novamente não tem nenhum efeito.
Para confirmar que o pg realmente verifica o certificado, execute a migration sem sslrootcert. Por padrão, o Node.js não confia na CA do seu serviço, então a conexão falha:

Consultar o banco de dados

Crie src/server.mts, um pequeno servidor HTTP que cria, lê, atualiza e exclui tarefas (to-dos) com o Kysely. Em uma aplicação existente, você pode usar as mesmas consultas nos seus próprios handlers de rota:
src/server.mts
Como toda consulta é verificada com base na interface Database, um nome de tabela ou de coluna digitado incorretamente, ou um insert sem o campo obrigatório title, gera um erro na verificação de tipos. Verifique o projeto:

Verificar

Inicie o servidor:
Em um aplicativo existente, no qual npm start executa o seu próprio aplicativo, inicie o servidor de exemplo com node --env-file=.env src/server.mts. Em outro terminal, crie, atualize e exclua algumas tarefas:
Abra http://localhost:3000/todos no navegador para listar as tarefas pendentes. A resposta será semelhante a esta:
Para ver os mesmos dados no console, abra o SQL Console na barra lateral esquerda do seu serviço, expanda guide_kysely e o schema public e clique na tabela todo. As tabelas kysely_migration e kysely_migration_lock criadas pelo Kysely aparecem listadas ao lado dela:

Próximos passos