change_user

A função mysqli_change_user() altera o usuário — e opcionalmente o banco de dados padrão — de uma conexão MySQL já aberta, sem encerrar e reconectar. Esta página explica o que a função faz, seus parâmetros e valor de retorno, quando ela é realmente útil e os problemas que costumam surpreender quem a usa pela primeira vez.

O que mysqli_change_user() faz

mysqli_change_user() reautentica a conexão existente como um usuário MySQL diferente. A conexão TCP/socket permanece aberta; apenas a identidade (e, portanto, os privilégios) associada a ela é alterada. É um wrapper fino em torno do comando COM_CHANGE_USER do MySQL.

Está disponível tanto como função procedural quanto como método orientado a objetos:

// Procedural style
mysqli_change_user($mysqli, $username, $password, $database);

// Object-oriented style (used in the examples below)
$mysqli->change_user($username, $password, $database);

Parâmetros

Valor de retorno

Retorna true em caso de sucesso e false em caso de falha (por exemplo, credenciais incorretas ou privilégios insuficientes). Sempre verifique o valor de retorno antes de executar outras consultas.

Um exemplo básico

Você chama o método em um objeto MySQLi válido e passa o novo nome de usuário e senha. O argumento de banco de dados é opcional:

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

// Switch to a new user on the existing connection
if (!$mysqli->change_user("newusername", "newpassword", null)) {
    echo "Error changing user: " . $mysqli->error;
    exit();
}

// Run queries with the new user's privileges from here on
// ...

$mysqli->close();
?>

Abrimos uma conexão e, em seguida, chamamos change_user() para reautenticar como um usuário diferente na mesma conexão. Verificamos o valor de retorno para confirmar que a troca foi bem-sucedida antes de executar qualquer outra consulta.

Trocando o usuário e o banco de dados juntos

O terceiro argumento permite alterar o banco de dados padrão ao mesmo tempo que o usuário. Isso evita uma chamada separada a select_db():

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

// Switch to a different user and select a new default database
if (!$mysqli->change_user("newusername", "newpassword", "newdatabase")) {
    echo "Error changing user: " . $mysqli->error;
    exit();
}

// Queries now run as "newusername" against "newdatabase"
// ...

$mysqli->close();
?>

Se você omitir o argumento de banco de dados (ou passar null), a conexão ficará sem banco de dados padrão selecionado — observe que isso não é o mesmo que manter o anterior. Se precisar continuar trabalhando com o mesmo banco de dados, passe seu nome explicitamente.

Quando usar isso?

mysqli_change_user() é uma ferramenta de nicho. O uso mais comum no mundo real é o pool de conexões: uma conexão de longa duração em pool é entregue a diferentes requisições, e change_user() a redefine para um estado limpo para o próximo consumidor. Também é útil quando um único script precisa executar parte do trabalho com privilégios elevados e outra parte com uma conta restrita, sem pagar o custo de abrir uma segunda conexão.

Para a maioria das aplicações do dia a dia, você simplesmente abre uma conexão como o usuário correto e nunca chama essa função.

Armadilhas a observar

• O estado é reiniciado. change_user() redefine a conexão como se fosse recém-aberta: reverte a transação atual, desativa LOCK TABLES, libera tabelas temporárias e redefine variáveis de sessão (exceto o conjunto de caracteres, que é preservado). Não a chame no meio de uma transação importante.
• O banco de dados não é preservado. Como mencionado acima, omitir o terceiro argumento limpa o banco de dados padrão em vez de manter o atual.
• Os privilégios seguem o novo usuário. Após a troca, cada consulta é avaliada de acordo com as permissões do novo usuário. Uma consulta que funcionava antes pode agora falhar com um erro de permissão — isso é comportamento esperado, não um bug.
• Não confunda com a alteração dos dados de um usuário. Esta função altera qual conta MySQL a conexão usa. Ela não atualiza linhas em uma tabela users; para isso, você executa uma consulta UPDATE comum com mysqli_query().

Conclusão

mysqli_change_user() reautentica uma conexão MySQL aberta como um novo usuário, opcionalmente selecionando um novo banco de dados padrão, e retorna true/false para que você possa verificar a troca. Saber que ela redefine o estado da conexão e limpa o banco de dados padrão quando o terceiro argumento é omitido permite usá-la com segurança — na maioria das vezes para pool de conexões ou troca de privilégios em uma conexão compartilhada.

Para continuar explorando a extensão MySQLi, veja mysqli_connect() e mysqli_query().

Prática