DEV Community: Vídeos de Ti

🇺🇸 3 Essential Gems to Eliminate Friction in Your Rails Workflow

Jackson Pires — Thu, 04 Jun 2026 21:48:37 +0000

Anyone who works with Ruby on Rails knows that, despite the framework being incredible for productivity, there are some classic workflow deficiencies that haunt almost every project.

You are focused on writing code, but suddenly you need to open an external tool like Postman to test a route. Then, you run a complex script to generate a static database diagram. And at the end of the day, you still need to manually update the API documentation, which will inevitably become outdated in the next sprint.

This constant context switching and manual maintenance generates enormous friction. To cover these deficiencies, I developed three gems that bring these tools inside your application. They are so practical that they quickly become indispensable in any Rails project. Meet each one of them:

1. `rails-api-docs`: The End of Outdated Documentation]

https://github.com/jacksonpires/rails-api-docs

The deficiency: API documentation always starts with good intentions, but as the system evolves—new routes, parameters, and response fields—it quickly stops representing reality. Keeping this updated manually is repetitive and frustrating work.

The solution: The rails-api-docs gem solves this by leveraging what Rails already knows. It inspects your routes, controllers (via AST analysis using Prism), and the ActiveRecord schema to automatically generate the first draft of your documentation. Everything is saved in a single YAML file (config/rails-api-docs.yml), which serves as the single source of truth.

Why it is indispensable:

Append-only strategy: When adding new routes and running the generator, the gem only appends what's new. Your descriptions, custom examples, and tags are never modified or deleted, making the documentation a living document.
Zero development friction: You edit the YAML in one window and view the updated documentation in the browser at localhost:3000/rails/api-docs instantly, with no build step required. For production, it exports a single static HTML file without any external dependencies.

2. `rails-http-lab`: Your HTTP Client Right in the App

https://github.com/jacksonpires/rails-http-lab

The deficiency: Testing HTTP endpoints usually requires switching to external tools (like Postman or Insomnia) or creating temporary scripts. Besides the loss of focus, these tools live outside your repository and frequently suffer from CORS issues when trying to access internal services.

The solution: The rails-http-lab is a Rails Engine that couples an HTTP request lab inside your own application. By accessing /rails/http-lab, you have a lightweight interface to test methods, headers, and payloads while visualizing the responses directly in the browser.

Why it is indispensable:

Stays in the Repository: Your requests are saved in .bru format (interchangeable with the Bruno desktop app) inside the project's docs/http-lab/ folder. This means your API tests are version-controlled in Git and can be easily reviewed in Pull Requests.
No CORS limits: Since the requests are executed by the Rails server itself, you don't have CORS problems and can reach internal services transparently.

3. `rails-realtime-erd`: Database Diagrams Always in Sync

https://github.com/jacksonpires/rails-realtime-erd

The deficiency: Understanding database relationships in a growing project is difficult. Traditional tools generate static diagrams (ERD) that require manual tasks and quickly become outdated as soon as a new migration is executed.

The solution: The rails-realtime-erd gem mounts a route at /rails/erd that renders your schema diagram in real-time using Mermaid, all processed by Hotwire (Stimulus), without relying on complex JavaScript frameworks.

Why it is indispensable:
You will never again need to run a rake step to generate a static image file. The introspection is done on the fly: if you run a migration, just refresh the page to see the new tables and relationships reflected in the diagram immediately. It is excellent for onboarding new developers and keeping a live documentation of your architecture.

Conclusion

These three tools share the same philosophy: your code already has the necessary knowledge, and the support tools should live as close to it as possible.

Adopting rails-api-docs, rails-http-lab, and rails-realtime-erd drastically reduces daily friction, eliminating external dependencies and manual rework. With simple installation steps, your development environment will become much more productive, robust, and integrated.

🇧🇷 3 Gems Indispensáveis para Eliminar as Deficiências do seu Fluxo de Trabalho no Rails

Jackson Pires — Thu, 04 Jun 2026 21:47:50 +0000

Quem trabalha com Ruby on Rails sabe que, embora o framework seja incrível para a produtividade, existem algumas deficiências clássicas no fluxo de desenvolvimento que assombram quase todo projeto.

Você está focado escrevendo código, mas de repente precisa abrir uma ferramenta externa como o Postman para testar uma rota. Depois, roda um script complexo para gerar um diagrama estático do banco de dados. E, no fim do dia, ainda precisa atualizar manualmente a documentação da API, que fatalmente ficará defasada na próxima sprint.

Essa constante alternância de contexto e manutenção manual geram um enorme atrito. Para cobrir essas deficiências, eu desenvolvi três gems que trazem essas ferramentas para dentro da sua aplicação. Elas são tão práticas que rapidamente se tornam indispensáveis em qualquer projeto Rails. Conheça cada uma delas:

1. `rails-api-docs`: O Fim da Documentação Desatualizada

https://github.com/jacksonpires/rails-api-docs

