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 co­mu­ni­ca­ção entre o banco de dados e a aplicação. Quem transmite arquivos grandes, muitos registros ou comandos SQL longos, pode ra­pi­da­mente 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 pa­râ­me­tros de con­fi­gu­ra­ção mais im­por­tan­tes no MariaDB e no MySQL quando se trata de garantir a es­ta­bi­li­dade e a con­fi­a­bi­li­dade das trans­fe­rên­cias 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 dis­tri­bui­ção ou a versão do MariaDB.

Um pacote de dados no MariaDB agrupa ins­tru­çõ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), ul­tra­pas­sar 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 re­qui­si­ções ex­ces­si­va­mente grandes, que podem so­bre­car­re­gar os recursos ou causar ins­ta­bi­li­dade. Ao mesmo tempo, permite que ad­mi­nis­tra­do­ras e ad­mi­nis­tra­do­res ajustem o limite conforme as ne­ces­si­da­des do ambiente.

É im­por­tante saber que tanto o servidor quanto o cliente possuem seus próprios valores para max_allowed_packet. A trans­fe­rên­cia só funciona se ambos aceitarem pacotes do mesmo tamanho. Por exemplo, se o servidor estiver con­fi­gu­rado 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 tem­po­rá­rios ou per­ma­nen­tes do valor de max_allowed_packet. A sintaxe varia conforme a fi­na­li­dade:

Alterar max_allowed_packet tem­po­ra­ri­a­mente para uma sessão

Se quiser ajustar o valor apenas para uma conexão es­pe­cí­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 glo­bal­mente 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á es­ta­be­le­ci­das per­ma­ne­cem com a con­fi­gu­ra­ção antiga. Essa alteração vale apenas até o próximo reinício do servidor, sendo ideal para ajustes per­ma­nen­tes 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 ra­pi­da­mente in­su­fi­ci­ente. Isso acontece prin­ci­pal­mente em processos que envolvem grandes volumes de dados ou operações au­to­ma­ti­za­das. A seguir, veja situações comuns em que o ajuste desse parâmetro é re­co­men­dado:

• Im­por­ta­ção de grandes arquivos SQL: Ao restaurar backups ou dumps de banco de dados volumosos, o valor padrão pode não ser su­fi­ci­ente. Um limite maior evita in­ter­rup­ções.
• Ma­ni­pu­la­ção de grandes BLOBs: Apli­ca­ções que armazenam arquivos binários (como PDFs, imagens ou arquivos ZIP) no banco ge­ral­mente precisam de um max_allowed_packet mais alto.
• INSERT com muitos valores: Processos de ETL ou car­re­ga­men­tos em massa que utilizam comandos únicos com muitos dados aumentam ra­pi­da­mente o tamanho dos pacotes.
• Apli­ca­ções web com uploads ou for­mu­lá­rios dinâmicos: Fra­meworks que geram au­to­ma­ti­ca­mente comandos SQL extensos podem atingir o limite de pacote sem um ajuste apro­pri­ado.

Evite con­fi­gu­rar a max_allowed_packet no MariaDB com valores ex­ces­si­va­mente altos, pois isso pode aumentar o consumo de memória e afetar a es­ta­bi­li­dade do sistema. Na maioria das apli­ca­ções pro­du­ti­vas, valores entre 16M e 64M são su­fi­ci­en­tes. Valores maiores só são re­co­men­da­dos 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 é su­fi­ci­ente 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á se­me­lhante a este:

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

O apli­ca­tivo agora pode processar pacotes de dados de até 64 megabytes sem problemas. Isso evita erros, melhora a es­ta­bi­li­dade e permite uma operação confiável mesmo com trans­fe­rên­cias de dados maiores.