> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usando MySQL com ORMs: Django, Rails e Prisma

> Configurando Django, Rails e Prisma corretamente para o MySQL: configurações de charset e modo estrito, o problema N+1 e quando descer para SQL puro.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

ORMs são a forma como a maioria das aplicações realmente fala com o MySQL, e a maioria dos problemas de ORM remonta a um punhado de linhas de configuração e a um padrão de consulta. Este guia cobre as configurações do lado do MySQL para Django, Rails e Prisma, e os hábitos que impedem que o SQL gerado pelo ORM se torne a parte lenta do seu produto. Como o VillageSQL é um substituto direto do MySQL, toda configuração aqui funciona com ele sem alteração: o ORM não consegue notar a diferença.

## As Configurações Que Importam em Todo Lugar

Seja qual for o framework, três coisas precisam ser verdadeiras:

* **A conexão usa `utf8mb4`**, ou os emojis quebram no caminho. Consulte [utf8mb4 e emoji](https://villagesql.com/docs/pt-BR/guides/utf8mb4.md).
* **O modo SQL estrito está ligado** (é o padrão do MySQL 8.x), para que dados ruins gerem erro em vez de serem truncados silenciosamente.
* **O tamanho do pool é deliberado.** Todo framework abre um pool por processo; multiplique pela sua contagem de processos antes de escolher um número. Consulte [Pool de conexões](https://villagesql.com/docs/pt-BR/guides/connection-pooling.md).

## Django

```python theme={null}
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "NAME": "myapp",
        "USER": "app",
        "PASSWORD": environ["DB_PASSWORD"],
        "HOST": "127.0.0.1",
        "PORT": "3306",
        "OPTIONS": {
            "charset": "utf8mb4",
            "init_command": "SET sql_mode='STRICT_TRANS_TABLES'",
        },
    }
}
```

Observações específicas do Django:

* Use `mysqlclient`, o driver em C mantido que a documentação do Django recomenda.
* O Django emula algumas restrições em Python; adicione restrições reais no banco de dados também (`unique=True` vira um índice único real, mas restrições check precisam de `CheckConstraint` em `Meta`).
* `select_related()` (JOIN) e `prefetch_related()` (segunda consulta) são as ferramentas contra N+1; veja abaixo quando usar cada uma.

## Rails

```yaml theme={null}
# config/database.yml
production:
  adapter: mysql2
  database: myapp
  username: app
  password: <%= ENV["DB_PASSWORD"] %>
  host: 127.0.0.1
  encoding: utf8mb4
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
```

Observações específicas do Rails:

* `encoding: utf8mb4` em `database.yml` define tanto o charset da conexão quanto o padrão para `rails db:create`.
* As validações do ActiveRecord (`validates_uniqueness_of`) sofrem condições de corrida sob concorrência; sustente toda validação de unicidade com um índice único real, e deixe o [erro 1062 de chave duplicada](https://villagesql.com/docs/pt-BR/guides/common-mysql-errors.md) ser a última linha de defesa.
* `includes` é a ferramenta contra N+1; o modo `strict_loading` transforma o carregamento preguiçoso em erro, para que os N+1 falhem em desenvolvimento em vez de irem para produção.
* O Rails 8.1 gera `max_connections` em `database.yml` onde versões anteriores geravam `pool`. Uma chave `pool:` ainda funciona, silenciosamente, como o valor de fallback que `max_connections` lê; definir as duas com valores diferentes lança erro na inicialização. Consulte [Rails 8 com MySQL](https://villagesql.com/docs/pt-BR/guides/rails-mysql.md) para uma aplicação completa, incluindo a flag `--database=mysql` de que o Rails 8 precisa, já que ele não usa mais o MySQL por padrão.

## Prisma

```prisma theme={null}
datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}
```

```text theme={null}
DATABASE_URL="mysql://app:password@127.0.0.1:3306/myapp?connection_limit=10"
```

Observações específicas do Prisma:

* O Prisma fala utf8mb4 por padrão; a configuração a observar é `connection_limit` na URL, cujo padrão é baixo.
* `prisma migrate` gera DDL a partir da diferença de schema. Leia o SQL gerado antes de aplicá-lo em produção, exatamente como faria com uma migração escrita à mão. Consulte [Migrações de schema](https://villagesql.com/docs/pt-BR/guides/schema-migrations.md).
* Consultas de relação usam `include`; o formato N+1 aparece quando você itera sobre os resultados e acessa as relações uma a uma.
* O Prisma 7 move a URL de conexão acima para fora de `schema.prisma`, para um arquivo de configuração separado, e exige um driver adapter para conectar. Consulte [Next.js e Prisma com MySQL](https://villagesql.com/docs/pt-BR/guides/mysql-with-prisma.md) para uma aplicação completa com Prisma 7.

## O Problema N+1, de Uma Vez

O bug de desempenho universal dos ORMs: carregue 100 pedidos, depois carregue preguiçosamente o cliente de cada pedido, e o ORM emite 101 consultas. A correção é a mesma ideia em todos os frameworks — declare de antemão as relações de que você precisa para que o ORM as busque em uma ou duas consultas (`select_related` / `includes` / `include`). A ferramenta de detecção também é universal: ligue o log de consultas em desenvolvimento e leia o que o ORM realmente envia, ou observe o [slow query log](https://villagesql.com/docs/pt-BR/guides/slow-query-log.md) em produção.

## Quando Descer para SQL

ORMs valem o que custam em CRUD e deixam de valer em analytics. Funções de janela, CTEs, upserts em massa e consultas de relatório com várias tabelas são mais claras em SQL do que em uma cadeia de query builder tentando expressá-las. Todo ORM tem uma válvula de escape (`raw()` no Django, `find_by_sql` no Rails, `$queryRaw` no Prisma); usá-la para os 5 por cento de consultas que a merecem é boa engenharia, não derrota. É também assim que as funções de extensão do VillageSQL chegam a uma aplicação com ORM: `SELECT UUID_V7()` ou `ai_prompt(...)` funcionam por qualquer uma dessas válvulas de escape, já que o ORM apenas repassa o SQL.

## Veja também

* [Next.js e Prisma com MySQL](https://villagesql.com/docs/pt-BR/guides/mysql-with-prisma.md) — uma aplicação completa com Prisma 7, não só a configuração
* [Next.js e Drizzle com MySQL](https://villagesql.com/docs/pt-BR/guides/mysql-with-drizzle.md) — uma aplicação completa com Drizzle, uma alternativa mais leve e orientada a SQL não coberta acima
* [Next.js com MySQL](https://villagesql.com/docs/pt-BR/guides/nextjs-mysql.md) — configuração de conexão e padrões de consulta sem nenhum ORM
* [Rails 8 com MySQL](https://villagesql.com/docs/pt-BR/guides/rails-mysql.md) — uma aplicação completa, incluindo a flag de scaffold de que o Rails 8 precisa para sequer escolher o MySQL
* [Laravel 12 com MySQL](https://villagesql.com/docs/pt-BR/guides/laravel-mysql.md) — uma aplicação completa com o ORM Eloquent do Laravel, não coberto acima
* [Go e sqlc com MySQL](https://villagesql.com/docs/pt-BR/guides/go-sqlc-mysql.md) — consultas geradas e com tipagem segura em vez de um ORM em tempo de execução
* [Pool de conexões](https://villagesql.com/docs/pt-BR/guides/connection-pooling.md) — dimensionando pools entre processos
* [utf8mb4 e emoji](https://villagesql.com/docs/pt-BR/guides/utf8mb4.md) — a configuração de charset que toda configuração acima define
* [Slow query log](https://villagesql.com/docs/pt-BR/guides/slow-query-log.md) — capturando o que o ORM gera
* [Migrações de schema](https://villagesql.com/docs/pt-BR/guides/schema-migrations.md) — aplicando DDL gerado pelo ORM com segurança


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.