> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL INSERT

> Como a instrução INSERT do MySQL adiciona uma linha, o que o servidor coloca nas colunas que você deixa de fora, e os 2 erros que um primeiro INSERT encontra com mais frequência.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

Todas as lições até aqui leram dados. `INSERT` os grava. Daqui em diante uma instrução
muda o que está na tabela, então o resto do tutorial trabalha em um banco de dados
próprio em vez de nos dados de exemplo.

## Um banco de dados de prática

O Sakila é a referência que todas as lições de leitura descrevem, então deixe-o em paz. Faça
um banco de dados pequeno ao lado dele, e rode isto de novo sempre que quiser
começar do zero.

```sql theme={null}
DROP DATABASE IF EXISTS sakila_practice;
CREATE DATABASE sakila_practice;
USE sakila_practice;

CREATE TABLE member (
  member_id  INT UNSIGNED NOT NULL AUTO_INCREMENT,
  first_name VARCHAR(45) NOT NULL,
  last_name  VARCHAR(45) NOT NULL,
  email      VARCHAR(100) DEFAULT NULL,
  joined     DATE NOT NULL,
  active     TINYINT NOT NULL DEFAULT 1,
  PRIMARY KEY (member_id),
  UNIQUE KEY uq_member_email (email)
);

INSERT INTO member (first_name, last_name, email, joined, active) VALUES
  ('Mary',     'Smith',    'mary.smith@example.com',       '2026-01-04', 1),
  ('Patricia', 'Johnson',  'patricia.johnson@example.com', '2026-02-11', 1),
  ('Linda',    'Williams', 'linda.williams@example.com',   '2026-03-02', 0);

CREATE TABLE rating_count (
  rating VARCHAR(10) NOT NULL,
  films  INT UNSIGNED NOT NULL,
  PRIMARY KEY (rating)
);

CREATE TABLE account (
  account_id INT UNSIGNED NOT NULL AUTO_INCREMENT,
  owner      VARCHAR(45) NOT NULL,
  balance    DECIMAL(10,2) NOT NULL,
  PRIMARY KEY (account_id)
);

INSERT INTO account (owner, balance) VALUES
  ('Mary Smith',       500.00),
  ('Patricia Johnson', 250.00);
```

Todas as lições desta seção partem desse estado. Abra o cliente com
`mysql -u root -p sakila_practice` antes de começar, e rode o bloco de novo
entre as lições.

## Como o INSERT funciona

```sql theme={null}
INSERT INTO TABLE_NAME (COLUMN_LIST)
VALUES (VALUE_LIST);
```

Substitua `TABLE_NAME` pela tabela em que você está gravando, `COLUMN_LIST` pelas
colunas que você está fornecendo, e `VALUE_LIST` por 1 valor para cada uma dessas
colunas, na mesma ordem.

O servidor adiciona uma linha e relata quantas gravou. Ele não imprime nenhuma linha de volta,
então um `SELECT` em seguida é como você vê o resultado.

## Exemplos

### Adicionar uma linha

```sql theme={null}
INSERT INTO member (first_name, last_name, email, joined)
VALUES ('Jennifer', 'Davis', 'jennifer.davis@example.com', '2026-03-18');
```

```text theme={null}
Query OK, 1 row affected (0.00 sec)
```

`Query OK` e `1 row affected` é o relatório inteiro. Peça a tabela para ver
o que entrou.

```sql theme={null}
SELECT * FROM member;
```

```text theme={null}
+-----------+------------+-----------+------------------------------+------------+--------+
| member_id | first_name | last_name | email                        | joined     | active |
+-----------+------------+-----------+------------------------------+------------+--------+
|         1 | Mary       | Smith     | mary.smith@example.com       | 2026-01-04 |      1 |
|         2 | Patricia   | Johnson   | patricia.johnson@example.com | 2026-02-11 |      1 |
|         3 | Linda      | Williams  | linda.williams@example.com   | 2026-03-02 |      0 |
|         4 | Jennifer   | Davis     | jennifer.davis@example.com   | 2026-03-18 |      1 |
+-----------+------------+-----------+------------------------------+------------+--------+
4 rows in set (0.00 sec)
```

A instrução nomeou 4 colunas e a linha tem 6. `member_id` se incrementou sozinho
porque a coluna é `AUTO_INCREMENT`, e `active` recebeu o `DEFAULT 1` que a
tabela declara.

### Ler de volta o id que o servidor escolheu

Um valor `AUTO_INCREMENT` é decidido durante o insert, então o único jeito de
descobri-lo é perguntar. Pergunte na mesma sessão que fez o insert.

```sql theme={null}
INSERT INTO member (first_name, last_name, email, joined)
VALUES ('Barbara', 'Jones', 'barbara.jones@example.com', '2026-03-20');
SELECT LAST_INSERT_ID() AS new_id;
```

