DEV Community: Vídeos de Ti

Stop Writing Setup READMEs: Add Nix to Your Project in 5 Minutes

Rodrigo Barreto — Sat, 14 Feb 2026 22:54:24 +0000

You have a Laravel API and a React frontend. Add one file and your team never fights dependency versions again.

Note: Ignore the quality of the PHP and React code, this post is focused on Nix and creating a simple environment for your development team.

How This Started

A friend of mine works with Symfony for a local government office. His team is growing fast, they went from 10 to 73 developers in a few months, and onboarding has become a nightmare. Every new hire spends their first day fighting PHP versions, MySQL configs, and missing extensions.

He uses Docker for development and it works fine. But he was curious if there was something lighter for local dev environments, especially for smaller projects or quick onboarding, without having to maintain Dockerfiles and docker-compose configs.

He called me one evening, "do you have 5 minutes?" We caught up, had some good laughs, but at the end of the call I suggested he look at Nix.

Nix is a package manager that guarantees reproducibility. You declare what your project needs in a single file, commit it, and anyone who clones your repo gets the exact same environment, same PHP, same Node, same MySQL, same everything. No containers, no VMs. Just your terminal with the right tools available. And it works with any language or framework, Python, Ruby, Go, you name it.

# Outside nix develop
$ php --version    # whatever your system has (or nothing)

# Inside nix develop
$ php --version    # PHP 8.3.x, exactly what the file says
$ node --version   # v22.x.x
$ mysql --version  # mysql Ver 8.4.x

$ exit             # back to normal, nothing changed

I told him I'd write a post showing exactly how to do it. So here we are. I'm using Laravel for this tutorial, but everything you'll see here applies to any framework.

Installing Nix

Nix runs on macOS, Linux, and WSL2. The recommended installer is from Determinate Systems, it's simpler than the official one and enables Flakes by default:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

Restart your terminal after installing, then verify:

nix --version
# nix (Determinate Nix) 2.33.x

nix flake --help
# Should show flake commands

If nix flake --help fails, add experimental-features = nix-command flakes to ~/.config/nix/nix.conf.

WSL2 users: Keep your projects inside the Linux filesystem (~/projects/), not /mnt/c/. Performance is much better.

That's it. One install, and you're ready for any Nix-managed project, forever.

The Sample Project

For this post I created a simple backend with a product CRUD in Laravel and a React frontend that lists those products. The code was generated with AI, ignore it, our focus is Nix.

You can find the full source code here: github.com/rodrigonbarreto/nix_blog_post

The structure looks like this:

workspace/
├── product-api/          ← Laravel API (PHP + MySQL)
├── product-frontend/     ← React list (Node)

Both projects work fine with my local PHP 8.3, Node, and MySQL. The question is: how do I make sure the next person who clones this doesn't spend half a day setting things up?

The Problem

Your project README probably looks something like this:

## Setup
1. Install PHP 8.3
2. Install Composer
3. Install Node 22
4. Install MySQL
5. Copy .env.example to .env
6. Run composer install
7. Run npm install
8. Create the database
9. Run migrations
10. Pray it works

Every new developer spends half a day on this. Someone has PHP 8.1, someone else has MySQL 5.7, and the intern can't compile the pdo_mysql extension.

Nix replaces all of that with one command: nix develop.

The Solution: One File

We add a single file, flake.nix, next to our projects:

workspace/
├── product-api/
├── product-frontend/
└── flake.nix              ← this is all we add

Here's the file:

{
  description = "Dev environment, PHP, Node, MySQL";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};

        php = pkgs.php83.buildEnv {
          # All extensions Laravel needs out of the box
          extensions = { all, ... }: with all; [
            mbstring
            iconv
            pdo_mysql
            mysqlnd
            openssl
            tokenizer
            xmlwriter
            xmlreader
            ctype
            fileinfo
            bcmath
            curl
            dom
            filter
            pdo
            session
            simplexml
            zip
          ];
        };

      in
      {
        devShells.default = pkgs.mkShell {
          buildInputs = [
            php
            php.packages.composer

            pkgs.nodejs_22
            pkgs.mariadb

            pkgs.git
            pkgs.curl
            pkgs.unzip
          ];

          shellHook = ''
            # Prevent tools like Laravel Herd from hijacking PHP config
            unset PHP_INI_SCAN_DIR
            unset PHPRC

            export MYSQL_HOME="$PWD/.nix-mysql"
            export MYSQL_DATADIR="$MYSQL_HOME/data"
            export MYSQL_UNIX_PORT="$MYSQL_HOME/mysql.sock"
            export MYSQL_TCP_PORT="3307"

            if [ ! -d "$MYSQL_DATADIR" ]; then
              echo "Initializing MySQL..."
              mkdir -p "$MYSQL_HOME"
              mysql_install_db --datadir="$MYSQL_DATADIR" --auth-root-authentication-method=normal > /dev/null 2>&1
            fi

            echo ""
            echo "=========================================="
            echo "  Dev Environment Ready"
            echo "=========================================="
            echo "  PHP:    $(php -r 'echo PHP_VERSION;')"
            echo "  Node:   $(node --version)"
            echo "  MySQL:  port $MYSQL_TCP_PORT"
            echo "=========================================="
            echo ""
            echo "  Start MySQL:"
            echo "    mysqld --datadir=\$MYSQL_DATADIR --socket=\$MYSQL_UNIX_PORT --port=\$MYSQL_TCP_PORT &"
            echo ""
          '';
        };
      }
    );
}

That's it. One file.

What's Happening Here?

flake.nix
│
├── inputs          → where packages come from (pinned to nixos-24.11)
│
└── outputs
    └── devShell
        ├── buildInputs   → packages: PHP, Node, MySQL, etc.
        └── shellHook     → bash that runs on entry (sets up local MySQL)

A few things worth noting:

nixos-24.11 pins the package versions. Everyone with this file gets the same PHP, same Node, same MySQL. Always.
php83.buildEnv builds PHP with the exact extensions your project needs. The base PHP in Nix is minimal, you declare what you need explicitly.
unset PHP_INI_SCAN_DIR prevents tools like Laravel Herd from injecting their own PHP config and overriding the Nix extensions.
mariadb is used instead of MySQL because it's easier to manage locally with Nix and is fully MySQL-compatible. Your Laravel app won't notice the difference.
Port 3307 avoids conflicts if you already have MySQL running on 3306.
shellHook initializes a MySQL data directory inside the project. Nothing touches your system.

Let's Use It

Enter the shell

cd workspace
nix develop

First time takes a few minutes (downloads packages). After that, it's instant.

You'll see:

==========================================
  Dev Environment Ready
==========================================
  PHP:    8.3.11
  Node:   v22.9.0
  MySQL:  port 3307
==========================================

Everything from this point runs inside nix develop.

Start MySQL

mysqld --datadir=$MYSQL_DATADIR --socket=$MYSQL_UNIX_PORT --port=$MYSQL_TCP_PORT &

Wait a couple of seconds, then create the database:

mysql -u root --socket=$MYSQL_UNIX_PORT -e "CREATE DATABASE IF NOT EXISTS product_api;"

Run the backend

Update product-api/.env to use port 3307:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3307
DB_DATABASE=product_api
DB_USERNAME=root
DB_PASSWORD=

Then:

cd product-api
composer install
php artisan migrate
php artisan db:seed
php artisan serve

If you previously ran composer install with a different PHP, delete vendor/ first: rm -rf vendor && composer install.

Run the frontend

Open a new terminal, same directory:

cd workspace
nix develop
cd product-frontend
npm install
npm run dev

Open http://localhost:5173, your product list is running, powered entirely by Nix.

The Day-to-Day

Every time you work on the project:

cd workspace
nix develop

# Start MySQL
mysqld --datadir=$MYSQL_DATADIR --socket=$MYSQL_UNIX_PORT --port=$MYSQL_TCP_PORT &

# Terminal 1: backend
cd product-api && php artisan serve

# Terminal 2 (new terminal, nix develop first): frontend
cd product-frontend && npm run dev

Everything you're used to works normally:

php artisan tinker
php artisan migrate
php artisan make:model
composer require <package>
npm install <package>
mysql -u root --socket=$MYSQL_UNIX_PORT product_api

What to Commit

git add flake.nix flake.lock
git commit -m "Add Nix dev environment"

Add to .gitignore:

.nix-mysql/
.direnv/
result

The flake.lock pins exact versions, treat it like composer.lock.

When a New Developer Joins

Before Nix:

1. Read the README
2. Install PHP 8.3 (they install 8.1)
3. Install Node (wrong version)
4. Install MySQL (can't connect)
5. Spend 4 hours debugging
6. Finally get it running

After Nix:

# One-time: install Nix
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# Every time:
git clone https://github.com/rodrigonbarreto/nix_blog_post.git
cd nix_blog_post
nix develop
# Same PHP, same Node, same MySQL. Done.

Customizing

Need Redis? Add it:

buildInputs = with pkgs; [
  # ... existing packages
  redis
];

Need more PHP extensions? Add them to the buildEnv block in flake.nix:

php = pkgs.php83.buildEnv {
  extensions = { all, ... }: with all; [
    # ... existing extensions
    redis
    imagick
    gd
  ];
};

Run nix develop again and the new packages are there.

Troubleshooting

"experimental feature 'flakes' is disabled": Add experimental-features = nix-command flakes to ~/.config/nix/nix.conf.

"The iconv OR mbstring extension is required": Add missing extensions to the buildEnv block in flake.nix, then exit and re-enter nix develop. Also make sure the shellHook includes unset PHP_INI_SCAN_DIR, tools like Laravel Herd can hijack the PHP config and hide Nix extensions.

MySQL won't start: Check if port 3307 is in use. Look at the error output from mysqld.

"command not found" outside the shell: Expected. Everything only exists inside nix develop.

Want auto-activation? Install direnv, create .envrc with use flake, run direnv allow. The environment activates automatically when you cd into the project.

Next Steps

If you found this useful, I'm planning a Part 2 where we set up the entire stack, MySQL, Laravel, and React, to start with a single command. No more opening 3 terminals. Just:

nix develop
start

And everything is running. Drop a comment or a like if you'd want to see that.

In the meantime, some useful links to go deeper:

direnv, auto-activate the environment on cd
devenv.sh, higher-level Nix tool with built-in services
Nix language tutorial, understand what's inside the flake

One file. One command. Every machine. That's Nix.

Source code: github.com/rodrigonbarreto/nix_blog_post

Configuração setup básico p/ projetos Ruby/Rails - utilizando o WSL 2

Dominique Morem — Wed, 08 Oct 2025 15:44:48 +0000

O que será visto durante esta postagem:

Instalação do Windows Terminal.
Instalação do WSL 2.
Instalação e configuração do Ubuntu.
Instalação do Git.
Instalação do PostgreSQL.
Instalação e configuração do VSCode.
Instalação do Rails.

Observação inicial

Pessoal, alguns dos passos apresentados neste guia podem ser acompanhados em vídeo no canal Vídeos de TI no Youtube, que também traz tutoriais práticos e explicativos sobre a temática aqui abordada. Para quem aprende bem por meio de audiovisual, fica a dica. Alguns dos exemplos de conteúdos aqui presentes que vocês também encontrarão por lá são os comandos básicos do terminal Ubuntu (video) e o processo de instalação do RVM (video).

Assim, você poderá optar por seguir via texto por aqui, ou por acompanhar visualmente pelo canal, o que for mais confortável a sua pessoa.

1 - Começando pela instalação do Windows Terminal

Este passo é opcional

O Windows Terminal é uma interface moderna para usar vários shells (CMD, PowerShell, WSL, etc). Apesar de ser opcional, ele é muito recomendado pois facilita quando formos utilizar o WSL 2.

Para instalá-lo é muito simples.

1.1 - Vá até a Microsoft Store

1.2 - Na Microsoft Store busque por ‘Windows Terminal’

E clique nessa opção do menu:

1.3 - Clique em 'Abrir'

Pronto! Já temos o Windows Terminal instalado!

2 - Instalando o WSL 2

O que é o WSL 2 e por que instalá-lo?

WSL 2 (Windows Subsystem for Linux 2) é uma tecnologia da Microsoft que permite rodar um ambiente Linux completo dentro do Windows, de maneira leve e integrada.

Em vez de usar uma máquina virtual tradicional, o WSL 2 roda um kernel Linux real dentro do Windows - só que em segundo plano - permitindo executar comandos, ferramentas e aplicações Linux, como se você estivesse num Ubuntu ou Debian, contudo sem sair do Windows.

Por que o WSL 2 é importante no desenvolvimento em Ruby?

A maioria das aplicações Ruby (especialmente as do Rails) são desenvolvidas e implantadas em servidores Linux.
Usar WSL 2 faz com que seu ambiente local seja idêntico ao do servidor de produção — evitando aquele clássico “funcionava no meu Windows”.
Muitas gems Ruby dependem de bibliotecas nativas do Linux

2.1 - Checando a nossa versão do Windows

Por que checar a versão: É importante checar a versão do Windows antes de instalar o WSL 2 (Windows Subsystem for Linux 2) porque nem todas as versões do Windows suportam o WSL 2 ou suas funções mais recentes.

O WSL 2 requer recursos específicos do sistema operacional, como o subsistema de máquina virtual (Virtual Machine Platform), que só está presente a partir do Windows 10 ( versão 1903 - build 18362 ou superior) e do Windows 11 (em todas as versões).

Para checar a versão do SO vamos pressionar:

Na janela de execução que se abrir digite ‘winver’ e dê um ‘ok’.

O Windows lhe trará a versão que está em vigor na sua máquina.

Certifique-se de que é versão 10 ou alguma acima desta.

2.2 - Verificando se há atualizações a serem feitas

Antes de seguir com o processo, é importante verificar se há atualizações a fazer. Para isso:

Abra o menu iniciar e vá em ‘configurações’.

Vá em ‘Atualização e segurança’.

Verifique se há alguma atualização disponível, caso exista, instale-a.

2.3 - Ativando recursos

Agora vamos ativar alguns recursos do Windows que serão necessários à instalação do WSL 2. Vamos acessá-los.

No menu iniciar vá em ‘ativar ou desativar recursos Windows’.

2.3.1 - Subsistema do Windows para Linux

explicação: É o componente principal do WSL, ele cria a camada de compatibilidade que permite rodar binários Linux (ELF64) diretamente no Windows.

Na janela de opções que irá se abrir ative o ‘Subsistema do Windows para Linux'.

2.3.2 - Plataforma de Máquina Virtual

explicação: Ela fornece os recursos básicos de virtualização que o WSL 2 precisa para rodar um kernel Linux real. Ou seja, ela cria e gerencia pequenas máquinas virtuais leves, usadas pelo WSL 2 para executar o kernel Linux.

Ative também a opção ‘Plataforma de Máquina Virtual’.

2.3.3 - Plataforma do Hipervisor do Windows

explicação: É o conjunto de APIs que permite que o sistema operacional e aplicativos (como WSL 2 ou Docker) usem o Hyper-V — o hipervisor nativo do Windows. É interessante ativar, pois o kernel Linux do WSL 2 roda em uma VM gerenciada por esse hipervisor, que faz o isolamento entre o Windows e o Linux.

Ative adicionalmente a 'Plataforma do Hipervisor do Windows'

2.3.4 - Depois de marcar todas essas opções clique em ‘ok’

2.4 - Reiniciando a máquina para efetivar as mudanças

Depois de feito o carregamento dos recursos selecionados anteriormente, o Windows vai pedir para reiniciar a máquina, clique em ‘reiniciar agora’.

2.5 - Baixando o pacote

explicação: Nós já ativamos os componentes: Subsistema do Windows para Linux, Plataforma de Máquina Virtual e Plataforma do Hipervisor, ou seja, habilitamos o ambiente onde o WSL 2 vai rodar. Mas, ainda falta o kernel Linux propriamente dito — ou seja, “coração” do sistema. O Windows não vem com ele instalado por padrão, o que vamos fazer agora é baixar e instalar o pacote kernel Linux compilado pela Microsoft.

Reiniciada a nossa máquina, agora vamos ao navegador. Insira esta URL neste para baixar o WSL, posteriormente, dê um ‘Enter’:

https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

Depois de baixado, vamos executá-lo. Clique no arquivo baixado.

E depois clique em 'Executar'.

E instale o pacote.

2.6 - Definindo o WSL 2 como a versão padrão

Como o WSL possui duas versões, o WSL e o WSL 2, vamos dar um comando para definir o WSL 2 como a versão padrão para todas as novas distribuições Linux que você instalar no Windows.

Para definir isso, precisaremos dos 'poderes' de Administrador.

Portanto, vamos abrir o terminal ‘PowerShell’ e executá-lo como 'Administrador'.

No terminal ‘PowerShell’ vamos digitar/colar a seguinte opção e rodá-la:

wsl --set-default-version 2

3 - Instalação e configuração do Ubuntu

3.1 - Instalação do Ubuntu

Uma vez instalado o WSL 2, vamos finalmente poder instalar agora o Ubuntu.

Para isso, vá até a ‘Microsoft Store’.

Uma vez nesta, vamos procurar por ‘Ubuntu’ e instalar a versão 'Ubuntu 24.04.1 LTS'.

Clique em ‘Abrir’ para confirmar se a instalação foi concluída corretamente.

3.2 - Checando se o Ubuntu consta no Windows Terminal

Vamos checar se o Ubuntu foi certinho para o menu de terminais do Windows Terminal.

Para isso acesse o seu Windows Terminal.
Clique na setinha ao lado do ‘+’ na parte superior da janela.
No menu que aparecer clique na opção ‘Ubuntu’.

Como mostrado na figura à seguir:

Assim que abrir o terminal no Ubuntu ele vai mostrar essa mensagem na tela:

Aguarde uns segundinhos até ele terminar de instalar.

3.3 - Atribuindo Usuário e Senha ao Ubuntu

Depois disso ele vai pedir para você atribuir um nome para o novo usuário UNIX em:

Enter new UNIX username:

Insira o nome de usuário desejado.

E vai pedir uma senha - e uma repetição de senha - a esse novo usuário em:

New password:

e em

Retype new password:

Depois disso ele vai terminar de configurar o Ubuntu.

A tela vai ficar mais ou menos assim:

3.4 - Confirmando se as distros estão utilizando o WSL 2

Vá até o PowerShell, digite o comando:

wsl --list --verbose

O terminal vai mostrar algo assim - caso o WSL que está em uso seja o 2 - na coluna ‘Version’, nesta estará o número 2:

4 - APRENDENDO OS COMANDOS BÁSICOS NO TERMINAL DO UBUNTU

Alguns comandos são essenciais para uma boa navegação em terminais do Ubuntu. Aqui traremos alguns, vale a pena revisar:

pwd — Exibe o caminho completo da pasta onde você está.
ls — Lista arquivos e pastas.
cd Documentos - Entra na pasta Documentos.
cd .. - volta uma pasta.
cd ~ - volta para o diretório pessoal.(home)
mkdir projetos — Cria uma nova pasta.
rm -r pasta - apaga uma pasta e seu conteúdo.
cp arquivo.txt backup.txt - copia um arquivo.
cp -r pasta1 pasta2 - copia uma pasta com tudo dentro.
cat arquivo.txt - — Exibe o conteúdo de um arquivo.

O link para a videoaula é esse:

5 - COMANDOS ESSENCIAIS ANTES DAS INSTALAÇÕES

Se você acabou de instalar o Ubuntu via WSL 2 ou precisa instalar um novo programa, é bom começar com:

sudo apt update

E depois, se quiser aplicar as atualizações de fato dando um:

sudo apt upgrade

explicação: Porque dar esses comandos antes de começar as instalações? Rodar ambos os comandos antes de instalar qualquer pacote no WSL 2 é uma prática essencial por motivos técnicos e de segurança. Quando você instala o Ubuntu no WSL 2, ele vem com uma lista de pacotes desatualizada.
Se você não rodar sudo apt update, o sistema pode: não encontrar o Git (ou outro pacote), instalar versões antigas, ou gerar erros de dependência ao instalar.
Já o ‘sudo apt upgrade’ vai atualizar os pacotes que já estão no sistema, isso é importante para: corrigir bugs e falhas de segurança, garantir que tudo esteja compatível com os pacotes novos que serão instalados (como o Git).

6 - INSTALAÇÃO DO GIT

Vá ao Windows Terminal (no Ubuntu) e dê o comando para atualizar a lista de pacotes disponíveis nos repositórios.

sudo apt update

Depois dê o comando para instalar as atualizações disponíveis dos pacotes listados

sudo apt upgrade

Se ele perguntar se quer continuar a instalação aperte ‘y’ para ‘yes’ se ele perguntar:

Do you want to continue? [Y/n]

Ok, agora que tomamos medidas seguras, vamos instalar o GIT de fato.

Para isso utilizaremos o comando:

sudo apt install git

Para checar se o GIT foi de fato instalado podemos dar os seguintes comandos (de mesma função):

git -v

git --version

Pronto, agora já temos o Git instalado!

7 - INSTALAÇÃO DO RUBY

Nós vamos instalar a nossa primeira versão do Ruby e todas as demais versões que quisermos utilizar depois de uma mesma maneira: Ruby Version Manager(RVM), ou seja, via Gerenciador de Versões do Ruby. Usa-se essa forma pois é bem mais eficiente do que as demais e mais fácil de gerenciar também.

Para isso, vamos lá:

Abra o Windows Terminal.
Dê os dois comandos de praxe que sempre damos antes de instalar qualquer coisa:

sudo apt update

sudo apt upgrade

Vamos ao site oficial do RVM (Ruby Version Manager), na parte de instalação.
Copie a chave GPG que estiver lá e cole no seu terminal.

A do nosso caso aqui é essa:

gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

Verifique que ele importou as chaves.

Importadas com sucesso. Vamos ao próximo passo.

Retorne ao site do RVM, copie o comando à seguir e cole-o no terminal:

No nosso exemplo:

\curl -sSL https://get.rvm.io | bash

Se tudo der certo, vai aparecer uma tela assim:

Feche o Windows Terminal. Posteriormente a isso, abra-o novamente para tirar a prova real se a instalação do RVM deu certo ou não. Dê um:

rvm -v

Se a instalação tiver sido bem sucedida vai aparecer isso aqui:

Uma vez instalado o RVM podemos baixar a nossa primeira versão do Ruby. Vá ao site oficial da linguagem e veja qual é a current version do momento.
Pegue a numeração da current version e aplique o seguinte comando no terminal (contendo essa versão):
'rvm install '.

Exemplo prático, eu quero a versão 3.4.7:

 rvm install 3.4.7

O processo de instalação será exibido no terminal.

Dê um ‘rvm list’ para checar se a versão do Ruby que queremos foi instalada de fato.

8 - INSTALAÇÃO DO POSTGRESQL

No Windows Terminal, digite:

sudo apt install postgresql postgresql-contrib libpq-dev

Nota: Esse comando serve para instalar o PostgreSQL, os módulos adicionais (postgresql-contrib) e a biblioteca de desenvolvimento (libpq-dev).

Durante a instalação ele pede a senha do seu usuário do Ubuntu, bem como pergunta se você deseja seguir com o processo de instalação.

Vamos checar a versão do PostgreSQL que foi instalada.

Para isso utilizamos o seguinte comando no terminal.

psql --version

Apesar de instalado o PostgreSQL ainda não está funcionando, para que ele funcione precisamos startá-lo.
Mas antes disso precisamos setar uma nova senha para o SGBD.
Alterando a senha do usuário postgres no sistema (usuário padrão do PostgreSQL).

Dê o comando:

sudo passwd postgres

Insira a senha que deseja e depois repita-a e ele dará uma mensagem de sucesso.

Startando o PostgreSQL

Para isso vamos dar o comando para startar o serviço:

sudo service postgresql start

E depois vamos checar se o serviço/banco está ativo com um:

sudo service postgresql status

Entrando no PostgreSQL com o usuário postgres

Podemos acessar o console interativo do PostgreSQL (psql) como usuário postgres dando o seguinte comando:

sudo -u postgres psql

Esse comando vai abrir o terminal, para trabalharmos com o PostgreSQL.

O banco já está funcionando e a instalação do PostgreSQL já foi concluída!

9 - INSTALAÇÃO DO VSCODE

Se você já tiver o VSCode instalado na sua máquina, no seu Windows mesmo, não há a necessidade de baixar uma nova versão no WSL 2. Vamos utilizar o VSCode baixado no Windows mesmo.

Caso ainda não possua o editor de código:

Acesse o site oficial para baixar.
Veja esse tutorialrápido para instalação.

10 - CONFIGURANDO EXTENSÃO NO VSCODE

Abra o VSCode que foi instalado.
Uma vez neste clique neste botão para acessar as extensões:

Digite ‘WSL’ e instale a extensão indicada:

Há também outras 2 sugestões de extensões para quem trabalha com o VSCode e com o Ruby/Rails:

A Material Icon Theme - Para que o seu projeto, quando você abre no VSCode saia com aqueles ícones todos bonitinhos.
E essa aqui - Que muda as cores gerais do seu VScode.

11 - INSTALAÇÃO DO RAILS

Você pode instalar o Rails de maneira global no seu sistema. Mas não é uma prática recomendada. o ideal é instalar a versão do Rails especificamente na pasta de cada projeto.

Portanto, vamos começar criando uma pasta para os nossos projetos.

11.1 - Consultando o acesso as pastas em diferentes sistemas

Para evitar problemas de desempenho e de compatibilidade as pastas do nosso projeto NÃO serão criadas no Windows, ou seja, no caminho (/mnt/c/).

Vamos ao Windows Terminal para acessar a pasta do usuário no Ubuntu.

Para consultar essa pasta vamos dar o comando:

pwd

Nota: Esse comando vem de print working directory e serve para mostrar a sua pasta atual e o caminho para ela. Ou seja, o comando localiza aonde você está dentro da hierarquia de pastas.

Por exemplo, ao dar esse comando no Ubuntu vamos ter:

Já no Windows esse caminho estará bem aqui:

11.2 - Criando a pasta para os seus projetos no Ubuntu

Para criar a pasta, escolha e navegue até a pasta mãe - onde deseja deixar os seus projetos Rails - e dê o comando 'mkdir + nome_da_pasta_do_seu_projeto'.

Exemplo:

mkdir Projetos

11.3 - Mude para dentro da pasta que foi criada

Para isso utilize o comando:

cd Projetos

Ou 'cd nomedasuapasta'

11.4 - Instalando o Rails na pasta de Projetos

O Rails além de ser um framework é uma Gem, logo é instalado como uma. Os pacotes no Ruby são Gems.

Aqui você pode acompanhar todas as versões do Rails.

Se quiser instalar uma versão mais específica do Rails, dê este comando no terminal:

gem install rails -v 8.0.1

Se eu quiser instalar a versão mais recente e atualizada do Rails eu dou o comando:

gem install rails

A instalação do Rails vai gerar algo semelhante a isso:

11.5 - Checando se o Rails foi instalado com sucesso

rails -v

Dê um comando para consultar a versão do framework Rails.

12 - CRIANDO UM PROJETO NO RAILS NO VSCODE

Para criar um projeto no Rails dê o comando:

rails new nome_do_seu_projeto

Você também pode deixar algumas coisas pré-definidas, como por exemplo o SGBD que será utilizado:

rails new meu_projeto --database=postgresql

Ou deixar pré-definido se vai utilizar o Tailwind no projeto ou não:

rails new meu_projeto -d postgresql -c tailwind

Vamos gerar o nosso próprio projeto aqui:

rails new teste --database=postgresql

Aqui o projeto sendo criado:

Uma vez criado o projeto, se mude para dentro da pasta deste utilizando um 'cd teste'.

Posteriormente, abra o seu projeto com o Visual Studio Code e vá mexer nele. Edite-o como quiser. Para isso se utilize do comando: 'code .'

Repare que ele vai - na primeira vez que o VSCode abre ali - instalar o editor de código para o Linux x64:

Com isso, fico por aqui. Espero que tenham gostado da explicação sobre como instalar o setup para desenvolvimento em Ruby/Rails. Tentei deixar o mais detalhado possível, para evitar que as pessoas - mesmo as mais iniciantes em programação - consigam ter um bom entendimento desse processo de instalação da linguagem e dos demais componentes utilizados no desenvolvimento web com a linguagem.

Vejo vocês na próxima.

Tchau tchau.

Importação de Dados em Rails: Do Jeito Menos Indicado ao Otimizado 🚀🇧🇷

Rodrigo Barreto — Sat, 23 Aug 2025 23:11:05 +0000

Este post foi 100% criado com meus exemplos, código e experiências reais, mas formatado com ajuda de AI para melhor organização. A AI pode nos ajudar a formatar e estruturar conteúdo, mas não substitui o conhecimento e experiência prática que nós, desenvolvedores, trazemos!

📦 Código completo disponível no GitHub: https://github.com/rodrigonbarreto/event_reservation_system/tree/blog_post_import_data

Importar dados de arquivos JSON ou Excel é uma tarefa comum no dia a dia de desenvolvimento Rails, mas muita gente ainda faz isso de forma ineficiente. Hoje vou mostrar três abordagens com resultados impressionantes: em um teste local com apenas 10.000 registros, a diferença foi de ~40 segundos para ~5 segundos - uma melhoria de mais de 8x!

O que este post NÃO aborda 📝

Como ler arquivos muito grandes de forma eficiente (isso fica para outro post)
Importações por chunks/batches avançados (para não deixar o post muito extenso)
Estratégias de paralelização com Sidekiq/ActiveJob

💡 Dica de ouro: Para quem usa PostgreSQL, o livro High Performance PostgreSQL for Rails é leitura obrigatória!

Preparando Nosso Cenário 🎬

Primeiro, vamos criar dados mockados para testar nossas implementações:

# file_generator.rb (na raiz do projeto)
require 'json'
require 'faker'

base_users = [
  { name: "John Smith", email: "john@example.com", bio: "Ruby on Rails dev..." },
  { name: "Sarah Johnson", email: "sarah@example.com", bio: "Tech Lead..." },
  { name: "Mike Wilson", email: "mike@example.com", bio: "Full-stack dev..." },
  { name: "Emma Davis", email: "emma@example.com", bio: "DevOps engineer..." },
  { name: "Alex Rodriguez", email: "alex@example.com", bio: "Senior dev..." }
]

base_titles = [
  "Complete Guide to Active Record Queries",
  "Avoiding the N+1 Problem in Rails",
  "TDD with RSpec: From Basic to Advanced"
]

base_contents = [
  "In this article, we explore...",
  "Let's dive deep into...",
  "This tutorial covers..."
]

base_categories = ["Ruby on Rails", "Performance", "Database", "DevOps", "Architecture"]

posts = []

10_000.times do |i|
  user = base_users.sample
  post = {
    title: "#{base_titles.sample} ##{i}",
    content: "#{base_contents.sample} #{Faker::Lorem.paragraph(sentence_count: 5)}",
    published: [true, false].sample,
    user: user,
    categories: base_categories.sample(rand(1..3))
  }
  posts << post
end

File.write("blog_json_data_10k.json", JSON.pretty_generate(posts))

Como executar 🏃‍♂️

Gere o arquivo JSON com dados de teste:

# Na raiz do seu projeto Rails, execute:
ruby file_generator.rb

Isso vai criar um arquivo blog_json_data_10k.json com 10.000 posts mockados.

Para testar as diferentes implementações no Rails console:

# Abra o console Rails
rails console

# Para testar a implementação menos recomendada (prepare o café!)
Importer::BadImporter.import!

# Para testar a implementação razoável
Importer::BlogDataImporter.import!

# Para testar a implementação otimizada (vai voar!)
Importer::BlogDataImporterWithActiveRecordImport.import!

💡 Nota: Você pode alterar 10_000.times para gerar mais ou menos dados. Para começar, 1.000 registros já mostram bem a diferença!

A Classe JsonImporter (Auxiliar) 📄

Você deve ter notado que estamos usando Importer::JsonImporter em todos os exemplos. É uma classe auxiliar simples para ler o arquivo JSON:

# app/services/importer/json_importer.rb
module Importer
  class JsonImporter
    attr_reader :file_name, :file_path

    def initialize(file_name:)
      @file_name = file_name
      @file_path = Rails.root.join(file_name)
    end

    def import!
      unless File.exist?(@file_path)
        raise "File not found: #{@file_path}"
      end

      puts "📁 Reading JSON file: #{@file_name}"
      file_content = File.read(@file_path)
      JSON.parse(file_content)
    rescue JSON::ParserError => e
      raise "Invalid JSON format: #{e.message}"
    rescue StandardError => e
      raise "Error reading file: #{e.message}"
    end
  end
end

Esta é uma implementação básica que carrega todo o arquivo na memória. Existem maneiras MUITO mais performáticas e eficientes de ler arquivos grandes (streaming, chunking, etc.), mas isso fica para outro post! O foco aqui é na importação dos dados para o banco.

Exemplo 1: O Jeito Menos Recomendado ❌

# app/services/importer/bad_importer.rb
module Importer
  class BadImporter
    def self.import!
      start_time = Time.current

      blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

      # Processa cada post individualmente
      blog_json.each do |post_data|

        # Cria usuário para cada post (verifica duplicatas toda vez!)
        user = User.find_or_create_by(email: post_data["user"]["email"]) do |u|
          u.name = post_data["user"]["name"]
          u.bio = post_data["user"]["bio"]
        end

        # Cria post
        post = Post.find_or_create_by(title: post_data["title"]) do |p|
          p.content = post_data["content"]
          p.published = post_data["published"]
          p.user = user
        end

        # Cria categorias para cada post (mais verificações!)
        post_data["categories"].each do |category_name|
          category = Category.find_or_create_by(name: category_name)

          # Cria associação
          PostCategory.find_or_create_by(post: post, category: category)
        end
      end

      elapsed_time = Time.current - start_time
      puts "Tempo total: #{elapsed_time.round(2)} segundos"
    end
  end
end

Por que esse código não é o mais recomendável? 🤔

Query explosion: Para cada post, fazemos múltiplas queries (find_or_create_by)
Sem transação: Se algo falhar no meio, você terá dados parciais no banco
Performance sofrível: No meu teste, levou 38.43 segundos para apenas 10.000 registros!
Uso desnecessário de recursos: Verifica duplicatas a cada iteração
Sem proteção contra falhas: Um erro em qualquer linha pode deixar lixo no banco

⚠️ Realidade: Já vi código assim em produção processando muitos de registros. Imagina o tempo!

Exemplo 2: O Jeito Razoável ✅

# app/services/importer/blog_data_importer.rb
module Importer
  class BlogDataImporter
    def self.import!
      start_time = Time.current

      ActiveRecord::Base.transaction do
        blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

        # Extrai dados únicos ANTES de inserir
        categories = blog_json.map{ |post| post["categories"] }.flatten.uniq
        users = blog_json.map{ |post| post["user"] }.uniq { |user| user["email"] }

        # Insere categorias e usuários de uma vez só
        Category.insert_all(categories.map { |category| {name: category} })
        User.insert_all(users.map { |user| {name: user["name"], email: user["email"], bio: user["bio"]} })

        # Cria hashes de lookup (OTIMIZAÇÃO CHAVE!)
        categories_hash = Category.all.pluck(:name, :id).to_h
        users_hash = User.all.pluck(:email, :id).to_h

        # Importa posts
        blog_json.map do |post|
          result = {
            title: post["title"],
            content: post["content"],
            published: post["published"],
            user_id: users_hash[post["user"]["email"]]
          }
          post_data = Post.create!(result)

          # Cria associações post-categoria em lote
          PostCategory.insert_all(
            post["categories"].map { |category| 
              {post_id: post_data.id, category_id: categories_hash[category]} 
            }
          )
        end

      rescue ActiveRecord::RecordInvalid, StandardError => e
        error = "Error: #{e.message}"
        puts error
        Rails.logger.error error
      end

      elapsed_time = Time.current - start_time
      puts "Tempo total: #{elapsed_time.round(2)} segundos"
    end
  end
end

Por que este código é bem melhor? 👍

Usa transação: Garante atomicidade - ou importa tudo ou nada
insert_all: Reduz drasticamente o número de queries
Hashes de lookup: Transforma buscas O(n) em O(1) - genial!
Processa duplicatas uma vez só: Muito mais eficiente

A Mágica dos Hashes de Lookup 🎩

categories_hash = Category.all.pluck(:name, :id).to_h
# Resultado: {"Ruby on Rails" => 1, "Performance" => 2, ...}

Ao invés de buscar a categoria no banco para cada post (10.000 buscas!), fazemos uma query só e acessamos via hash. Isso é ouro puro para performance!

Exemplo 3: O Jeito OTIMIZADO com activerecord-import 🚀

Primeiro, adicione ao Gemfile:

gem 'activerecord-import'
# Se estiver usando PostgreSQL (como no exemplo do repositório)
gem 'pg', '~> 1.1'

💡 Nota: Este post funciona com qualquer banco de dados (SQLite, MySQL, PostgreSQL). No código de exemplo que disponibilizei no GitHub, usei PostgreSQL, mas você pode usar o banco que preferir!

Agora veja a mágica acontecer:

# app/services/importer/blog_data_importer_with_active_record_import.rb
module Importer
  class BlogDataImporterWithActiveRecordImport
    def self.import!
      start_time = Time.current

      ActiveRecord::Base.transaction do
        blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

        # Prepara dados únicos
        categories = blog_json.map{ |post| post["categories"] }.flatten.uniq
        users = blog_json.map{ |post| post["user"] }.uniq { |user| user["email"] }

        # Importa categorias e usuários em batch
        category_objects = categories.map { |name| Category.new(name: name) }
        Category.import category_objects, on_duplicate_key_ignore: true, validate: false

        user_objects = users.map { |user| 
          User.new(name: user["name"], email: user["email"], bio: user["bio"]) 
        }
        User.import user_objects, on_duplicate_key_ignore: true, validate: false

        # Cria hashes de lookup
        categories_hash = Category.all.pluck(:name, :id).to_h
        users_hash = User.all.pluck(:email, :id).to_h

        # Importa posts em batches para economizar memória
        blog_json.in_groups_of(1000, false) do |post_batch|
          posts_to_import = post_batch.map do |post|
            Post.new(
              title: post["title"],
              content: post["content"],
              published: post["published"],
              user_id: users_hash[post["user"]["email"]]
            )
          end

          # Importa este batch de posts (sem validações para máxima performance!)
          Post.import posts_to_import, validate: false
        end

        # Prepara e importa associações em batches
        Post.where(title: blog_json.map { |p| p["title"] }).find_in_batches(batch_size: 1000) do |post_batch|
          post_categories = []

          post_batch.each do |post|
            post_data = blog_json.find { |p| p["title"] == post.title }
            post_data["categories"].each do |category_name|
              post_categories << PostCategory.new(
                post_id: post.id,
                category_id: categories_hash[category_name]
              )
            end
          end

          # Importa as associações deste batch (sem validações!)
          PostCategory.import post_categories, validate: false if post_categories.any?
        end

      rescue StandardError => e
        error = "Error: #{e.message}"
        puts error
        Rails.logger.error error
      end

      elapsed_time = Time.current - start_time
      puts "Tempo total: #{elapsed_time.round(2)} segundos"
    end
  end
end

Por que activerecord-import é SENSACIONAL? 🎯

SQL otimizado: Gera um único INSERT com múltiplos VALUES
Gestão de memória: Processa em batches de 1000 registros
Flexibilidade total: Validações opcionais, upserts, callbacks
Performance brutal: No meu teste: ~5 segundos!

A gem oferece opções poderosas:

on_duplicate_key_ignore: Ignora duplicatas silenciosamente
on_duplicate_key_update: Atualiza registros existentes
validate: false: Pula validações do Rails (ganho extra de performance!)
batch_size: Controla o uso de memória

Comparação de Performance Real 📊

Teste local com 10.000 registros em um Apple M3 Pro com 18GB RAM:

BadImporter: ~40 segundos 😱
BlogDataImporter: ~15 segundos 😊
BlogDataImporterWithActiveRecordImport: ~5 segundos 🚀

A versão otimizada foi 8x mais rápida que a menos recomendada!

⚠️ Importante sobre os tempos: Estes testes foram feitos em uma máquina potente (M3 Pro, 18GB RAM). Em uma VPS básica (1GB RAM, 1 vCPU), esses tempos podem ser 3-4x maiores - ou seja, o BadImporter poderia levar 2-3 minutos! Mas a proporção de melhoria se mantém: a versão otimizada sempre será muito mais rápida, independente do hardware.

Com volumes maiores (100.000 ou 1.000.000 de registros), você precisaria de estratégias ainda mais avançadas como processamento paralelo, filas, ou ferramentas especializadas - mas mesmo essa versão já é infinitamente melhor que o approach tradicional!

Conclusão e Boas Práticas 🎉

A diferença entre uma importação mal feita e uma otimizada pode significar:

Seu script rodando em segundos ao invés de horas
Menos carga no banco de dados
Menor uso de memória
Rollback automático em caso de erro

Sempre use:

Transações para garantir consistência
Inserções em lote (insert_all ou activerecord-import)
Hashes de lookup para evitar queries desnecessárias
Processamento de dados únicos antes da inserção
Batches para controlar uso de memória

activerecord-import é seu melhor amigo para importações em massa!

Gostou do post? Deixe um ❤️ e compartilhe com outros devs Rails!

Quer mais conteúdo sobre performance e banco de dados?

Comenta aí embaixo o que você gostaria de ver:

Estratégias avançadas com a gem activerecord-import
Migrations e alterações de colunas em bases de dados existentes com milhões de registros
Casos reais com Kafka ou SQS para processamento assíncrono
Outras estratégias de otimização de banco de dados

É só pedir que a gente prepara o conteúdo! 🚀

rails #ruby #performance #database #postgresql #activerecord

Data Import in Rails: From Less Recommended to Optimised 🚀🇬🇧

Rodrigo Barreto — Sat, 23 Aug 2025 23:10:53 +0000

This post was 100% created with my examples, code, and real experiences, but formatted with AI assistance for better organization. AI can help us format and structure content, but it doesn't replace the knowledge and practical experience that we developers bring!

Importing data from JSON or Excel files is a common task in Rails development, but many people still do it inefficiently. Today I'll show you three approaches with impressive results: in a local test with just 10,000 records, the difference was from ~40 seconds to ~5 seconds - an improvement of more than 8x!

What this post does NOT cover 📝

How to efficiently read very large files (that's for another post)
Advanced chunks/batches imports (to keep the post concise)
Parallelization strategies with Sidekiq/ActiveJob

💡 Golden tip: For PostgreSQL users, the book High Performance PostgreSQL for Rails is a must-read!

Setting Up Our Scenario 🎬

First, let's create mock data to test our implementations:

# file_generator.rb (at the root of your project)
require 'json'
require 'faker'

base_users = [
  { name: "John Smith", email: "john@example.com", bio: "Ruby on Rails dev..." },
  { name: "Sarah Johnson", email: "sarah@example.com", bio: "Tech Lead..." },
  { name: "Mike Wilson", email: "mike@example.com", bio: "Full-stack dev..." },
  { name: "Emma Davis", email: "emma@example.com", bio: "DevOps engineer..." },
  { name: "Alex Rodriguez", email: "alex@example.com", bio: "Senior dev..." }
]

base_titles = [
  "Complete Guide to Active Record Queries",
  "Avoiding the N+1 Problem in Rails",
  "TDD with RSpec: From Basic to Advanced"
]

base_contents = [
  "In this article, we explore...",
  "Let's dive deep into...",
  "This tutorial covers..."
]

base_categories = ["Ruby on Rails", "Performance", "Database", "DevOps", "Architecture"]

posts = []

10_000.times do |i|
  user = base_users.sample
  post = {
    title: "#{base_titles.sample} ##{i}",
    content: "#{base_contents.sample} #{Faker::Lorem.paragraph(sentence_count: 5)}",
    published: [true, false].sample,
    user: user,
    categories: base_categories.sample(rand(1..3))
  }
  posts << post
end

File.write("blog_json_data_10k.json", JSON.pretty_generate(posts))

How to run 🏃‍♂️

Generate the JSON file with test data:

# At the root of your Rails project, run:
ruby file_generator.rb

This will create a blog_json_data_10k.json file with 10,000 mock posts.

To test the different implementations in Rails console:

# Open Rails console
rails console

# To test the less recommended implementation (grab some coffee!)
Importer::BadImporter.import!

# To test the reasonable implementation
Importer::BlogDataImporter.import!

# To test the optimized implementation (it will fly!)
Importer::BlogDataImporterWithActiveRecordImport.import!

💡 Note: You can change 10_000.times to generate more or less data. To start, 1,000 records already show the difference well!

The JsonImporter Class (Helper) 📄

You may have noticed we're using Importer::JsonImporter in all examples. It's a simple helper class to read the JSON file:

# app/services/importer/json_importer.rb
module Importer
  class JsonImporter
    attr_reader :file_name, :file_path

    def initialize(file_name:)
      @file_name = file_name
      @file_path = Rails.root.join(file_name)
    end

    def import!
      unless File.exist?(@file_path)
        raise "File not found: #{@file_path}"
      end

      puts "📁 Reading JSON file: #{@file_name}"
      file_content = File.read(@file_path)
      JSON.parse(file_content)
    rescue JSON::ParserError => e
      raise "Invalid JSON format: #{e.message}"
    rescue StandardError => e
      raise "Error reading file: #{e.message}"
    end
  end
end

This is a basic implementation that loads the entire file into memory. There are MUCH more performant and efficient ways to read large files (streaming, chunking, etc.), but that's for another post! The focus here is on importing data to the database.

Example 1: The Less Recommended Way ❌

# app/services/importer/bad_importer.rb
module Importer
  class BadImporter
    def self.import!
      start_time = Time.current

      blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

      # Process each post individually
      blog_json.each do |post_data|

        # Create user for every post (checks for duplicates every time!)
        user = User.find_or_create_by(email: post_data["user"]["email"]) do |u|
          u.name = post_data["user"]["name"]
          u.bio = post_data["user"]["bio"]
        end

        # Create post
        post = Post.find_or_create_by(title: post_data["title"]) do |p|
          p.content = post_data["content"]
          p.published = post_data["published"]
          p.user = user
        end

        # Create categories for every post (more checks!)
        post_data["categories"].each do |category_name|
          category = Category.find_or_create_by(name: category_name)

          # Create association
          PostCategory.find_or_create_by(post: post, category: category)
        end
      end

      elapsed_time = Time.current - start_time
      puts "Total time: #{elapsed_time.round(2)} seconds"
    end
  end
end

Why is this code not recommended? 🤔

Query explosion: For each post, we make multiple queries (find_or_create_by)
No transaction: If something fails in the middle, you'll have partial data in the database
Poor performance: In my test, it took ~40 seconds for just 10,000 records!
Unnecessary resource usage: Checks for duplicates on every iteration
No failure protection: An error on any line can leave garbage in the database

⚠️ Reality: I've seen code like this in production processing a lot of records. Imagine the time!

Example 2: The Reasonable Way ✅

# app/services/importer/blog_data_importer.rb
module Importer
  class BlogDataImporter
    def self.import!
      start_time = Time.current

      ActiveRecord::Base.transaction do
        blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

        # Extract unique data BEFORE inserting
        categories = blog_json.map{ |post| post["categories"] }.flatten.uniq
        users = blog_json.map{ |post| post["user"] }.uniq { |user| user["email"] }

        # Insert categories and users all at once
        Category.insert_all(categories.map { |category| {name: category} })
        User.insert_all(users.map { |user| {name: user["name"], email: user["email"], bio: user["bio"]} })

        # Create lookup hashes (KEY OPTIMIZATION!)
        categories_hash = Category.all.pluck(:name, :id).to_h
        users_hash = User.all.pluck(:email, :id).to_h

        # Import posts
        blog_json.map do |post|
          result = {
            title: post["title"],
            content: post["content"],
            published: post["published"],
            user_id: users_hash[post["user"]["email"]]
          }
          post_data = Post.create!(result)

          # Create post-category associations in batch
          PostCategory.insert_all(
            post["categories"].map { |category| 
              {post_id: post_data.id, category_id: categories_hash[category]} 
            }
          )
        end

      rescue ActiveRecord::RecordInvalid, StandardError => e
        error = "Error: #{e.message}"
        puts error
        Rails.logger.error error
      end

      elapsed_time = Time.current - start_time
      puts "Total time: #{elapsed_time.round(2)} seconds"
    end
  end
end

Why is this code much better? 👍

Uses transaction: Ensures atomicity - either imports everything or nothing
insert_all: Drastically reduces the number of queries
Lookup hashes: Transforms O(n) searches into O(1) - genius!
Process duplicates only once: Much more efficient

The Magic of Lookup Hashes 🎩

categories_hash = Category.all.pluck(:name, :id).to_h
# Result: {"Ruby on Rails" => 1, "Performance" => 2, ...}

Instead of searching for the category in the database for each post (10,000 searches!), we make one query and access via hash. This is pure gold for performance!

Example 3: The OPTIMIZED Way with activerecord-import 🚀

First, add to your Gemfile:

gem 'activerecord-import'
# If using PostgreSQL (as in the repository example)
gem 'pg', '~> 1.1'

💡 Note: This post works with any database (SQLite, MySQL, PostgreSQL). In the example code I've made available on GitHub, I used PostgreSQL, but you can use whatever database you prefer!

Now watch the magic happen:

# app/services/importer/blog_data_importer_with_active_record_import.rb
module Importer
  class BlogDataImporterWithActiveRecordImport
    def self.import!
      start_time = Time.current

      ActiveRecord::Base.transaction do
        blog_json = Importer::JsonImporter.new(file_name: "blog_json_data_10k.json").import!

        # Prepare unique data
        categories = blog_json.map{ |post| post["categories"] }.flatten.uniq
        users = blog_json.map{ |post| post["user"] }.uniq { |user| user["email"] }

        # Import categories and users in batch
        category_objects = categories.map { |name| Category.new(name: name) }
        Category.import category_objects, on_duplicate_key_ignore: true, validate: false

        user_objects = users.map { |user| 
          User.new(name: user["name"], email: user["email"], bio: user["bio"]) 
        }
        User.import user_objects, on_duplicate_key_ignore: true, validate: false

        # Create lookup hashes
        categories_hash = Category.all.pluck(:name, :id).to_h
        users_hash = User.all.pluck(:email, :id).to_h

        # Import posts in batches to save memory
        blog_json.in_groups_of(1000, false) do |post_batch|
          posts_to_import = post_batch.map do |post|
            Post.new(
              title: post["title"],
              content: post["content"],
              published: post["published"],
              user_id: users_hash[post["user"]["email"]]
            )
          end

          # Import this batch of posts (without validations for maximum performance!)
          Post.import posts_to_import, validate: false
        end

        # Prepare and import associations in batches
        Post.where(title: blog_json.map { |p| p["title"] }).find_in_batches(batch_size: 1000) do |post_batch|
          post_categories = []

          post_batch.each do |post|
            post_data = blog_json.find { |p| p["title"] == post.title }
            post_data["categories"].each do |category_name|
              post_categories << PostCategory.new(
                post_id: post.id,
                category_id: categories_hash[category_name]
              )
            end
          end

          # Import associations for this batch (without validations!)
          PostCategory.import post_categories, validate: false if post_categories.any?
        end

      rescue StandardError => e
        error = "Error: #{e.message}"
        puts error
        Rails.logger.error error
      end

      elapsed_time = Time.current - start_time
      puts "Total time: #{elapsed_time.round(2)} seconds"
    end
  end
end

Why is activerecord-import AMAZING? 🎯

Optimized SQL: Generates a single INSERT with multiple VALUES
Memory management: Processes in batches of 1000 records
Total flexibility: Optional validations, upserts, callbacks
Brutal performance: In my test: ~5 seconds!

The gem offers powerful options:

on_duplicate_key_ignore: Silently ignores duplicates
on_duplicate_key_update: Updates existing records
validate: false: Skips Rails validations (extra performance gain!)
batch_size: Controls memory usage

Real Performance Comparison 📊

Local test with 10,000 records on an Apple M3 Pro with 18GB RAM:

BadImporter: ~40 seconds 😱
BlogDataImporter: ~15 seconds 😊
BlogDataImporterWithActiveRecordImport: ~5 seconds 🚀

The optimized version was 8x faster than the less recommended one!

⚠️ Important about timing: These tests were done on a powerful machine (M3 Pro, 18GB RAM). On a basic VPS (1GB RAM, 1 vCPU), these times could be 3-4x higher - meaning BadImporter could take 2-3 minutes! But the improvement ratio remains: the optimized version will always be much faster, regardless of hardware.

With larger volumes (100,000 or 1,000,000 records), you'd need even more advanced strategies like parallel processing, queues, or specialized tools - but even this version is infinitely better than the traditional approach!

Conclusion and Best Practices 🎉

The difference between a poorly done import and an optimized one can mean:

Your script running in seconds instead of hours
Less database load
Lower memory usage
Automatic rollback in case of error

Always use:

Transactions to ensure consistency
Batch insertions (insert_all or activerecord-import)
Lookup hashes to avoid unnecessary queries
Process unique data before insertion
Batches to control memory usage

activerecord-import is your best friend for bulk imports!

Liked this post? Leave a ❤️ and share with other Rails devs!

Want more content about performance and databases?

Comment below what you'd like to see:

Advanced strategies with the activerecord-import gem
Migrations and column changes in existing databases with millions of records
Real cases with Kafka or SQS for asynchronous processing
Other database optimization strategies

Just ask and we'll prepare the content! 🚀

rails #ruby #performance #database #postgresql #activerecord

Tips and Tricks Ruby on Rails

Rodrigo Barreto — Sun, 27 Jul 2025 14:37:10 +0000

Where This Came From

This content was inspired by:

Drifting Ruby - Ruby on Rails screencasts
Videos de TI - Portuguese course by @jacksonpires
thoughtbot - English courses

Note: Don't let AI do your work, but let it help you! All the content and experience are mine, but it was formatted and organized with AI help for better clarity and structure.

The other day, a friend asked for help with his project. We spent hours catching up and laughing, and he ended up picking up several Rails tips from me - simple stuff that can help Junior and Mid-level developers.

At the end of our chat, he said - "Why don't you create a post about this???"

And I said: "you know what, why not?"

The "Tips and Tricks" title came from Drifting Ruby episode with the same name. They have lots of other examples there, but I literally brought just this one part from there:

Project.find(1).present? 
Project.exists?(id: 1) 
Project.where(id: 1).any?

By the way, I recommend the subscription - they have lots of cool stuff.

Also, if you want to learn Ruby on Rails better, I recommend Videos de TI (only in Portuguese), but I do recommend it - it's from my friend @jacksonpires, he's a great teacher.

And thoughtbot has awesome courses in English.

Let's go, let's build this post!

What's Inside

Project Setup
Console Tips & Navigation
Active Record Basics
Hands-on Console Examples
Wrap Up

Project Setup

First, let's create some simple blog models to test our examples:

📁 Full project available at: github.com/rodrigonbarreto/event_reservation_system

Rails Generate Commands

# Create the models
rails generate model User name:string email:string bio:text
rails generate model Category name:string description: "text"
rails generate model Post title: "string content:text published:boolean user:references"
rails generate model Comment content:text post:references user:references
rails generate model PostCategory post:references category:references

rails db:migrate
rails db:seed

Complete Models

📂 Click to see the complete models

# app/models/user.rb
class User &lt; ApplicationRecord
  has_many :posts, dependent: :destroy
  has_many :comments, dependent: :destroy
  has_many :post_categories, through: :posts
  has_many :categories, through: :post_categories

  validates :name, presence: true
  validates :email, presence: true, uniqueness: true

  def published_posts
    posts.where(published: true)
  end
end

# app/models/category.rb
class Category &lt; ApplicationRecord
  has_many :post_categories, dependent: :destroy
  has_many :posts, through: :post_categories
  has_many :users, through: :posts

  validates :name, presence: true, uniqueness: true

  scope :with_published_posts, -&gt; { joins(:posts).where(posts: { published: true }).distinct }

  def published_posts_count
    posts.where(published: true).count
  end
end

# app/models/post.rb
class Post &lt; ApplicationRecord
  belongs_to :user
  has_many :comments, dependent: :destroy
  has_many :post_categories, dependent: :destroy
  has_many :categories, through: :post_categories

  validates :title, presence: true
  validates :content, presence: true

  scope :published, -&gt; { where(published: true) }
  scope :recent, -&gt; { where('created_at &gt; ?', 1.week.ago) }
  scope :by_user, -&gt;(user) { where(user: user) }

  def comments_count
    comments.count
  end
end

# app/models/comment.rb
class Comment &lt; ApplicationRecord
  belongs_to :post
  belongs_to :user

  validates :content, presence: true

  scope :recent, -&gt; { where('created_at &gt; ?', 1.day.ago) }
  scope :by_user, -&gt;(user) { where(user: user) }

  delegate :title, to: :post, prefix: true
  delegate :name, to: :user, prefix: true
end

# app/models/post_category.rb
class PostCategory &lt; ApplicationRecord
  belongs_to :post
  belongs_to :category

  validates :post_id, uniqueness: { scope: :category_id }

  scope :for_published_posts, -&gt; { joins(:post).where(posts: { published: true }) }
  scope :recent, -&gt; { where('created_at &gt; ?', 1.week.ago) }
end

Console Tips & Navigation

🎯 The Magic Underscore (_)

The underscore always returns the result of the last command you ran in the console. It's a quick way to grab the previous result without running the query again:

Comment.last
# => #<Comment id: 5, content: "Great post!", ...>

# The underscore (_) will always contain the last result
comment = _
# => #<Comment id: 5, content: "Great post!", ...>

# Works with any command
User.where(name: "John").limit(3)
users = _  # Grabs the 3 users without running the query again

🛠️ Helper Methods

# See available helpers
ActionController::Base.helpers

# Use Rails helpers
ActionController::Base.helpers.pluralize(5, 'post')
# => "5 posts"

ActionController::Base.helpers.time_ago_in_words(1.hour.ago)
# => "about 1 hour"

ActionController::Base.helpers.number_to_currency(29.95)
# => "$29.95"

🔄 Reload

# Reload code without leaving the console
reload!

🔍 Inspection Tricks

user = User.first

# Different output formats
user.attributes
# => {"id"=>1, "name"=>"John", ...}

user.attributes.to_json
# => "{\"id\":1,\"name\":\"John\",...}"

JSON.pretty_generate(user.attributes)
# => Nice formatted JSON output

# Pretty print
pp user.attributes

# See just the keys
user.attributes.keys
# => ["id", "name", "email", "bio"]

# Check unsaved changes
user.name = "New Name"
user.changes
# => {"name"=>["John", "New Name"]} (shows old value -> new value)

user.changed_attributes
# => {"name"=>"John"} (just the old values)

# See available methods - great for finding methods you don't know about
user.methods.sort                    # All methods in alphabetical order
user.methods.grep(/name/)           # Only methods that contain "name"
user.public_methods(false)          # Only the class's own methods (no inheritance)

# Inspect - See a readable object representation
user.inspect
# => "#<User id: 1, name: \"John\", email: \"john@example.com\", bio: \"Developer...\">"

# Useful for debugging and logs
puts user.inspect
Rails.logger.info(user.inspect)

Active Record Basics

⚡ Pluck vs Select - Getting IDs Fast

When you only need IDs, there are two main approaches:

# Example: Get all posts from "Ruby on Rails" category

# ❌ Less efficient way - loads complete objects
category_ids = Category.where(name: "Ruby on Rails").map(&:id)
posts = Post.joins(:post_categories).where(post_categories: { category_id: category_ids })

# ✅ PLUCK - Returns array, runs 1 query + 1 query = 2 total queries
ids = Category.where(name: "Ruby on Rails").pluck(:id)
# Category Pluck (0.2ms) SELECT "categories"."id" FROM "categories" WHERE "categories"."name" = 'Ruby on Rails'
posts = Post.joins(:post_categories).where(post_categories: { category_id: ids })
# Post Load (0.4ms) SELECT "posts".* FROM "posts" INNER JOIN "post_categories"...

# ✅ SELECT - Returns ActiveRecord::Relation, runs just 1 optimized query
ids = Category.where(name: "Ruby on Rails").select(:id)
posts = Post.joins(:post_categories).where(post_categories: { category_id: ids })
# Post Load (0.4ms) SELECT "posts".* FROM "posts" INNER JOIN "post_categories" 
# WHERE "post_categories"."category_id" IN (SELECT "categories"."id" FROM "categories" WHERE "categories"."name" = 'Ruby on Rails')

Key differences:

Method	Returns	Queries run	Use when
`pluck(:id)`	`[1, 3, 5]` (Array)	2 queries	Need array of values
`select(:id)`	`ActiveRecord::Relation`	1 optimized query	Using in subqueries or chains

# PLUCK - Runs the query right away and returns Array
ids = Category.where(name: "Ruby on Rails").pluck(:id)
# => [1, 3, 5] (Array of integers)

# SELECT - Returns ActiveRecord::Relation, better for chaining
ids = Category.where(name: "Ruby on Rails").select(:id)
ids.class
# => Category::ActiveRecord_Relation

# When used in the next query, makes an optimized subquery in 1 go:
Post.where(category_id: ids)  # One query with subquery, not two separate ones!

In the image below, you can see the practical difference:

PLUCK (2 queries): When we run the two lines with pluck, Rails makes two separate queries
SELECT (1 query): When we run the two lines with select, Rails optimizes and makes just one query with subquery

🎯 When to Use user_id vs user.id

One of the simplest and most important optimizations - when you only need the ID, use the direct attribute:

comment = Comment.first
# Comment Load (0.3ms) SELECT "comments".* FROM "comments" ORDER BY "comments"."id" ASC LIMIT 1

# ✅ EFFICIENT - Uses the already loaded value
comment.user_id
# => 5
# No extra query!

# ❌ INEFFICIENT - Loads the complete User object
comment.user.id  
# User Load (0.4ms) SELECT "users".* FROM "users" WHERE "users"."id" = 5 LIMIT 1
# => 5

Practical examples:

# ✅ EFFICIENT - Use when you only need the ID
if comment.user_id == current_user.id
  # Just comparing IDs, no need to load user
end

# ❌ INEFFICIENT - Loads the complete User object just for ID
if comment.user.id == current_user.id  
  # This loads the entire user object unnecessarily
end

# ✅ EFFICIENT - Use when you need other user attributes too
name = comment.user.name  # Now we're using the loaded user
id = comment.user.id      # OK to use .id since we already loaded user

Impact on Tests (RSpec):

In a test suite, this difference can be significant. In 1000 tests, this can add 2-3 extra minutes to execution:

# ❌ In a suite of 1000 tests, this can add 2-3 MINUTES
it "checks comment ownership" do
  expect(comment.user.id).to eq(current_user.id)  # Loads user unnecessarily
end

# ✅ Much faster - no extra query
it "checks comment ownership" do
  expect(comment.user_id).to eq(current_user.id)  # Just uses the already loaded ID
end

When to use each:

user_id: For comparisons, validations, foreign keys
user.id: When you're going to use other user attributes later

🚫 N+1 Problem & Includes

The N+1 problem is one of the worst performance killers:

# ❌ N+1 PROBLEM - Runs 1 + N queries
posts = Post.all  # 1 query
posts.each do |post|
  puts post.user.name  # N queries (one for each post)
end

# ✅ SOLUTION - Runs just 2 queries
posts = Post.includes(:user)  # 1 query + 1 query for users
posts.each do |post|
  puts post.user.name  # No extra queries
end

# For more complex relationships
Post.includes(:user, :comments, categories: :posts)

✅ Existence Checks - Performance Matters

# ❌ INEFFICIENT - Loads the complete object in memory
Project.find(1).present?  # SELECT * FROM projects WHERE id = 1

# ✅ EFFICIENT - Just checks if it exists in the database
Project.exists?(id: 1)    # SELECT 1 FROM projects WHERE id = 1 LIMIT 1

# ✅ ALTERNATIVE - For complex queries
Project.where(id: 1, active: true).exists?

# ⚠️ BE CAREFUL - Loads all records
Project.where(id: 1).any?  # SELECT * (can be dangerous with lots of data)

📊 Count vs Size vs Length - Performance Matters

# Scenario: User with many posts
user = User.first

# 1. COUNT - Always runs SQL query
user.posts.count
# => SELECT COUNT(*) FROM posts WHERE user_id = 1

# 2. SIZE - Smart: uses cache if collection was already loaded
user.posts.size
# If posts weren't loaded: SELECT COUNT(*)
# If posts were already loaded: posts.length (no query)

# 3. LENGTH - Forces complete collection loading
user.posts.length
# => SELECT * FROM posts WHERE user_id = 1 (DANGEROUS!)

Rule of thumb:

size: Use by default (99% of cases)
count: Use when you need the exact value from database
length: Avoid, except for small collections already loaded

🔍 Query Explain - Performance Debugging

# Analyze query performance
User.joins(:posts).where(posts: { published: true }).explain

# IRB result:
# User Load (1.2ms)  SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id" WHERE "posts"."published" = ?  [["published", 1]]
# => 
# EXPLAIN for: SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id" WHERE "posts"."published" = ? [["published", 1]]
# 3|0|0|SCAN posts
# 7|0|0|SEARCH users USING INTEGER PRIMARY KEY (rowid=?)

# Look for:
# "SCAN" = Complete table scan (can be slow)
# "SEARCH USING INDEX" = Using index (fast)  
# "USING INTEGER PRIMARY KEY" = Primary key search (awesome)

🔗 Merge - Combining Scopes Nicely

merge lets you combine conditions from different models in a clean way:

# Scenario: Published posts from active users
class User < ApplicationRecord
  scope :active, -> { where(active: true) }
  scope :premium, -> { where(premium: true) }
end

class Post < ApplicationRecord
  scope :published, -> { where(published: true) }
  scope :recent, -> { where('created_at > ?', 1.week.ago) }
end

# ❌ Verbose way
Post.joins(:user)
    .where(published: true)
    .where(users: { active: true, premium: true })

# ✅ Clean way with merge + scopes
Post.published
    .joins(:user)
    .merge(User.active)
    .merge(User.premium)

# ✅ Merge also works with where directly
Post.joins(:user)
    .merge(User.where(active: true))
    .where(published: true)

# ✅ Combining multiple conditions
Post.joins(:user, :comments)
    .merge(User.where('created_at > ?', 1.year.ago))
    .merge(Comment.where('created_at > ?', 1.week.ago))

Hands-on Console Examples

Now that you've populated the data with rails db:seed, try these commands:

# Test basic relationships
user = User.first
user.posts.published

# Test includes
Post.includes(:user, :categories, :comments).first

# Count by category
Category.joins(:posts).group('categories.name').count

# Example of pluck vs select
Category.where(name: "Ruby on Rails").pluck(:id)
Category.where(name: "Ruby on Rails").select(:id)

# Test existence checks
Post.exists?(title: "Complete Guide to Active Record Queries")
Post.where(published: true).any?

# Performance comparison
user.posts.count
user.posts.size

Wrap Up

These simple tips can make a huge difference in your Rails code performance and readability. Remember:

✅ Use pluck when you need specific values and won't continue with other queries
✅ Use select when using in subqueries or continuing the query chain
✅ Use exists? instead of loading objects just to check existence
✅ Always prefer includes to avoid N+1
✅ size is usually the best choice between count/size/length
✅ merge makes your queries more readable and reusable

💡 Tip: If this content helped you, share it with other developers!

Dicas e truques Ruby on Rails

Rodrigo Barreto — Sun, 27 Jul 2025 14:12:36 +0000

Tips and Tricks Ruby on Rails

Inspirações e Conteúdo

Este conteúdo foi inspirado por:

Drifting Ruby - Screencasts de Ruby on Rails
Videos de TI - Curso com conteúdo em português do @jacksonpires
thoughtbot - Cursos com conteúdo em inglês

Observação: Não deixe a AI fazer o seu serviço, mas deixe ela te ajudar! Todo o conteúdo e experiência são meus, mas foi formatado e organizado com ajuda de AI para melhor clareza e estrutura.

Outro dia um amigo me pediu uma ajuda no projeto dele, e perdemos horas dando boas risadas para matar a saudade e ele acabou pegando várias dicas comigo no Ruby on Rails, coisas simples, mas que podem ajudar um Junior e um Medior.

No final da conversa ele até comentou - no caso ele me chama de xará pois o nome dele também é Rodrigo - "porque você não cria um post sobre isso???"

E eu falei: "olha, porque não?"

O título "Tips and Tricks" veio do Drifting Ruby episódio com o mesmo nome. Lá tem muitos outros exemplos, mas literalmente essa única parte eu trouxe de lá:

Project.find(1).present? 
Project.exists?(id: 1) 
Project.where(id: 1).any?

Por sinal, recomendo a assinatura - eles têm muitas coisas legais.

Além disso, se você quiser aprender melhor Ruby on Rails, recomendo o Videos de TI (só tem em português), mas eu recomendo - é do meu amigo @jacksonpires, ele é um ótimo professor.

Já a thoughtbot tem ótimos cursos em inglês.

Bora lá, vamos montar esse post!

Índice

Setup do Projeto
Truques e Navegação no Console
Fundamentos do Active Record
Exemplos Práticos no Console
Conclusão

Setup do Projeto

Primeiro, vamos criar os modelos de um blog simples para testar nossos exemplos:

📁 Projeto completo disponível em: github.com/rodrigonbarreto/event_reservation_system

Comandos Rails Generate

# Gerar os modelos
rails generate model User name:string email:string bio:text
rails generate model Category name:string description: "text"
rails generate model Post title: "string content:text published:boolean user:references"
rails generate model Comment content:text post:references user:references
rails generate model PostCategory post:references category:references

rails db:migrate
rails db:seed

Modelos Completos

📂 Clique para ver os modelos completos

# app/models/user.rb
class User &lt; ApplicationRecord
  has_many :posts, dependent: :destroy
  has_many :comments, dependent: :destroy
  has_many :post_categories, through: :posts
  has_many :categories, through: :post_categories

  validates :name, presence: true
  validates :email, presence: true, uniqueness: true

  def published_posts
    posts.where(published: true)
  end
end

# app/models/category.rb
class Category &lt; ApplicationRecord
  has_many :post_categories, dependent: :destroy
  has_many :posts, through: :post_categories
  has_many :users, through: :posts

  validates :name, presence: true, uniqueness: true

  scope :with_published_posts, -&gt; { joins(:posts).where(posts: { published: true }).distinct }

  def published_posts_count
    posts.where(published: true).count
  end
end

# app/models/post.rb
class Post &lt; ApplicationRecord
  belongs_to :user
  has_many :comments, dependent: :destroy
  has_many :post_categories, dependent: :destroy
  has_many :categories, through: :post_categories

  validates :title, presence: true
  validates :content, presence: true

  scope :published, -&gt; { where(published: true) }
  scope :recent, -&gt; { where('created_at &gt; ?', 1.week.ago) }
  scope :by_user, -&gt;(user) { where(user: user) }

  def comments_count
    comments.count
  end
end

# app/models/comment.rb
class Comment &lt; ApplicationRecord
  belongs_to :post
  belongs_to :user

  validates :content, presence: true

  scope :recent, -&gt; { where('created_at &gt; ?', 1.day.ago) }
  scope :by_user, -&gt;(user) { where(user: user) }

  delegate :title, to: :post, prefix: true
  delegate :name, to: :user, prefix: true
end

# app/models/post_category.rb
class PostCategory &lt; ApplicationRecord
  belongs_to :post
  belongs_to :category

  validates :post_id, uniqueness: { scope: :category_id }

  scope :for_published_posts, -&gt; { joins(:post).where(posts: { published: true }) }
  scope :recent, -&gt; { where('created_at &gt; ?', 1.week.ago) }
end

Truques e Navegação no Console

🎯 Magia do Underscore (_)

O underscore sempre retorna o resultado do último comando executado no console. É uma forma rápida de capturar o resultado anterior sem precisar executar a query novamente:

Comment.last
# => #<Comment id: 5, content: "Great post!", ...>

# O underscore (_) sempre vai conter o último resultado
comment = _
# => #<Comment id: 5, content: "Great post!", ...>

# Funciona com qualquer comando
User.where(name: "John").limit(3)
users = _  # Captura os 3 usuários sem executar a query novamente

🛠️ Métodos Helper

# Ver helpers disponíveis
ActionController::Base.helpers

# Usar helpers do Rails
ActionController::Base.helpers.pluralize(5, 'post')
# => "5 posts"

ActionController::Base.helpers.time_ago_in_words(1.hour.ago)
# => "about 1 hour"

ActionController::Base.helpers.number_to_currency(29.95)
# => "$29.95"

🔄 Reload

# Recarregar código sem sair do console
reload!

🔍 Truques de Inspeção

user = User.first

# Diferentes formatos de saída
user.attributes
# => {"id"=>1, "name"=>"John", ...}

user.attributes.to_json
# => "{\"id\":1,\"name\":\"John\",...}"

JSON.pretty_generate(user.attributes)
# => Saída JSON formatada e legível

# Pretty print
pp user.attributes

# Ver apenas keys
user.attributes.keys
# => ["id", "name", "email", "bio"]

# Inspecionar mudanças não salvas
user.name = "New Name"
user.changes
# => {"name"=>["John", "New Name"]} (mostra valor antigo -> valor novo)

user.changed_attributes
# => {"name"=>"John"} (apenas os valores antigos)

# Ver métodos disponíveis - útil para descobrir métodos que você não conhece
user.methods.sort                    # Todos os métodos em ordem alfabética
user.methods.grep(/name/)           # Apenas métodos que contém "name"
user.public_methods(false)          # Apenas métodos próprios da classe (sem herança)

# Inspect - Ver representação do objeto de forma legível
user.inspect
# => "#<User id: 1, name: \"John\", email: \"john@example.com\", bio: \"Developer...\">"

# Útil para debugging e logs
puts user.inspect
Rails.logger.info(user.inspect)

Fundamentos do Active Record

⚡ Pluck vs Select - Performance na Recuperação de IDs

Quando você precisa apenas de IDs, existem duas abordagens principais:

# Exemplo: Buscar todos os posts da categoria "Ruby on Rails"

# ❌ Forma menos eficiente - carrega objetos completos
category_ids = Category.where(name: "Ruby on Rails").map(&:id)
posts = Post.joins(:post_categories).where(post_categories: { category_id: category_ids })

# ✅ PLUCK - Retorna array, executa 1 query + 1 query = 2 queries totais
ids = Category.where(name: "Ruby on Rails").pluck(:id)
# Category Pluck (0.2ms) SELECT "categories"."id" FROM "categories" WHERE "categories"."name" = 'Ruby on Rails'
posts = Post.joins(:post_categories).where(post_categories: { category_id: ids })
# Post Load (0.4ms) SELECT "posts".* FROM "posts" INNER JOIN "post_categories"...

# ✅ SELECT - Retorna ActiveRecord::Relation, executa apenas 1 query otimizada
ids = Category.where(name: "Ruby on Rails").select(:id)
posts = Post.joins(:post_categories).where(post_categories: { category_id: ids })
# Post Load (0.4ms) SELECT "posts".* FROM "posts" INNER JOIN "post_categories" 
# WHERE "post_categories"."category_id" IN (SELECT "categories"."id" FROM "categories" WHERE "categories"."name" = 'Ruby on Rails')

Diferenças importantes:

Método	Retorno	Queries executadas	Use quando
`pluck(:id)`	`[1, 3, 5]` (Array)	2 queries	Precisar de array de valores
`select(:id)`	`ActiveRecord::Relation`	1 query otimizada	Usar em subqueries ou chains

# PLUCK - Executa a query imediatamente e retorna Array
ids = Category.where(name: "Ruby on Rails").pluck(:id)
# => [1, 3, 5] (Array de integers)

# SELECT - Retorna ActiveRecord::Relation, mais eficiente para chains
ids = Category.where(name: "Ruby on Rails").select(:id)
ids.class
# => Category::ActiveRecord_Relation

# Quando usado na próxima query, faz subquery otimizada em 1 comando só:
Post.where(category_id: ids)  # Uma query com subquery, não duas separadas!

Na imagem abaixo, você pode ver a diferença prática:

PLUCK (2 queries): Quando executamos as duas linhas com pluck, o Rails faz duas queries separadas
SELECT (1 query): Quando executamos as duas linhas com select, o Rails otimiza e faz apenas uma query com subquery

🎯 Quando Usar user_id vs user.id

Uma das otimizações mais simples e importantes - quando você só precisa do ID, use o atributo direto:

comment = Comment.first
# Comment Load (0.3ms) SELECT "comments".* FROM "comments" ORDER BY "comments"."id" ASC LIMIT 1

# ✅ EFICIENTE - Usa o valor já carregado
comment.user_id
# => 5
# Sem query adicional!

# ❌ INEFICIENTE - Carrega o objeto User completo
comment.user.id  
# User Load (0.4ms) SELECT "users".* FROM "users" WHERE "users"."id" = 5 LIMIT 1
# => 5

Exemplos práticos:

# ✅ EFICIENTE - Use quando precisar apenas do ID
if comment.user_id == current_user.id
  # Comparando apenas IDs, sem carregar user
end

# ❌ INEFICIENTE - Carrega o objeto User completo só para pegar o ID
if comment.user.id == current_user.id  
  # Isso carrega o objeto user inteiro desnecessariamente
end

# ✅ EFICIENTE - Use quando for usar outros atributos do user também
name = comment.user.name  # Agora estamos usando o user carregado
id = comment.user.id      # OK usar .id já que carregamos o user

Impacto nos Testes (RSpec):

Em uma suite de testes, essa diferença pode ser significativa. Em 1000 testes, isso pode adicionar 2-3 minutos extras na execução:

# ❌ Em uma suite de 1000 testes, isso pode adicionar 2-3 MINUTOS
it "checks comment ownership" do
  expect(comment.user.id).to eq(current_user.id)  # Carrega user desnecessariamente
end

# ✅ Muito mais rápido - sem query extra
it "checks comment ownership" do
  expect(comment.user_id).to eq(current_user.id)  # Só usa o ID já carregado
end

Quando usar cada um:

user_id: Para comparações, validações, foreign keys
user.id: Quando você já vai usar outros atributos do user depois

🚫 Problema N+1 & Includes

O problema N+1 é um dos mais críticos em performance:

# ❌ PROBLEMA N+1 - Executa 1 + N queries
posts = Post.all  # 1 query
posts.each do |post|
  puts post.user.name  # N queries (uma para cada post)
end

# ✅ SOLUÇÃO - Executa apenas 2 queries
posts = Post.includes(:user)  # 1 query + 1 query para users
posts.each do |post|
  puts post.user.name  # Sem queries adicionais
end

# Para relacionamentos mais complexos
Post.includes(:user, :comments, categories: :posts)

✅ Verificações de Existência - Performance Importa

# ❌ INEFICIENTE - Carrega o objeto completo na memória
Project.find(1).present?  # SELECT * FROM projects WHERE id = 1

# ✅ EFICIENTE - Apenas verifica existência no banco
Project.exists?(id: 1)    # SELECT 1 FROM projects WHERE id = 1 LIMIT 1

# ✅ ALTERNATIVA - Para queries complexas
Project.where(id: 1, active: true).exists?

# ⚠️ CUIDADO - Carrega todos os registros
Project.where(id: 1).any?  # SELECT * (pode ser perigoso com muitos dados)

📊 Count vs Size vs Length - Performance Crítica

# Cenário: User com muitos posts
user = User.first

# 1. COUNT - Sempre executa query SQL
user.posts.count
# => SELECT COUNT(*) FROM posts WHERE user_id = 1

# 2. SIZE - Inteligente: usa cache se collection já foi carregada
user.posts.size
# Se posts não foram carregados: SELECT COUNT(*)
# Se posts já foram carregados: posts.length (sem query)

# 3. LENGTH - Força carregamento completo da collection
user.posts.length
# => SELECT * FROM posts WHERE user_id = 1 (PERIGOSO!)

Regra de ouro:

size: Use por padrão (99% dos casos)
count: Use quando precisar do valor exato do banco
length: Evite, exceto em collections pequenas já carregadas

🔍 Query Explain - Debug de Performance

# Analisar performance de queries
User.joins(:posts).where(posts: { published: true }).explain

# Resultado do IRB:
# User Load (1.2ms)  SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id" WHERE "posts"."published" = ?  [["published", 1]]
# => 
# EXPLAIN for: SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id" WHERE "posts"."published" = ? [["published", 1]]
# 3|0|0|SCAN posts
# 7|0|0|SEARCH users USING INTEGER PRIMARY KEY (rowid=?)

# Procure por:
# "SCAN" = Table scan completo (pode ser lento)
# "SEARCH USING INDEX" = Usando índice (rápido)  
# "USING INTEGER PRIMARY KEY" = Busca por chave primária (ótimo)

🔗 Merge - Combinando Scopes com Elegância

O merge permite combinar condições de diferentes modelos de forma limpa:

# Cenário: Posts publicados de usuários ativos
class User < ApplicationRecord
  scope :active, -> { where(active: true) }
  scope :premium, -> { where(premium: true) }
end

class Post < ApplicationRecord
  scope :published, -> { where(published: true) }
  scope :recent, -> { where('created_at > ?', 1.week.ago) }
end

# ❌ Forma verbosa
Post.joins(:user)
    .where(published: true)
    .where(users: { active: true, premium: true })

# ✅ Forma elegante com merge + scopes
Post.published
    .joins(:user)
    .merge(User.active)
    .merge(User.premium)

# ✅ Merge também funciona com where direto
Post.joins(:user)
    .merge(User.where(active: true))
    .where(published: true)

# ✅ Combinando múltiplas condições
Post.joins(:user, :comments)
    .merge(User.where('created_at > ?', 1.year.ago))
    .merge(Comment.where('created_at > ?', 1.week.ago))

Exemplos Práticos no Console

Agora que você já populou os dados com rails db:seed, teste estes comandos:

# Teste básico de relacionamentos
user = User.first
user.posts.published

# Teste de includes
Post.includes(:user, :categories, :comments).first

# Contagem por categoria
Category.joins(:posts).group('categories.name').count

# Exemplo de pluck vs select
Category.where(name: "Ruby on Rails").pluck(:id)
Category.where(name: "Ruby on Rails").select(:id)

# Teste de existence checks
Post.exists?(title: "Complete Guide to Active Record Queries")
Post.where(published: true).any?

# Performance comparison
user.posts.count
user.posts.size

Conclusão

Essas dicas simples podem fazer uma grande diferença na performance e legibilidade do seu código Rails. Lembre-se:

✅ Use pluck quando precisar apenas de valores específicos e não continuar com outras queries
✅ Use select quando for usar em subqueries ou continuar o chain de queries
✅ Use exists? em vez de carregar objetos só para verificar existência
✅ Sempre prefira includes para evitar N+1
✅ size é geralmente a melhor opção entre count/size/length
✅ merge torna suas queries mais legíveis e reutilizáveis

💡 Dica: Se este conteúdo te ajudou, compartilhe com outros desenvolvedores!

Tornando as portas do DevContainer disponíveis localmente com forwardPorts

Aureamar Jose Garcia Rocha — Thu, 10 Jul 2025 03:04:53 +0000

Introdução

Durante o desenvolvimento de um projeto utilizando DevContainer, surgiu a necessidade de acessar o banco de dados PostgreSQL que estava rodando dentro do contêiner, diretamente do meu sistema local (host). Foi nesse contexto que descobri o uso da propriedade "forwardPorts" no arquivo devcontainer.json, que permite tornar portas específicas acessíveis fora do contêiner de forma simples e eficaz.

Os passos a seguir mostram como fiz essa configuração para a fim de usar o DBeaver em minha máquina local.

Primeiro passo

A configuração é bem simples: basta adicionar a propriedade "forwardPorts" ao arquivo devcontainer.json

# .devcontainer/devcontainer.json
{
        "name": "Ruby on Rails & Postgres",
    "dockerComposeFile": "docker-compose.yml",
    "service": "app",
    "workspaceFolder": "/workspaces/task_control/rails_app",
    "forwardPorts": [
        5435
    ]
}

Neste exemplo, utilizei a porta 5435 em vez da 5432, pois a porta 5432 já está sendo usada pelo PostgreSQL instalado na minha máquina. Essa mudança evita conflitos entre os serviços locais e o banco de dados que está rodando dentro do container.

Segundo passo

Mapeando as portas com Docker Compose

Agora precisamos mapear a porta 5432 (porta padrão do PostgreSQL dentro do contêiner) para a porta 5435 no host. Para isso, vamos configurar o arquivo docker-compose.yml da seguinte forma:

db:
    image: postgres:latest
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./create-db-user.sql:/docker-entrypoint-initdb.d/create-db- 
         user.sql
    environment:
      POSTGRES_USER: postgres
      POSTGRES_DB: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - 5435:5432

Com essa configuração, sempre que você acessar 127.0.0.1:5435 no seu host, estará se comunicando com o PostgreSQL rodando na porta 5432 dentro do container. Isso garante que não haja conflito com o PostgreSQL local (caso você já tenha um instalado e ativo na porta padrão 5432).

Terceiro passo

Depois de ajustar as configurações no devcontainer.json e no docker-compose.yml, basta reabrir o DevContainer e fazer o build novamente para aplicar as alterações.

Quarto passo

Acessando o banco de dados com o DBeaver
Para se conectar ao banco de dados utilizando o DBeaver, siga o passos abaixo:

Abra o DBeaver
No meu superior, vá em Database -> New Database Connection
Selecione a opção PostgreSQL e clicar em Next.

Agora, basta preencher os campos de conexão com as informações configuradas no contêiner:

Host: 127.0.0.1
Port: 5435 (a porta mapeada no docker-compose.yml)
Database: postgres
Username: postgres
Password: ******

Agora é só testar a conexão. Se tudo estiver configurado corretamente, uma caixa de diálogo será exibida confirmando que a conexão foi estabelecida com sucesso.

Após isso, você poderá visualizar as tabelas do banco de dados diretamente no DBeaver, facilitando a navegação, consultas e até alterações na estrutura dos dados.

Conclusão

Utilizar o forwardPorts em conjunto com o mapeamento de portas no docker-compose.yml é uma solução simples e eficaz para expor serviços do DevContainer ao seu ambiente local. Essa abordagem facilita o desenvolvimento, permitindo o uso de ferramentas externas, testes e conexões diretas com o banco de dados sem complicações.

Internacionalização com GetText no Rails

Karine Vieira — Tue, 20 May 2025 12:13:00 +0000

Quando pensamos em internacionalização (i18n) em projetos Rails, a abordagem mais comum é utilizar a API nativa do framework com chaves de tradução. No entanto, recentemente descobri uma alternativa que torna esse processo mais direto e com maior visibilidade do conteúdo traduzido: o uso do GetText.

GetText é um framework utilizado no ecossistema Linux, que oferece um conjunto de ferramentas para facilitar a tradução de textos em aplicações. Integrado ao Rails, ele permite uma forma mais automática de localizar strings, sem a necessidade de criar e gerenciar nomes de chaves.

No modelo tradicional com I18n, criamos chaves de tradução e mapeamos seus conteúdos em arquivos YML. Nas views, essas chaves são utilizadas da seguinte forma:

t(".empty_state_message")
# => Nenhum resultado encontrado

Já com GetText, podemos escrever diretamente o texto original:

_("Nenhum resultado encontrado")
# => Nenhum resultado encontrado

Essa abordagem destaca imediatamente o conteúdo que será traduzido, tornando o código mais legível e intuitivo.

Setup

Instalação das Gems

Para integrar o GetText ao Rails, instalei as gems gettext_i18n_rails e gettext. Apesar de gettext ser uma dependência opcional da gettext_i18n_rails, vale a pena incluí-la no projeto, pois ela oferece rake tasks bastante úteis:

Para adicionar suporte a um novo idioma:

LANGUAGE=xx rake gettext:add_language

Substitua xx pelo código do idioma desejado, por exemplo, en para inglês. A lista completa dos idiomas suportados está disponível aqui.

Para buscar traduções ausentes e adicioná-las aos arquivos .po:

rake gettext:find

Configurações iniciais

Depois da instalação, é necessário criar um initializer para definir os domínios de tradução e os idiomas disponíveis. Para isso, usamos classes da gem fast_gettext, já que gettext_i18n_rails atua como um wrapper para facilitar a integração do GetText com projetos Rails.

# config/initializers/gettext_i18n_rails.rb
FastGettext.add_text_domain "app", path: "locale", type: :po
FastGettext.default_available_locales = ["pt_BR", "en", "es"]
FastGettext.default_text_domain = "app"

Essa configuração permite organizar as traduções por domínio. No exemplo acima, usei apenas o domínio app para fins de demonstração, mas é possível definir domínios separados por módulos da aplicação, evitando centralizar todas as traduções em um único arquivo.

Além disso, ajuste o before_action responsável por definir o idioma da aplicação para também atualizar o locale do GetText:

 def set_locale
   locale = params[:locale] || I18n.default_locale

+  FastGettext.set_locale(locale)
   I18n.locale = locale
 end

Por fim, como a aplicação já estava usando I18n para mensagens de erro do ActiveRecord (e alterar isso demandaria mais esforço), desativei esse comportamento do GetText:

# config/initializers/gettext_i18n_rails.rb
Rails.application.config.gettext_i18n_rails.use_for_active_record_attributes = false

Processo de tradução

Para iniciar o processo de tradução, adicionei um texto usando o método do GetText:

<%= _("Nenhum resultado encontrado") %>

Em seguida, executei a rake task:

rake gettext:find

Essa rake task escaneia o projeto e adiciona as novas strings aos arquivos .po.

Depois, incluí a tradução correspondente no campo msgstr de cada arquivo .po:

 # locale/en/app.po

 msgid "Nenhum resultado encontrado"
-msgstr ""
+msgstr "No result found"

Após atualizar as traduções, é importante rodar a rake task novamente. Isso garante que os arquivos edit.po sejam atualizados corretamente. Caso contrário, as alterações podem se misturar com novas strings adicionadas posteriormente, o que dificulta o controle de versões e a revisão das mudanças.

Features

Fallback automático

Se uma string não tiver tradução, ou se você esquecer de adicionar, o GetText retorna o valor original por padrão:

_("Nenhuma categoria encontrada")
# => Nenhuma categoria encontrada

Também é possível fornecer um bloco. Se esse bloco for passado, seu conteúdo será retornado como valor padrão, o que permite definir um fallback mais explícito:

_("Não foi encontrada uma tradução") { "Texto alternativo" }
# => Texto alternativo

Pluralização

A pluralização no GetText é semelhante à do I18n do Rails. Para que funcione corretamente, é necessário configurar a regra de plural de cada idioma nos arquivos .po.

No meu caso, os idiomas configurados ficaram assim:

# locale/en/app.po
- "Plural-Forms: nplurals=; plural=;\n"
+ "Plural-Forms: nplurals=2; plural=(n != 1);\n"

# locale/es/app.po
- "Plural-Forms: nplurals=; plural=;\n"
+ "Plural-Forms: nplurals=2; plural=(n != 1);\n"

# locale/pt_BR/app.po
- "Plural-Forms: nplurals=; plural=;\n"
+ "Plural-Forms: nplurals=2; plural=(n != 1);\n"

Depois disso, basta usar o método n_ passando o singular, o plural e o número.

n_("tarefa pendente", "tarefas pendentes", @total)

Após rodar a rake task gettext:find , serão geradas as entradas necessárias nos arquivos .po . Com as chaves criadas, é só adicionar as traduções correspondentes.

Traduções dinâmicas

É possível interpolar variáveis dentro das strings normalmente. O conteúdo será exibido dinamicamente:

_("Publicado por %{username}") % { username: @user.username }

Conclusão

Se você busca uma forma mais simples e direta de gerenciar traduções, vale a pena experimentar o GetText no seu projeto Rails. A integração é tranquila, o ganho em produtividade é real e você ainda pode manter o I18n do Rails para casos onde preferir.

Referências

Criando APIs com Grape e Rails: Uma Jornada Completa - Parte 3

Rodrigo Barreto — Fri, 18 Apr 2025 12:47:16 +0000

Introdução

Olá, devs! 👋

Bem-vindos à terceira parte da nossa série sobre Grape e Rails! Nos posts anteriores, exploramos a configuração básica da API e implementamos operações CRUD para nossos eventos. Hoje, vamos dar um passo adiante e implementar autenticação para nossa API.

A segurança é um aspecto crucial de qualquer API, e implementar um sistema de autenticação robusto é essencial para proteger seus recursos. Neste post, vamos explorar como implementar autenticação com JWT (JSON Web Tokens) e como proteger nossas rotas.

Configurando Autenticação com JWT

Para nosso exemplo, vamos utilizar JWT para autenticação. Se você não está familiarizado com JWT, é um padrão para a criação de tokens de acesso que podem ser validados sem a necessidade de consultar um banco de dados. Os tokens JWT contêm informações sobre o usuário e expiram após um determinado período.

Primeiro, vamos adicionar as gems necessárias ao nosso projeto:

gem 'devise'  # Para autenticação de usuários
gem 'jwt'     # Para trabalhar com tokens JWT

Execute bundle install para instalar as dependências.

1. Criando o Serviço de JWT

Primeiro, precisamos criar um serviço para lidar com a codificação e decodificação de tokens JWT. Em app/services/jwt/json_web_token.rb:

# frozen_string_literal: true

module Jwt
  class JsonWebToken
    # SECRET = Rails.application.credentials.secret_key_base
    SECRET = "secret-key" # usar algum código no secrets ou algo mais seguro
    ENCRYPTION = "HS256"

    def self.encode(payload, exp = 120.hours.from_now)
      payload[:exp] = exp.to_i
      JWT.encode(payload, SECRET)
    rescue JWT::EncodeError => e
      Rails.logger.error("JWT Encode Error: #{e.message}")
    end

    def self.decode(token)
      body = JWT.decode(token, SECRET)[0]
      ActiveSupport::HashWithIndifferentAccess.new(body)
    rescue JWT::ExpiredSignature, JWT::DecodeError => e
      Rails.logger.error("JWT Encode Error: #{e.message}")
      nil
    end
  end
end

Observação: No ambiente de produção, você deve armazenar a chave secreta em um local seguro, como Rails.application.credentials.secret_key_base ou uma variável de ambiente.

2. Criando Helpers para Autenticação

Em seguida, vamos criar helpers para lidar com a autenticação em nossos endpoints. Em app/api/helpers/auth_helpers.rb:

# frozen_string_literal: true

module Helpers
  module AuthHelpers
    extend Grape::API::Helpers

    # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
    def authenticate_request!
      # Este exemplo é simplificado; no projeto real, usamos apenas headers["Authorization"]
      token = headers["Authorization"]&.split&.last || headers["authorization"]&.split&.last
      error!({ error: "Unauthorized", success: false }, 401) unless token

      # Decodifica o token JWT
      @jwt_result = Jwt::JsonWebToken.decode(token)
      error!({ error: "Invalid Token", success: false }, 401) unless @jwt_result

      # Busca o usuário atual (ou gera erro se não for encontrado)
      current_user!
    rescue StandardError => e
      error!({ error: "Authentication Error: #{e.message}" }, 401)
    end
    # rubocop:enable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity

    # Este método busca o usuário atual e gera erro se não for encontrado
    def current_user!
      @current_user ||= User.find_by(id: @jwt_result["id"])
      error!({ error: "Invalid Token", success: false }, 401) unless @current_user
      @current_user
    end

    # Este método permite usar o current_user em qualquer lugar
    def current_user
      @current_user
    end
  end
end

3. Implementando o Endpoint de Login

Agora, vamos criar um endpoint para autenticar usuários e gerar tokens JWT. Em app/api/v1/login.rb:

# frozen_string_literal: true

module V1
  class Login < Grape::API
    resource :login do
      desc "Login ", {
        success: Entities::Users::LoginResponse,
        failure: [{ code: 401, message: "Unauthorized" }],
        params: ::Helpers::ContractToParams.generate_params(LoginContract)
      }
      post do
        contract = LoginContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        @user = User.find_by(email: params[:email])
        if @user&.valid_password?(params[:password])
          token = ::Jwt::JsonWebToken.encode({ id: @user.id })
          status 200
          present({ user: @user, token: token }, with: Entities::Users::LoginResponse)
        else
          error!({ error: "Unauthorized" }, 401)
        end
      end
    end
  end
end

Nota: Este exemplo usa valid_password? do Devise, que é um método padrão para verificar senhas.

4. Definindo Entidades para Resposta de Login

Para formatar as respostas do endpoint de login, vamos criar algumas entidades:

Em app/api/entities/users/user_response.rb:

# frozen_string_literal: true

module Entities
  module Users
    class UserResponse < Grape::Entity
      expose :id, documentation: { type: "Integer", desc: "User id" }
      expose :email, documentation: { type: "String", desc: "User email" }
    end
  end
end

Em app/api/entities/users/login_response.rb:

# frozen_string_literal: true

module Entities
  module Users
    class LoginResponse < Grape::Entity
      expose :user, using: Entities::Users::UserResponse,
                   documentation: { type: "Array", desc: "List of users" }
      expose :token, documentation: { type: "String", desc: "JWT token" }
    end
  end
end

5. Atualizando o API Grape

Agora, vamos atualizar nosso arquivo app/api/v1/api_grape.rb para incluir os helpers de autenticação e o novo endpoint de login:

# frozen_string_literal: true

class V1::ApiGrape < Grape::API
  version "v1", using: :path
  format :json
  default_format :json

  use CustomErrorMiddleware

  helpers ::Helpers::AuthHelpers

  mount V1::Events
  mount V1::Login

  add_swagger_documentation(
    api_version: "v1",
    hide_documentation_path: true,
    mount_path: "/swagger_doc",
    hide_format: true,
    info: {
      title: "Events API",
      description: "API for event management",
      contact_name: "Support Team",
      contact_email: "contact@example.com"
    },
    security_definitions: {
      Bearer: {
        type: "apiKey",
        name: "Authorization",
        in: "header",
        description: 'Enter "Bearer" followed by your token. Example: Bearer abc123'
      }
    },
    security: [{ Bearer: [] }]
  )
end

6. Adicionando Dados de Teste

Para facilitar os testes, podemos criar um usuário padrão usando seeds:

# db/seeds.rb

User.find_or_create_by!(email: "teste@examle.com") do |user|
  user.password = "123456"
  user.password_confirmation = "123456"
end

Execute rails db:seed para criar o usuário.

Protegendo Endpoints

Com nossa configuração de autenticação em vigor, agora podemos proteger nossos endpoints. Vamos atualizar nosso controlador de eventos para exigir autenticação:

module V1
  class Events < Grape::API
    before { authenticate_request! }

    # Resto do código permanece o mesmo...
  end
end

Agora, todos os endpoints no recurso events exigirão um token JWT válido para acesso.

Implementando Middleware para Tratamento de Erros

Para melhorar ainda mais nossa API, vamos implementar um middleware personalizado para tratar erros comuns. Em app/middleware/custom_error_middleware.rb:

# frozen_string_literal: true

class CustomErrorMiddleware < Grape::Middleware::Base
  def call(env)
    @app.call(env) # Passa a requisição adiante
  rescue Grape::Exceptions::MethodNotAllowed => e
    handle_method_not_allowed(e, env)
  rescue ActiveRecord::RecordNotFound => e
    handle_record_not_found(e)
  rescue StandardError => e
    handle_standard_error(e)
  end

  private

  def handle_record_not_found(error)
    # Poderia usar, por exemplo: Sentry.capture_exception(error, extra: { message: error.message })
    error_response(message: "Couldn't find #{error.model || 'record'} with id: #{error.id}", status: 404)
  end

  def handle_method_not_allowed(error, env)
    request_method = env["REQUEST_METHOD"]
    path = env["PATH_INFO"]

    Rails.logger.error "Method not allowed: #{request_method} for path #{path}"

    allowed_methods = if error.respond_to?(:headers) && error.headers["Allow"]
                        "Allowed methods: #{error.headers['Allow']}"
                      else
                        "Please use the appropriate HTTP methods for this endpoint"
                      end

    error_message = "The
    #{request_method} method is not allowed for this resource.
   #{allowed_methods}. please check your parameters"

    unless Rails.env.development?
      # Sentry.capture_exception(error, extra: {
      #                            request_method: request_method,
      #                            path: path,
      #                            message: error_message
      #                          })
    end

    error_response(message: error_message, status: 405)
  end

  def handle_standard_error(error)
    Rails.logger.error(error.message)
    Rails.logger.error(error.backtrace.join("\n"))
    # Sentry.capture_exception(error, extra: { message: error.message }) unless Rails.env.development?
    error_response(message: "Something went wrong", status: 500)
  end

  def error_response(message:, status:)
    throw :error, message: { error: message }, status: status
  end
end

Este middleware captura exceções comuns e as transforma em respostas de API adequadas. Com ele implementado, podemos simplificar nossos endpoints:

get ":id" do
  @event = Event.find(params[:id])
  present @event, with: ::Entities::EventResponse
end

O middleware capturará automaticamente a exceção ActiveRecord::RecordNotFound e retornará uma resposta de erro apropriada.

Testando a Autenticação

Agora que implementamos a autenticação, vamos adicionar alguns testes para garantir que tudo funcione corretamente:

# spec/api/v1/login_spec.rb

require 'rails_helper'

RSpec.describe V1::Login, type: :request do
  let(:base_url) { "/api/v1/login" }
  let(:email) { "user@example.com" }
  let(:password) { "password123" }

  before do
    @user = create(:user, email: email, password: password)
  end

  describe "POST /api/v1/login" do
    context "with valid credentials" do
      it "returns a JWT token" do
        post base_url, params: { email: email, password: password }

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["user"]["id"]).to eq(@user.id)
        expect(json_response["user"]["email"]).to eq(@user.email)
        expect(json_response["token"]).not_to be_nil
      end
    end

    context "with invalid credentials" do
      it "returns an error" do
        post base_url, params: { email: email, password: "wrong_password" }

        expect(response).to have_http_status(:unauthorized)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Unauthorized")
      end
    end
  end
end

Documentação Swagger Atualizada

Com a adição da autenticação e do endpoint de login, nossa documentação Swagger agora mostrará:

Um novo endpoint /login para autenticação
Informações de segurança para todos os endpoints protegidos
Um botão "Authorize" na interface Swagger para inserir o token JWT

Conclusão

Nesta terceira parte da nossa série, implementamos um sistema de autenticação completo para nossa API Grape:

Configuramos JWT para gerar e verificar tokens
Criamos helpers para autenticação
Implementamos um endpoint de login
Protegemos nossos endpoints com autenticação
Adicionamos middleware para tratamento de erros
Atualizamos nossa documentação Swagger

A autenticação é um componente crucial para qualquer API, e o Grape torna relativamente simples implementá-la. Ao combinar JWT com os helpers do Grape, conseguimos um sistema de autenticação robusto que protege nossos recursos e proporciona uma experiência de desenvolvedor agradável.

No próximo post, exploraremos recursos mais avançados do Grape, como paginação, ordenação e filtragem, para tornar nossa API ainda mais poderosa e flexível.

Gostou deste post? Deixe seus comentários abaixo e não se esqueça de conferir as partes anteriores desta série!

Repositório do exemplo: https://github.com/rodrigonbarreto/event_reservation_system/tree/mvp_sample_pt3

Referências:

Me chamo Rodrigo Nogueira Barreto. Trabalho com Ruby on Rails desde 2015.

Caso queiram acompanhar essa jornada, por favor comentem e deixem seu like!

Criando APIs com Grape e Rails: Uma Jornada Completa - Parte 2

Rodrigo Barreto — Sun, 13 Apr 2025 15:40:17 +0000

Introdução

Olá, devs! 👋

Bem-vindos à segunda parte da nossa jornada criando APIs com Grape e Rails. Na Parte 1, abordamos o básico da configuração de uma API Grape e como escrever testes eficazes. Hoje, vamos elevar o nível da nossa API implementando duas gems poderosas que podem melhorar significativamente seu fluxo de desenvolvimento:

dry-validation - Para validação robusta de parâmetros
interactor - Para uma lógica de negócios limpa e organizada

Também vou compartilhar um helper personalizado que criei para simplificar o trabalho com dry-validation em APIs Grape. Foi algo que desenvolvi rapidamente para um MVP, mas funcionou perfeitamente para nossas necessidades.

Configurando Nosso Projeto

Vamos adicionar as gems necessárias ao nosso Gemfile:

gem 'grape'
gem 'grape-swagger'
gem 'grape-entity'
gem 'grape-swagger-entity'
gem 'rswag-ui'
gem 'rack-cors'

# Adicione essas novas gems
gem 'dry-validation', '~> 1.10'
gem 'interactor', '~> 3.1'

Execute bundle install para instalar as dependências.

O Poder dos Contratos com dry-validation

Em vez de depender apenas da validação de parâmetros integrada do Grape, podemos usar contratos do dry-validation para criar regras de validação mais robustas. Vamos criar dois contratos para nosso recurso de eventos:

# app/contracts/events_create_contract.rb
# frozen_string_literal: true

class EventsCreateContract < Dry::Validation::Contract
  params do
    # @title = Título do evento, com no mínimo 3 caracteres
    required(:title).filled(:string, min_size?: 3)

    # @description = Descrição detalhada do evento
    optional(:description).maybe(:string)

    # @event_type = Tipo de evento (business ou birthday)
    required(:event_type).filled(:string, included_in?: %w[business birthday])

    # @number_of_people = Número esperado de participantes
    optional(:number_of_people).maybe(:integer, gt?: 0)

    # @special_requests = Quaisquer requisitos especiais para o evento
    optional(:special_requests).maybe(:string)
  end

  rule(:number_of_people) do
    key.failure("must be provided for business events") if values[:event_type] == "business" && value.nil?
  end
end

Observe como estamos usando comentários com um formato especial (# @nome_do_parametro = descrição) - isso é importante para o helper personalizado que discutiremos mais adiante.

Para operações de atualização, criamos um contrato separado:

# app/contracts/events_update_contract.rb
# frozen_string_literal: true

class EventsUpdateContract < Dry::Validation::Contract
  params do
    # @id = ID do evento
    required(:id).filled(:integer)

    # @title = Título do evento, com no mínimo 3 caracteres
    required(:title).filled(:string, min_size?: 3)

    # @description = Descrição detalhada do evento
    optional(:description).maybe(:string)

    # @event_type = Tipo de evento (business ou birthday)
    required(:event_type).filled(:string, included_in?: %w[business birthday])

    # @number_of_people = Número esperado de participantes
    optional(:number_of_people).maybe(:integer, gt?: 0)

    # @special_requests = Quaisquer requisitos especiais para o evento
    optional(:special_requests).maybe(:string)
  end
end

Você pode estar se perguntando por que criei dois contratos separados que parecem muito semelhantes. Embora seja tentador seguir o princípio DRY e reutilizar o mesmo contrato, na prática, descobri que ter contratos separados para diferentes operações (criar vs atualizar) oferece mais flexibilidade. É um padrão derivado do conceito de DTOs (Data Transfer Objects), e vamos nos aprofundar nisso em um post futuro!

O Helper ContractToParams: Uma Ponte Entre dry-validation e Grape

Um dos desafios ao usar dry-validation com Grape é que você acaba definindo parâmetros duas vezes: uma vez no contrato e outra vez no endpoint do Grape. Para resolver isso, eu criei um helper que gera automaticamente definições de parâmetros do Grape a partir de contratos do dry-validation:

# app/api/helpers/contract_to_params.rb
# frozen_string_literal: true

module Helpers
  module ContractToParams
    extend Grape::API::Helpers

    def self.generate_params(contract_class, options = {})
      annotations = extract_annotations(contract_class)
      contract = contract_class.new
      param_type = options[:param_type] || 'body'

      contract.schema.rules.each_with_object({}) do |(name, rule), params_hash|
        type = extract_type(rule)
        required = !optional_field?(rule)
        description = annotations[name] || name.to_s.humanize

        params_hash[name] = {
          type: type,
          desc: description,
          required: required,
          documentation: { param_type: param_type }
        }
      end
    end

    def self.extract_annotations(contract_class)
      # Lê o conteúdo do arquivo fonte usando o path da classe
      file_path = contract_class.name.underscore
      paths_to_try = [
        Rails.root.join("app/contracts/", "#{file_path}.rb"),
        Rails.root.join("app/api/contracts/", "#{file_path}.rb"),
        Rails.root.join("app/models/#{file_path}.rb")
      ]

      source_path = paths_to_try.find { |path| File.exist?(path) }
      return {} unless source_path

      source_lines = File.readlines(source_path)
      annotations = {}
      field_pattern = /\s*(optional|required)\(:([\w_]+)\)/

      source_lines.each_with_index do |line, index|
        next unless line.match?(field_pattern)

        field_name = line.match(field_pattern)[2]

        previous_line = source_lines[index - 1]
        if previous_line&.match?(/^\s*#\s*@#{field_name}\s*=\s*(.+)/)
          annotations[field_name.to_sym] = previous_line.match(/^\s*#\s*@#{field_name}\s*=\s*(.+)/)[1].strip
        end
      end

      annotations
    end

    def self.extract_type(rule)
      predicates = extract_all_predicates(rule)

      return [TrueClass, FalseClass] if predicates.include?(:bool?)
      return Integer if predicates.include?(:int?) || predicates.include?(:integer?)
      return Float if predicates.include?(:float?)
      return Array if predicates.include?(:array?)
      return Hash if predicates.include?(:hash?)
      return Date if predicates.include?(:date?)
      return Time if predicates.include?(:time?)

      String
    end

    def self.extract_all_predicates(rule)
      predicates = []

      case rule
      when Dry::Logic::Operations::And, Dry::Logic::Operations::Or
        rule.rules.each do |sub_rule|
          predicates.concat(extract_all_predicates(sub_rule))
        end
      when Dry::Logic::Operations::Key
        predicates.concat(extract_all_predicates(rule.rules.first))
      when Dry::Logic::Operations::Implication
        predicates << :optional
        rule.rules.each do |sub_rule|
          predicates.concat(extract_all_predicates(sub_rule))
        end
      when Dry::Logic::Rule::Predicate
        predicates << rule.predicate.name if rule.predicate&.name
      end

      predicates.uniq
    end

    def self.optional_field?(rule)
      return true if rule.is_a?(Dry::Logic::Operations::Implication)

      if rule.is_a?(Dry::Logic::Operations::And)
        rule.rules.any? do |sub_rule|
          sub_rule.is_a?(Dry::Logic::Operations::Implication)
        end
      else
        false
      end
    end
  end
end

Este helper foi feito às pressas e sempre que posso trabalho em melhorias nele, mas atualmente supre 99% a necessidade do nosso projeto.

Como você vê nas fotos, o nosso helper ajuda a melhorar nossa documentação seguem as fotos abaixo

Organizando a Lógica de Negócios com Interactors

Se você fala português super recomendo fazer o curso do Jackson Pires no site https://videosdeti.com.br/ ele ensina a usar bem a gem Interactors entre outras coisas.

A gem interactor nos ajuda a dividir a lógica de negócios em pequenas classes focadas. Vamos ver como implementamos isso para nosso recurso de eventos:

# app/services/events/interactors/create_event.rb
# frozen_string_literal: true

module Events
  module Interactors
    class CreateEvent
      include Interactor

      delegate :params, to: :context
      def call
        event = Event.new(context.params)

        if event.save
          context.event = event
        else
          context.fail!(errors: event.errors)
        end
      end
    end
  end
end

Este interactor tem uma única responsabilidade: criar um evento no banco de dados.

Em seguida, criamos um interactor para enviar uma notificação após a criação do evento:

# app/services/events/interactors/send_notification.rb
# frozen_string_literal: true

module Events
  module Interactors
    class SendNotification
      include Interactor

      delegate :event, to: :context
      def call
        Rails.logger.info("Event '#{event.title}' was created successfully!")

        # Aqui você poderia enviar uma notificação real via email, SMS, etc.
        # Para fins de demonstração, estamos apenas registrando uma mensagem
      end
    end
  end
end

Finalmente, criamos um organizador para coordenar esses interactors:

# app/services/events/organizers/register.rb
# frozen_string_literal: true

module Events
  module Organizers
    class Register
      include Interactor::Organizer

      organize ::Events::Interactors::CreateEvent,
               ::Events::Interactors::SendNotification

      around do |interactor|
        ActiveRecord::Base.transaction do
          interactor.call
          raise ActiveRecord::Rollback if context.failure?
        end
      end
    end
  end
end

O organizador faz duas coisas importantes:

Define a ordem de execução dos interactors usando organize
Envolve a execução em uma transação, garantindo que, se qualquer interactor falhar, todas as mudanças no banco de dados sejam revertidas

O que é incrível sobre esse padrão é como ele torna a lógica de negócios fácil de entender, testar e manter.

Integrando Com Nossa API Grape

Agora, vamos juntar tudo e ver como nossa API Grape fica com essas melhorias:

# app/api/v1/events.rb
# frozen_string_literal: true

module V1
  class Events < Grape::API
    # este é um exemplo apenas pro post, recomendo planejar melhor e criar algo como
    # FormatErrorHelpers e chamando
    # helpers ::Helpers::FormatErrorHelpers
    helpers do
      def format_errors(errors)
        case errors
        when ActiveModel::Errors
          errors.messages.transform_values { |messages| messages.join(", ") }
        when Hash
          errors
        else
          { base: errors.to_s }
        end
      end
    end

    resource :events do
      desc "Get all events", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" }
        ],
        tags: ["events"]
      }
      get do
        @events = Event.all
        present @events, with: ::Entities::EventResponse
      end

      desc "Get a specific event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        params: {
          id: { type: Integer, desc: "Event ID" }
        },
        tags: ["events"]
      }
      get ":id" do
        @event = Event.find(params[:id])
        present @event, with: ::Entities::EventResponse
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end

      desc "Create a new event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        params: ::Helpers::ContractToParams.generate_params(EventsCreateContract)
      }
      post do
        contract = EventsCreateContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        service_result = ::Events::Organizers::Register.call(params: result.to_h)

        if service_result.success?
          present service_result.event, with: ::Entities::EventResponse, status: :created
        else
          error!({ errors: format_errors(service_result.errors) }, 422)
        end
      end

      desc "Update an existing event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        params: ::Helpers::ContractToParams.generate_params(EventsUpdateContract),
        # Mesmo que os campos sejam praticamente os mesmos, a gente sabe que os detalhes fazem toda a diferença!
        # Recomendo usar o EventsUpdateContract – repetindo os campos do EventsCreateContract, nem tudo precisa ser 100% DRY (Don't Repeat Yourself).
        # E isso vale para os DTOs (sim, nossos contracts também!).
        # Mas fique à vontade para usar herança ou módulos para evitar repetir os campos; o importante é que você e sua equipe entrem em acordo e se divirtam.
        #
        # Ah, e se vocês tiverem curiosidade sobre por que eu não uso abstração em DTOs... quem sabe a gente discute isso num próximo post!
        tags: ["events"]
      }
      put ":id" do
        contract = EventsUpdateContract.new
        result = contract.call(params)
        error!({ errors: result.errors.to_h }, 422) if result.failure?

        @event = ::Event.find(params[:id])
        @event.assign_attributes(result.to_h)

        if @event.save
          present @event, with: ::Entities::EventResponse
        else
          error!({ errors: format_errors(@event.errors) }, 422)
        end
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end

      desc "Delete an event", {
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        params: {
          id: { type: Integer, desc: "Event ID" }
        },
        tags: ["events"]
      }
      delete ":id" do
        @event = Event.find(params[:id])

        if @event.destroy
          { success: true, message: "Event successfully deleted" }
        else
          error!({ errors: format_errors(@event.errors) }, 422)
        end
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end
    end
  end