A deficiência: A documentação de API sempre começa com boas intenções, mas conforme o sistema evolui — novas rotas, parâmetros e campos na resposta —, ela rapidamente deixa de representar a realidade. Manter isso atualizado manualmente é um trabalho repetitivo e frustrante.

A solução: A gem rails-api-docs resolve isso aproveitando o que o Rails já sabe. Ela inspeciona suas rotas, controllers (via análise AST usando Prism) e o schema do ActiveRecord para gerar automaticamente o primeiro rascunho da sua documentação. Tudo é salvo em um único arquivo YAML (config/rails-api-docs.yml), que serve como fonte da verdade.

Por que é indispensável:

Estratégia Append-only: Ao adicionar novas rotas e rodar o gerador, a gem apenas adiciona o que é novo. Suas descrições, exemplos customizados e tags não são apagados, tornando a documentação um documento vivo.
Zero atrito no desenvolvimento: Você edita o YAML de um lado e visualiza a documentação atualizada no navegador em localhost:3000/rails/api-docs instantaneamente, sem etapa de build. Para produção, ela exporta um único arquivo HTML estático, sem dependências externas.

2. `rails-http-lab`: Seu Client HTTP Direto na Aplicação

https://github.com/jacksonpires/rails-http-lab

A deficiência: Testar endpoints HTTP geralmente exige alternar para ferramentas externas (como Postman ou Insomnia) ou criar scripts temporários. Além da perda de foco, essas ferramentas vivem fora do seu repositório e frequentemente sofrem com problemas de CORS ao tentar acessar serviços internos.

A solução: O rails-http-lab é uma Rails Engine que acopla um laboratório de requisições HTTP dentro da sua própria aplicação. Ao acessar /rails/http-lab, você tem uma interface leve para testar métodos, headers e payloads visualizando as respostas diretamente no navegador.

Por que é indispensável:

Fica no Repositório: As suas requisições são salvas no formato .bru (compatível com o aplicativo desktop Bruno) dentro da pasta docs/http-lab/ do projeto. Isso significa que os testes da sua API são versionados no Git e podem ser revisados nos Pull Requests.
Sem limites de CORS: Como as requisições são executadas pelo próprio servidor Rails, você não tem problemas de CORS e pode alcançar serviços internos de forma transparente.

3. `rails-realtime-erd`: Diagramas de Banco de Dados Sempre Sincronizados

https://github.com/jacksonpires/rails-realtime-erd

A deficiência: Entender os relacionamentos do banco de dados em um projeto que está crescendo é difícil. As ferramentas tradicionais geram diagramas estáticos (ERD) que exigem tarefas manuais e rapidamente ficam defasados assim que uma nova migration é executada.

A solução: A gem rails-realtime-erd monta uma rota em /rails/erd que renderiza o diagrama do seu schema em tempo real usando o Mermaid, tudo processado pelo Hotwire (Stimulus), sem depender de frameworks JavaScript complexos.

Por que é indispensável:
Você nunca mais precisará rodar um passo de rake para gerar um arquivo de imagem estático. A introspecção é feita sob demanda: se você rodar uma migration, basta atualizar a página para ver as tabelas e relacionamentos novos refletidos no diagrama imediatamente. É excelente para o onboarding de novos desenvolvedores e documentação viva da arquitetura.

Conclusão

Essas três ferramentas compartilham a mesma filosofia: o seu código já possui o conhecimento necessário, e as ferramentas de apoio devem viver o mais próximo possível dele.

Adotar o rails-api-docs, o rails-http-lab e o rails-realtime-erd reduz drasticamente o atrito no dia a dia, eliminando dependências externas e o retrabalho manual. Com passos simples de instalação (basta adicionar ao Gemfile e rodar um comando), seu ambiente de desenvolvimento se tornará muito mais produtivo, robusto e integrado.

🇺🇸 I Got Tired of Stale API Documentation in Rails — So I Built `rails-api-docs`

Jackson Pires — Wed, 03 Jun 2026 12:25:33 +0000

API documentation always starts with good intentions.

At the beginning of a project, everything is in sync.

Routes match reality.

Examples are accurate.

Parameters make sense.

Responses reflect exactly what the API returns.

But as the system evolves, documentation starts falling behind.

A new route gets added.

A parameter changes.

An endpoint gains authentication.

A response receives new fields.

And before you realize it, the documentation no longer represents reality.

If you've worked with Rails APIs for long enough, you've probably experienced this.

I certainly have.

And it was exactly that frustration that led me to create rails-api-docs.

GitHub: https://github.com/jacksonpires/rails-api-docs

The idea started with a simple question

Your Rails application already knows a lot.

It knows:

your routes
your controllers
your parameters
your models
your database schema
your HTTP verbs

So why should documentation always start from scratch?

Why do we need to manually rewrite information that already exists inside the application?

The idea behind rails-api-docs was to leverage the knowledge Rails already has to generate the first draft of the documentation automatically.

The workflow I wanted didn't exist

I didn't want another tool where the workflow looked like this:

edit documentation
→ generate artifacts
→ rebuild
→ restart server
→ validate changes

I wanted something closer to the typical Rails development experience:

edit
→ refresh browser
→ keep working

