VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
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
\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:Converta
OCONVERT TO CHARACTER SET reescreve a tabela, convertendo tanto as definições das colunas quanto os dados armazenados:
ALTER bloqueante e execute-a com as suas ferramentas normais de migração online. Consulte Migrações de esquema.
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 linhaDYNAMIC) permitem 3.072 bytes, portanto isso afeta principalmente tabelas herdadas com os formatos de linhaREDUNDANTouCOMPACTde servidores muito antigos. Se oALTERfalhar 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:
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 cobre as regras de comparação em profundidade.
Veja também
- Conjuntos de caracteres e collations — o modelo mais amplo de charset do qual este guia é um caso especial
- Migrações de esquema — executando o ALTER de conversão com segurança em produção
- Escolhendo tipos de dados — dimensionamento de colunas quando cada caractere pode ter quatro bytes
- Usando o MySQL com ORMs: Django, Rails e Prisma — as configurações de conexão de ORM que usam este charset
- Sensibilidade a maiúsculas e minúsculas no MySQL — entendendo a collation que acompanha este charset