end

Observe como nossa API está mais limpa e organizada:

Usamos ::Helpers::ContractToParams.generate_params(EventsCreateContract) para gerar automaticamente a documentação de parâmetros.
Validamos os parâmetros com os contratos do dry-validation.
Delegamos a lógica de negócios a interactors.

E aqui está nossa configuração principal da API Grape:

# app/api/v1/api_grape.rb
# frozen_string_literal: true

class V1::ApiGrape < Grape::API
  version "v1", using: :path
  format :json
  default_format :json

  mount V1::Events

  add_swagger_documentation(
    api_version: "v1",
    hide_documentation_path: true,
    mount_path: "/swagger_doc",
    hide_format: true,
    info: {
      title: "Events API",
      description: "API for event management",
      contact_name: "Support Team",
      contact_email: "contact@example.com"
    },
    security_definitions: {
      Bearer: {
        type: "apiKey",
        name: "Authorization",
        in: "header",
        description: 'Enter "Bearer" followed by your token. Example: Bearer abc123'
      }
    },
    security: [{ Bearer: [] }]
  )
end

Benefícios Desta Abordagem

Usamos os contracts (uma espécie de DTO) para as validações de negócio no request e não no modelo, usamos os modelos apenas para representar as regras do banco de dados (no nosso projeto que eu e meu amigo estamos trabalhando, mesmo com validação nos modelos também temos as regras de validação no próprio banco de dados para o projeto não ser refém de um framework).

