Cada recurso usado na internet possui um tipo de mídia, também conhecido como tipo MIME (sigla em inglês para Multipurpose Internet Mail Extension, ou Extensão de Correio da Internet Multifuncional, em português). Essa informação é necessária para transações entre servidores e clients.

O navegador precisa saber qual o tipo dos recursos de mídia que são enviados a ele e como lidar com esses recursos de maneira correta.

A mesma situação acontece com o servidor. Ele precisa saber o tipo de recursos que são enviados a ele para análise e processamento precisos.

O que é a declaração de Content-Type?

O tipo de mídia de qualquer recurso é declarado na propriedade Content-Type no cabeçalho de uma requisição (no client, quando fazendo a requisição ao servidor) e no cabeçalho de resposta (no servidor, quando enviando uma reposta).

Sem declarar explicitamente o tipo de conteúdo de uma fonte, o client pode tentar automaticamente detectar o tipo, mas o resultado pode não ser o mais preciso. Por isso a importância de o declarar explicitamente.

Tipos de mídia

Os tipos de mídia existentes têm diversas formas. Eles são categorizados em vários grupos:

• aplicação (application)
• áudio (audio)
• fonte (font)
• exemplo (example)
• imagem (image)
• mensagem (message)
• modelo (model)
• multiparte (multipart)
• texto (text)
• e vídeo (video)

Essas categorias também têm seus tipos. Por exemplo, application/json é um tipo em application e text/html é um tipo em text.

Você pode encontrar uma lista completa dos tipos de mídia na IANA (uma organização que coordena alguns dos elementos principais da internet).

Todos esses vários tipos de dados, como texto, áudio, imagens, HTML e tantos outros são usados por toda a internet.

O navegador precisa saber o tipo de mídia de um recurso

Como mencionei acima, o navegador precisa saber que tipo de conteúdo ele recebe. Aqui temos um exemplo ilustrativo.

O código abaixo é um servidor do Node que serve um arquivo HTML:

const http = require("http");
const fs = require("fs");
const path = require("path");

const server = http.createServer(function (req, res) {
	const filePath = path.join(__dirname, "index.html");
	var stat = fs.statSync(filePath);

	res.writeHead(200, {
		"Content-Type": "text/css",
		"Content-Length": stat.size,
	});

	const readStream = fs.createReadStream(filePath);
	readStream.pipe(res);
});

server.listen(5000);

console.log("Servidor da web do Node.js na porta 5000 em execução.");

Não se preocupe com as especificidades do código. O que importa aqui é o arquivo index.html que estamos servindo e que Content-Type é text/css.

Aqui está o conteúdo de index.html:

<h1>Homepage</h1>

Logicamente, um documento HTML é diferente de um arquivo CSS. Aqui está o resultado em localhost:5000 quando o servidor é iniciado:

Você também pode confirmar a resposta obtida conferindo os cabeçalhos na aba Rede (ou em inglês, Network) das ferramentas do desenvolvedor.

Aqui vemos o resultado em um navegador do Google Chrome:

O navegador obteve o conteúdo como um tipo CSS. Por isso, tentou tratá-lo como um arquivo CSS.

Observe também que o conhecimento pleno do tipo de conteúdo obtido pelo navegador reduz vulnerabilidades de segurança, pois o navegador conhece os padrões de segurança a serem utilizados para os dados em questão.

Agora que você compreendeu o conceito de tipos MIME e sua importância, vamos tratar do JSON.

O tipo correto de Content-Type para JSON

O JSON precisa ser interpretado corretamente pelo navegador para ser usado adequadamente. text/plain era tipicamente usado para JSON, mas, de acordo com a IANA, o tipo MIME oficial para o JSON é application/json.

Isso significa que, quando você estiver enviando JSON para o servidor ou recebendo JSON do servidor, deve sempre declarar o Content-Type do cabeçalho como application/json, pois esse é o padrão que tanto o client quanto o servidor entendem.

Conclusão

Como vimos acima, o servidor (assim como o navegador) precisa saber o tipo de dados enviados a ele, por exemplo, em uma solicitação de POST. Esse é o motivo pelo qual forms com arquivos geralmente contêm o atributo enctype com o valor de multipart/form-data.

Sem codificar a solicitação dessa maneira, a solicitação de POST não dará certo. Além disso, quando o servidor sabe o tipo de dados que foi enviado para ele, ele saberá como fazer o parsing dos dados codificados.

Neste artigo, examinamos o que são os tipos MIME e sua finalidade. Vimos também qual é o tipo oficial de conteúdo para JSON. Espero que você agora saiba da importância de declarar os tipos de recursos quando utilizá-los na internet.

Escrito por: Emre Savcı

Neste artigo, mostrarei como escrever testes unitários em aplicações do SpringBoot.

A razão da necessidade de escrever testes unitários pede um outro artigo para explicar. Para uma breve explicação, no entanto, vou contar a você algumas coisas.

Normalmente, eu defendo o argumento de que um código sem testes unitários é um código morto. Isso porque, quando um desenvolvedor adiciona uma nova funcionalidade a um código que não é coberta por testes unitários, fica propenso a sobrescrever alguma regra de negócio (o que mata o código que foi escrito anteriormente). Talvez não fique exatamente propenso, mas você consegue imaginar que podem acontecer erros quando um projeto precisar ser modificado. Testes unitários são a única forma de proteger seu código contra quebras que podem ocorrer em mudanças.

Por que testes unitários em enpoints?

Toda vez que escrevemos um endpoint, precisamos ter certeza de que algumas coisas estão funcionando corretamente. O endpoint deve retornar os dados em uma estrutura correta e lidar com a requisição corretamente. Podemos testar manualmente, o que não é preferível. Então, escrevemos testes unitários para garantir que nossos endpoints funcionam corretamente. Existe também uma forma de testar endpoints usando testes automatizados, mas não é o objetivo deste artigo.

Por que testes unitário em serviços?

Isso já deveria ser claro, mas, em todo caso: precisamos ter certeza que nossa regra de negócio funciona corretamente.

Por que testes unitários em repositórios?

Existem alguns casos para testar repositórios. É claro que não testamos o próprio framework. Porém, escrevemos testes unitários para ter a certeza de que nossas especificações ou relações foram implementadas corretamente.

Como testamos controllers?

Agora é a hora de mostrar a você como testar nossos controllers no SpringBoot. Vamos imaginar que escrevemos uma aplicação que nos permite salvar usuários no nosso banco de dados. Definimos uma entidade user (usuário), um serviço para o usuário e um controller.

Observação: os exemplos demonstrados nesse artigo não são para arquiteturas de aplicações reais em produção.

@Data@Entitypublic class User {    @Id    @GeneratedValue(generator = "uuid2")    @GenericGenerator(name = "uuid2", strategy = "org.hibernate.id.UUIDGenerator")    @Column(name = "id", columnDefinition = "BINARY(16)")    private UUID id;    private String name;    private String email;    private int age;}

@Datapublic class CreateUserRequest {    private String name;    private String email;    private int age;}

@RestController@RequestMapping("/users")public class UserController {    UserService userService;    @Autowired    public UserController(UserService userService) {        this.userService = userService;    }    @PostMapping    public ResponseEntity<User> createUser(@RequestBody CreateUserRequest request) {        User created = userService.save(request);        return ResponseEntity.ok(created);    }}

Nossos controllers tem uma dependência no UserService, mas não estamos interessados no que o serviço faz agora.

Agora vamos escrever um teste unitário para nosso controller e garantir que ele funciona corretamente.

Simulamos nosso serviço porque ainda não temos sua implementação em detalhes. Testamos nosso controller apenas aqui. Usamos o MockMvc para testar nosso controller e mapear nosso objeto para fins de serialização.

Configuramos o método userService.Save() para retornar nosso objeto user desejado. Passamos uma requisição para nosso controller e depois verificamos os dados retornados na seguinte linha:

andExpect(jsonPath("$.name").value(request.getName())) .

Também temos outros métodos que podem ser usados (documentação do Spring Boot, em inglês). Aqui está a lista:

Quando executamos o teste, vemos que ele passa:

Como testamos nosso serviço?

Agora, vamos testar o UserService. Ele é bem simples de testar.

Simulamos um repositório e injetamos nele um UserService. Agora, quando executarmos o teste, veremos que ele passa.

Vamos adicionar uma regra de negócio ao UserService: digamos que o usuário precisa ter um endereço de e-mail.

