// Referência de erro do SQLite

SQLITE_CONSTRAINT_FOREIGNKEY: falha na restrição FOREIGN KEY

Uma escrita deixaria uma linha filha apontando para um pai que não existe, ou excluiria um pai que ainda tem filhos. As chaves estrangeiras devem ser ativadas por conexão.

Código de resultado
SQLITE_CONSTRAINT_FOREIGNKEY
Nome
787
Categoria
Códigos de resultado estendidos
Mensagem de erro
FOREIGN KEY constraint failed

O que significa

SQLITE_CONSTRAINT_FOREIGNKEY (787) significa que uma verificação de chave estrangeira falhou. O SQLite aplica restrições de chave estrangeira somente em conexões que executam PRAGMA foreign_keys = ON; ela está desativada por padrão para compatibilidade com versões anteriores, o que explica por que o mesmo insert pode ter sucesso em uma ferramenta e falhar em outra.

A mensagem não diz qual chave falhou. PRAGMA foreign_key_check lista cada linha que viola.

Causas comuns

  • Inserindo uma linha filha cujo id do pai não existe.
  • Excluindo ou atualizando uma linha pai que ainda tem filhos, sem ON DELETE CASCADE ou SET NULL.
  • Carregar as tabelas na ordem errada: filhos antes dos pais.
  • Restrições adiadas (DEFERRABLE INITIALLY DEFERRED) falhando em COMMIT.

Como corrigir

  1. Encontre as linhas que quebram uma chave estrangeira.

    PRAGMA foreign_key_check;
    PRAGMA foreign_key_list(orders);
  2. Insira os pais antes dos filhos, ou exclua os filhos antes dos pais.

  3. Para cargas em massa, adie a verificação para o final da transação.

    BEGIN;
    PRAGMA defer_foreign_keys = ON;
    -- load tables in any order
    COMMIT;
  4. Se excluir um pai deve remover seus filhos, declare a ação na chave estrangeira.

    CREATE TABLE orders (
        id          INTEGER PRIMARY KEY,
        customer_id INTEGER NOT NULL REFERENCES customers(id) ON DELETE CASCADE
    );

Reproduza com segurança

PRAGMA foreign_keys = ON;
CREATE TABLE p (id INTEGER PRIMARY KEY);
CREATE TABLE c (pid INTEGER REFERENCES p(id));
INSERT INTO c VALUES (1);  -- Runtime error: FOREIGN KEY constraint failed (19)

Perguntas

Por que as chaves estrangeiras não são aplicadas no meu banco de dados SQLite?

A aplicação é por conexão e desativada por padrão. Cada conexão deve executar PRAGMA foreign_keys = ON, e isso não pode ser alterado dentro de uma transação.

Erros relacionados

Mais erros de códigos de resultado estendidos

O código e o texto da mensagem são de Documentação de códigos de resultado e erro do SQLite. Veja toda a Lista de erros do SQLite ou pesquise todos os erros do banco de dados.

// menos erros, correções mais rápidas

Trabalhe com SQLite no SQLly

Um cliente SQL nativo para macOS, Windows e Linux com IntelliSense que conhece o esquema, proteções para instruções arriscadas e mensagens de erro claras, para o SQLite e os outros bancos de dados que você usa.