Depois de implementar esses padrões em nosso projeto, percebemos vários benefícios:

Usando Contratos dry-validation

Separação de responsabilidades: A validação está completamente separada da API e dos modelos.
Validações mais poderosas: Podemos expressar regras de negócios complexas de maneira clara.
Reutilização: Os contratos podem ser usados em diferentes contextos, não apenas na API.
Documentação automática: Com nosso helper personalizado, a documentação é gerada automaticamente.

Usando Interactors

Código modular: Cada interactor tem uma única responsabilidade.
Fácil de testar: Interactors podem ser testados isoladamente.
Controle transacional: O organizador cuida de envolver tudo em uma transação.
Legibilidade: É fácil entender o fluxo de negócios olhando para o organizador.

Uma coisa que eu gostaria de destacar é minha decisão de usar contratos separados para criação e atualização. Embora eles contenham campos semelhantes, eu acredito que manter os nossos Contracts (uma espécie de DTO) separados é uma boa prática. As necessidades de validação para criação e atualização muitas vezes divergem com o tempo, e ter contratos separados nos dá flexibilidade para evoluir.

Conclusão

Neste post, exploramos como elevar o nível da nossa API Grape usando dry-validation para validação de parâmetros e interactors para organizar a lógica de negócios. Também compartilhei um helper personalizado que desenvolvi para facilitar a integração entre dry-validation e Grape.

