VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
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 executarrails new:
PATH:
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:
~> 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. Executarrails 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:
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 contaroot. Crie um banco de dados e um usuário com escopo no servidor em execução:
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:
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 modeloPost e migre:
Conecte uma Rota e um Controller, e Teste no Servidor
Adicione uma rota resourceful paraindex e create:
curl:
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
Odatabase.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:
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:
config/puma.rb a lê diretamente, com um comentário que diz isso explicitamente:
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
- Usando MySQL com ORMs: Django, Rails e Prisma — configuração do Rails no nível das configurações, em três frameworks
- Pool de Conexões no MySQL — como o pool de conexões se comporta independentemente de qualquer framework