Tutorial de Knex.js com TypeScript e PostgreSQL

No tutorial de hoje eu vou te ensinar como usar o query builder Knex.js em aplicações Node.js para interagir com o banco de dados PostgreSQL. Não sabe o que é um query builder? Calma que eu já vou explicar, apenas tenha em mente que este é um tutorial para quem já sabe Node.js, TypeScript e já conhece também o banco Postgres.

Caso precise de um conhecimento básico/reforço em TS, use este tutorial.

#1 – Driver nativo x Query Builder x ORM

Quando vamos criar uma aplicação que se conecta a um banco de dados para consultar e guardar dados nós temos três abordagens para fazê-lo:

usando o driver nativo do banco para nossa linguagem;
usando um query builder;
usando um ORM (Object-Relationship Manager);

Cada uma dessas três abordagens possui suas vantagens e desvantagens, bem como seus admiradores e detratores. Resumidamente, nós temos o seguinte comparativo:

Driver: a forma “oficial”, com maior performance e que dá o maior trabalho (menos produtiva) por envolver uso direto de SQL e nenhuma abstração de dados. No caso do PostgreSQL por exemplo, seria desenvolver usando o pacote pg, como já fizemos nesse outro tutorial.
ORM: a forma mais “comum” e mais produtiva de desenvolver. Nela, você lida apenas com objetos, o mais alto grau de abstração na programação, sem tocar em SQL. No entanto, a conversão constante de e para objetos torna esta a forma mais lenta em termos de performance. Um exemplo famoso é o Sequelize, que já usamos nesse outro tutorial.
Query Builder: nessa abordagem, usamos objetos para construção das queries, o que representa um grau médio de abstração, mas mais leve do que o presente nos ORMs, mas mais produtivo do que gerenciar tudo na mão como no driver nativo. Pode-se dizer que os Query Builders como o Knex.js são o meio termo entre performance e produtividade no mundo de desenvolvimento.

Entendido esse ponto inicial em relação às abordagens, vamos em frente.

#2 – Ambiente e Projeto

Se você nunca programou com Node e Postgre antes, vou deixar abaixo um vídeo ensinando a instalação do ambiente.

Quando estiver com o ambiente pronto, pode criar o banco e tabela para nossa aplicação.

Agora, crie uma pasta na sua máquina para o projeto, eu vou usar o nome “crud-knex-postgresql”. Abra o terminal e dentro dessa pasta rode um “npm init -y” para inicializar o projeto e criar o package.json.

Ainda no terminal, mande instalar as dependências que vamos precisar neste tutorial

npm i pg knex dotenv

A saber:

pg: pacote com o driver nativo para PostgreSQL;
Knex: pacote do query builder Knex.js;
DotEnv: pacote para gestão das variáveis de ambiente;

Outras opções de banco de dados possíveis seriam CockroachDB, MS SQL Server, MySQL, MariaDB, SQLite3, Better-SQLite3, Oracle e Amazon Redshift, bastando mudar o conector (pg).

E agora as dependências de desenvolvimento:

npm i -D typescript tsx @types/node

Sendo:

TypeScript: pacote para usarmos TypeScript no projeto;
TSX: pacote que permite executar TS direto, sem transpilar para JS;
@types/node: pacote para os types do Node.js nativo;

E depois inicialize o TypeScript no projeto.

npx tsc --init

E ajuste seu package.json para que o type do projeto seja module, ao invés de commonjs e o script de start.

"type": "module",
"scripts": {
  "start": "tsx src/index.ts"
},

Feito isso, agora crie um arquivo .env na raiz do seu projeto e dentro coloque as seguintes variáveis de ambiente, devidamente configuradas com os dados do servidor PostgreSQL que você vai usar.

NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_USER=luiztools
DB_PASSWORD=
DB_DATABASE=luiztools
DEBUG=knex:query

A variável debug serve para o Knex imprimir no terminal o SQL que ele está executando no banco de dados, algo útil durante o desenvolvimento.

E com isso terminamos o setup inicial do projeto.

#3 – Configurando o Knex

O primeiro passo é criarmos uma pasta src na raiz do projeto e dentro dela uma pasta config, onde guardaremos arquivos de configuração. O primeiro arquivo de configuração que vamos precisar é o knex.ts, que como o próprio nome sugere, configura o query builder.

 import "dotenv/config";
import Knex from "knex";
 
const knex = Knex({
  client: "pg",
  connection: {
    host: `${process.env.DB_HOST}`,
    port: Number(process.env.DB_PORT),
    user: `${process.env.DB_USER}`,
    password: `${process.env.DB_PASSWORD}`,
    database: `${process.env.DB_DATABASE}`,
  },
  pool: {
    min: 2,
    max: 10,
  },
});
 
export const onDatabaseConnect = () => knex.raw("SELECT 1");
 
export default knex;

Começamos importando as variáveis de ambiente e depois o pacote do Knex. Como é comum em abstrações de banco de dados, primeiro precisamos apontar nosso query builder para o nosso banco (connection), bem como dizer qual o client de banco que vamos usar (pg) e as configurações de pool de conexões, algo opcional, mas recomendado para maior performance.

Após as configurações de conexão do Knex, eu crio e exporto uma função que testa a conexão. Se tudo estiver correto, essa função vai retornar uma linha com o número 1, caso contrário, um erro.