Vamos mudar nosso método de salvamento no UserService:

public User save(CreateUserRequest request) {    requireNonNull(request.getEmail());        User user = new User();    user.setName(request.getName());    user.setEmail(request.getEmail());    user.setAge(request.getAge());    userRepository.save(user);    return user;}

Quando executamos o teste novamente, veremos que o teste falha.

Antes de consertarmos, vamos escrever um teste que satisfaça essa regra.

Escrevemos um novo teste que especificou que, se enviarmos um e-mail nulo, ele lançará uma NullPointerException.

Vamos agora consertar o teste adicionando um e-mail à nossa requisição:

createUserRequest.setEmail("testemail");

Executando ambos os testes:

Como testamos nossos repositórios?

Agora, vamos testar nossos repositórios. Vamos usar um banco de dados h2 em memória com TestEntityManager.

Nosso repositório é definido assim:

@Repositorypublic interface UserRepository extends JpaRepository<User, Integer>, JpaSpecificationExecutor<User> {    Optional<User> findById(UUID id);}

Primeiro, configuramos o h2db. Criamos um arquivo chamado application.yaml em test -> resources:

spring:  application:    name: Spring Boot Rest API  datasource:    type: com.zaxxer.hikari.HikariDataSource    url: "jdbc:h2:mem:test-api;INIT=CREATE SCHEMA IF NOT EXISTS dbo\\;CREATE SCHEMA IF NOT EXISTS definitions;DATABASE_TO_UPPER=false;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=false;MODE=MSSQLServer"    name:    password:    username:    initialization-mode: never    hikari:      schema: dbo  jpa:    database: H2    database-platform: org.hibernate.dialect.H2Dialect    show-sql: true    hibernate:      ddl-auto: create-drop  test:    database:      replace: none

Em seguida, escrevemos o primeiro teste básico para nosso repositório: salvar um usuário e recuperá-lo:

@RunWith(SpringRunner.class)@DataJpaTestpublic class UserRepositoryTest {    @Autowired    TestEntityManager entityManager;    @Autowired    UserRepository sut;    @Test    public void it_should_save_user() {        User user = new User();        user.setName("test user");        user = entityManager.persistAndFlush(user);        assertThat(sut.findById(user.getId()).get()).isEqualTo(user);    }}

Quando executamos veremos algumas saídas no console, e nosso teste também passa:

Agora, vamos adicionar outro método ao nosso repositório para buscar um usuário através do seu e-mail:

Optional<User> findByEmail(String email);

Escrevemos, por fim, outro teste:

@Testpublic void it_should_find_user_byEmail() {    User user = new User();    user.setEmail("testmail@test.com");    user = entityManager.persistAndFlush(user);    assertThat(sut.findByEmail(user.getEmail()).get()).isEqualTo(user);}

Quando damos uma olhada no console depois de executar o teste, vemos o SQL gerado pelo hibernate:

SELECT user0_.id AS id1_1_,user0_.age AS age2_1_,user0_.email AS email3_1_,user0_.name AS name4_1_FROM user user0_WHERE user0_.email=?

Até agora, tudo bem. Cobrimos o básico de testes unitários com o SpringBoot.

Agora, não temos mais desculpas para não escrever testes unitários! Espero que tenha sido claro para você como escrever testes unitários para cada tipo de propósito.

O que é uma função hash?

Uma função hash recebe um valor de entrada (como uma string, por exemplo) e retorna um valor de comprimento fixo. Uma função hash ideal tem as seguintes propriedades:

• É rápida (em inglês)
• É capaz de retornar uma quantidade enorme de valores hash
• Gera valores únicos de hash para cada entrada (sem colisões)
• Gera diferentes de hash para valores de entrada similares
• Os valores hash não tem padrão discernível em sua distribuição (em inglês)

Não existe uma função hash ideal, claro, mas cada uma procura operar o mais perto possível do ideal. Dado que (em grande parte) as funções de hash retornam valores de comprimento fixo e que o intervalo de valores é, portanto, restrito, essa restrição pode ser praticamente ignorada. O número de valores possíveis que podem ser retornados por uma função hash de 256 bits, por exemplo, é aproximadamente o mesmo número de átomos no universo (em inglês).

Idealmente, uma função hash não retorna colisões, praticamente - dito isso, dois valores de entrada não geram hashes iguais. Isso é particularmente importante para funções hash de criptografia: colisões de hashes são consideradas vulnerabilidades (em inglês).

Por fim, uma função hash deve gerar valores imprevisíveis para cada valor de entrada. Por exemplo, observe as duas sentenças abaixo com valores similares:

1. "The quick brown fox."
2. "The quick brown fax."

Podemos comparar os valores hash gerados em MD5 para cada uma das duas sentenças:

1. 2e87284d245c2aae1c74fa4c50a74c77
2. c17b6e9b160cda0cf583e89ec7b7fc22

Dois valores diferentes foram gerados para duas sentenças similares, o que é uma propriedade muito útil para validação e para a criptografia. Isso é um corolário de uma distribuição (em inglês): os valores hash de todas as entradas deveriam propagar de maneira uniforme e imprevisível em todo o intervalo de valores possíveis de hash.

Funções hash comuns

Existem diversas funções hash amplamente usadas. Todas foram desenhadas por matemáticos e cientistas da computação.  Ao longo de mais pesquisas, algumas mostraram ter alguns pontos fracos. Ainda assim, foram consideradas boas o suficiente para aplicações não criptográficas.

MD5

Uma função hash MD5 produz valores hash de 128 bits. Ela foi projetada para uso criptográfico, mas algumas vulnerabilidades foram descobertas no mesmo período e, por conta disso, passou a não ser mais recomendada. No entanto, ainda é usada para particionamento de banco de dados e somas de verificação de computação para validar transferências de arquivos.

SHA-1

SHA significa Secure Hash Algorithm (ou Algoritmo de Hash Seguro, em português). A primeira versão do algoritmo foi a SHA-1, seguida mais tarde pela SHA-2 (veja abaixo).

Enquanto o MD5 produz um hash de 128 bits, o SHA-1 gera um hash de 160 bits (20 bytes). Em um formato hexadecimal, isso seria um valor inteiro de 40 algarismos. Como o MD5, ele foi projetado para criptografia de aplicações, mas também foram encontradas vulnerabilidades. Hoje, é considerado tão pouco resistente a ataques quanto o MD5.

SHA-2

A segunda versão do SHA, chamada de SHA2, tem muitas variações. Provavelmente, uma das mais comuns é a SHA-256, cujo uso é recomendado pelo National Institute of Standards and Technology (NIST) no lugar do MD5 ou do SHA-1.

O algoritmo SHA-256 retorna um valor hash de 256 bits, ou 64 algarismos hexadecimais. Mesmo que ainda não seja perfeito, pesquisas recentes indicam que ele é consideravelmente mais seguro do que o MD5 ou o SHA-1.

Em termos de desempenho, o SHA-256 é entre 20 a 30% mais lento de calcular do que o MD5 ou o SHA-1.

SHA-3

Esse método hash foi desenvolvido no final de 2015 e ainda não foi visto em amplo uso. Seu algoritmo não se relaciona com seu predecessor, o SHA-2.

O algoritmo SHA3-256 é uma variante com aplicabilidade equivalente à do SHA-256 anterior, demorando um pouco mais para calcular do o SHA-2.

Usando valores hash para validação

O uso típico de uma função hash é fazer verificações de validação. Um uso frequente é a validação de coleções de arquivos comprimidos, como arquivos do tipo .zip ou .tar.

Dado o arquivo e o seu valor de hash esperado (comumente referido como uma soma de verificação - ou checksum, em inglês), você pode realizar seu próprio cálculo de hash para validar se o arquivo que recebeu está completo ou corrompido.

Por exemplo, eu posso gerar uma soma de verificação de MD5 para um arquivo .tar a partir de um sistema Unix usando os seguintes comandos:

tar cf - files | tee tarfile.tar | md5sum -

Para conseguir o hash MD5 para um arquivo no Windows, use o comando Get-FileHash no PowerShell.

Get-FileHash tarfile.tar -Algorithm MD5

A soma de verificação gerada pode ser exibida no local de download, próximo ao link de download. Para o receptor, uma vez que ele faz o download do arquivo, ele também pode fazer a validação de que está tudo correto executando o seguinte comando:

echo '2e87284d245c2aae1c74fa4c50a74c77 tarfile.tar' | md5sum -c

