max_allowed_packet no MariaDB: Definir tamanho máximo do pacote de dados

O max_allowed_packet do MariaDB é uma variável de sistema que define o tamanho máximo permitido para um único pacote de dados na comunicação entre o banco de dados e a aplicação. Quem transmite arquivos grandes, muitos registros ou comandos SQL longos, pode rapidamente atingir limites se esse valor não for ajustado.

O que é max_allowed_packet no MariaDB?

A variável de sistema max_allowed_packet é um dos parâmetros de configuração mais importantes no MariaDB e no MySQL quando se trata de garantir a estabilidade e a confiabilidade das transferências de dados. Ela define o tamanho máximo de um único pacote de dados que um cliente, como uma aplicação ou um script SQL, pode enviar para um servidor MariaDB ou receber dele. O valor padrão dessa variável varia conforme o sistema, a distribuição ou a versão do MariaDB.

Um pacote de dados no MariaDB agrupa instruções SQL e conteúdos que o servidor ou o cliente trocam pela rede. Se um comando SQL, como um INSERT com muitos valores ou um BLOB (Binary Large Object), ultrapassar esse tamanho máximo, o servidor recusará a execução. Nesse caso, é comum aparecer o seguinte erro:

ERROR 1153 (08S01): Got a packet bigger than 'max_allowed_packet' bytes

O max_allowed_packet no MariaDB protege o servidor contra requisições excessivamente grandes, que podem sobrecarregar os recursos ou causar instabilidade. Ao mesmo tempo, permite que administradoras e administradores ajustem o limite conforme as necessidades do ambiente.

É importante saber que tanto o servidor quanto o cliente possuem seus próprios valores para max_allowed_packet. A transferência só funciona se ambos aceitarem pacotes do mesmo tamanho. Por exemplo, se o servidor estiver configurado para 64 megabytes e o cliente apenas para 16 megabytes, um pacote com mais de 16 megabytes ainda falhará.

Sintaxe de max_allowed_packet no MariaDB

O MariaDB permite ajustes temporários ou permanentes do valor de max_allowed_packet. A sintaxe varia conforme a finalidade:

Alterar max_allowed_packet temporariamente para uma sessão

Se quiser ajustar o valor apenas para uma conexão específica, use este comando:

SET SESSION max_allowed_packet = 67108864;

Esse comando aumenta o limite para 64 megabytes, mas apenas durante a sessão atual do cliente.

Alterar max_allowed_packet globalmente em tempo de execução (em todo o servidor)

Para ajustar max_allowed_packet em todo o servidor, defina o valor como variável global:

SET GLOBAL max_allowed_packet = 67108864;

Com isso, o MariaDB aplica o novo valor a todas as conexões futuras. Sessões já estabelecidas permanecem com a configuração antiga. Essa alteração vale apenas até o próximo reinício do servidor, sendo ideal para ajustes permanentes feitos durante a execução do sistema.

Casos de uso típicos de max_allowed_packet no MariaDB

Em muitos cenários, o valor padrão de max_allowed_packet se mostra rapidamente insuficiente. Isso acontece principalmente em processos que envolvem grandes volumes de dados ou operações automatizadas. A seguir, veja situações comuns em que o ajuste desse parâmetro é recomendado:

• Importação de grandes arquivos SQL: Ao restaurar backups ou dumps de banco de dados volumosos, o valor padrão pode não ser suficiente. Um limite maior evita interrupções.
• Manipulação de grandes BLOBs: Aplicações que armazenam arquivos binários (como PDFs, imagens ou arquivos ZIP) no banco geralmente precisam de um max_allowed_packet mais alto.
• INSERT com muitos valores: Processos de ETL ou carregamentos em massa que utilizam comandos únicos com muitos dados aumentam rapidamente o tamanho dos pacotes.
• Aplicações web com uploads ou formulários dinâmicos: Frameworks que geram automaticamente comandos SQL extensos podem atingir o limite de pacote sem um ajuste apropriado.

Evite configurar a max_allowed_packet no MariaDB com valores excessivamente altos, pois isso pode aumentar o consumo de memória e afetar a estabilidade do sistema. Na maioria das aplicações produtivas, valores entre 16M e 64M são suficientes. Valores maiores só são recomendados em casos especiais, como migrações de banco de dados.

Exemplo de uso de max_allowed_packet do MariaDB

Suponha que você opere uma aplicação web que permite que usuários enviem arquivos PDF de até 64 megabytes para o banco de dados. Um valor padrão definido de 4 megabytes não é suficiente para isso. Para que a aplicação funcione de forma confiável, ajuste esse valor.

Abra o arquivo /etc/mysql/my.cnf no Linux ou my.ini, se você estiver usando o Windows. Adicione a seguinte linha sob a seção [mysqld]:

max_allowed_packet=64M

Reinicie o servidor MariaDB:

sudo systemctl restart mariadb

Verifique o novo valor:

SHOW VARIABLES LIKE 'max_allowed_packet';

O resultado será semelhante a este:

+---------------------+----------+
| Variable_name       | Value    |
+---------------------+----------+
| max_allowed_packet  | 67108864 |
+---------------------+----------+

O aplicativo agora pode processar pacotes de dados de até 64 megabytes sem problemas. Isso evita erros, melhora a estabilidade e permite uma operação confiável mesmo com transferências de dados maiores.