insert_id

Quando você insere uma linha em uma tabela que possui uma chave primária AUTO_INCREMENT (ou SERIAL), o banco de dados gera o novo ID para você. A função mysqli_insert_id() permite ler esse valor gerado de volta no PHP imediatamente após a inserção, para que você possa usá-lo como chave estrangeira, retorná-lo em uma resposta de API ou redirecionar o usuário para o novo registro.

Este artigo aborda o que mysqli_insert_id() retorna, tanto a sintaxe procedural quanto a orientada a objetos, e as armadilhas comuns que fazem com que ela retorne o valor errado (ou 0).

O que mysqli_insert_id() retorna

mysqli_insert_id() retorna o ID gerado pela última query que inseriu em uma coluna AUTO_INCREMENT, para a conexão fornecida.

• Se a query anterior armazenou um valor em uma coluna AUTO_INCREMENT, ela retorna esse valor.
• Se a query anterior não foi um INSERT/UPDATE que tocou em uma coluna AUTO_INCREMENT, ela retorna 0.
• O valor tem escopo para a conexão atual, portanto inserções simultâneas de outros clientes nunca afetam o que você recebe de volta. Isso o torna seguro mesmo em um servidor movimentado.

Nota: o valor reflete o primeiro id gerado automaticamente pela instrução. Para uma inserção de linha única, esse é o id da linha; para uma inserção de múltiplas linhas, é o id da primeira linha.

Sintaxe

mysqli_insert_id() recebe a conexão MySQLi como único argumento:

int|string mysqli_insert_id(mysqli $mysql)

No PHP moderno (8.1+), se uma query falhar, o MySQLi lança uma mysqli_sql_exception em vez de retornar false, portanto os exemplos abaixo assumem que os erros serão exibidos como exceções.

Exemplo procedural

Este é o estilo mais comum que você verá em tutoriais e bases de código mais antigos:

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

mysqli_query(
    $mysqli,
    "INSERT INTO users (name, email) VALUES ('Ada', '[email protected]')"
);

$id = mysqli_insert_id($mysqli);

echo "Last inserted ID is: " . $id;

mysqli_close($mysqli);
?>

Aqui abrimos uma conexão com mysqli_connect(), executamos um INSERT com mysqli_query(), depois lemos o id gerado de volta com mysqli_insert_id() antes de fechar a conexão.

Exemplo orientado a objetos

A mesma lógica com a interface OOP, que a maioria dos códigos novos usa. O id gerado é exposto como a propriedade insert_id:

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

$mysqli->query(
    "INSERT INTO users (name, email) VALUES ('Ada', '[email protected]')"
);

echo "Last inserted ID is: " . $mysqli->insert_id;

$mysqli->close();
?>

Usando com prepared statements

Em aplicações reais, você deve inserir dados do usuário com um prepared statement para evitar injeção SQL. O id de inserção ainda está disponível depois, tanto a partir da conexão quanto do objeto statement:

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

$stmt = $mysqli->prepare("INSERT INTO users (name, email) VALUES (?, ?)");
$stmt->bind_param("ss", $name, $email);

$name  = "Grace";
$email = "[email protected]";
$stmt->execute();

echo "New user id: " . $stmt->insert_id; // same as $mysqli->insert_id here

$stmt->close();
$mysqli->close();
?>

Armadilhas comuns

• Leia imediatamente. O valor reflete apenas a última inserção na conexão. Se você executar outro INSERT (mesmo em uma tabela não relacionada) antes de ler, você obtém o id daquela inserção. Capture-o em uma variável logo após a inserção.
• Sem coluna AUTO_INCREMENT significa 0. Se a chave primária da sua tabela for definida manualmente, nada é gerado, portanto a função retorna 0.
• UPDATE e SELECT redefinem as expectativas. Um UPDATE bem-sucedido que não toca em uma coluna de auto-incremento, ou qualquer SELECT, não deixa nenhum id gerado novo, e a função retorna 0.
• Inserções de múltiplas linhas retornam o primeiro id. Após INSERT INTO t VALUES (...),(...),(...), você obtém o id da primeira linha inserida; as demais seguem sequencialmente.

Funções relacionadas

• mysqli_affected_rows() — quantas linhas a última query alterou.
• mysqli_query() — executa o INSERT cujo id você lê.
• Visão geral do PHP MySQLi — a extensão MySQLi completa.
• Inserir dados no MySQL — um guia completo de inserção.

Conclusão

mysqli_insert_id() é a maneira padrão de recuperar a chave primária gerada automaticamente logo após uma inserção. Leia-a imediatamente após o INSERT, lembre-se de que ela é por conexão (portanto é segura em ambiente concorrente), e espere 0 sempre que a última instrução não tiver gerado um valor de auto-incremento.

Prática