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çãoCREATE DATABASEno SQL Console.curl, para chamar a API.
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 comsslmode=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
Pooldopgjá 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
Migratordo 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.
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 driverpg e o TypeScript:
Configure a conexão
Mova o certificado da CA que você baixou para o diretório do seu projeto e renomeie-o paraca-certificate.pem. Em seguida, crie um banco de dados para o aplicativo:
.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
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.
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. Criesrc/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 oMigrator 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
src/migrate.mts para aplicar todas as migrations pendentes. No Kysely 0.29, importe Migrator e FileMigrationProvider de kysely/migration:
src/migrate.mts
kysely_migration, então executar o comando novamente não tem nenhum efeito.
Consultar o banco de dados
Criesrc/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
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: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:
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
- Conexão: strings de conexão, PgBouncer e TLS.
- Configurações: ajuste parâmetros do PostgreSQL e do PgBouncer, como
max_connections. - Réplicas de leitura: escale cargas de trabalho com alto volume de leitura.
- Documentação do Kysely: junções, transações e geração de tipos.