onde 2e87284d245c2aae1c74fa4c50a74c77 é o valor postado da soma de verificação. Uma execução com sucesso do comando acima gerará um status de "OK" como esse:

echo '2e87284d245c2aae1c74fa4c50a74c77 tarfile.tar' | md5sum -ctarfile.tar: OK

As joins (ou junções, no português) do SQL permitem que nossos sistemas de gerenciamento de banco de dados sejam, bem, relacionais.

Joins nos permitem reconstruir nossas tabelas separadas dentro do banco de dados em relacionamentos poderosos para nossas aplicações.

Neste artigo, vamos olhar para cada tipo diferente de join no SQL e aprender como usá-los.

Sobre o que vamos tratar neste artigo:

• O que é uma join?
• Como configurar nosso banco de dados
• CROSS JOIN
• Como configurar nossos dados de exemplo (diretores e filmes)
• FULL OUTER JOIN
• INNER JOIN
• LEFT JOIN / RIGHT JOIN
• Como filtrar dados com LEFT JOIN
• Múltiplas joins
• Joins com condições extras
• A realidade sobre escrever queries (ou buscas, no português)  com joins

(Alerta de spoiler: abordaremos cinco tipos diferentes– mas você precisará saber apenas dois deles!)

O que é uma join?

Uma join é uma operação que combina duas ou mais linhas em uma só linha.

Essas linhas normalmente vêm de duas tabelas diferentes, embora não precisem ser.

Antes de olharmos como escrever uma join propriamente dita, vamos olhar para o que seria o resultado de uma join.

Vamos pegar o exemplo de um sistema que armazena informações sobre usuários e seus endereços.

As linhas da tabela que armazena as informações dos usuários se parece com isso:

 id |     name     |        email        | age
----+--------------+---------------------+-----
  1 | John Smith   | johnsmith@gmail.com |  25
  2 | Jane Doe     | janedoe@Gmail.com   |  28
  3 | Xavier Wills | xavier@wills.io     |  3
...
(7 rows)

E as linhas da tabela que armazena informações sobre os endereços seria desse jeito:

 id |      street       |     city      | state | user_id
----+-------------------+---------------+-------+---------
  1 | 1234 Main Street  | Oklahoma City | OK    |       1
  2 | 4444 Broadway Ave | Oklahoma City | OK    |       2
  3 | 5678 Party Ln     | Tulsa         | OK    |       3
(3 rows)

Poderíamos escrever queries para buscar separadamente tanto as informações do usuário como seu endereço – mas, idealmente, poderíamos escrever apenas uma query para retornar todos os usuários e seus endereços no mesmo resultado.

E é exatamente isso que a join nos permite!

Veremos como escrever essas junções em breve, mas, se juntarmos nossas informações de usuário com as de endereço, teremos este resultado:

 id |     name     |        email        | age | id |      street       |     city      | state | user_id
----+--------------+---------------------+-----+----+-------------------+---------------+-------+---------
  1 | John Smith   | johnsmith@gmail.com |  25 |  1 | 1234 Main Street  | Oklahoma City | OK    |       1
  2 | Jane Doe     | janedoe@Gmail.com   |  28 |  2 | 4444 Broadway Ave | Oklahoma City | OK    |       2
  3 | Xavier Wills | xavier@wills.io     |  35 |  3 | 5678 Party Ln     | Tulsa         | OK    |       3
(3 rows)

Aqui, podemos ver todos os nossos usuários e seus respectivos endereços em um único resultado.

Além de produzir resultados combinados, outro uso importante das joins é retirar informações adicionais da nossa busca, que também podem ser filtrados.

Por exemplo, se quisermos enviar uma correspondência física para nossos usuários que moram na cidade de Oklahoma, podemos usar essa join e definir um filtro baseado na coluna city.

Agora que sabemos o propósito das joins– vamos escrever algumas!

Como configurar nosso banco de dados

Antes de começarmos a escrever nossas queries, precisamos configurar nosso banco de dados.

Para os nossos exemplos, usaremos o PostgreSQL, mas a escrita das queries e os conceitos mostrados aqui podem ser facilmente traduzidos para qualquer outro sistema de banco de dados moderno (como o MySQL, o SQL Server etc.).

Para trabalhar com um banco PostgreSQL, usamos o psql – a linha de comando interativa do PostgreSQL. Se você tiver algum outro client (ou serviço, em português) com o qual esteja acostumado a trabalhar, não tem problema.

Vamos começar criando nosso banco de dados. Com o PostegreSQL já instalado, podemos executar o comando createdb <nome-do-banco-da-dados> em nosso terminal para criar um banco de dados. Vou chamar o meu de fcc:

$ createdb fcc

Vamos iniciar o console interativo usando o comando  psql e conectar o banco de dados que criamos usando \c <nome-do-banco-de-dados>:

$ psql
psql (11.5)
Type "help" for help.

john=# \c fcc
You are now connected to database "fcc" as user "john".
fcc=#

Observação: eu limpei o resultado do psql nesses exemplos para tornar mais fácil a leitura. Então, não se preocupe se o seu retorno não for exatamente igual ao que está vendo no seu terminal.

Eu aconselho você a seguir os exemplos e executar as queries por conta própria. Desse modo, você aprenderá e se lembrará com mais facilidade, trabalhando nos exemplos em vez de apenas ler sobre eles.

Agora, vamos às joins!

CROSS JOIN

O tipo mais simples de join que podemos fazer é a CROSS JOIN, ou "produto cartesiano".

Essa join pega cada linha de uma tabela e a combina com cada linha da outra tabela.

Se tivéssemos duas listas – uma contendo 1, 2, 3 e a outra contendo A, B, C — o produto cartesiano das duas seria:

1A, 1B, 1C
2A, 2B, 2C
3A, 3B, 3C

Cada valor da primeira lista é emparelhado com cada valor da segunda lista.

Vamos escrever esse exemplo simples em uma query do SQL.

Primeiro, vamos criar duas tabelas simples e inserir alguns dados:

CREATE TABLE letters(
  letter TEXT
);

INSERT INTO letters(letter) VALUES ('A'), ('B'), ('C');

CREATE TABLE numbers(
  number TEXT
);

INSERT INTO numbers(number) VALUES (1), (2), (3);

Nossas duas tabelas, letters e numbers, tem apenas uma coluna: um simples campo de texto.

Agora, vamos juntá-las com um CROSS JOIN:

SELECT *
FROM letters
CROSS JOIN numbers;

 letter | number
--------+--------
 A      | 1
 A      | 2
 A      | 3
 B      | 1
 B      | 2
 B      | 3
 C      | 1
 C      | 2
 C      | 3
(9 rows)

Esse é o tipo mais simples de join que podemos fazer – mesmo nesse exemplo simples, no entanto, podemos ver a join em funcionamento: as duas linhas separadas (uma de letters e outra de numbers) foram combinadas para formar uma única linha.

Embora esse tipo de join seja frequentemente discutido como sendo apenas um exemplo acadêmico, ele tem um bom caso de uso: cobrir intervalos de datas.

CROSS JOIN com intervalos de datas

Um bom caso de uso do CROSS JOIN é pegar cada linha de uma tabela e aplicar para cada dia de um intervalo de data específico.

Digamos, por exemplo, que estávamos criando uma aplicação que monitora atividades diárias – coisas como escovar os dentes, tomar o café da manhã ou tomar banho.

Se você quiser gerar um registro para cada tarefa e para cada dia da semana passada, você poderia usar a CROSS JOIN em um intervalo de datas.

Para criar esse intervalo, podemos usar a função generate_series:

SELECT generate_series(
  (CURRENT_DATE - INTERVAL '5 day'),
  CURRENT_DATE,
  INTERVAL '1 day'
)::DATE AS day;

A função generate_series recebe três parâmetros:

O primeiro parâmetro é o valor de início. Nesse exemplo, usamos CURRENT_DATE - INTERVAL '5 day'. Isso retorna o dia atual menos 5 dias – ou "cinco dias atrás".

O segundo parâmetro é a data atual (CURRENT_DATE).

O terceiro parâmetro é o "intervalo" – ou o quanto nós queremos incrementar em cada valor por vez. Já que essas são tarefas diárias, vamos usar o intervalo de um dia (INTERVAL '1 day').

Juntando tudo, isso gera uma série de datas começando de cinco dias atrás, terminando hoje e sendo incrementando um dia por vez.