Embora algumas dessas soluções tenham sido desenvolvidas rapidamente para um MVP, elas demonstram como podemos criar APIs mais robustas e manuteníveis com relativamente pouco esforço.

No próximo post vamos falar de Middleware,Policies e Authorization com login usando JWT tokens, com isso o projeto vai ficar mais robusto ainda. Fique ligado!

Você já usou dry-validation ou interactors em seus projetos Rails? Qual foi sua experiência? Deixe um comentário abaixo!

Repositório: https://github.com/rodrigonbarreto/event_reservation_system/tree/mvp_sample_pt2

Referências:

Me chamo Rodrigo Nogueira - Desenvolvedor Ruby on Rails desde 2015
Pós em Engenharia de Software (PUC-RJ) e trabalho com tecnologia desde 2011.
Se você quiser acompanhar esta jornada, por favor, comente e deixe seu like!

Criando APIs com Grape e Rails: Uma Jornada Completa - Parte 1

Rodrigo Barreto — Sat, 12 Apr 2025 13:18:50 +0000

Introdução

Olá, devs! 👋

No ano passado, embarquei em um projeto com um amigo onde decidimos criar uma aplicação usando Ruby on Rails para o backend API e React para o frontend. Como muitos de vocês sabem, criar uma API robusta e bem documentada pode ser uma tarefa desafiadora, especialmente quando você quer focar mais no desenvolvimento do que na documentação.

