Guia Completo da Função mysqli_stat em PHP

Ao trabalhar com bancos de dados MySQL em PHP, a extensão mysqli expõe diversas funções para comunicação com o servidor. mysqli_stat é a mais simples para verificações de saúde: ela consulta o servidor MySQL por uma única linha de status ao vivo — tempo de atividade, quantas consultas foram executadas, quantas threads estão abertas, e assim por diante.

Este guia explica o que mysqli_stat retorna, como chamá-la nos estilos procedural e orientado a objetos, como transformar sua saída bruta em números utilizáveis e os problemas comuns a observar.

mysqli_stat não é a função stat() do sistema de arquivos. Se você procura metadados de arquivo (tamanho, permissões, inode), consulte stat em PHP e fstat.

O que mysqli_stat faz

mysqli_stat é uma função embutida que retorna o status atual do servidor MySQL como uma string separada por espaços. É o equivalente PHP de executar mysqladmin status na linha de comando — um instantâneo rápido, não um dump completo de desempenho.

Um valor de retorno típico tem esta aparência:

Uptime: 272701  Threads: 1  Questions: 18  Slow queries: 0  Opens: 17  Flush tables: 1  Open tables: 5  Queries per second avg: 0.000

Os campos significam:

Sintaxe

// Procedural style
mysqli_stat(mysqli $connection): string|false

// Object-oriented style
$connection->stat(): string|false

Ela recebe o link de conexão retornado por mysqli_connect (procedural) ou um objeto mysqli (OOP), e retorna a string de status em caso de sucesso ou false em caso de falha (por exemplo, quando a conexão foi perdida).

Uso básico

Estilo procedural

Primeiro conecte, depois leia o status. Sempre trate um retorno false como erro.

<?php

$connection = mysqli_connect('localhost', 'username', 'password', 'mydatabase');

if (!$connection) {
    die('Connection failed: ' . mysqli_connect_error());
}

$status = mysqli_stat($connection);

if ($status === false) {
    echo 'Error: ' . mysqli_error($connection);
} else {
    echo $status;
}

Estilo orientado a objetos

A mesma chamada como método no objeto mysqli:

<?php

$mysqli = new mysqli('localhost', 'username', 'password', 'mydatabase');

if ($mysqli->connect_errno) {
    die('Connection failed: ' . $mysqli->connect_error);
}

echo $mysqli->stat();

Analisando o status em números

A string bruta é adequada para registros, mas para monitoramento você geralmente quer valores individuais. Cada campo é Nome: valor, separado por dois espaços, então você pode dividi-lo em um mapa de chave/valor:

<?php

function parseMysqlStat(string $status): array
{
    $result = [];

    foreach (explode('  ', $status) as $pair) {
        // Each pair looks like "Uptime: 272701"
        [$key, $value] = array_map('trim', explode(':', $pair, 2));
        $result[$key] = $value;
    }

    return $result;
}

$status = 'Uptime: 272701  Threads: 1  Questions: 18  Slow queries: 0  Opens: 17  Flush tables: 1  Open tables: 5  Queries per second avg: 0.000';

$stats = parseMysqlStat($status);

echo 'Uptime in seconds: ' . $stats['Uptime'] . PHP_EOL;
echo 'Active threads: ' . $stats['Threads'] . PHP_EOL;
echo 'Slow queries: ' . $stats['Slow queries'] . PHP_EOL;

Saída:

Uptime in seconds: 272701
Active threads: 1
Slow queries: 0

Agora $stats['Uptime'] e $stats['Slow queries'] são fáceis de usar como limites, alertas ou gráficos.

Casos de uso comuns

• Verificação de disponibilidade. Chame mysqli_stat em um endpoint de verificação de saúde; se retornar false, o banco de dados está inacessível.
• Monitoramento leve. Amostre Threads e Queries per second avg periodicamente para identificar picos de carga.
• Detectar consultas lentas. Um aumento no contador Slow queries é um sinal precoce de que um índice está faltando.

Problemas comuns

• Retorna uma string, não um array. var_dump no resultado mostra uma única string. Analise-a você mesmo (veja acima) antes de fazer operações matemáticas com os valores.
• Verifique false, não string vazia. Em uma conexão perdida a função retorna o boolean false. Use comparação estrita (=== false) para não confundi-lo com uma string vazia.
• É um instantâneo, não histórico. Valores como Questions são cumulativos desde a inicialização do servidor; para medir a taxa você precisa amostrar duas vezes e subtrair.
• Requer uma conexão válida. Se a conexão falhou, chamar mysqli_stat sobre ela vai gerar aviso ou erro. Sempre verifique a conexão primeiro — veja mysqli_connect_error.

Funções relacionadas

• mysqli_connect — abre a conexão que mysqli_stat precisa.
• mysqli_get_server_info — a string de versão do servidor.
• mysqli_ping — verifica (e opcionalmente reconecta) uma conexão.

Conclusão

mysqli_stat é uma ferramenta pequena, mas prática para monitorar um servidor MySQL a partir do PHP. Ela retorna uma única string de status com métricas de tempo de atividade, threads e consultas. Verifique o resultado contra false para detectar uma conexão inativa e analise a string em um mapa de chave/valor quando precisar dos números individuais para verificações de saúde ou painéis.

Prática