That's where the core concept of the gem came from:

A single editable YAML file that powers both development-time documentation and production-ready documentation.

A single source of truth

The entire workflow revolves around a single file:

config/rails-api-docs.yml

This file becomes the source of truth for your documentation.

From it, the gem generates:

live documentation during development
request examples
response examples
documented schemas
static HTML documentation for production

You update one file.

Everything else updates automatically.

How it works

First, generate the initial YAML file:

rails g rails-api-docs:init

The gem automatically inspects:

Rails.application.routes
controllers (via Prism AST analysis)
ActiveRecord schema

And creates an initial documentation structure.

Then start your application:

rails server

And visit:

http://localhost:3000/rails/api-docs

Whenever you modify the YAML file, simply refresh the page.

No build step.

No frontend tooling.

No intermediate process.

Let the code write the first draft

One of the most interesting parts of this project was using Prism to analyze controllers.

For example:

params.require(:user).permit(
  :email,
  :password,
  :role
)

The gem can automatically identify these fields and use them to build the initial documentation structure.

Combined with ActiveRecord schema information, it can also infer:

field types
required attributes
initial examples
schema metadata

The goal was never to replace developers.

The goal was to eliminate repetitive work.

Let the machine handle what it can already discover.

And let humans focus on the important part: explaining the API.

Documentation updates shouldn't destroy your work

This is probably the feature that frustrated me most in existing approaches.

You generate documentation.

Spend time writing descriptions.

Add examples.

Organize sections.

Customize schemas.

Then you run the generator again.

And hope nothing gets overwritten.

rails-api-docs follows an append-only strategy.

When you add new routes to your application, simply run:

rails g rails-api-docs:update

The gem appends only new endpoints.

Everything you've written remains untouched.

That includes:

descriptions
examples
tags
authentication details
schemas
section organization

In practice, the documentation becomes a living document rather than a disposable artifact.

Organizing larger APIs with tags

As APIs grow, navigation becomes increasingly important.

That's why the gem supports tags:

tags:
  - auth
  - public

These tags aren't just labels.

They also become interactive filters in the generated documentation.

Clicking a tag instantly filters the navigation to show only endpoints associated with that category.

This makes large APIs significantly easier to explore.

Production should be simple

Another important goal was making deployment boring.

When you're ready to publish the documentation, simply run:

rake rails-api-docs:build

The result is:

public/api-docs.html

A single HTML file.

Everything embedded.

Inline CSS.

Inline JavaScript.

No external dependencies.

No CDN.

No Asset Pipeline.

No JavaScript runtime.

Just a static file that can be hosted almost anywhere.

I'm not trying to replace OpenAPI

There are excellent OpenAPI and Swagger-based tools available today.

They solve many problems extremely well.

The goal of rails-api-docs is not to replace that ecosystem.

The idea is different.

I wanted a solution that allows developers to:

generate documentation from an existing Rails application
edit everything in YAML
preview changes instantly
export a static HTML file
keep documentation synchronized with minimal effort

That's the workflow I was looking for.

And since I couldn't find exactly what I wanted, I decided to build it.

Final thoughts

API documentation should be easy to create and easy to maintain.

In my experience, generating the first version isn't the hard part.

Keeping it updated over time is.

rails-api-docs was created to reduce that friction.

By inspecting the application to generate a starting point.

By preserving your customizations over time.

And by providing an extremely fast feedback loop during development.

If you'd like to try it out:

⭐ https://github.com/jacksonpires/rails-api-docs

Feedback, suggestions, and contributions are always welcome.

🇧🇷 Eu Cansei de Documentação de API Desatualizada no Rails — Então Criei a Gem `rails-api-docs`

Jackson Pires — Wed, 03 Jun 2026 12:24:43 +0000

Documentação de API sempre começa com boas intenções.

No início do projeto, tudo está sincronizado.

As rotas batem com a aplicação.

Os exemplos estão corretos.

Os parâmetros fazem sentido.

As respostas refletem exatamente o que a API retorna.

Mas conforme o sistema evolui, a documentação começa a ficar para trás.

Uma nova rota é criada.

Um parâmetro muda.

Um endpoint ganha autenticação.

Uma resposta recebe novos campos.

E, sem perceber, a documentação deixa de representar a realidade.

Se você trabalha com APIs em Rails há algum tempo, provavelmente já passou por isso.

Eu certamente já passei.

E foi justamente essa frustração que me levou a criar o rails-api-docs.

GitHub: https://github.com/jacksonpires/rails-api-docs

A ideia surgiu de uma pergunta simples

Sua aplicação Rails já sabe muita coisa.

Ela conhece:

suas rotas
seus controllers
seus parâmetros
seus modelos
seu schema do banco
seus verbos HTTP

Então por que a documentação precisa começar sempre do zero?

Por que precisamos reescrever manualmente informações que já existem dentro da aplicação?

A ideia por trás do rails-api-docs foi justamente aproveitar esse conhecimento que o Rails já possui para gerar um primeiro rascunho da documentação automaticamente.

O workflow que eu queria não existia