```text theme={null}
Query OK, 1 row affected (0.00 sec)

+--------+
| new_id |
+--------+
|      5 |
+--------+
1 row in set (0.00 sec)
```

`LAST_INSERT_ID()` responde só pela sua conexão, então um servidor ocupado não pode
entregar a você o id de outra sessão. Uma conexão nova não tem resposta para dar e
retorna 0.

## ERROR 1062 significa que a linha já está lá

Uma coluna `UNIQUE` recusa uma segunda linha que carregue um valor que ela já tem. Aqui
`email` é único, e o endereço de Mary Smith já está em uso.

```sql theme={null}
INSERT INTO member (first_name, last_name, email, joined)
VALUES ('Mary', 'Smith', 'mary.smith@example.com', '2026-05-01');
```

```text theme={null}
ERROR 1062 (23000): Duplicate entry 'mary.smith@example.com' for key 'member.uq_member_email'
```

A mensagem nomeia o valor e o índice que o rejeitou, o que normalmente basta
para distinguir uma duplicata de verdade de uma coluna que você pretendia tornar única e
não tornou. [Upsert](https://villagesql.com/docs/pt-BR/tutorial/upsert.md) é a instrução que espera isso e
atualiza a linha existente em vez disso.

## ERROR 1364 significa que uma coluna obrigatória está faltando

Deixe de fora uma coluna que é `NOT NULL` e não tem valor padrão, e o servidor não tem
nada para gravar.

```sql theme={null}
INSERT INTO member (first_name) VALUES ('Sam');
```

```text theme={null}
ERROR 1364 (HY000): Field 'last_name' doesn't have a default value
```

Ele nomeia 1 coluna por vez, então uma instrução em que faltam 3 delas leva 3 tentativas.
Leia a tabela com `DESCRIBE member;` e forneça tudo que estiver marcado como `NO` em
`Null` e não tiver valor padrão.

Uma coluna que aceita NULL é um caso diferente. Deixe-a de fora e a linha recebe
NULL.

```sql theme={null}
INSERT INTO member (first_name, last_name, joined)
VALUES ('George', 'Miller', '2026-04-01');
```

```text theme={null}
Query OK, 1 row affected (0.00 sec)
```

## Uma chave duplicada ainda consome um id

Peça os ids agora e o 6 está faltando.

```sql theme={null}
SELECT member_id, first_name, last_name, email, active FROM member;
```

```text theme={null}
+-----------+------------+-----------+------------------------------+--------+
| member_id | first_name | last_name | email                        | active |
+-----------+------------+-----------+------------------------------+--------+
|         1 | Mary       | Smith     | mary.smith@example.com       |      1 |
|         2 | Patricia   | Johnson   | patricia.johnson@example.com |      1 |
|         3 | Linda      | Williams  | linda.williams@example.com   |      0 |
|         4 | Jennifer   | Davis     | jennifer.davis@example.com   |      1 |
|         5 | Barbara    | Jones     | barbara.jones@example.com    |      1 |
|         7 | George     | Miller    | NULL                         |      1 |
+-----------+------------+-----------+------------------------------+--------+
6 rows in set (0.00 sec)
```

A tentativa com chave duplicada pegou o 6 antes de falhar, e o InnoDB não devolve
o número. A tentativa com `ERROR 1364` não pegou nada, porque foi recusada
antes de chegar à tabela. Lacunas como essa são normais e não significam que algo foi
perdido. Trate a coluna como um identificador, nunca como uma contagem das linhas ou como uma
promessa de que os números correm sem interrupção.

## Resumo

* Escreva `INSERT INTO table (columns) VALUES (values)` para adicionar uma linha.
* Espere uma contagem de linhas gravadas em vez da linha em si.
* Deixe de fora uma coluna com valor padrão ou `AUTO_INCREMENT` e deixe o servidor preenchê-la.
* Leia `ERROR 1062` como um valor que uma coluna `UNIQUE` já tem.
* Leia `ERROR 1364` como uma coluna obrigatória que você não forneceu.
* Espere lacunas em uma coluna `AUTO_INCREMENT`, porque uma falha por chave duplicada fica com o número dela.

## Veja também

* [Inserir várias linhas](https://villagesql.com/docs/pt-BR/tutorial/insert-multiple-rows.md) — 1 instrução, muitas linhas
* [INSERT SELECT](https://villagesql.com/docs/pt-BR/tutorial/insert-select.md) — linhas de uma consulta em vez de digitadas
* [Upsert](https://villagesql.com/docs/pt-BR/tutorial/upsert.md) — inserir, ou atualizar a linha que está no caminho
* [UPDATE](https://villagesql.com/docs/pt-BR/tutorial/update.md) — mudando uma linha que já está lá


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.