Essa jornada começou quando percebi que estava cansado de escrever testes RSpec apenas para gerar documentação com o Rswag. Então tomamos uma decisão: vamos sim escrever testes, mas para validar nosso código como deve ser feito, não para gerar documentação da API.

Foi aí que decidimos usar o Grape. No início, confesso que havia uma certa resistência e desconfiança do meu amigo. Mas hoje, com nossa stack 100% pronta, posso dizer com confiança que foi uma das melhores decisões que o convenci a tomar. Ele também confiou e deu 100% de suporte nesses tipos de decisões.

Nesta série de posts, vou compartilhar nossa jornada completa, desde a configuração básica até recursos mais avançados. No post de hoje, vou mostrar como configurar uma API usando Grape com Rails e escrever testes eficazes para ela.

O que é Grape?

Grape é um framework para construir APIs REST-like em Ruby. Ele foi projetado para funcionar com frameworks como Rails e Sinatra, ou mesmo de forma standalone. Algumas das características que nos fizeram escolher o Grape incluem:

Sintaxe clara e expressiva para definir endpoints e rotas
Validação de parâmetros integrada
Formatação de resposta flexível
Documentação automática com Swagger
Versionamento de API simplificado

Instalação e Configuração Inicial

Para começar, precisamos adicionar as gems necessárias ao nosso projeto. Adicione essas gems ao seu Gemfile:

gem 'grape'
gem 'grape-swagger'
gem 'grape-entity'
gem 'grape-swagger-entity'
gem 'rswag-ui'
gem 'rack-cors'

Execute bundle install para instalar as dependências.

Configurando o Projeto

Vamos começar com um modelo simples para nossos eventos:

class Event < ApplicationRecord
  enum event_type: { business: 'business', birthday: 'birthday' }
end

Estrutura de Arquivos

Para manter nosso código organizado, criamos a seguinte estrutura de diretórios:

app/
├── api/
│   ├── entities/
│   │   └── event_response.rb
│   └── v1/
│       ├── api_grape.rb
│       └── events.rb
└── models/
    └── event.rb

Configuração de Rotas

No arquivo config/routes.rb, montamos nossa API e a documentação Swagger:

Rails.application.routes.draw do
  mount Rswag::Ui::Engine => "/api-docs"

  mount V1::ApiGrape => "api", as: :v1_api

  # O código abaixo está comentado, pois agora estamos usando Grape em vez das rotas padrão do Rails
  # namespace :api do
  #   namespace :v1 do
  #     resources :events
  #   end
  # end
end

Configuração do Swagger UI

Para melhorar a experiência de visualização da documentação da API, vamos configurar o Rswag UI para apontar para nossa documentação Swagger gerada pelo Grape. Em config/initializers/rswag_ui.rb:

Rswag::Ui.configure do |c|
  # Esta é a URL gerada pelo grape-swagger e nosso arquivo de configuração app/api/v1/api_grape.rb
  c.swagger_endpoint "/api/v1/swagger_doc.json", "Events V1 Docs"

  # Add Basic Auth in case your API is private
  # c.basic_auth_enabled = true
  # c.basic_auth_credentials 'username', 'password'
