SQLite: códigos de erro

O código de resultado SQLITE_ABORT indica que uma operação foi abortada antes da conclusão, geralmente por solicitação de aplicação. Veja também: SQLITE_INTERRUPT. Se a função callback para sqlite3_exec() devolve não-zero, sqlite3_exec() retornará SQLITE_ABORT. Se uma operação ROLLBACK ocorrer na mesma conexão de banco de dados que uma leitura ou gravação pendente, então a leitura ou gravação pendente pode falhar com um erro SQLITE_ABORT ou SQLITE_ABORT_ROLLBACK. Além de ser um código de resultado, o valor SQLITE_ABORT também é usado como um modo de resolução de conflito devolvido da interface sqlite3_vtab_on_conflict().

O código de erro SQLITE_ABORT_ROLLBACK é um código de erro estendido para SQLITE_ABORT indicando que uma instrução SQL abortou porque a transação que estava ativa quando a instrução SQL começou foi reiniciada. As operações de gravação pendentes sempre falham com este erro quando ocorre um reinício. Um ROLLBACK fará com que uma operação de leitura pendente falhe apenas se o esquema foi alterado dentro da transação que está reiniciada.

O erro SQLITE_AUTH é devolvido quando o callback do autor indica que uma instrução SQL em preparação não está autorizada.

O código de erro SQLITE_AUTH_USER é um código de erro estendido para SQLITE_AUTH indicando que uma operação foi tentada em um banco de dados para o qual o usuário logado não tem autorização suficiente.

O código de resultado SQLITE_BUSY indica que o arquivo de base de dados não pôde ser escrito (ou, em alguns casos, lido) por causa da atividade concorrente por alguma outra conexão de base de dados, normalmente uma conexão de base de dados em um processo separado. Por exemplo, se o processo A estiver no meio de uma grande transação de escrita e ao mesmo tempo o processo B tentará iniciar uma nova transação de gravação, o processo B recuperará um resultado SQLITE_BUSY porque o SQLite só suporta um escritor de cada vez. O processo B precisará esperar pelo processo A para terminar a sua transação antes de iniciar uma nova transação. As interfaces sqlite3_busy_timeout() e sqlite3_busy_handler() e o pragma ocupado_timeout estão disponíveis para o processo B para ajudá-lo a lidar com erros SQLITE_BUSY. Um erro SQLITE_BUSY pode ocorrer em qualquer ponto em qualquer momento. uma transação: quando a transação é iniciada pela primeira vez, durante qualquer operação de gravação ou atualização, ou quando a transação se compromete. Para evitar encontrar erros SQLITE_BUSY no meio de uma transação, o aplicativo pode usar BEGIN IMMEDIATE em vez de apenas BEGIN para iniciar uma transação. O comando BEGIN IMMEDIATE pode ser ele próprio a devolver SQLITE_BUSY, mas se tiver sucesso, então SQLite garante que nenhuma operação subsequente no mesmo banco de dados através do próximo COMMIT irá devolver SQLITE_BUSY. Veja também: SQLITE_BUSY_RECOVERY e SQLITE_BUSY_SNAPSHOT. O código de resultado SQLITE_BUSY difere de SQLITE_LOCKED nesse SQLITE_BUSY indica um conflito com uma conexão de banco de dados separada, provavelmente num processo separado, enquanto SQLITE_L O BOCKED indica um conflito dentro da mesma conexão de banco de dados (ou às vezes uma conexão de banco de dados com um cache compartilhado).

O código de erro SQLITE_BUSY_RECOVERY é um código de erro estendido para SQLITE_BUSY que indica que uma operação não pôde continuar porque outro processo está ocupado recuperando um arquivo de banco de dados do modo WAL após um crash. O código de erro SQLITE_BUSY_RECOVERY ocorre apenas nos bancos de dados do modo WAL.

O código de erro SQLITE_BUSY_SNAPSHOT é um código de erro estendido para SQLITE_BUSY que ocorre em bases de dados de modo WAL quando uma conexão de banco de dados tenta promover uma transação de leitura em uma transação de gravação, mas descobre que outra conexão de banco de dados já foi escrita no banco de dados e assim invalidou leituras anteriores. O seguinte cenário ilustra como um erro SQLITE_BUSY_SNAPSHOT pode surgir:

O código de erro SQLITE_BUSY_TIMEOUT indica que um pedido de bloqueio de arquivos de assessoria Posix bloqueado na camada VFS falhou devido a um timeout. Os bloqueios de assessoria Posix bloqueados só estão disponíveis como uma extensão SQLite proprietária e, mesmo assim, só são suportados se o SQLite for compilado com a opção de compilação SQLITE_ENABLE_SETLK_TIMEOUT.

O código de resultado SQLITE_CANTOPEN indica que o SQLite não foi capaz de abrir um arquivo. O arquivo em questão pode ser um arquivo de base de dados primário ou um de vários arquivos de disco temporários.

O código de erro SQLITE_CANTOPEN_CONVPATH é um código de erro estendido para SQLITE_CANTOPEN usado apenas pelo Cygwin VFS e indicando que a chamada do sistema cygwin_conv_path() falhou ao tentar abrir um arquivo. Veja também: SQLITE_IOERR_CONVPATH

O código de resultado SQLITE_CANTOPEN_DIRTYWAL não é utilizado neste momento.

O código de erro SQLITE_CANTOPEN_FULLPATH é um código de erro estendido para SQLITE_CANTOPEN indicando que uma operação de arquivo aberto falhou porque o sistema operacional não conseguiu converter o nome do arquivo em um caminho completo.

O código de erro SQLITE_CANTOPEN_ISDIR é um código de erro estendido para SQLITE_CANTOPEN indicando que uma operação de arquivo aberto falhou porque o arquivo é realmente um diretório.

O código de erro SQLITE_CANTOPEN_NOTEMPDIR já não é usado.

O código de resultado SQLITE_CANTOpen_SYMLINK é devolvido pela interface sqlite3_open() e seus irmãos quando a bandeira SQLITE_OPEN_NOFOLLOW é usada e o arquivo de banco de dados é um link simbólico.

O código de erro SQLITE_CONSTRAINT significa que houve uma violação da constrição SQL ao tentar processar uma instrução SQL. Informações adicionais sobre a constrição falhada podem ser encontradas consultando a mensagem de erro (retornada via sqlite3_errmsg() ou sqlite3_errmsg16()) ou olhando para o código de erro estendido. O código SQLITE_CONSTRAINT também pode ser usado como o valor de retorno do método xBestIndex() de uma implementação de tabela virtual. Quando xBestIndex() retorna SQLITE_CONSTRAINT, que indica que a combinação particular de entradas enviadas ao xBestIndex() não pode resultar em um plano de consulta utilizável e não deve ser dada mais consideração.

O código de erro SQLITE_CONSTRAINT_CHECK é um código de erro estendido para SQLITE_CONSTRAINT indicando que uma constrição do CHECK falhou.

O código de erro SQLITE_CONSTRAINT_COMMITHOOK é um código de erro estendido para SQLITE_CONSTRAINT indicando que um callback commit hook retornou não-zero que fez com que a instrução SQL fosse rolada de volta.

O código de erro SQLITE_CONSTRAINT_DATATYPE é um código de erro estendido para SQLITE_CONSTRAINT indicando que uma inserção ou atualização tentou armazenar um valor incoerente com o tipo declarado da coluna em uma tabela definida como STRICT.

O código de erro SQLITE_CONSTRAINT_FOREIGNKEY é um código de erro estendido para SQLITE_CONSTRAINT indicando que uma constrição de chave estrangeira falhou.

O código de erro SQLITE_CONSTRAINT_FUNCTION não é atualmente usado pelo núcleo SQLite. No entanto, este código de erro está disponível para uso por funções de extensão.

O código de erro SQLITE_CONSTRAINT_NOTNULL é um código de erro estendido para SQLITE_CONSTRAINT indicando que uma constrição NOT NULL falhou.

O código de erro SQLITE_CONSTRAINT_PINNED é um código de erro estendido para SQLITE_CONSTRAINT indicando que um gatilho UPDATE tentou excluir a linha que estava sendo atualizada no meio da atualização.

O código de erro SQLITE_CONSTRAINT_PRIMARYKEY é um código de erro estendido para SQLITE_CONSTRAINT indicando que uma constrição PRIMARY KEY falhou.

O código de erro SQLITE_CONSTRAINT_ROWID é um código de erro estendido para SQLITE_CONSTRAINT indicando que um rowid não é único.