Por fim, exporto como default o objeto do Knex, devidamente conectado.

Agora vamos ao index.ts que deve existir dentro de src para escrever um código inicial que testa a conexão usando o Knex.

 
import {onDatabaseConnect} from "./config/knex.js";
 
console.log(await onDatabaseConnect());

Se executar o projeto agora com npm start, vai receber no console o SQL que o Knex tentou executar e o objeto de retorno da consulta. Caso receba um erro, aí é caso de rever suas variáveis do .env, a depender do erro.

#4 – Migrations com Knex

Com a conexão devidamente testada, é hora de criar a tabela no nosso banco de dados. Você poderia fazer isso manualmente mas fica mais profissional fazer isso através do recurso de migrations, onde podemos ir fazendo o versionamento do banco de dado através de mudanças incrementais.

Para criarmos e usarmos migrations, precisamos usar o Knex CLI, um utilitátio de linha de comando do Knex. O primeiro passo para usá-lo é inicializar as configurações dele em nosso projeto, usando o comando abaixo. A flag -x indica que vamos usar TypeScript (ts) nesse arquivo.

npx knex init -x ts

O arquivo de configuração do Knex CLI se chama knexfile.ts e fica na raiz do projeto. Abra ele e faça o carregamento das variáveis de ambiente e preenchimento das configurações com elas, de maneira análoga ao que fizemos no knex.ts. Você notará que as configurações se repetem algumas vezes e isso se deve ao fato que você pode ter configurações diferentes para ambientes diferentes, sendo que o Knex olhará a variável NODE_ENV para decidir qual configuração vai usar.

Abaixo, trecho de código que mostra apenas a configuração do bloco que vamos usar:

import "dotenv/config";
import type { Knex } from "knex";


const config: { [key: string]: Knex.Config } = {
  development: {
    client: "pg",
    connection: {
      host: `${process.env.DB_HOST}`,
      port: Number(process.env.DB_PORT),
      user: `${process.env.DB_USER}`,
      password: `${process.env.DB_PASSWORD}`,
      database: `${process.env.DB_DATABASE}`,
    },
    pool: {
      min: 2,
      max: 10,
    },
    migrations: {
      tableName: "knex_migrations",
    },
  },

Repare que ao final eu coloquei uma configuração chamada migrations. Nela, eu especifico qual tabela irá guardar os metadados das migrações, ou seja, os registros de controle de versão do banco pelo Knex. Eu reparei que no meu, a exportação default ao final estava errada também, e ajustei para:

export default config;

Agora para criar nossa migration com essas configurações, vamos executar o seguinte comando no terminal.

npx knex migrate:make add_books_table -x ts

Essa instrução executa o Knex CLI com o comando migrate: make, que serve para criar uma nova migration, seguido do nome da mesma e da linguagem que queremos usar nela.

Se digitado corretamente, esse comando vai criar uma pasta migrations no seu projeto e dentro dela, um arquivo para nossa migration de criação de tabela, com funções up e down, que servem para avançar uma versão em nosso banco ou retornar uma versão, desfazendo alterações, respectivamente. Pode ser que dê alguns erros no terminal, mas se a pasta e o arquivo foram criados, não há nada com o que se preocupar.

Agora o código da nossa migration:

import type { Knex } from "knex";


export async function up(knex: Knex): Promise<void> {
    await knex.schema.createTable("books", (table) => {
        table.increments("id").primary();
        table.string("title").notNullable();
        table.string("author").notNullable();
        table.integer("year").notNullable();
        table.timestamps(true, true);
    });
}


export async function down(knex: Knex): Promise<void> {
    await knex.schema.dropTableIfExists("books");
}

Na função up, que recebe um objeto knex por parâmetro, nós usamos esse objeto para acessar knex.schema onde temos as funções de DDL (Data Definition Language), como a createTable. Nela, nós passamos o nome da tabela (books) e uma função que recebe a table e devemos adicionar as colunas nesse objeto usando funções, uma para cada coluna.

id: usamos a função increments que serve para criar ids autoincrementais, bem como a primary para torná-lo nossa chave primária;
title e author: usamos a função string que serve para campos de texto curto e notNullable para exigir o preenchimento deste campo;
year: usamos a função integer pois guardaremos apenas o ano de publicação do livro, além de notNullable;
timestamps: esta função serve para criar campos de timestamp padrões do Knex, enquanto que o segundo true indica que eles receberão automaticamente a hora atual do sistema quando um registro for salvo;

Agora no down, nós temos que fazer a operação reversa ao up, no caso, a dropTableIfExists, que vai excluir a tabela books do nosso banco.

Para executar essa migration, rode o comando abaixo.

npx knex migrate:latest

Isso vai executar todas migrations pendentes, ou seja, que foram criadas mas ainda não foram executadas, sendo que este controle é feito através da tabela knex_migrations. Para conferir você pode usar alguma ferramenta de gestão de banco Postgre, como a pgAdmin.

Na parte dois nós vamos aprender a usar essa tabela para fazer operações de CRUD.

Até lá!

De 0 a 10, o quanto você recomendaria este artigo para um amigo?

Powered by:

Tutorial de Knex.js com TypeScript e PostgreSQL

Luiz Fernando Duarte Junior

#1 – Driver nativo x Query Builder x ORM

#2 – Ambiente e Projeto

#3 – Configurando o Knex

Luiz Fernando Duarte Junior