end

É importante destacar que o endpoint /api/v1/swagger_doc.json gera a documentação no formato OpenAPI 2.0. Estou usando o mount Rswag::Ui::Engine para deixar a visualização da documentação mais agradável, embora eu já tenha começado a trabalhar em uma gem para gerar documentação OpenAPI 3.0 (assunto para um post futuro). Mesmo assim, esta configuração tem funcionado perfeitamente para o cenário de trabalho entre mim e meu amigo.

Definindo a API

A configuração principal da API fica no arquivo app/api/v1/api_grape.rb:

# frozen_string_literal: true

class V1::ApiGrape < Grape::API
  version "v1", using: :path
  format :json
  default_format :json

  # Monte seus endpoints aqui
  mount V1::Events

  add_swagger_documentation(
    api_version: "v1",
    hide_documentation_path: true,
    mount_path: "/swagger_doc",
    hide_format: true,
    info: {
      title: "Events API",
      description: "API para gerenciamento de eventos",
      contact_name: "Support Team",
      contact_email: "contact@example.com"
    },
    security_definitions: {
      Bearer: {
        type: "apiKey",
        name: "Authorization",
        in: "header",
        description: 'Enter "Bearer" followed by your token. Example: Bearer abc123'
      }
    },
    security: [{ Bearer: [] }]
  )
end

Implementando os Endpoints

No arquivo app/api/v1/events.rb, implementamos o CRUD completo para nossos eventos:

# frozen_string_literal: true

module V1
  class Events < Grape::API
    helpers do
      def event_params
        ActionController::Parameters.new(params).permit(
          :title,
          :description,
          :event_type,
          :number_of_people,
          :special_requests
        )
      end

      def find_event
        @event = Event.find(params[:id])
      rescue ActiveRecord::RecordNotFound
        error!({ error: "Event not found" }, 404)
      end
    end

    resource :events do
      desc "Get all events", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" }
        ],
        tags: ["events"]
      }
      get do
        @events = Event.all
        present @events, with: ::Entities::EventResponse
      end

      desc "Get a specific event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        tags: ["events"]
      }
      params do
        requires :id, type: Integer, desc: "Event ID"
      end
      get ":id" do
        find_event
        present @event, with: ::Entities::EventResponse
      end

      desc "Create a new event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        tags: ["events"]
      }
      params do
        requires :title, type: String, desc: "Event title"
        requires :event_type, type: String, values: %w[business birthday], desc: "Event type"
        optional :description, type: String, desc: "Event description"
        optional :number_of_people, type: Integer, desc: "Number of attendees"
        optional :special_requests, type: String, desc: "Special requests"
      end
      post do
        @event = Event.new(event_params)
        if @event.save
          present @event, with: ::Entities::EventResponse
        else
          error!({ errors: @event.errors.full_messages }, 422)
        end
      end

      desc "Update an existing event", {
        success: ::Entities::EventResponse,
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" },
          { code: 422, message: "Unprocessable Entity" }
        ],
        tags: ["events"]
      }
      params do
        requires :id, type: Integer, desc: "Event ID"
        optional :title, type: String, desc: "Event title"
        optional :event_type, type: String, values: %w[business birthday], desc: "Event type"
        optional :description, type: String, desc: "Event description"
        optional :number_of_people, type: Integer, desc: "Number of attendees"
        optional :special_requests, type: String, desc: "Special requests"
      end
      put ":id" do
        find_event
        if @event.update(event_params)
          present @event, with: ::Entities::EventResponse
        else
          error!({ errors: @event.errors.full_messages }, 422)
        end
      end

      desc "Delete an event", {
        failure: [
          { code: 401, message: "Unauthorized" },
          { code: 404, message: "Not Found" }
        ],
        tags: ["events"]
      }
      params do
        requires :id, type: Integer, desc: "Event ID"
      end
      delete ":id" do
        find_event
        if @event.destroy
          { success: true, message: "Event successfully deleted" }
        else
          error!({ errors: @event.errors.full_messages }, 422)
        end
      end
    end
  end
end

Definindo Entidades para Representação de Dados

Para formatar nossas respostas de API, usamos entidades do Grape em app/api/entities/event_response.rb:

# frozen_string_literal: true

module Entities
  class EventResponse < Grape::Entity
    expose :id, documentation: { type: "Integer", desc: "Event ID" }
    expose :title, documentation: { type: "String", desc: "Event Title" }
    expose :description, documentation: { type: "String", desc: "Event Description" }
    expose :event_type, documentation: { type: "String", desc: "Event Type" }
    expose :number_of_people, documentation: { type: "Integer", desc: "Number of People" }
    expose :special_requests, documentation: { type: "String", desc: "Special Requests" }
  end
end

Testando a API com RSpec

Uma das grandes vantagens do Grape é que podemos escrever testes diretos e eficientes para nossa API sem precisar gerar documentação através deles. Vamos ver como isso funciona:

Configurando os Testes

Primeiro, adicione as gems necessárias no seu Gemfile:

group :development, :test do
  gem 'rspec-rails'
  gem 'factory_bot_rails'
end

Execute bundle install e configure o RSpec com rails generate rspec:install.

Criando Factory para os Testes

Em spec/factories/events.rb:

# frozen_string_literal: true

FactoryBot.define do
  factory :event do
    title { "Event Title" }
    description { "Event Description" }
    event_type { "business" }
    number_of_people { 5 }
    special_requests { "Event Special Requests" }

    trait :business do
      event_type { "business" }
    end

    trait :birthday do
      event_type { "birthday" }
    end
  end
end

Testando os Endpoints

Em spec/api/v1/events_spec.rb:

# frozen_string_literal: true

require "rails_helper"

RSpec.describe V1::Events, type: :request do
  let(:base_url) { "/api/v1/events" }
  let(:event_type) { "business" }
  let(:title) { "Meeting with clients" }
  let(:description) { "Quarterly planning meeting" }
  let(:number_of_people) { 10 }
  let(:special_requests) { "Need projector and coffee" }

  let(:valid_event_params) do
    {
      title: title,
      description: description,
      event_type: event_type,
      number_of_people: number_of_people,
      special_requests: special_requests
    }
  end

  let(:invalid_event_params) do
    {
      title: "",
      event_type: "invalid_type"
    }
  end

  describe "GET /api/v1/events" do
    context "when there are events" do
      before do
        create(:event, title: "First event", event_type: "business")
        create(:event, title: "Second event", event_type: "birthday")
      end

      it "returns all events" do
        get base_url
        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)
        expect(json_response.size).to eq(2)
        expect(json_response.first["title"]).to eq("First event")
        expect(json_response.second["title"]).to eq("Second event")
      end
    end

    context "when there are no events" do
      it "returns an empty array" do
        get base_url

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response).to be_empty
      end
    end
  end

  describe "GET /api/v1/events/:id" do
    context "when the event exists" do
      let(:event) { create(:event, valid_event_params) }

      it "returns the event" do
        get "#{base_url}/#{event.id}"

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["id"]).to eq(event.id)
        expect(json_response["title"]).to eq(event.title)
        expect(json_response["description"]).to eq(event.description)
        expect(json_response["event_type"]).to eq(event.event_type)
        expect(json_response["number_of_people"]).to eq(event.number_of_people)
        expect(json_response["special_requests"]).to eq(event.special_requests)
      end
    end

    context "when the event does not exist" do
      it "returns a 404 error" do
        get "#{base_url}/999"

        expect(response).to have_http_status(:not_found)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Event not found")
      end
    end
  end

  describe "POST /api/v1/events" do
    context "with valid parameters" do
      it "creates a new event" do
        expect do
          post base_url, params: valid_event_params
        end.to change(Event, :count).by(1)

        expect(response).to have_http_status(:created)
        json_response = JSON.parse(response.body)

        expect(json_response["title"]).to eq(title)
        expect(json_response["description"]).to eq(description)
        expect(json_response["event_type"]).to eq(event_type)
        expect(json_response["number_of_people"]).to eq(number_of_people)
        expect(json_response["special_requests"]).to eq(special_requests)
      end
    end

    context "with invalid parameters" do
      it "does not create an event and returns errors" do
        expect do
          post base_url, params: invalid_event_params
        end.not_to change(Event, :count)

        expect(response).to have_http_status(:bad_request)
        json_response = JSON.parse(response.body)
        expect(json_response).to have_key("error")
        expect(json_response["error"]).to eq("event_type does not have a valid value")
      end
    end
  end

  describe "PUT /api/v1/events/:id" do
    let!(:event) { create(:event, valid_event_params) }
    let(:new_title) { "Updated Event Title" }
    let(:update_params) { { title: new_title } }

    context "when the event exists" do
      it "updates the event" do
        put "#{base_url}/#{event.id}", params: update_params

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["id"]).to eq(event.id)
        expect(json_response["title"]).to eq(new_title)
        expect(event.reload.title).to eq(new_title)
      end
    end

    context "when the event does not exist" do
      it "returns a 404 error" do
        put "#{base_url}/999", params: update_params

        expect(response).to have_http_status(:not_found)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Event not found")
      end
    end

    context "with invalid parameters" do
      it "does not update the event and returns errors" do
        put "#{base_url}/#{event.id}", params: invalid_event_params

        expect(response).to have_http_status(:bad_request)
        JSON.parse(response.body)
      end
    end
  end

  describe "DELETE /api/v1/events/:id" do
    let!(:event) { create(:event, valid_event_params) }

    context "when the event exists" do
      it "deletes the event" do
        expect do
          delete "#{base_url}/#{event.id}"
        end.to change(Event, :count).by(-1)

        expect(response).to have_http_status(:success)
        json_response = JSON.parse(response.body)

        expect(json_response["success"]).to be true
        expect(json_response["message"]).to eq("Event successfully deleted")
      end
    end

    context "when the event does not exist" do
      it "returns a 404 error" do
        delete "#{base_url}/999"

        expect(response).to have_http_status(:not_found)
        json_response = JSON.parse(response.body)

        expect(json_response["error"]).to eq("Event not found")
      end
    end
  end
end

Detalhes Importantes sobre os Testes

Durante o desenvolvimento dos testes, descobrimos algumas particularidades do Grape que vale a pena compartilhar:

Validação em Duas Camadas: O Grape tem duas camadas de validação:
- Validação de Parâmetros: Acontece antes do código do endpoint ser executado e retorna status 400 (Bad Request)
- Validação do Modelo: Acontece dentro do código do endpoint e retorna status 422 (Unprocessable Entity)
Comportamento com Parâmetros Inválidos: Quando usamos values: %w[business birthday] na definição dos parâmetros, o Grape rejeita valores inválidos automaticamente com um erro 400 antes mesmo de executar o código do endpoint. Nossos testes refletem esse comportamento esperando o status 400 quando enviamos um event_type inválido.
Mensagens de Erro Específicas: O Grape fornece mensagens de erro específicas, como "event_type does not have a valid value", que são úteis tanto para debugging quanto para informar adequadamente os usuários da API.

Executando os testes:

bundle exec rspec spec/api/v1/events_spec.rb

# Resultado:
# Finished in 0.04411 seconds (files took 1.16 seconds to load)
# 11 examples, 0 failures

Benefícios do Uso do Grape

Após implementar nossa API com Grape, percebemos diversos benefícios:

Código mais limpo e organizado: A estrutura do Grape nos ajuda a manter o código organizado e fácil de entender.
Documentação automática: Grape gera automaticamente documentação Swagger sem a necessidade de testes específicos para isso.
Validação de parâmetros robusta: A validação integrada de parâmetros acontece antes da execução do código, evitando processamento desnecessário.
Testes mais diretos: Os testes se concentram em verificar o comportamento real da API, não em gerar documentação.
Mensagens de erro claras: O Grape fornece mensagens de erro específicas e bem formatadas.
Agora, quando eu especifico o formato do response:
present @event, with: ::Entities::EventResponse
basta definir no endpoint o tipo de resposta esperado:
success: ::Entities::EventResponse

Muitas vezes alteramos o serializer e corrigimos o teste onde mudamos os dados, mas esquecemos de outros pontos onde o mesmo serializer é usado. Se o teste não for 100% bem coberto, nossa API começa a ficar inconsistente na documentação Swagger ou com um alto custo de manutenção.

Como Testar Manualmente

Após configurar sua API, você pode testá-la usando ferramentas como Postman, curl ou a interface Swagger gerada automaticamente:

Inicie seu servidor Rails: rails s
Acesse a documentação Swagger: http://localhost:3000/api-docs
Experimente os endpoints disponíveis

Próximos Passos

Neste post, vimos como configurar uma API básica com Grape e Rails e como testá-la eficientemente. Nos próximos posts da série, vou abordar tópicos mais avançados, como:

Uso da gem contracts para validação
Organizando o código com a gem Interactor e controlando ações com organizers e interactors
Criação de helpers customizados
Adição de middlewares para tratamento de erros
Autenticação e autorização com Pundit
Paginação de recursos
E muito mais!

Conclusão

Usar Grape com Rails para criar APIs tem sido uma experiência extremamente positiva. A combinação de uma API expressiva com testes diretos e eficientes nos permitiu focar no que realmente importa: construir uma API robusta e bem documentada sem o overhead de testes voltados apenas para documentação.

Se você está cansado de escrever testes apenas para gerar documentação e quer uma solução mais direta e eficiente para suas APIs, definitivamente recomendo experimentar o Grape.

Nos vemos no próximo post, onde vamos aprofundar em recursos mais avançados do Grape!

Você já usou Grape em seus projetos Rails? Quais foram suas experiências? Deixe seus comentários abaixo!

Repositório do exemplo: https://github.com/rodrigonbarreto/event_reservation_system/tree/mvp_sample

Referências:

Me chamo Rodrigo Nogueira - Desenvolvedor Ruby on Rails desde 2015
Pós em Engenharia de Software (PUC-RJ) e trabalho com tecnologia desde 2011

Caso queiram acompanhar essa jornada, por favor comentem e deixem seu like!

Ambiente de desenvolvimento rails e postgres com dev containers

gustavo marciano — Fri, 04 Apr 2025 11:59:43 +0000

Requisitos Iniciais

Windows

WSL: https://learn.microsoft.com/pt-br/windows/wsl/install
Docker Desktop: Docker Desktop
Docker Settings
Vscode https://code.visualstudio.com/

Mantenha todo o seu projeto no WSL para evitar lentidão.

Linux

Docker Docker Desktop
Vscode https://code.visualstudio.com/

Iniciando o Setup

1-Crie o arquivo com o nome do projeto.

mkdir meu-app-rails
cd meu-app-rails

2-Baixe | Abra no vscode.

code .

3-Com o vscode aberto na pasta do projeto vá na aba extensões e verifique se a extensão dev containers já está habilitada, se não estiver procure no por dev containers e faça a instalação.

4-Com a extensão no Vscode aperte o botão F1 do seu teclado, um menu de opções do dev container aparecerá, escolha a opção "Dev containers: Open Folder in Container...".

5-Confirme o arquivo que você abrirá no container.

6-No próximo menu escreva “ruby” a extensão te retorna algumas opções de containers com Ruby, escolha opção Ruby on Rails & Postgres e em seguida escolha a versão do Ruby (recomendado sempre escolher a primeira/default).

7-Agora no menu de features vamos escolher algumas ferramentas importantes para o desenvolvimento. Nesse menu vamos procurar por Redis Server,Node e github-cli.

Depois dessa etapa a extensão vai mostrar alguns prompts de versões das features, apenas escolha default ou latest e prossiga com a instalação.
Após isso um novo container será criado.

Importante!

Isto pode demorar um bom tempo, o Docker vai baixar as imagens e fazer todo o setup ,então não estranhe se demorar muito.

8-Após o término do setup é recomendado testar se tudo está funcionando corretamente.

ruby -v

rails -v

node -v

redis-cli ping

Se os comandos tiverem retorno o seu setup já está pronto para o desenvolvimento.

9-Inicie um novo projeto com:

rails new . -d postgresql

Usar o “.” após o “new” faz com que o seu projeto seja criado na pasta atual e com o nome da mesma.

10-Após isso adicione o host, user e password no config/database.yml.

development:
  <<: *default
  database: pr_test_development
  host: db
  username: postgres
  password: postgres

test:
  <<: *default
  database: pr_test_test
  host: db
  username: postgres
  password: postgres

11-agora é só iniciar a sua aplicação rails e fazer a migration:

rails s

Software de Terceiros

Algumas ferramentas do Rails ,como Active Storage , necessitam que software de terceiros sejam instalados para o seu funcionamento. Ah forma correta de instalar essas ferramentas é o usando o DockerFile localizado dentro da pasta .devcontainer.

Dentro do arquivo descomente a linhas:

# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
#     && apt-get -y install --no-install-recommends <your-package-list-here>

Exemplo, linha modificada para instalar o postgresql-client ,libvips e imagemagick:

# [Optional] Uncomment this section to install additional OS packages.
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y curl libvips imagemagick postgresql-client && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

Extensões do Vscode

Para adicionar extensões e temas ao vscode pesquise pela extensão que deseja acionar e na pagina da extensão vá no símbolo de engrenagem e escolha a opção "Add to devcontainer.json" e faça o Rebuild do container.Agora todas as vezes que iniciar o container terá sempre as extensões que você escolheu.

Gems e comandos adicionais

Às vezes precisamos de Gems no ambiente de desenvolvimento ,mas não da aplicação para isso existe uma maneira fácil de fazer usando containers.

Vá em devcontainers.json
Descomente a linha com "postCreateCommand":
Agora adicione as gems e os comandos que você quiser ao seu ambiente

Exemplo:

"postCreateCommand": "gem install solargraph && bundle",

Recomendo adicionar sempre o comando budle em todos os containers para que o container já faça o bundle install automaticamente ao iniciar.

Fim