Eu não queria mais uma ferramenta onde o fluxo fosse:

editar documentação
→ gerar artefatos
→ rebuild
→ reiniciar servidor
→ validar alterações

Eu queria algo mais próximo do desenvolvimento Rails tradicional:

editar
→ atualizar navegador
→ continuar trabalhando

Foi daí que surgiu o conceito central da gem:

Um único arquivo YAML editável que gera tanto a documentação em desenvolvimento quanto a documentação de produção.

Uma única fonte da verdade

O fluxo da gem gira em torno de apenas um arquivo:

config/rails-api-docs.yml

Esse arquivo é a fonte da verdade para toda a documentação.

A partir dele a gem gera:

visualização em tempo real durante o desenvolvimento
exemplos de requisição
exemplos de resposta
schemas documentados
documentação HTML estática para produção

Você altera um único lugar.

Todo o resto é atualizado automaticamente.

Como funciona

Primeiro você gera o YAML inicial:

rails g rails-api-docs:init

A gem inspeciona automaticamente:

Rails.application.routes
controllers (via análise AST usando Prism)
schema do ActiveRecord

E cria uma estrutura inicial de documentação.

Depois basta subir a aplicação:

rails server

E acessar:

http://localhost:3000/rails/api-docs

Sempre que você alterar o YAML, basta atualizar a página.

Não existe etapa de build durante o desenvolvimento.

Não existe pipeline frontend.

Não existe processo intermediário.

Deixe o código escrever o primeiro rascunho

Uma das partes mais interessantes do projeto foi utilizar o Prism para analisar controllers.

Por exemplo:

params.require(:user).permit(
  :email,
  :password,
  :role
)

A gem consegue identificar automaticamente esses campos e utilizá-los para montar a estrutura inicial da documentação.

Quando combinamos isso com as informações do ActiveRecord, também é possível inferir:

tipos dos campos
obrigatoriedade
exemplos iniciais
informações do schema

O objetivo nunca foi substituir o trabalho do desenvolvedor.

O objetivo foi eliminar tarefas repetitivas.

Deixar a máquina fazer aquilo que ela consegue descobrir sozinha.

E deixar os humanos cuidarem da parte importante: explicar a API.

Atualizações não deveriam apagar seu trabalho

Essa talvez seja a característica que mais me incomodava em algumas abordagens existentes.

Você gera documentação.

Investe tempo escrevendo descrições.

Adiciona exemplos.

Organiza seções.

Personaliza schemas.

Então roda novamente o gerador.

E precisa rezar para não perder nada.

No rails-api-docs o YAML segue uma estratégia append-only.

Quando você adiciona novas rotas à aplicação basta executar:

rails g rails-api-docs:update

A gem adiciona apenas os endpoints novos.

Todo o conteúdo que você escreveu continua intacto.

Isso inclui:

descrições
exemplos
tags
autenticação
schemas
organização das seções

Na prática, a documentação deixa de ser um artefato descartável e passa a ser um documento vivo.

Organizando APIs maiores com Tags

Conforme uma API cresce, navegar pela documentação pode ficar mais difícil.

Por isso a gem possui suporte a tags:

tags:
  - auth
  - public

Essas tags não são apenas informativas.

Elas também funcionam como filtros interativos na documentação gerada.

Ao clicar em uma tag, a navegação passa a exibir apenas os endpoints relacionados àquela categoria.

Isso facilita bastante a exploração de APIs maiores.

Produção deveria ser simples

Outro objetivo importante era simplificar o deploy da documentação.

Quando chega o momento de publicar, basta executar:

rake rails-api-docs:build

O resultado é:

public/api-docs.html

Um único arquivo HTML.

Tudo embutido.

CSS inline.

JavaScript inline.

Sem dependências externas.

Sem CDN.

Sem Asset Pipeline.

Sem runtime JavaScript.

Apenas um arquivo estático que pode ser hospedado praticamente em qualquer lugar.

Não estou tentando substituir OpenAPI

Existem excelentes ferramentas baseadas em OpenAPI e Swagger.

Elas resolvem muito bem diversos cenários.

O objetivo do rails-api-docs não é substituir esse ecossistema.

A proposta é diferente.

Eu queria uma solução que permitisse:

gerar documentação a partir de uma aplicação Rails existente
editar tudo em YAML
visualizar mudanças instantaneamente
exportar um HTML estático
manter a documentação sincronizada com pouco esforço

Era esse workflow que eu procurava.

E como não encontrei exatamente dessa forma, resolvi construir.

Considerações finais

Documentação de API deveria ser simples de criar e simples de manter.

Na minha experiência, o maior problema não é gerar a primeira versão.

O desafio é mantê-la atualizada ao longo do tempo.

O rails-api-docs nasceu justamente para reduzir esse atrito.

Inspecionando a aplicação para gerar um ponto de partida.

Preservando suas customizações ao longo do tempo.

E oferecendo um ciclo de feedback extremamente rápido durante o desenvolvimento.

Se quiser experimentar:

⭐ https://github.com/jacksonpires/rails-api-docs