Finalmente, removemos a parte do tempo, lançando a saída desses valores para uma data usando ::DATE, e atribuímos um nome à coluna usando AS day para fazer com que o retorno seja um pouco melhor.

O resultado dessa query são os últimos cinco dias mais o dia de hoje:

    day
------------
 2020-08-19
 2020-08-20
 2020-08-21
 2020-08-22
 2020-08-23
 2020-08-24
(6 rows)

Voltando ao nosso exemplo de tarefas diárias, vamos criar uma tabela simples para conter as tarefas que queremos completar e inserir algumas tarefas:

CREATE TABLE tasks(
  name TEXT
);

INSERT INTO tasks(name) VALUES
('Escovar os dentes'),
('Tomar o café da manhã'),
('Tomar banho'),
('Vestir-se');

Nossa tabela tasks tem apenas uma coluna, name, Nela, nós inserimos quatro tarefas.

Agora, vamos usar a CROSS JOIN nas nossas tarefas e na query que cria o intervalo de datas:

SELECT
  tasks.name,
  dates.day
FROM tasks
CROSS JOIN
(
  SELECT generate_series(
    (CURRENT_DATE - INTERVAL '5 day'),
    CURRENT_DATE,
    INTERVAL '1 day'
  )::DATE	AS day
) AS dates

(Já que nossa query de produção de dados não é exatamente uma tabela, nós podemos escrevê-la como uma subquery.)

A partir dessa query, retornamos o nome das tarefas e o dia. O resultado terá essa aparência:

     name              |    day
---------------+-------------------
 Escovar os dentes     | 2020-08-19
 Escovar os dentes     | 2020-08-20
 Escovar os dentes     | 2020-08-21
 Escovar os dentes     | 2020-08-22
 Escovar os dentes     | 2020-08-23
 Escovar os dentes     | 2020-08-24
 Tomar o café da manhã | 2020-08-19
 Tomar o café da manhã | 2020-08-20
 Tomar o café da manhã | 2020-08-21
 Tomar o café da manhã | 2020-08-22
 ...
 (24 rows)

Como esperávamos, nós recebemos uma linha para cada tarefa para cada dia em nosso intervalo de datas.

A CROSS JOIN é a join mais simples que podemos fazer, mas, para ver os outros tipos, vamos precisar de um exemplo mais realista de configuração de tabela:

Como configurar nossos dados de exemplo (diretores e filmes)

Para ilustrar os próximos tipos de join, vamos usar o exemplo de movies e movie directors (filmes e diretores de filmes, em português).

Nessa situação, o filme tem apenas um diretor, mas um filme não necessariamente precisa ter um diretor associado – imagine que um novo filme foi anunciado mas a escolha do diretor ainda não foi feita ou confirmada.

Nossa tabela directors armazenará o nome de cada diretor, enquanto a tabela movies armazenará o nome de cada filme, assim como a referência do diretor associado (caso haja uma).

Vamos criar as duas tabelas e inserir alguns dados nelas:

CREATE TABLE directors(
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL
);

INSERT INTO directors(name) VALUES
('John Smith'),
('Jane Doe'),
('Xavier Wills')
('Bev Scott'),
('Bree Jensen');

CREATE TABLE movies(
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  director_id INTEGER REFERENCES directors 
);

INSERT INTO movies(name, director_id) VALUES
('Movie 1', 1),
('Movie 2', 1),
('Movie 3', 2),
('Movie 4', NULL),
('Movie 5', NULL);

Temos cinco diretores, cinco filmes e três desses filmes tem diretores associados a eles. O diretor com o ID 1 tem dois filmes, enquanto o diretor ID 2 tem um.

FULL OUTER JOIN

Agora que temos alguns dados para trabalhar, vamos olhar a FULL OUTER JOIN.

A FULL OUTER JOIN tem algumas semelhanças com a CROSS JOIN, mas algumas diferenças importantes.

A primeira diferença é que uma FULL OUTER JOIN precisa de uma condição para fazer a join.

A condição da join especifica como duas linhas de duas tabelas diferentes estão relacionadas uma com a outra, bem como o critério a ser usado para juntá-las.

No nosso exemplo, nossa tabela movies tem uma referência aos diretores através da coluna director_id. Essa coluna corresponde à coluna id da tabela directors. Essas são as duas colunas que usaremos como condição para a join.

Escrevemos essa join entre as duas tabelas desta forma:

SELECT *
FROM movies
FULL OUTER JOIN directors
  ON directors.id = movies.director_id;

Observe a condição da join especificada, que corresponde o filme ao seu diretor : ON movies.director_id = directors.id.

Nossos resultados vão se parecer com um produto cartesiano estranho:

  id  |  name   | director_id |  id  |     name
------+---------+-------------+------+--------------
    1 | Movie 1 |           1 |    1 | John Smith
    2 | Movie 2 |           1 |    1 | John Smith
    3 | Movie 3 |           2 |    2 | Jane Doe
    4 | Movie 4 |        NULL | NULL | NULL
    5 | Movie 5 |        NULL | NULL | NULL
 NULL | NULL    |        NULL |    5 | Bree Jensen
 NULL | NULL    |        NULL |    4 | Bev Scott
 NULL | NULL    |        NULL |    3 | Xavier Wills
(8 rows)

As primeiras linhas que veremos são aquelas onde o filme tem um diretor e que nossa condição de join avaliou como verdadeira.

No entanto, após essas linhas, vemos algumas linhas restantes de cada tabela – mas com valores NULL, onde a outra tabela não teve uma correspondência.

Observação: se você não está familiarizado com valores do tipo NULL, pode veja esta explicação (em inglês) no tutorial de operadores SQL

Também vemos outra diferença entre a CROSS JOIN e a FULL OUTER JOIN aqui. A FULL OUTER JOIN retorna uma linha distinta em cada linha– diferentemente da CROSS JOIN, que retorna múltiplas.

INNER JOIN

O próximo tipo de join, a INNER JOIN, é mais comumente utilizado do que todos os outros.

Uma inner join retorna apenas as linhas onde a condição de join é verdadeira.

No nosso exemplo, uma inner join entre nossas tabelas de  movies e directors retornaria apenas registros onde o filme possui um diretor atribuído.

A sintaxe é basicamente a mesma que vimos antes:

SELECT *
FROM movies
INNER JOIN directors
  ON directors.id = movies.director_id;

Nosso resultado mostra apenas os três filmes que possuem um diretor.

 id |  name   | director_id | id |    name
----+---------+-------------+----+------------
  1 | Movie 1 |           1 |  1 | John Smith
  2 | Movie 2 |           1 |  1 | John Smith
  3 | Movie 3 |           2 |  2 | Jane Doe
(3 rows)

Já que uma inner join inclui apenas as linhas que tenham uma condição de join que a corresponda, a ordem de junção das duas tabelas não fará diferença.

Se invertermos a ordem das tabelas, a query terá o mesmo resultado:

SELECT *
FROM directors
INNER JOIN movies
  ON movies.director_id = directors.id;

 id |    name    | id |  name   | director_id
----+------------+----+---------+-------------
  1 | John Smith |  1 | Movie 1 |           1
  1 | John Smith |  2 | Movie 2 |           1
  2 | Jane Doe   |  3 | Movie 3 |           2
(3 rows)

Como listamos a tabela de directors primeiro nessa query e selecionamos todas as colunas (SELECT *), vemos a coluna de directors primeiro e depois as outras colunas de movies - o resultado dos dados, no entanto, é o mesmo.

Essa é uma propriedade muito útil das inner joins, mas não é uma realidade de todos os outros tipos de join– como veremos no nosso próximo exemplo.

LEFT JOIN/RIGHT JOIN

Os próximos dois tipos de join usam um modificador (LEFT ou RIGHT) que afeta qual dado de tabela será incluído no resultado final.

Observação: a LEFT JOIN e a RIGHT JOIN também podem ser referidas como LEFT OUTER JOIN e RIGHT OUTER JOIN.

Essas joins são usadas em queries onde queremos retornar todos os dados da tabela específica e, caso existam, os dados correspondentes da outra tabela.

Se os dados correspondentes não existirem, ainda teremos os dados da tabela primária.

Seria como uma busca por uma informação específica e um bônus caso a informação de bônus exista.

Isso será simples de entender com um exemplo. Vamos encontrar todos os filmes e seus diretores, mas não vamos nos importar com o fato de eles terem um diretor ou não – esse é o bônus:

SELECT *
FROM movies
LEFT JOIN directors
  ON directors.id = movies.director_id;

A query segue o mesmo padrão que vimos antes – apenas especificamos a join como LEFT JOIN.

Nesse exemplo, a tabela movies é a tabela left (ou da esquerda, em português).

Se escrevermos a query em uma linha, fica um pouco mais fácil de ver:

... FROM movies LEFT JOIN directors ...

Uma left join retorna todos os dados da tabela da esquerda.

Uma left join retorna também todas linhas da tabela da direita (a outra tabela, no caso) que correspondam à condição da join.

As colunas da tabela da direita que não correspondam à condição da join serão retornadas como NULL.

 id |  name   | director_id |  id  |    name
----+---------+-------------+------+------------
  1 | Movie 1 |           1 |    1 | John Smith
  2 | Movie 2 |           1 |    1 | John Smith
  3 | Movie 3 |           2 |    2 | Jane Doe
  4 | Movie 4 |        NULL | NULL | NULL
  5 | Movie 5 |        NULL | NULL | NULL
(5 rows)

Olhando para os resultados,  podemos ver o porquê de esse tipo de join ser útil para uma busca que "traga tudo disto e, caso exista, um pouco daquilo".

RIGHT JOIN

A RIGHT JOIN funciona exatamente como a LEFT JOIN – exceto que as regras agora são inversas para a ordem das tabelas.

Em uma right join, todas as linhas da tabela da direita são retornadas. A tabela da esquerda é retornada com base na condição da join.

Vamos usar a mesma query que vimos acima e substituir a LEFT JOIN por RIGHT JOIN:

SELECT *
FROM movies
RIGHT JOIN directors
  ON directors.id = movies.director_id;

  id  |  name   | director_id | id |     name
------+---------+-------------+----+--------------
    1 | Movie 1 |           1 |  1 | John Smith
    2 | Movie 2 |           1 |  1 | John Smith
    3 | Movie 3 |           2 |  2 | Jane Doe
 NULL | NULL    |        NULL |  5 | Bree Jensen
 NULL | NULL    |        NULL |  4 | Bev Scott
 NULL | NULL    |        NULL |  3 | Xavier Wills
(6 rows)

Nosso resultado agora são todas as linhas de directors e, caso existam, os dados de movies.

Tudo  o que fizemos foi trocar qual tabela é considerada primária – a tabela da qual queremos ver todos os dados sem considerar se temos dados associados.

LEFT JOIN/RIGHT JOIN na produção de aplicações

Na criação de uma aplicação, eu utilizo apenas LEFT JOIN e nunca uso RIGHT JOIN.

Eu faço isso porque, na minha opinião, um LEFT JOIN torna a query muito mais fácil de ser lida e entendida.

Quando estou escrevendo uma query, gosto de começar a pensar em um resultado "base", digamos todos os dados de filmes, e então trazer (ou retirar) os grupos de informações dessa base.

Como eu gosto de começar com uma base, a LEFT JOIN se encaixa bem nessa linha de raciocínio. Eu quero todas as linhas da minha tabela base (a tabela da esquerda) e, condicionalmente, as da tabela da direita.

Na prática, eu não acho que já tenha visto uma RIGHT JOIN em uma aplicação em produção. Entenda, não tem nada de errado com uma RIGHT JOIN - eu apenas acho que deixa a query mais difícil de entender.

Reescrevendo o RIGHT JOIN

Se quisermos virar nosso cenário acima, ao invés de retornar todos os diretores e condicionalmente seus filmes, podemos facilmente reescrever a RIGHT JOIN para uma LEFT JOIN.

Tudo que precisamos fazer é trocar a ordem das tabelas da query e mudar a palavra RIGHT para LEFT:

SELECT *
FROM directors
LEFT JOIN movies
  ON movies.director_id = directors.id;

Observação: eu gosto de colocar a tabela que será adicionada (a da direita– no exemplo acima, de movies) primeiro na condição da join (ON movies.director_id = ...) – mas essa é apenas minha preferencia pessoal.

Como filtrar dados com LEFT JOIN

Existem dois casos de uso para a LEFT JOIN (ou a RIGHT JOIN).

O primeiro, nós já vimos: retornar todas as linhas de uma tabela e, condicionalmente, as da outra.

O segundo caso de uso é para retornar as linhas da primeira tabela onde os dados da segunda tabela não estão presentes.

O cenário tem essa aparência: encontre todos os diretores que não pertencem a nenhum filme.

Para fazer isso, vamos começar com uma LEFT JOIN e nossa tabela directors será a primária ou a tabela da esquerda:

SELECT *
FROM directors
LEFT JOIN movies
  ON movies.director_id = directors.id;

Para um diretor que não pertence a nenhum filme, as colunas da tabela movies são NULL:

 id |     name     |  id  |  name   | director_id
----+--------------+------+---------+-------------
  1 | John Smith   |    1 | Movie 1 |           1
  1 | John Smith   |    2 | Movie 2 |           1
  2 | Jane Doe     |    3 | Movie 3 |           2
  5 | Bree Jensen  | NULL | NULL    |        NULL
  4 | Bev Scott    | NULL | NULL    |        NULL
  3 | Xavier Wills | NULL | NULL    |        NULL
(6 rows)

No nosso exemplo, os diretores com ID 3, 4 e 5 não pertencem a nenhum filme.

Para filtrar nosso resultado para apenas essas linhas, podemos adicionar uma cláusula WHERE que retornará apenas os filmes onde os dados são NULL:

SELECT *
FROM directors
LEFT JOIN movies
  ON movies.director_id = directors.id
WHERE movies.id IS NULL;

 id |     name     |  id  | name | director_id
----+--------------+------+------+-------------
  5 | Bree Jensen  | NULL | NULL |        NULL
  4 | Bev Scott    | NULL | NULL |        NULL
  3 | Xavier Wills | NULL | NULL |        NULL
(3 rows)

E aqui estão nossos três filmes sem diretor!

É comum usar a coluna id da tabela para filtrar os dados (WHERE movies.id IS NULL), mas todas as colunas da tabela movies são NULL - nesse caso, qualquer uma funcionaria.

Já que sabemos que todas as colunas de movies seriam NULL. Na query acima, poderíamos escrever apenas SELECT directors.* ao invés de SELECT * para retornar todas as informações dos diretores.

Usando a LEFT JOIN para encontrar dados correspondentes

Na nossa query anterior, encontramos diretores que não pertenciam a nenhum filme.

Usando a mesma estrutura, podemos encontrar os diretores que pertencem a algum filme mudando apenas a nossa condição WHERE para buscar as linhas onde os dados do filme não são NULL:

SELECT *
FROM directors
LEFT JOIN movies
  ON movies.director_id = directors.id
WHERE movies.id IS NOT NULL;

 id |    name    | id |  name   | director_id
----+------------+----+---------+-------------
  1 | John Smith |  1 | Movie 1 |           1
  1 | John Smith |  2 | Movie 2 |           1
  2 | Jane Doe   |  3 | Movie 3 |           2
(3 rows)

Pode até parecer prático, mas, na verdade, nós implementamos novamente a INNER JOIN!

Múltiplas joins

Nós já vimos como combinar duas tabelas, mas e se quisermos fazer múltiplas joins em uma linha?

Na verdade, é bastante simples, mas para ilustrar isso vamos precisar de uma terceira tabela: tickets.

Essa tabela representará os ingressos vendidos por filme:

CREATE TABLE tickets(
  id SERIAL PRIMARY KEY,
  movie_id INTEGER REFERENCES movies NOT NULL
);

INSERT INTO tickets(movie_id) VALUES (1), (1), (3);

A tabela tickets  tem apenas um id e a referência a um filme: movie_id.

Nós também inserimos dois ingressos vendidos para o filme ID 1, e um ingresso vendido para o filme ID 3.

Agora, vamos combinar directors com movies — e, então, movies com tickets!

SELECT *
FROM directors
INNER JOIN movies
  ON movies.director_id = directors.id
INNER JOIN tickets
  ON tickets.movie_id = movies.id;

Já que ambas são inner joins, a ordem em que nós escrevemos a join não importa. Poderíamos ter começado com tickets e, então, adicionado movies e finalizado com a adição de directors.

Novamente, tudo se resume a forma na qual você está tentando consultar e o que faz a busca mais compreensível.

No nosso resultado, vamos perceber que reduzimos ainda mais as linhas retornadas:

 id |    name    | id |  name   | director_id | id | movie_id
