drizzle-kit é a CLI que o acompanha para gerar e executar migrações. Neste guia, você define uma tabela todos em TypeScript, cria essa tabela com uma migração do drizzle-kit e processa consultas de criação, leitura, atualização e exclusão em um pequeno servidor HTTP em Node.js. Todas as conexões usam TLS com verificação completa de certificados.
Pré-requisitos
- Node.js 20 ou superior
- Uma conta no ClickHouse Cloud
psql, para criar o banco de dados. Você também pode executar a instruçãoCREATE DATABASEno SQL Console.
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. O modal exibe seu nome de usuário, senha, servidor e porta, além de um seletor Directly / via PgBouncer. Este guia usa duas strings de conexão:- Direta (porta
5432) para odrizzle-kit. As migrações executam DDL, podem levar bastante tempo e podem depender do estado da sessão, comoSET lock_timeout; por isso, devem se comunicar diretamente com o Postgres. - PgBouncer (porta
6432) para a aplicação. O PgBouncer incluído opera no modo de pooling por transação e permite que muitas instâncias da aplicação, incluindo funções serverless, compartilhem um pequeno número de conexões com o Postgres.
sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem, e a porta é 5432. Selecione via PgBouncer para ver os detalhes da conexão com pooling: a porta muda para 6432, e a URL sempre inclui sslmode=verify-full.
No modal, clique em Download CA certificate. Você também pode baixá-lo em Settings → CA Certificate. O certificado é exclusivo da sua instância, o que permite ao driver usá-lo para verificar se está se comunicando com o seu servidor.
Configure o projeto
Crie um projeto e instale o Drizzle ORM, o drivernode-postgres (pg) e o drizzle-kit:
Configure a conexão
Mova o certificado de CA que você baixou para o diretório do projeto e renomeie-o paraca-certificate.pem.
Crie um banco de dados para a aplicação. Substitua <PASSWORD> e o host pelos valores exibidos no modal Connect:
.env na raiz do projeto ou ao seu .env atual. Elas diferem apenas na porta, e ambas apontam para o banco de dados guide_drizzle:
.env
node-postgres lê sslmode=verify-full e sslrootcert diretamente da URL. Ele carrega o arquivo da CA e verifica tanto a cadeia de certificados quanto o hostname, então você não precisa escrever nenhum código TLS adicional. O caminho em sslrootcert é resolvido em relação ao diretório em que você executa os comandos. Não inclua o .env no controle de versão.
Se a CA estiver ausente ou incorreta, a conexão falhará com
unable to verify the first certificate. Se o hostname não corresponder ao certificado, a falha será ERR_TLS_CERT_ALTNAME_INVALID. Se a sua senha contiver caracteres especiais, como @, / ou #, aplique a codificação de URL (URL-encode) a eles.Defina o schema
Crie o arquivosrc/db/schema.ts:
src/db/schema.ts
drizzle.config.ts na raiz do projeto. Ele direciona o drizzle-kit para o schema e para a conexão direta:
drizzle.config.ts
Executar migrações
Gere uma migração SQL a partir do schema:drizzle/0000_init.sql gerado contém a instrução CREATE TABLE. Revise-o e faça o commit da pasta drizzle junto com o seu código. Em seguida, aplique-o:
drizzle-kit migrate registra as migrações aplicadas na tabela drizzle.__drizzle_migrations e, nas execuções seguintes, executa apenas as novas. Sempre que você alterar o schema.ts, execute generate e depois migrate novamente.
O drizzle-kit push aplica alterações de schema sem arquivos de migração. Ele é prático para prototipagem, mas, em produção, generate e migrate oferecem arquivos SQL que podem ser revisados e um histórico das alterações.
Consultar o banco de dados
Criesrc/db/index.ts. Esse arquivo cria o cliente Drizzle sobre um pool do node-postgres usando a conexão do PgBouncer:
src/db/index.ts
src/server.ts, um pequeno servidor HTTP que executa uma consulta Drizzle por rota. Em uma aplicação existente, você pode chamar as mesmas consultas db diretamente dos seus próprios handlers de rota:
src/server.ts
Não é necessária nenhuma configuração de driver para o PgBouncer. Por padrão, as consultas do Drizzle usam instruções sem nome, e o PgBouncer incluído também oferece suporte a prepared statements nomeados, como os criados com o
.prepare do Drizzle, no modo de pooling de transações. Recursos no nível de sessão, como LISTEN e advisory locks de sessão, não funcionam por meio do PgBouncer. Consulte as Perguntas frequentes.Executar e verificar
Inicie o servidor:PATCH retorna a linha atualizada:
http://localhost:3101/todos no navegador para listar as tarefas restantes. A resposta será semelhante a esta:
guide_drizzle e depois public e clique na tabela todos. O schema drizzle armazena a tabela de histórico de migrações. A tabela contém a linha restante:
Próximos passos
- Conexão: strings de conexão, PgBouncer e TLS
- Configurações: parâmetros do Postgres e do PgBouncer, como
max_connections - Réplicas de leitura: escale as leituras com o
withReplicasdo Drizzle - Segurança: listas de acesso por IP e rede privada