> ## 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.

# utf8mb4 no MySQL: Armazenando Emoji e Unicode Completo

> Por que o charset utf8 do MySQL rejeita emoji, como converter tabelas para utf8mb4 com segurança e o limite de comprimento de índice que costumava fazer as conversões falharem.

> [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 →

O charset do MySQL chamado `utf8` não é UTF-8. É um subconjunto de três bytes por caractere (`utf8mb3`), congelado no tempo antes dos emoji, e qualquer caractere de quatro bytes — emoji, muitos ideogramas CJK, símbolos matemáticos — não pode ser armazenado nele. `utf8mb4` é o UTF-8 de verdade. No MySQL 8.0 e posteriores, ele é o padrão para novas tabelas, mas as tabelas criadas em versões mais antigas, ou com `utf8` explícito no seu DDL, ainda carregam a armadilha.

## A Falha

```sql theme={null}
CREATE TABLE notes_mb3 (
  body VARCHAR(100)
) CHARACTER SET utf8mb3;

INSERT INTO notes_mb3 (body) VALUES ('launch day 🚀');
```

```text theme={null}
ERROR 1366 (HY000): Incorrect string value: '\xF0\x9F\x9A\x80' for column 'body' at row 1
```

`\xF0\x9F\x9A\x80` são os quatro bytes do emoji de foguete. Com o modo SQL estrito desligado, isso chega como um aviso, e o caractere problemático é substituído silenciosamente por `?` enquanto o restante da string é mantido — o que é pior: você descobre semanas depois, a partir dos dados.

## Encontre o Que Precisa de Conversão

Pergunte aos metadados quais tabelas e colunas ainda usam o utf8 de três bytes:

```sql theme={null}
SELECT table_schema, table_name, column_name, character_set_name
FROM information_schema.columns
WHERE character_set_name = 'utf8mb3'
  AND table_schema NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys');
```

Verifique também os padrões do esquema e da tabela, ou as novas colunas nascerão erradas:

```sql theme={null}
SELECT schema_name, default_character_set_name
FROM information_schema.schemata;
```

## Converta

O `CONVERT TO CHARACTER SET` reescreve a tabela, convertendo tanto as definições das colunas quanto os dados armazenados:

```sql theme={null}
ALTER TABLE notes_mb3 CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
```

Em seguida, corrija os padrões para que os objetos futuros herdem o charset correto:

```sql theme={null}
ALTER DATABASE myapp CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
```

Em uma tabela grande, isso é uma reescrita completa; trate-a como qualquer outro `ALTER` bloqueante e execute-a com as suas ferramentas normais de migração online. Consulte [Migrações de esquema](https://villagesql.com/docs/pt-BR/guides/schema-migrations.md).

Duas coisas a verificar antes de converter:

* **Comprimento do índice.** Um índice único em `VARCHAR(255)` precisava de 765 bytes em utf8mb3, mas de 1.020 em utf8mb4. Os padrões modernos do InnoDB (formato de linha `DYNAMIC`) permitem 3.072 bytes, portanto isso afeta principalmente tabelas herdadas com os formatos de linha `REDUNDANT` ou `COMPACT` de servidores muito antigos. Se o `ALTER` falhar com um erro de comprimento máximo de chave, verifique primeiro o formato de linha da tabela.
* **O charset da conexão.** O armazenamento é só metade do caminho. Se a conexão do cliente negociar `utf8mb3`, os emoji morrem em trânsito, mesmo que a coluna pudesse armazená-los. Verifique o que a sua sessão realmente usa:

```sql theme={null}
SHOW VARIABLES LIKE 'character_set_c%';
```

Você quer que `character_set_client` e `character_set_connection` mostrem ambos `utf8mb4`. A maioria dos drivers modernos faz isso por padrão; configurações mais antigas de JDBC e PHP podem fixar `utf8`.

## Collation, em Resumo

O charset é o que os bytes significam; a collation é como eles se comparam. Para utf8mb4 no MySQL 8.x, `utf8mb4_0900_ai_ci` é o padrão e a resposta geral correta: insensível a acentos, insensível a maiúsculas e minúsculas, ordenação correta do Unicode 9.0. Misturar collations entre tabelas que são unidas por colunas de string força conversões e pode deixar de usar índices, portanto escolha uma e use-a em todos os lugares. [Conjuntos de caracteres e collations](https://villagesql.com/docs/pt-BR/guides/character-sets.md) cobre as regras de comparação em profundidade.

## Veja também

* [Conjuntos de caracteres e collations](https://villagesql.com/docs/pt-BR/guides/character-sets.md) — o modelo mais amplo de charset do qual este guia é um caso especial
* [Migrações de esquema](https://villagesql.com/docs/pt-BR/guides/schema-migrations.md) — executando o ALTER de conversão com segurança em produção
* [Escolhendo tipos de dados](https://villagesql.com/docs/pt-BR/guides/choosing-data-types.md) — dimensionamento de colunas quando cada caractere pode ter quatro bytes
* [Usando o MySQL com ORMs: Django, Rails e Prisma](https://villagesql.com/docs/pt-BR/guides/mysql-with-orms.md) — as configurações de conexão de ORM que usam este charset
* [Sensibilidade a maiúsculas e minúsculas no MySQL](https://villagesql.com/docs/pt-BR/tutorial/case-sensitivity.md) — entendendo a collation que acompanha este charset


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