Feedbacks, sugestões e contribuições são muito bem-vindos.

🇺🇸 Introducing Rails HTTP Lab: Test Your Rails Routes Directly Inside Your Application

Jackson Pires — Fri, 29 May 2026 17:57:35 +0000

When working with Ruby on Rails, testing HTTP endpoints is part of everyday development.

Most of the time, we rely on tools like Postman, Insomnia, curl, or even temporary scripts just to validate requests, headers, payloads, and responses.

But during development, I found myself asking:

What if I could test my Rails routes directly from inside the application itself?

That idea led me to create Rails HTTP Lab.

What is Rails HTTP Lab?

rails-http-lab is a Rails Engine that provides an embedded interface inside your Rails application to test HTTP requests against your own routes.

Think of it as a lightweight HTTP client focused on your Rails app.

With it, you can experiment with your endpoints without constantly switching between your editor, terminal, browser, and external API tools.

Features

Current capabilities include:

Support for common HTTP verbs
Send request parameters and payloads
Inspect responses directly in the browser
Mountable Rails Engine
Seamless integration with your Rails development workflow
Simple setup

Installation

Add the gem to your Gemfile:

gem "rails-http-lab"

Then install it:

bundle install

Now start your Rails server and access:

/rails/http-lab

And you're ready to start testing your routes.

Why build this?

I wanted something that felt more integrated with the Rails developer experience.

External API clients are great, but sometimes you simply want a quick way to:

test an endpoint
tweak parameters
inspect responses
validate controller behavior

…without leaving your application context.

Rails HTTP Lab was created to reduce that friction.

Open Source & Feedback Welcome

The project is open source and still evolving.

If you like the idea, have suggestions, or want to contribute, feel free to check out the repository:

👉 https://github.com/jacksonpires/rails-http-lab

Feedback, issues, PRs, and ideas are very welcome.

Happy hacking 🚀