----+------------+----+---------+-------------+----+----------
  1 | John Smith |  1 | Movie 1 |           1 |  1 |        1
  1 | John Smith |  1 | Movie 1 |           1 |  2 |        1
  2 | Jane Doe   |  3 | Movie 3 |           2 |  3 |        3
(3 rows)

Isso faz sentido porque adicionamos outra INNER JOIN. Na prática, ela adiciona uma outra condicional do tipo "AND" na nossa busca.

Nossa query, essencialmente, diz: "retorne todos os diretores que pertencem a filmes que também tenham ingressos vendidos"

Se, ao invés disso, quiséssemos encontrar diretores que pertencem a filmes que talvez não tenham ingressos vendidos ainda, poderíamos substituir nossa INNER JOIN por uma LEFT JOIN:

SELECT *
FROM directors
JOIN movies
  ON movies.director_id = directors.id
LEFT JOIN tickets
  ON tickets.movie_id = movies.id;

Podemos ver que Movie 2 agora volta ao nosso conjunto de resultados:

 id |    name    | id |  name   | director_id |  id  | movie_id
----+------------+----+---------+-------------+------+----------
  1 | John Smith |  1 | Movie 1 |           1 |    1 |        1
  1 | John Smith |  1 | Movie 1 |           1 |    2 |        1
  2 | Jane Doe   |  3 | Movie 3 |           2 |    3 |        3
  1 | John Smith |  2 | Movie 2 |           1 | NULL |     NULL
(4 rows)

Esse filme ainda não teve nenhum ingresso vendido, mas foi excluído anteriormente dos resultados por conta da INNER JOIN.

Vou deixar isso como um Exercício para o Leitor™. Como você encontraria os diretores que pertencem a algum filme e não tem nenhum ingresso vendido?

A ordem de execução das joins

No fim, realmente não ligamos para a ordem como as joins são executadas.

Uma das diferenças principais entre o SQL e outras linguagens de programação modernas é o fato de o SQL ser uma linguagem declarativa.

Isso significa que especificamos o que queremos, mas não especificamos os detalhes da execução – esses detalhes são deixados para o planejador de buscas da base de dados. Especificamos as joins que queremos e as condições e o planejador do banco de dados cuida do resto.

Na realidade, porém, o banco de dados não está juntando três tabelas ao mesmo tempo. Ao invés disso, ele provavelmente unirá as duas primeiras tabelas em um resultado intermediário e, então, usará esse resultado para unir a terceira tabela.

(Observação: essa é uma explicação bastante simplificada.)

Então, como estamos trabalhando em buscas com várias joins, podemos simplesmente pensar que são joins entre duas tabelas – mesmo que uma delas seja bastante grande.

Joins com condições extras

O último tópico de que trataremos são as joins com condições extras.

Da mesma forma que ocorre com a cláusula WHERE, podemos adicionar quantas condicionais quisermos as condições da join.

Por exemplo, se quisermos encontrar os filmes cujos diretores não tenham o nome "John Smith", podemos adicionar uma condição extra à nossa join com um AND:

SELECT *
FROM movies
INNER JOIN directors
  ON directors.id = movies.director_id
  AND directors.name <> 'John Smith';

Podemos usar qualquer operador onde colocaríamos uma cláusula WHERE nessa condicional da join.

Podemos também ter o mesmo resultado dessa busca se colocarmos a condicional com a cláusula WHERE :

SELECT *
FROM movies
INNER JOIN directors
  ON directors.id = movies.director_id
WHERE directors.name <> 'John Smith';

Existem algumas diferenças sutis acontecendo por trás dos panos aqui, mas, para o propósito deste artigo, o resultado é o mesmo.

(Se você não é familiarizado com todas as outras formas de filtrar uma busca em SQL, dê uma olhada neste artigo comentado anteriormente - em inglês.)

A realidade sobre escrever queries e joins

Na realidade, eu apenas uso joins de três formas diferentes:

INNER JOIN

O primeiro caso de uso é o de registros onde o relacionamento entre duas tabelas existe. Isso é coberto totalmente pelo INNER JOIN.

Essas são situações como encontrar "filmes que tenham diretores" ou "usuários que tenham postagens".

LEFT JOIN

O segundo caso de uso é o de registros de uma tabela – e se o relacionamento existir– e registros de uma segunda tabela. Esse caso é coberto pelo LEFT JOIN.

Esse caso é o de situações como "filmes com diretores caso existam" ou "usuários com postagens caso haja alguma"

Exclusão do  LEFT JOIN

O terceiro caso de uso mais comum é o nosso segundo caso com uma LEFT JOIN: encontrar os registros de uma tabela que não tenham relação com a segunda tabela.

São situações como "filmes sem diretores" ou "usuários sem postagens".

Dois tipos de joins muito úteis.

Eu não acho que já tenha usado uma FULL OUTER JOIN ou uma  RIGHT JOIN em uma aplicação em produção. Esses tipos de caso de uso não costumam aparecer frequentemente ou a query pode ser escrita de forma mais simples (no caso do RIGHT JOIN).

Ocasionalmente, eu já usei o CROSS JOIN para algumas coisas como espalhar registros em um intervalo de datas (como vimos no começo do artigo), mas esse cenário também não costuma aparecer com frequência.

Então, boas notícias! Existem realmente dois tipos de joins que você precisa saber para 99,9% dos casos que aparecerão: INNER JOIN e LEFT JOIN!

Se você gostou deste artigo, pode seguir o autor no Twitter, onde ele fala sobre assuntos relacionados a bancos de dados e a desenvolvimento.

Obrigado pela leitura!

Um último conselho para o final: a maioria dos bancos de dados permitirá que você escreva apenas JOIN no lugar do INNER JOIN – isso poupará um pouco de digitação. :)

Escrito por: Nick Karnik

Mongoose é um biblioteca de Modelagem de Dados de Objeto (ou ODM, do inglês: Object Data Modeling) para MongoDB e Node.js. Ele gerencia o relacionamento entre dados, fornece a validação de esquemas e é usado como tradutor entre objetos no código e a representação desses objetos no MongoDB.

O MongoDB é um banco de dados de documentos NoSQL que não possui esquemas. Isso significa que ele guarda documentos JSON e que a estrutura deles pode variar, já que não há a estrutura rígida igual a dos bancos SQL. Essa é uma das vantagens de se usar NoSQL, pois acelera o desenvolvimento de aplicações e reduz a complexidade das implementações.

Abaixo vemos um exemplo de como os dados são armazenados dentro do MongoDB x bancos de dados SQL:

Terminologia

Coleções ("Collections")

As coleções (ou 'Collections', em inglês) no MongoDB são equivalentes às tabelas dos bancos de dados relacionais, podendo guardar múltiplos documentos JSON.

Documentos ("Documents")

Os documentos (ou 'Documents', em inglês) equivalem aos registros ou às linhas de dados no SQL. Enquanto uma linha em um banco SQL pode referenciar dados em outras tabelas, os documentos do MongoDB normalmente combinam isso dentro de um único documento.

Campos ("Fields")

Os campos (ou 'Fields', em inglês) ou atributos são similares a colunas em uma tabela SQL.

Esquema ("Schema")

Embora o MongoDB não possua esquemas, o SQL define esquemas por meio da definição de uma tabela. Um "esquema" no Mongoose é uma estrutura de dados de documento (ou a forma de um documento), que é aplicada por meio da camada da aplicação.

Modelos ("Models")

Os modelos (ou 'Models', em inglês) são construtores de ordem superior, que utilizam um esquema e instanciam um documento, equivalente aos registros de um banco de dados relacional.

Introdução

Instalação do MongoDB

Antes de começarmos, vamos configurar o Mongo. Você pode escolher uma das seguintes opções (nesse artigo usaremos a nº 1):

1. Faça o download da versão correta do MongoDB para o seu sistema operacional a partir do site do MongoDB e siga as instruções de instalação
2. Crie uma inscrição gratuita para disponibilizar uma sandbox de seu banco de dados
3. Instale o MongoDB usando o Docker, se preferir.

Vamos agora navegar por alguns conceitos básicos do Mongoose, implementando um modelo que represente os dados de um catálogo de endereços simplificado.

Neste exemplo, estou usando o Visual Studio Code, o Node 8.9 e o NPM 5.6. Use seu editor de código favorito, crie um projeto em branco e vamos começar! Usaremos uma sintaxe um pouco mais limitada do ES6 no Node e, por isso, não vamos configurar o Babel.