O código de erro SQLITE_CONSTRAINT_TRIGGER é um código de erro estendido para SQLITE_CONSTRAINT indicando que uma função RAISE dentro de um gatilho disparado, fazendo com que a instrução SQL aborte.

O código de erro SQLITE_CONSTRAINT_UNIQUE é um código de erro estendido para SQLITE_CONSTRAINT indicando que uma constrição UNIQUE falhou.

O código de erro SQLITE_CONSTRAINT_VTAB não é atualmente utilizado pelo núcleo SQLite. No entanto, este código de erro está disponível para uso por tabelas virtuais definidas por aplicativos.

O código de resultado SQLITE_CORRUPT indica que o arquivo de banco de dados foi corrompido. Veja como corromper seus arquivos de banco de dados para mais discussão sobre como a corrupção pode ocorrer.

O código de resultado SQLITE_CORRUPT_INDEX significa que o SQLite detectou ou estava ausente de um índice. Este é um caso especial do código de erro SQLITE_CORRUPT que sugere que o problema pode ser resolvido executando o comando REINDEX, assumindo que não existem outros problemas em outro lugar no arquivo de banco de dados.

O código de resultado SQLITE_CORRUPT_SEQUENCE significa que o esquema da tabela sqlite_sequence está corrompido. A tabela sqlite_sequence é usada para ajudar a implementar a funcionalidade AUTOINCREMENT. A tabela sqlite_sequence deve ter o seguinte formato: Se SQLite descobrir que a tabela sqlite_sequence tem qualquer outro formato, retorna o erro SQLITE_CORRUPT_SEQUENCE.

O código de erro SQLITE_CORRUPT_VTAB é um código de erro estendido para SQLITE_CORRUPT usado por tabelas virtuais. Uma tabela virtual pode devolver SQLITE_CORRUPT_VTAB para indicar que o conteúdo na tabela virtual está corrompido.

O código de resultado SQLITE_EMPTY não é utilizado atualmente.

O código de resultado SQLITE_ERROR é um código de erro genérico que é usado quando nenhum outro código de erro mais específico está disponível.

O código de resultado SQLITE_ERROR_MISSING_COLLSEQ significa que uma instrução SQL não pôde ser preparada porque uma sequência de agrupamento nomeada nessa instrução SQL não pôde ser localizada. Às vezes, quando este código de erro for encontrado, a rotina sqlite3_prepare_v2() converterá o erro em SQLITE_ERROR_RETRY e tentará novamente preparar a instrução SQL usando um plano de consulta diferente que não exige o uso da sequência de agrupamento desconhecida.

O SQLITE_ERROR_RETRY é usado internamente para provocar sqlite3_prepare_v2() (ou uma de suas rotinas de irmãos para criar instruções preparadas) para tentar novamente preparar uma declaração que falhou com um erro na tentativa anterior.

O código de resultado SQLITE_ERROR_SNAPSHOT pode ser devolvido quando se tenta iniciar uma transação de leitura em uma versão histórica do banco de dados usando a interface sqlite3_snapshot_open(). Se o instantâneo histórico não estiver mais disponível, então a transação de leitura falhará com o SQLITE_ERROR_SNAPSHOT. Este código de erro só é possível se o SQLite for compilado com -DSQLITE_ENAPSHOT.

O código de erro SQLITE_FORMAT não é atualmente utilizado pelo SQLite.

O código de resultado SQLITE_FULL indica que uma gravação não pôde ser completa porque o disco está cheio. Note que este erro pode ocorrer ao tentar escrever informações no arquivo principal do banco de dados, ou também pode ocorrer ao escrever em arquivos de disco temporários. Às vezes, as aplicações encontram este erro mesmo que haja uma abundância de espaço de disco primário porque o erro ocorre ao escrever em arquivos de disco temporários num sistema onde arquivos temporários são armazenados em uma partição separada com muito menos espaço do que o disco primário.

O código de resultado SQLITE_INTERNAL indica um mau funcionamento interno. Numa versão de trabalho do SQLite, uma aplicação nunca deverá ver este código de resultado. Se a aplicação encontrar este código de resultado, ele mostra que há um erro no motor do banco de dados. Este código de resultado pode ser causado por um erro no SQLite. No entanto, funções SQL definidas pela aplicação ou tabelas virtuais, ou VFSes, ou outras extensões também podem fazer com que este código de resultado seja devolvido, por isso o problema pode não ser culpa do núcleo SQLite.