Special thanks to Vini (https://github.com/viniwenz) and Karine (https://github.com/karinevieira) for helping me with testing!

🇧🇷 Apresentando Rails HTTP Lab: teste rotas Rails diretamente dentro da sua aplicação

Jackson Pires — Fri, 29 May 2026 17:55:55 +0000

Quem trabalha com Ruby on Rails sabe que testar endpoints HTTP faz parte da rotina de desenvolvimento.

Na maioria das vezes usamos ferramentas como Postman, Insomnia, curl ou até scripts temporários apenas para validar requests, headers, payloads e responses.

Mas durante o desenvolvimento eu comecei a me perguntar:

E se fosse possível testar as rotas da própria aplicação Rails diretamente de dentro dela?

Foi dessa ideia que nasceu o Rails HTTP Lab.

O que é o Rails HTTP Lab?

rails-http-lab é uma Rails Engine que adiciona uma interface integrada à sua aplicação para testar requisições HTTP contra as próprias rotas da aplicação.

Pense nele como um cliente HTTP leve, mas focado no seu ambiente Rails.

Com ele você pode experimentar endpoints sem precisar alternar constantemente entre editor, terminal, navegador e ferramentas externas de API.

Funcionalidades

Atualmente a gem oferece:

Suporte aos principais verbos HTTP
Envio de parâmetros e payloads
Visualização das responses diretamente no navegador
Rails Engine mountável
Integração natural com o fluxo de desenvolvimento Rails
Configuração simples

Instalação

Adicione a gem ao seu Gemfile:

gem "rails-http-lab"

Depois instale:

bundle install

Agora basta iniciar o servidor Rails e acessar:

/rails/http-lab

Pronto. Você já pode começar a testar suas rotas.

Por que criar isso?

Eu queria algo mais integrado à experiência de desenvolvimento com Rails.

Ferramentas externas de API são excelentes, mas às vezes você só precisa de uma forma rápida de:

testar um endpoint
ajustar parâmetros
inspecionar responses
validar o comportamento do controller

…sem sair do contexto da própria aplicação.

O Rails HTTP Lab surgiu justamente para reduzir esse atrito.

Open Source e feedback são bem-vindos

O projeto é open source e ainda está evoluindo.

Se a ideia parece interessante, você tem sugestões ou quer contribuir, confira o repositório:

👉 https://github.com/jacksonpires/rails-http-lab

Issues, PRs, feedbacks e ideias são muito bem-vindos.

Happy coding 🚀

Agradecimento especial a Vini (https://github.com/viniwenz) e Karine (https://github.com/karinevieira) que me ajudaram nos testes!

🇺🇸 Glancer — Ask your Rails database questions in plain language

Ernane Ferreira — Wed, 27 May 2026 17:11:10 +0000

A Rails engine that allows you to query the database using natural language, with RAG and LLMs. No need to write any code.

Every Rails project reaches a point where someone on the team (product, support, management) needs data, but no one has time to write a quick query for them. You know the drill: a Slack message, a GitHub issue titled "how many users signed up last week?", or a CSV request that ends up in someone's backlog.

So, I think about Glancer.

What it is

Glancer is a Ruby on Rails engine that mounts a full chat interface at /glancer inside your app. You type a question in plain language, it retrieves the relevant schema context, generates a SELECT query (or an ActiveRecord expression), validates and executes it safely, then returns the result with a human-readable explanation.

"How many orders were placed in the last 30 days, grouped by status?"
→ SELECT executed, results shown, answer written in plain language.

It is inspired by Blazer, but instead of writing SQL yourself, you just ask.

Getting started

Add it to your Gemfile:

gem "glancer"

Run the generator:

rails generate glancer:install
rails db:migrate
rails glancer:index:all

Then visit /glancer and start asking questions.

The generator creates an initializer where you configure your LLM provider. A minimal setup with Gemini looks like this:

Glancer.configure do |config|
  config.llm_provider   = :gemini
  config.llm_model      = "gemini-2.0-flash"
  config.gemini_api_key = ENV["GEMINI_API_KEY"]

  config.schema_permission = true
end

OpenAI and OpenRouter are also supported. It runs on top of RubyLLM, so any model it supports works here too. You can assign different models per role: a smarter model for query generation, a cheaper one for writing the response.

What it can do

A few things worth knowing:

Safety is not optional. Every query runs inside a transaction that always rolls back. The keyword blocklist rejects DELETE, UPDATE, INSERT, DROP, and friends before they even touch the executor. You can also point it at a read-only replica.

No extra infrastructure. Embeddings live in your existing database as a JSON column. No Pinecone, no Weaviate, nothing to set up.

It understands your domain. You can drop a Markdown file at config/glancer/llm_context.glancer.md and teach Glancer your business rules — what status values mean, how revenue is calculated, which columns to ignore:

- `orders.status` values: "pending" | "paid" | "shipped" | "refunded"
- Monthly revenue = SUM(orders.total) WHERE status = "paid"
- When asked about "churn", use the `churned_at` column on `subscriptions`

The UI has some nice touches. Results render in a table with one-click CSV export. Charts are auto-generated where they make sense. Queries run in a background thread, so the main app thread stays free. You can type @table_name to pin a specific table to your question, edit the generated SQL inline and re-run it, and even dictate questions via microphone. There is also a schema viewer at /glancer/db-schema.

Blazer integration. If you already have Blazer installed, Glancer shows a button to open the generated SQL there directly.

The story behind it

This started as a study project. I had never published a gem before and wanted to understand the full process, from engine internals to gemspec to CI. I shared it with a few colleagues and they actually found it useful, so I decided to put it out there for the community.

It is version 1.0.0.

If you try it, I would love to hear what you think, about the code or the idea itself. Issues and pull requests are open.

If you find it useful, a star on the repo goes a long way in helping more people discover it.

GitHub: https://github.com/ErnaneJ/glancer
RubyGems: https://rubygems.org/gems/glancer

🇧🇷 Glancer — Converse com seu banco de dados Rails em linguagem natural

Ernane Ferreira — Wed, 27 May 2026 17:05:40 +0000

Uma engine Rails que permite consultar o banco de dados com linguagem natural, usando RAG e LLMs. Sem precisar escrever código.

Todo projeto Rails chega num ponto em que alguém do time (produto, suporte, gestão, etc.) precisa de um dado, mas ninguém tem tempo de parar para compreender a necessidade e escrever uma query. A mensagem no Slack, o card aberto, o pedido de CSV que some no backlog. Quem nunca.

Foi isso que me fez pensar no Glancer.

O que é

Glancer é uma engine Ruby on Rails que monta uma interface de chat em /glancer dentro da sua aplicação. Você digita uma pergunta em linguagem natural, ele busca o contexto relevante do sistema, gera um SELECT (ou uma expressão ActiveRecord), valida, executa com segurança e retorna o resultado.

"Quantos pedidos foram feitos nos últimos 30 dias, agrupados por status?"
→ SELECT executado, resultados exibidos, resposta escrita em português.

A inspiração direta foi o Blazer, uma gem que já usei bastante. A ideia aqui é dar um passo a mais: em vez de escrever o SQL, você só pergunta.

Como começar

Adicione no Gemfile:

gem "glancer"

Execute o gerador:

rails generate glancer:install
rails db:migrate
rails glancer:index:all

Acesse /glancer e comece a perguntar.

O gerador cria um initializer onde você configura o provider de LLM. Uma configuração mínima com Gemini:

Glancer.configure do |config|
  config.llm_provider   = :gemini
  config.llm_model      = "gemini-2.0-flash"
  config.gemini_api_key = ENV["GEMINI_API_KEY"]
  config.schema_permission = true
end

OpenAI e OpenRouter também são suportados. Ela roda em cima do RubyLLM então os modelos que ele suportar, o Glancer suportará. Dá para usar modelos diferentes por papel, por exemplo, um modelo mais capaz para gerar a query e um mais barato para escrever a resposta.

O que ele faz

Alguns pontos que vale conhecer:

Segurança por padrão: Toda query roda dentro de uma transaction que sempre faz rollback. Um blocklist de palavras rejeita DELETE, UPDATE, INSERT, DROP e afins antes mesmo de chegar no executor. Também é possível apontar para uma réplica de leitura.

Sem infraestrutura adicional: Os embeddings ficam no seu banco existente, numa coluna JSON. Sem Pinecone, sem Weaviate, sem nada extra para subir. Raramente será muita coisa, por isso essa abordagem.

Ensina o contexto do seu negócio. Você coloca um arquivo Markdown em config/glancer/llm_context.glancer.md e explica as regras do domínio: o que os valores de status significam, como a receita é calculada, quais colunas/tabelas/modelos ignorar, etc:

- `orders.status`: "pending" | "paid" | "shipped" | "refunded"
- Receita mensal = SUM(orders.total) WHERE status = "paid"
- Para perguntas sobre "churn", usar a coluna `churned_at` em `subscriptions`

Informações adicionais mais dinâmicas podem ser adicionadas em um campo texto nas configurações. Entretanto, não será gerado embedding disso pois será utilizado de contexto ao modelo base.

A interface tem uns detalhes legais. Os resultados aparecem em tabela com export CSV de um clique. Gráficos são gerados automaticamente quando fazem sentido. O processo de execução foi pensado para não travar a thread principal da aplicação. Dá para digitar @nome_da_tabela para fixar e ser mais assertivo sobre uma tabela específica na pergunta, editar o SQL gerado e reexecutar, e até ditar a pergunta pelo microfone. Tem também um visualizador de schema em /glancer/db-schema.

Integração com Blazer. Se você já usa o Blazer, o Glancer mostra um botão para abrir o SQL gerado direto lá.

A história por trás

Comecei isso como projeto de estudo. Estudei bastante sobre RAG e LLMs ao longo do ano passado e quando a ideia surgiu eu nunca tinha publicado uma gem antes e queria experimentar o processo completo, de engine a gemspec a CI. Com isso, juntei o útil ao agradável. Como mostrei para alguns colegas e eles acharam útil, então decidi abrir para a comunidade.

Atualmente está na versão 1.0.0.

Se você testar, adoraria saber o que achou, seja sobre o código ou sobre a ideia. Issues e pull requests são bem-vindos.

Se gostar do projeto, uma estrela no repositório ajuda bastante a divulgar para mais pessoas da comunidade.

GitHub: https://github.com/ErnaneJ/glancer
RubyGems: https://rubygems.org/gems/glancer

🇺🇸 Rails Realtime ERD: Visualize Your Rails Schema in Real Time

Jackson Pires — Wed, 27 May 2026 13:23:42 +0000

Anyone who works with Ruby on Rails applications knows that, as a project grows, quickly understanding the relationships between models can become increasingly difficult.

Even when using traditional ERD (Entity Relationship Diagram) generation tools, there is usually some friction in the workflow: generating files, manually updating diagrams, or relying on external processes.

With that in mind, I created the Rails Realtime ERD gem.

What is Rails Realtime ERD?

rails-realtime-erd is a Ruby on Rails gem that allows you to visualize your schema ERD diagrams in real time directly inside your application.

The idea is simple:

Install the gem
Add it to your project
Open a route
See your diagram automatically updated

No manual image generation. No intermediate exports. No leaving your application context.

Key Features

✅ Real-time schema visualization
✅ Simple integration with Rails applications
✅ Built on Rails Engine
✅ Automatic updates as your models evolve
✅ Integrated web interface

Perfect for:

Understanding existing architectures
Onboarding new developers
Quickly exploring model relationships
Keeping living documentation of your application's domain

Installation

Add the gem to your Gemfile:

gem "rails-realtime-erd"

Then run:

bundle install

Now simply access:

/rails/erd

in your project to visualize your diagram.

Why create this gem?

During consulting work, training sessions, and Rails application development, I often felt the lack of a more dynamic experience for inspecting an application's domain.

I wanted something closer to the experience we already have with:

/rails/mailers
/sidekiq
internal dashboards
integrated development tools

In other words: open a URL and start exploring immediately.

That's how Rails Realtime ERD was born.

Open Source Project

The gem is open source and available on GitHub:

GitHub:

https://github.com/jacksonpires/rails-realtime-erd

Contributions, feedback, issues, and suggestions are very welcome.

If you work with Rails and enjoy tools that improve productivity and architectural understanding, give it a try.

🇧🇷 Rails Realtime ERD: visualize seu schema Rails em tempo real

Jackson Pires — Wed, 27 May 2026 13:10:31 +0000

Quem trabalha com aplicações Ruby on Rails sabe que, conforme o projeto cresce, entender rapidamente as relações entre modelos pode se tornar cada vez mais difícil.

Mesmo utilizando ferramentas tradicionais de geração de ERD (Entity Relationship Diagram), normalmente existe um pequeno atrito no fluxo: gerar arquivos, atualizar diagramas manualmente ou depender de processos externos.

Pensando nisso, criei a gem Rails Realtime ERD.

O que é o Rails Realtime ERD?

O rails-realtime-erd é uma gem para Ruby on Rails que permite visualizar diagramas ERD do seu schema em tempo real diretamente dentro da aplicação.

A proposta é simples:

Instalar a gem
Montar a engine no projeto
Abrir uma rota
Ver seu diagrama atualizado automaticamente

Sem geração manual de imagens. Sem exportações intermediárias. Sem sair do contexto da aplicação.

Principais recursos

✅ Visualização do schema em tempo real
✅ Integração simples com aplicações Rails
✅ Baseado em Rails Engine
✅ Atualizações automáticas conforme seus models evoluem
✅ Interface web integrada ao projeto

Ideal para:

Entender arquiteturas existentes
Onboarding de novos desenvolvedores
Exploração rápida de relacionamentos entre modelos
Documentação viva do domínio da aplicação

Instalação

Adicione a gem ao seu Gemfile:

gem "rails-realtime-erd"

Depois:

bundle install

Agora basta acessar

/rails/erd

em seu projeto e visualizar seu diagrama.

Por que criar essa gem?

Durante consultorias, cursos e desenvolvimento de aplicações Rails, frequentemente senti falta de uma experiência mais dinâmica para inspeção do domínio da aplicação.

Queria algo próximo da experiência que temos com:

/rails/mailers
/sidekiq
dashboards internos
ferramentas de desenvolvimento integradas

Ou seja: abrir uma URL e começar a explorar imediatamente.

Foi daí que nasceu o Rails Realtime ERD.

Projeto Open Source

A gem é open source e está disponível no GitHub:

GitHub:

https://github.com/jacksonpires/rails-realtime-erd

Contribuições, feedbacks, issues e sugestões são muito bem-vindos.

Se você trabalha com Rails e gosta de ferramentas para melhorar produtividade e entendimento de arquitetura, vale a pena experimentar.

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.

DEV Community: Vídeos de Ti

🇺🇸 3 Essential Gems to Eliminate Friction in Your Rails Workflow

1. rails-api-docs: The End of Outdated Documentation]

2. rails-http-lab: Your HTTP Client Right in the App

3. rails-realtime-erd: Database Diagrams Always in Sync

Conclusion

🇧🇷 3 Gems Indispensáveis para Eliminar as Deficiências do seu Fluxo de Trabalho no Rails

1. rails-api-docs: O Fim da Documentação Desatualizada

2. rails-http-lab: Seu Client HTTP Direto na Aplicação

3. rails-realtime-erd: Diagramas de Banco de Dados Sempre Sincronizados

Conclusão

🇺🇸 I Got Tired of Stale API Documentation in Rails — So I Built `rails-api-docs`

The idea started with a simple question

The workflow I wanted didn't exist

A single source of truth

How it works

Let the code write the first draft

Documentation updates shouldn't destroy your work

Organizing larger APIs with tags

Production should be simple

I'm not trying to replace OpenAPI

Final thoughts

🇧🇷 Eu Cansei de Documentação de API Desatualizada no Rails — Então Criei a Gem `rails-api-docs`

A ideia surgiu de uma pergunta simples

O workflow que eu queria não existia

Uma única fonte da verdade

Como funciona

Deixe o código escrever o primeiro rascunho

Atualizações não deveriam apagar seu trabalho

Organizando APIs maiores com Tags

Produção deveria ser simples

Não estou tentando substituir OpenAPI

Considerações finais

🇺🇸 Introducing Rails HTTP Lab: Test Your Rails Routes Directly Inside Your Application

What is Rails HTTP Lab?

Features

Installation

Why build this?

Open Source & Feedback Welcome

🇧🇷 Apresentando Rails HTTP Lab: teste rotas Rails diretamente dentro da sua aplicação

O que é o Rails HTTP Lab?

Funcionalidades

Instalação

Por que criar isso?

Open Source e feedback são bem-vindos

🇺🇸 Glancer — Ask your Rails database questions in plain language

What it is

Getting started

What it can do

The story behind it

🇧🇷 Glancer — Converse com seu banco de dados Rails em linguagem natural

O que é

Como começar

O que ele faz

A história por trás

🇺🇸 Rails Realtime ERD: Visualize Your Rails Schema in Real Time

What is Rails Realtime ERD?

Key Features

Installation

Why create this gem?

Open Source Project

🇧🇷 Rails Realtime ERD: visualize seu schema Rails em tempo real

O que é o Rails Realtime ERD?

Principais recursos

Instalação

Por que criar essa gem?

Projeto Open Source

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

How This Started

Installing Nix

The Sample Project

The Problem

The Solution: One File

What's Happening Here?

Let's Use It

Enter the shell

Start MySQL

Run the backend

Run the frontend

The Day-to-Day

1. `rails-api-docs`: The End of Outdated Documentation]

2. `rails-http-lab`: Your HTTP Client Right in the App

3. `rails-realtime-erd`: Database Diagrams Always in Sync

1. `rails-api-docs`: O Fim da Documentação Desatualizada

2. `rails-http-lab`: Seu Client HTTP Direto na Aplicação

3. `rails-realtime-erd`: Diagramas de Banco de Dados Sempre Sincronizados