Instalação do NPM

Vamos até a pasta onde está nosso projeto e inicializá-lo.

npm init -y

Agora, vamos instalar o Mongoose e a biblioteca de validação com os seguintes comandos:

npm install mongoose validator

O comando acima fará a instalação da versão mais recente dessas bibliotecas. A sintaxe do Mongoose nesse artigo é específica para a versão 5 do Mongoose ou superior.

Conexão com o banco de dados

Crie um arquivo ./src/database.js na raiz do seu projeto.

Agora, vamos adicionar uma classe e um método simples que faça a conexão com o banco de dados.

O endereço de conexão vai variar de acordo com a instalação que você fez.

let mongoose = require('mongoose');

const server = '127.0.0.1:27017'; // COLOQUE O NOME DO SEU SERVIDOR DO BANCO DE DADOS
const database = 'fcc-Mail';      // COLOQUE O NOME DO SEU BANCO DE DADOS

class Database {
  constructor() {
    this._connect()
  }
  
_connect() {
     mongoose.connect(`mongodb://${server}/${database}`)
       .then(() => {
         console.log('Database connection successful')
       })
       .catch(err => {
         console.error('Database connection error')
       })
  }
}

module.exports = new Database()

A chamada require('mongoose') retorna um objeto do tipo "Singleton". Isso significa que a primeira vez que o chamar, ele criará uma instância da classe do Mongoose e o retornará. Em chamadas subsequentes, ele retornará a mesma instância que foi criada da primeira vez. Isso acontece devido ao modo como o modulo de importação/exportação funciona no ES6.

De modo similar, transformamos nossa classe "Database" em um singleton retornando uma instância da classe no formato de uma declaração module.exports, pois só precisaremos de uma única conexão com nosso banco de dados.

O ES6 faz a criação de padrões singleton (ou de instância única) de modo bem fácil devido a maneira como o carregador do módulo (em inglês, module loader) funciona, criando o cache das respostas de arquivos importados anteriormente.

Esquema x Modelos no Mongoose

Um modelo Mongoose é um "wrapper" ou "empacotador" de esquemas Mongoose. Um esquema Mongoose define a estrutura do documento, os valores padrões, validadores, entre outros. O modelo Mongoose, por sua vez, fornece uma interface com o banco de dados para a criação, busca, atualização, deleção de registros, e assim por diante.

Criar um modelo Mongoose consiste primariamente em três partes:

1. Fazer a referência ao Mongoose

let mongoose = require('mongoose')

Essa referência será a mesma que foi retornada quando conectamos com o banco de dados, o que significa que as definições de esquema e modelo não precisarão ser explícitas novamente para se conectar ao banco.

2. Definir o esquema

O esquema define as propriedades do documento através de um objeto, onde o nome da chave corresponde ao nome da propriedade na coleção.

let emailSchema = new mongoose.Schema({
  email: String
})

Aqui, definimos a propriedade chamada email com o esquema no tipo String, que, internamente, mapeia um validador interno, que será disparado quando o modelo for salvo. Caso o valor do dado salvo não seja no formato string, ele falhará.

Os seguintes tipos de esquemas são permitidos:

• Array
• Boolean (ou booleano, em português)
• Buffer
• Date (ou formato de data, em português)
• Mixed (um tipo genérico/flexível de dados)
• Number (ou numérico, em português)
• ObjectId
• String

Os tipos "Mixed" e "ObjectId" são definidos em require(‘mongoose’).Schema.Types.

3. Exportar um modelo

Precisamos chamar o construtor de modelos na instância do Mongoose e passá-lo para a sua coleção, assim como sua referência na definição do esquema.

module.exports = mongoose.model('Email', emailSchema)

Vamos combinar o código acima no arquivo ./src/models/email.js para definir o conteúdo de um modelo básico de e-mail:

let mongoose = require('mongoose')

let emailSchema = new mongoose.Schema({
  email: String
})

module.exports = mongoose.model('Email', emailSchema)

A definição de um esquema deve ser simples, mas sua complexidade normalmente é baseada na aplicação dos requerimentos. Esquemas podem ser reutilizados e podem conter diversos esquemas derivados (no inglês, "child-schemas"). No exemplo acima, o valor da propriedade "email" é de um tipo simples. No entanto, poderia ser do tipo objeto com propriedades adicionais acopladas.

Podemos criar uma instância de um modelo que criamos acima e populá-la usando a seguinte sintaxe:

let EmailModel = require('./email')

let msg = new EmailModel({
  email: 'ada.lovelace@gmail.com'
})

Vamos aprimorar o esquema "email" para fazer com que o valor de email inserido seja de propriedade única, seja um campo obrigatório e tenha seus valores convertidos para caracteres minúsculos antes de ser salvo. Podemos também adicionar uma função de validação que garanta que o endereço de e-mail seja válido. Vamos referenciar e usar a biblioteca validadora que instalamos anteriormente.

let mongoose = require('mongoose')
let validator = require('validator')

let emailSchema = new mongoose.Schema({
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true,
    validate: (value) => {
      return validator.isEmail(value)
    }
  }
})

module.exports = mongoose.model('Email', emailSchema)

Operações básicas

O Mongoose tem uma API flexível e fornece várias formas de concluir uma tarefa. Não vamos focar nas variações, pois isso está fora do escopo deste artigo, mas lembre-se de que a maior parte das operações pode ser feita de mais de uma maneira sintaticamente ou por meio da arquitetura da aplicação.

Criando registros

Vamos criar uma instância de um modelo de e-mail e salvá-la no banco:

let EmailModel = require('./email')

let msg = new EmailModel({
  email: 'ADA.LOVELACE@GMAIL.COM'
})

msg.save()
   .then(doc => {
     console.log(doc)
   })
   .catch(err => {
     console.error(err)
   })

O resultado é o retorno de um documento apontando o sucesso da transação:

{ 
  _id: 5a78fe3e2f44ba8f85a2409a,
  email: 'ada.lovelace@gmail.com',
  __v: 0 
}

Os seguintes campos são retornados (campos internos são em forma de prefixo e seguidos de uma linha sublinhada (ou "underscore", no inglês)):

1. O campo _id é gerado automaticamente pelo Mongo e é a chave primária da sua coleção. Seu valor é único de forma a facilitar a identificação do documento.
2. O valor email é retornado. Perceba que ele está em minúsculas pois especificamos o lowercase:true nos atributos do esquema.

Se tentar repetir a mesma operação que fizemos acima, você receberá uma mensagem de erro, pois também especificamos que este campo deverá ser único.

Buscando o registro

Vamos tentar recuperar um registro que salvamos anteriormente em nosso banco de dados. A classe do nosso modelo expõe vários métodos estáticos e de instância para realizar operações no banco de dados. Vamos agora tentar encontrar o registro que criamos anteriormente usando o método de busca e passar o e-mail como parâmetro.

EmailModel
  .find({
    email: 'ada.lovelace@gmail.com'   // nossa busca
  })
  .then(doc => {
    console.log(doc)
  })
  .catch(err => {
    console.error(err)
  })

O documento retornado será similar ao que vimos quando criamos o registro em si:

{ 
  _id: 5a78fe3e2f44ba8f85a2409a,
  email: 'ada.lovelace@gmail.com',
  __v: 0 
}

Atualizando o registro

Agora, vamos modificar o registro acima mudando o endereço de e-mail e adicionando outro campo, tudo em uma única operação. Por questões de performance, o Mongoose não vai retornar o documento atualizado e, então, precisaremos passar um parâmetro adicional pedindo-o:

EmailModel
  .findOneAndUpdate(
    {
      email: 'ada.lovelace@gmail.com'  // nossa busca
    }, 
    {
      email: 'theoutlander@live.com'   // campo a ser atualizado
    },
    {
      new: true,                       // retorne o doc atualizado
      runValidators: true              // valide antes de atualizar
    })
  .then(doc => {
    console.log(doc)
  })
  .catch(err => {
    console.error(err)
  })

O documento retornado terá o campo email atualizado:

{ 
  _id: 5a78fe3e2f44ba8f85a2409a,
  email: 'theoutlander@live.com',
  __v: 0 
}

Apagando o registro

Para essa operação, usaremos a chamada findOneAndRemove para apagar o registro. O retorno é o documento original que foi removido:

EmailModel
  .findOneAndRemove({
    email: 'theoutlander@live.com'
  })
  .then(response => {
    console.log(response)
  })
  .catch(err => {
    console.error(err)
  })

Auxiliares (ou "Helpers", no inglês)

Vimos algumas das funcionalidades básicas conhecidas, como operações CRUD (Create, Read, Update, Delete), mas o Mongoose também fornece a possibilidade de configurar diversos outros tipos de métodos e propriedades auxiliares. Esses podem ser usados para simplificar futuramente o trabalho com os dados.

Vamos criar um esquema para um usuário no ./src/models/user.js com os campos firstName e lastName:

let mongoose = require('mongoose')

let userSchema = new mongoose.Schema({
  firstName: String,
  lastName: String
})

module.exports = mongoose.model('User', userSchema)

Propriedade virtual (Virtual Property)

Uma propriedade virtual não é persistida no banco de dados. Podemos adicioná-la ao nosso esquema como uma propriedade auxiliar para obter e definir valores.

Vamos criar uma propriedade virtual chamada fullName, que pode ser usada para definir os valores de firstName e lastName, além de recuperá-los como um valor combinado quando lidos:

userSchema.virtual('fullName').get(function() {
  return this.firstName + ' ' + this.lastName
})

userSchema.virtual('fullName').set(function(name) {
  let str = name.split(' ')
  
  this.firstName = str[0]
  this.lastName = str[1]
})

Callbacks ou "retornos de chamada" para obter e definir valores devem usar as palavras-chave da função, pois precisamos acessar o modelo através da palavra-chave this. Usar "fat arrow functions" (ou funções de setas grossas, em português) mudará a referência de this.

Agora, podemos definir firstName  e lastName através da atribuição de fullName:

let model = new UserModel()

model.fullName = 'Thomas Anderson'

console.log(model.toJSON())  // Mostra os campos do modelo como JSON
console.log()
console.log(model.fullName)  // Mostra o nome completo

O resultado da execução do código acima é esse:

{ _id: 5a7a4248550ebb9fafd898cf,
  firstName: 'Thomas',
  lastName: 'Anderson' }
  
Thomas Anderson

Métodos instanciados

Podemos criar métodos auxiliares personalizados no nosso esquema e acessá-los através de uma instancia de método. Esses métodos terão acessos ao objeto do modelo e podem ser usados de modo bastante criativo. Por exemplo, poderíamos criar um métodos para encontrar todas as pessoas que tenham o mesmo nome da instância atual.

Nesse exemplo, vamos criar uma função que retorne as iniciais do usuário em questão. Vamos adicionar o método auxiliar personalizado chamado getInitials  ao esquema:

userSchema.methods.getInitials = function() {
  return this.firstName[0] + this.lastName[0]
}

Esse método estará acessível através da instância do modelo:

let model = new UserModel({
  firstName: 'Thomas',
  lastName: 'Anderson'
})

let initials = model.getInitials()

console.log(initials) // O resultado será: TA

Métodos estáticos

Similar aos métodos instanciados, podemos criar também métodos estáticos no nosso esquema. Vamos criar um método para trazer todos os usuários que temos em nosso banco de dados:

userSchema.statics.getUsers = function() {
  return new Promise((resolve, reject) => {
    this.find((err, docs) => {
      if(err) {
        console.error(err)
        return reject(err)
      }
      
      resolve(docs)
    })
  })
}

Quando chamamos getUsers da classe Model, ele retornará todos os usuários de nosso banco de dados:

UserModel.getUsers()
  .then(docs => {
    console.log(docs)
  })
  .catch(err => {
    console.error(err)
  })

Adicionar um método instanciado e um estático é uma ótima abordagem para implementar uma interface de interação de banco de dados em coleções e registros.

Middleware

Middleware são funções executadas em estágios específicos de um "pipeline" (ou caminho, no português). O Mongoose tem suporte para middleware nas seguintes operações:

• Agregação
• Documento
• Modelo
• Busca (ou query, em inglês)

Por exemplo, o modelo tem funções pre e post, que aceitam dois parâmetros:

1. Tipo do evento ("init", "validate", "save", "remove")
2. Uma "callback", que é executada com o this referenciando a instância do modelo

Vamos executar um exemplo de adição de dois campos, chamados createdAt e updatedAt, no nosso esquema:

let mongoose = require('mongoose')

let userSchema = new mongoose.Schema({
  firstName: String,
  lastName: String,
  createdAt: Date,
  updatedAt: Date
})

module.exports = mongoose.model('User', userSchema)

Quando model.save() é chamado, é executado um evento de pre(‘save’, …) e post(‘save’, …). Para o segundo parâmetro, você pode passar a função que é chamada quando o evento é disparado. Essas funções recebem um parâmetro para a próxima função na cadeia de middleware.

Vamos adicionar um "hook" (ou gancho, no português) de "pre-save" (algo como "salvamento prévio", na tradução)  para definir os valores de createdAt e updatedAt:

userSchema.pre('save', function (next) {
  let now = Date.now()
   
  this.updatedAt = now
  // Define o valor para createdAt apenas se ele for nulo
  if (!this.createdAt) {
    this.createdAt = now
  }
  
  // Chama a próxima função na cadeia de pre-save
  next()    
})

Agora, vamos criar e salvar nosso modelo:

let UserModel = require('./user')

let model = new UserModel({
  fullName: 'Thomas Anderson'
}

msg.save()
   .then(doc => {
     console.log(doc)
   })
   .catch(err => {
     console.error(err)
   })

Você deverá ver os valores para createdAt  e updatedAt quando o registro for criado e exibido:

{ _id: 5a7bbbeebc3b49cb919da675,
  firstName: 'Thomas',
  lastName: 'Anderson',
  updatedAt: 2018-02-08T02:54:38.888Z,
  createdAt: 2018-02-08T02:54:38.888Z,
  __v: 0 }

Plug-ins

Suponha que você queira acompanhar quando um registro foi criado ou quando foi atualizado pela última vez em cada coleção do nosso banco de dados. Ao invés de repetir o processo acima, você pode criar um plug-in e aplicar em cada esquema:

Vamos criar um arquivo em ./src/model/plugins/timestamp.js e replicar a funcionalidade acima de modo a se tornar um módulo reutilizável:

module.exports = function timestamp(schema) {

  // Adiciona os dois campos ao esquema
  schema.add({ 
    createdAt: Date,
    updatedAt: Date
  })

  //Cria o pre-save hook
  schema.pre('save', function (next) {
    let now = Date.now()
   
    this.updatedAt = now
    // Define o valor para createdAt apenas se ele for nulo
    if (!this.createdAt) {
      this.createdAt = now
    }
   // Chama a próxima função na cadeia de pre-save
   next()    
  })
}

Para usar esse plug-in, simplesmente o passamos para nossos esquemas que deveriam utilizar essa funcionalidade:

let timestampPlugin = require('./plugins/timestamp')

emailSchema.plugin(timestampPlugin)
userSchema.plugin(timestampPlugin)

Criando pesquisas

O Mongoose tem uma API muito rica, que lida com diversos tipos de operações complexas que provém do MongoDB. Considere uma busca onde podemos criar incrementalmente os componentes de pesquisa.

Nesse exemplo, nós vamos:

1. Encontrar todos os usuários
2. Pular os primeiros 100 registros
3. Limitar o resultado a 10 registros
4. Ordenar os resultados pelo campo firstName
5. Selecionar firstName
6. Executar a busca

UserModel.find()                   // encontra todos os usuários
         .skip(100)                // pula os primeiros 100 registos
         .limit(10)                // limita a 10 itens
         .sort({firstName: 1}      // ordena firstName de forma ascendente
         .select({firstName: true} // seleciona firstName apenas
         .exec()                   // executa a busca
         .then(docs => {
            console.log(docs)
          })
         .catch(err => {
            console.error(err)
          })

Finalizando

Nós mal exploramos a superfície das funcionalidades do Mongoose. Esta é uma biblioteca rica, cheia de recursos poderosos e que trazem diversão ao trabalhar com modelos de dados na camada de aplicação.

Embora você possa interagir com o MongoDB usando o Mongo Driver, o Mongoose vai simplificar essa interação, permitindo que você modele relacionamentos entre os dados e os valide de modo fácil.

Curiosidade:  o Mongoose foi criado por Valeri Karpov, que é um engenheiro incrível! Ele cunhou o termo The MEAN Stack (texto em inglês).

Se esse artigo foi útil,  siga o autor no Twitter!