Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
Executar rails new sem flags dá a você SQLite em desenvolvimento, não MySQL. Apontar uma aplicação Rails 8 para o MySQL exige uma flag explícita na criação do projeto, um database.yml que nomeie um usuário e um host reais, e uma gem que precisa de uma biblioteca de cliente MySQL nativa para compilar. Este guia percorre os três passos contra um servidor ativo compatível com MySQL, usando o VillageSQL como o banco de dados em que tudo abaixo de fato rodou.

Confirme o Conjunto de Ferramentas Antes de Criar o Projeto

O Rails 8 exige Ruby 3.2 ou posterior. Verifique o que está na máquina antes de executar rails new:
Em uma instalação nova do macOS com somente o Ruby do sistema, isso pode retornar algo como:
O Ruby 2.6 não consegue executar o Rails 8. Instale um Ruby atual com o Homebrew e coloque-o antes do Ruby do sistema no PATH:
Isso produziu ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [arm64-darwin25], bem acima do mínimo do Rails 8. Instale o próprio Rails com uma restrição de versão em vez de confiar no que gem install rails resolver:
Isso instalou o Rails 8.1.3.1. O Rails 8.1 satisfaz a restrição ~> 8.0 porque esse operador significa “pelo menos 8.0, menor que 9.0”.

Crie o Projeto com o Adaptador MySQL

O Rails 8 não usa MySQL nem PostgreSQL por padrão. Executar rails new --help mostra o padrão real:
mysql continua sendo o valor correto no Rails 8; ele seleciona a gem e o adaptador mysql2. trilogy é um adaptador separado do protocolo MySQL, em Ruby puro, que o Rails também suporta, e é uma escolha diferente da que este guia faz. Crie a aplicação com o valor mysql:
Isso grava mysql2 no Gemfile e gera um config/database.yml pré-configurado com adapter: mysql2. --skip-git é opcional e só é relevante se o diretório da aplicação não for o seu próprio repositório git. A gem mysql2 tem uma extensão nativa e precisa de uma biblioteca de cliente MySQL com headers para compilar. Sem ela, bundle install falha na etapa do mysql2. No macOS com Homebrew:
mysql-client é keg-only no Homebrew (ele não recebe links simbólicos em /opt/homebrew porque conflita com a fórmula mysql completa), e é exatamente por isso que o bundle config precisa ser informado explicitamente de onde encontrá-lo, em vez de depender do PATH. Com isso configurado, bundle install compilou e instalou o mysql2 0.5.7 junto com o restante do conjunto de dependências do Rails 8.1.3.1.

Crie um Banco de Dados e um Usuário Dedicados

Não aponte uma aplicação nova para a conta root. Crie um banco de dados e um usuário com escopo no servidor em execução:
Aponte config/database.yml para esse usuário por TCP, e não pelo socket Unix, já que rails_app recebeu acesso a partir de 127.0.0.1, não de localhost:

O Que o rails db:create Realmente Precisa

rails db:create não cria somente o banco de dados nomeado no RAILS_ENV atual. Com rails_app tendo privilégios somente em rails_guide.*, executá-lo produziu isto:
rails_guide foi criado com sucesso: GRANT ALL PRIVILEGES ON rails_guide.* é suficiente para criar um banco de dados que ainda não existe, porque o grant tem escopo no nome do banco de dados, não em um objeto existente. Mas rails db:create também tenta criar o banco de dados do ambiente test na mesma execução, e rails_guide_test nunca recebeu grant. A tarefa cria os bancos de dados de development e test por padrão; somente production é excluído. Conceder o grant no segundo nome de banco de dados resolve:
Um usuário com escopo e sem privilégios elevados é suficiente para rails db:create, desde que ele receba grant em todos os nomes de banco de dados que o Rails vai tentar criar, e não só no nomeado em RAILS_ENV. Nenhum superusuário ou privilégio CREATE global é necessário.

Migre e Verifique Diretamente no Servidor

Gere um modelo Post e migre:
A migração gerada:
Confirme que a tabela existe consultando o servidor diretamente, e não confiando na saída de migração do próprio Rails:

Conecte uma Rota e um Controller, e Teste no Servidor

Adicione uma rota resourceful para index e create:
Um controller JSON mínimo:
Inicie o servidor e exercite as duas ações com curl:
Não pare na resposta HTTP. Confirme que a gravação chegou à tabela de verdade:
A linha está presente com o mesmo conteúdo que o ActiveRecord reportou, e o timestamp confirma que created_at fez a ida e volta pelo mysql2 corretamente.

O Tamanho do Pool de Conexões e a Contagem de Threads do Puma São o Mesmo Número

O database.yml gerado pelo Rails 8.1 não usa mais a chave pool que você talvez conheça de versões anteriores do Rails. Ele usa max_connections:
Uma chave pool: ainda funciona e não gera aviso: max_connections recorre a ela quando max_connections está ausente, como uma simples consulta sem caminho de depreciação. O que o Rails 8.1 depreciou foi o método Ruby HashConfig#pool, agora um alias de HashConfig#max_connections, que é uma coisa diferente da chave do database.yml. Definir as duas chaves com valores diferentes não é resolvido silenciosamente. Isso gera um erro na inicialização:
Isso importa porque a mesma variável de ambiente também dimensiona o pool de threads do Puma. O config/puma.rb a lê diretamente, com um comentário que diz isso explicitamente:
Os dois padrões não são o mesmo número: o database.yml recorre a 5 conexões se RAILS_MAX_THREADS não estiver definida, enquanto o puma.rb recorre a 3 threads. Deixados nos padrões, o pool tem mais conexões do que o Puma tem threads para usá-las, o que é seguro, mas um pouco desperdiçador. Defina RAILS_MAX_THREADS explicitamente assim que souber a sua contagem de threads alvo, e as duas configurações se movem juntas. Um pool menor que a contagem de threads é a direção perigosa: as threads vão enfileirar esperando por uma conexão livre, e sob carga isso aparece como latência de requisição sem nenhum erro no log para explicar.

Perguntas Frequentes

--database=mysql instala a mesma gem em todas as versões do Rails 8?

Dentro do Rails 8, sim. Ela resolve para a gem mysql2 e o adaptador mysql2, confirmado contra rails new --help no Rails 8.1.3.1. trilogy é um valor separado e válido para a mesma flag: é um cliente do protocolo de rede do MySQL em Ruby puro, sem extensão nativa para compilar, o que remove a dependência dos headers do mysql-client ao custo de usar uma gem diferente. Escolha um na criação do projeto; eles não são adaptadores intercambiáveis que você pode trocar depois sem mexer no database.yml e no Gemfile.

Por que rails db:create precisa de um grant específico por banco de dados em vez de só o privilégio CREATE?

Um GRANT ... ON dbname.* TO user do MySQL funciona mesmo quando dbname ainda não existe, e autoriza a criação desse banco de dados específico. Ele não autoriza a criação de um banco de dados com um nome diferente. Como rails db:create cria os bancos de dados de development e test a partir do config/database.yml em uma única execução, um usuário com escopo precisa de um grant nomeando cada um, e não de um único grant no ambiente que você espera usar no dia a dia.

Preciso executar as migrações no VillageSQL de forma diferente do MySQL padrão?

Não. Todos os comandos deste guia, rails db:create, rails db:migrate, rails generate model, rodaram sem modificação contra um servidor VillageSQL. O VillageSQL é um substituto direto para o MySQL, então o mysql2 e o adaptador MySQL do ActiveRecord veem o mesmo protocolo de rede e a mesma saída de SHOW/DESCRIBE que veriam contra o próprio MySQL.

Solução de Problemas

Veja também