Compartilhamento de tecnologia

한어Русский языкEnglishFrançaisIndonesianSanskrit日本語DeutschPortuguêsΕλληνικάespañolItalianoSuomalainenLatina

sqlite3 — Interface DB-API 2.0 para bancos de dados SQLite — documentação do Python 3.12.4

sqlite3— Interface DB-API 2.0 para bancos de dados SQLite
sqlite3 — Interface DB-API 2.0 para bancos de dados SQLite

Código fonte: Biblioteca/sqlite3/    Localização do código-fonte：Lib/sqlite3/

SQLite é uma biblioteca C que fornece um banco de dados leve baseado em disco que não requer um processo de servidor separado e permite acessar o banco de dados usando uma variante não padrão da linguagem de consulta SQL. Alguns aplicativos podem usar SQLite para armazenamento interno de dados. Também é possível prototipar um aplicativo usando SQLite e então portar o código para um banco de dados maior, como PostgreSQL ou Oracle.
SQLite é uma biblioteca de linguagem C que fornece um banco de dados leve baseado em disco que não requer um processo de servidor separado e permite que o banco de dados seja acessado usando uma variante não padrão da linguagem de consulta SQL. Alguns aplicativos podem usar SQLite para armazenamento interno de dados. Além disso, você pode usar SQLite para prototipar um aplicativo e depois migrar o código para um grande banco de dados como PostgreSQL ou Oracle.

Osqlite3módulo foi escrito por Gerhard Häring. Ele fornece uma interface SQL compatível com a especificação DB-API 2.0 descrita porPEP 249e requer SQLite 3.7.15 ou mais recente.
módulo sqlite3 Escrito por Gerhard Häring. Ele fornece uma interface SQL que está em conformidade com a especificação DB-API 2.0 descrita pelo PEP 249 e requer SQLite versão 3.7.15 ou superior.

Este documento inclui quatro seções principais: Este documento inclui principalmente as seguintes quatro seções principais

• Tutorialensina como usar osqlite3módulo.TutorialParte ensina como usar o módulo sqlite3.

• Referênciadescreve as classes e funções que este módulo define.
  referir-seseção descreve as classes e funções definidas por este módulo.

• Guias de instruçõesdetalha como lidar com tarefas específicas.
  Guia de operaçãoAs seções detalham como lidar com tarefas específicas.

• Explicaçãofornece informações aprofundadas sobre controle de transações.
  explicarEsta seção fornece uma introdução detalhada ao conhecimento prévio do controle de transações.

Veja também

https://www.sqlite.org

A página da web do SQLite; a documentação descreve a sintaxe e os tipos de dados disponíveis para o dialeto SQL suportado.
A página web do SQLite; sua documentação descreve a sintaxe dos dialetos SQL suportados e os tipos de dados disponíveis.

Tutorial de SQLTutorial SQL

Tutorial, referência e exemplos para aprender sintaxe SQL.
Tutoriais, referências e exemplos para aprender a sintaxe SQL.

PEP 249- Especificação de API de banco de dados 2.0 PEP 249 - Especificação de API de banco de dados 2.0

PEP escrito por Marc-André Lemburg PEP escrito por Marc-André Lemburg.

TutorialTutorial

Neste tutorial, você criará um banco de dados de Filmes do Monty Python usando básicosqlite3funcionalidade. Ele pressupõe uma compreensão fundamental dos conceitos de banco de dados, incluindocursoresetransações.
Neste tutorial, você usará a funcionalidade básica do sqlite3 para criar um banco de dados sobre filmes do Monty Python. Este tutorial pressupõe que você tenha conhecimento básico de conceitos de banco de dados, incluindo cursores e transações.

Primeiro, precisamos criar um novo banco de dados e abrir uma conexão de banco de dados para permitirsqlite3para trabalhar com isso. Liguesqlite3.conectar()para criar uma conexão com o banco de dadostutorial.dbno diretório de trabalho atual, criando-o implicitamente se não existir:
Primeiro, precisamos criar um novo banco de dados e abrir uma conexão com o banco de dados para que o sqlite3 possa interagir com ele. Chame sqlite3.connect() para criar uma conexão com o banco de dados tutorial.db no diretório de trabalho atual, criando-o de forma implícita e automática se o banco de dados não existir:

import sqlite3
con = sqlite3.connect("tutorial.db")

O retornadoConexãoobjetoconrepresenta a conexão com o banco de dados no disco.
O objeto Connection retornado (denominado con neste caso) representa a conexão com o banco de dados no disco.

A fim de executar instruções SQL ebuscar resultados de consultas SQL, precisaremos usar um cursor de banco de dados. Chamarcon.cursor()para criar oCursor:
Para executar instruções SQL e obter resultados de consultas SQL, precisamos usar cursores de banco de dados. Chame con.cursor() para criar um Cursor:

cur = con.cursor()

Agora que temos uma conexão de banco de dados e um cursor, podemos criar uma tabela de banco de dadosmoviecom colunas para título, ano de lançamento e pontuação de revisão. Para simplificar, podemos usar apenas nomes de colunas na declaração da tabela – graças aodigitação flexívelrecurso do SQLite, especificar os tipos de dados é opcional. Execute oCREATE TABLEdeclaração por chamadacur.execute(...):
Agora que temos a conexão com o banco de dados e o cursor, podemos criar uma tabela de banco de dados chamada filme com colunas como título, ano de lançamento e pontuação da revisão. Para simplificar as coisas, podemos usar os nomes das colunas diretamente na declaração da tabela - especificar o tipo de dados é opcional devido ao recurso de digitação flexível do SQLite. Execute a instrução CREATE TABLE chamando cur.execute(...):

cur.execute("CREATE TABLE movie(title, year, score)")

Podemos verificar se a nova tabela foi criada consultando osqlite_mastertabela incorporada ao SQLite, que agora deve conter uma entrada para omoviedefinição de tabela (verA Tabela de Esquemapara detalhes). Execute essa consulta chamandocur.execute(...), atribua o resultado ares, e ligueres.fetchone()para buscar a linha resultante:
Podemos verificar se a nova tabela foi criada consultando a tabela sqlite_master integrada do SQLite, que agora deve conter entradas para a definição da tabela do filme (consulte a tabela do esquema para obter detalhes). Execute a consulta chamando cur.execute(...), atribua os resultados a res e chame res.fetchone() para obter as linhas de resultados:

>>>

>>> res = cur.execute("SELECT name FROM sqlite_master")
>>> res.fetchone()
('movie',)

Podemos ver que a tabela foi criada, pois a consulta retorna umtuplacontendo o nome da tabela. Se consultarmossqlite_masterpara uma mesa inexistentespam, res.fetchone()retornaráNone:
Podemos ver que a tabela foi criada com sucesso porque a consulta retornou uma tupla contendo o nome da tabela. Se consultarmos sqlite_master para uma tabela inexistente (como spam), res.fetchone() retornará None.

>>>

>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() is None
True

Agora, adicione duas linhas de dados fornecidos como literais SQL executando umINSERTdeclaração, mais uma vez chamandocur.execute(...):
Agora, adicione duas linhas de dados, fornecidas como literais SQL, executando uma instrução INSERT (chamando cur.execute(...) novamente):

cur.execute("""
    INSERT INTO movie VALUES
        ('Monty Python and the Holy Grail', 1975, 8.2),
        ('And Now for Something Completely Different', 1971, 7.5)
""")

OINSERTdeclaração abre implicitamente uma transação, que precisa ser confirmada antes que as alterações sejam salvas no banco de dados (consulteControle de transaçõespara detalhes). Chamarcon.commit()no objeto de conexão para confirmar a transação:
A instrução INSERT inicia implícita e automaticamente uma transação que precisa ser confirmada antes que as alterações sejam salvas no banco de dados (consulte Controle de Transações para obter detalhes). Chame con.commit() no objeto de conexão para confirmar a transação:

con.commit()

Podemos verificar se os dados foram inseridos corretamente executando umSELECTconsulta. Use o agora familiarcur.execute(...)para atribuir o resultado ares, e ligueres.buscar()para retornar todas as linhas resultantes:
Podemos verificar se os dados foram inseridos corretamente executando uma consulta SELECT. Atribua os resultados a res usando o agora familiar cur.execute(...) e chame res.fetchall() para retornar todas as linhas de resultados:

>>>

>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]

O resultado é umlistaaaaaaaade doistuples, um por linha, cada um contendo a linhascorevalor.
O resultado é uma lista de duas tuplas, uma para cada linha, e cada tupla contendo o valor da pontuação dessa linha.

Agora, insira mais três linhas chamandocur.executemany(...):
Agora, insira mais três linhas de dados chamando cur.executemany(...):

data = [
    ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
    ("Monty Python's The Meaning of Life", 1983, 7.5),
    ("Monty Python's Life of Brian", 1979, 8.0),
]
cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
con.commit()  # Remember to commit the transaction after executing INSERT.

Notar que?Os marcadores de posição são usados ​​para vinculardatapara a consulta. Sempre use marcadores de posição em vez deformatação de stringpara vincular valores Python a instruções SQL, para evitarAtaques de injeção de SQL(verComo usar marcadores de posição para vincular valores em consultas SQLpara mais detalhes).
Observe que o espaço reservado ? é usado para vincular os dados à consulta. Sempre use espaços reservados em vez de formatação de string para vincular valores Python a instruções SQL para evitar ataques de injeção de SQL (consulte "Como vincular valores usando espaços reservados em consultas SQL" para obter mais detalhes).

Podemos verificar se as novas linhas foram inseridas executando umSELECTconsulta, desta vez iterando sobre os resultados da consulta:
Podemos verificar se a nova linha foi inserida executando uma consulta SELECT, desta vez iremos iterar sobre os resultados da consulta:

>>>

>>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
...     print(row)
(1971, 'And Now for Something Completely Different')
(1975, 'Monty Python and the Holy Grail')
(1979, "Monty Python's Life of Brian")
(1982, 'Monty Python Live at the Hollywood Bowl')
(1983, "Monty Python's The Meaning of Life")

Cada linha é um item de doistuplade(year, title), correspondendo às colunas selecionadas na consulta.
Cada linha é uma tupla contendo dois elementos (ano, título), que corresponde à coluna selecionada na consulta.

Por fim, verifique se o banco de dados foi gravado no disco chamandocon.fechar()para fechar a conexão existente, abrir uma nova, criar um novo cursor e, em seguida, consultar o banco de dados:
Finalmente, ligandocon.close() para fechar a conexão de banco de dados existente e garantir que o banco de dados foi gravado no disco. Em seguida, abra uma nova conexão, crie um novo cursor e consulte o banco de dados para verificar se os dados foram gravados com sucesso.

>>>

>>> con.close()
>>> new_con = sqlite3.connect("tutorial.db")
>>> new_cur = new_con.cursor()
>>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
>>> title, year = res.fetchone()
>>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
>>> new_con.close()

Agora você criou um banco de dados SQLite usando osqlite3módulo, inseriu dados e recuperou valores dele de várias maneiras.
você já usousqlite3 O módulo cria um banco de dados SQLite e insere e recupera dados dele de diversas maneiras [Recuperar? 】O valor que.

Veja tambémVeja também

• Guias de instruçõespara leitura adicional: Como vincular valores usando espaços reservados em consultas SQL:

  • Como usar marcadores de posição para vincular valores em consultas SQL
    Como vincular valores usando espaços reservados em consultas SQL:

  • Como adaptar tipos Python personalizados aos valores SQLite
    Como adaptar um tipo Python personalizado a um valor SQLite:

  • Como converter valores SQLite em tipos Python personalizados
    Como converter o valor SQLite para o tipo Python personalizado:

  • Como usar o gerenciador de contexto de conexão
    Como usar o gerenciador de contexto de conexão:

  • Como criar e usar fábricas de linhas
    Como criar e usar fábricas de linhas:

• Explicaçãopara obter informações detalhadas sobre o controle de transações.
  Uma explicação detalhada do controle de transações:

ReferênciaDescrição do parâmetro：

Funções do módulo

sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)

Abrir uma conexão com um banco de dados SQLite Esta função é usada para abrir uma conexão com um banco de dados SQLite.

Parâmetros:

• base de dados (objeto semelhante a um caminho) – O caminho para o arquivo de banco de dados a ser aberto. Você pode passar":memory:"para criar umBanco de dados SQLite existente apenas na memóriae abra uma conexão com ele.database (path-like object) 
  banco de dados (objeto semelhante a um caminho) — Este é o caminho para o arquivo de banco de dados a ser aberto.Você pode passar":memory:"para criar um banco de dados SQLite na memória e abrir um .database (objeto semelhante a um caminho) conectado a ele.

• tempo esgotado (flutuador) – Quantos segundos a conexão deve esperar antes de gerar umErro operacionalquando uma tabela é bloqueada. Se outra conexão abrir uma transação para modificar uma tabela, essa tabela será bloqueada até que a transação seja confirmada. Padrão cinco segundos.timeout (float) — A conexão está sendo lançada quando a mesa está bloqueadaOperationalError Quantos segundos devem ser esperados antes. Se outra conexão abrir uma transação para modificar a tabela, a tabela será bloqueada até que a transação seja confirmada. O valor padrão é cinco segundos.

• detectar_tipos (Inteiro) – Controlar se e como tipos de dados nãosuportado nativamente pelo SQLitesão procurados para serem convertidos em tipos Python, usando os conversores registrados comregistrar_conversor(). Defina-o para qualquer combinação (usando|, bit a bit ou) deANALISAR_DECLTYPESeANALISAR_NOMES_DE_COLUNASpara habilitar isso. Nomes de colunas tem precedência sobretipos declarados se ambos os sinalizadores estiverem definidos. Os tipos não podem ser detectados para campos gerados (por exemplomax(data)), mesmo quando odetectar_tiposparâmetro está definido;strserá retornado em vez disso. Por padrão (0), a detecção de tipo está desabilitada.
  detect_types (int)— Controla se e como os tipos de dados que o SQLite não suporta nativamente são encontrados para usoregister_converter() Os conversores registrados os convertem em tipos Python.configure-o paraPARSE_DECLTYPESePARSE_COLNAMESqualquer combinação de (usando bit a bit ou| ) para ativar esse recurso.Se ambos os sinalizadores estiverem definidos, entãoLista terá precedência sobredeclaração tipo.Para regiões geradas, estes tipos não podem ser detectados (por exemplomax(data)), mesmo se definidodetect_typesparâmetros; em vez disso, ele retornarástr tipo. Por padrão (0), a detecção de tipo está desabilitada.

Insira aqui
Neste parágrafo em inglês, quem é o sujeito de “são admirados”?
Neste parágrafo em inglês, o assunto "são procurados" são aqueles "tipos de dados não suportados nativamente pelo SQLite (tipos de dados não suportados nativamente pelo SQLite)".Esta frase significa que usandoregister_converter() Conversores registrados para encontrar e converter tipos de dados não suportados nativamente pelo SQLite para tipos Python. Portanto, assuntos são aqueles tipos de dados específicos que precisam ser encontrados e convertidos.

• nível_de_isolamento (str | Nenhum) – Controle o comportamento de manipulação de transações legadas. VejaConexão.nível_isolamentoeControle de transações por meio do atributo isolation_levelpara mais informações. Pode ser"DEFERRED"(padrão),"EXCLUSIVE"ou"IMMEDIATE"; ouNonepara desabilitar a abertura de transações implicitamente. Não tem efeito a menos queConexão.autocommitestá configurado paraCONTROLE_DE_TRANSAÇÃO_LEGADO(o padrão).
  isolation_level(Sequência | Nenhum) – Controlar o comportamento de processamento de transações legado.Para mais informações, vejaConnection.isolation_levele "passarisolation_levelTransação de controle de propriedade". Pode ser"DEFERRED"(valor padrão),"EXCLUSIVE"ou"IMMEDIATE";ou definido comoNone para desabilitar a abertura implícita de transações implicitamente.A menos queConnection.autocommitDefinir comoLEGACY_TRANSACTION_CONTROL(padrão), caso contrário esta configuração não terá efeito.

• verificar_mesmo_tópico (bool) - SeTrue(padrão),Erro de programaçãoserá levantado se a conexão com o banco de dados for usada por um thread diferente daquele que o criou. SeFalse, a conexão pode ser acessada em vários threads; operações de gravação podem precisar ser serializadas pelo usuário para evitar corrupção de dados. Vejasegurança de roscaPara maiores informações.
  check_same_thread(Valor booleano) – Se definido paraTrue(padrão), será gerado quando a conexão com o banco de dados for usada por um thread diferente do thread que a criou.ProgrammingError anormal.Se definido paraFalse , vários threads têm permissão para acessar a conexão, mas os usuários podem precisar serializar (continuamente) as operações de gravação para evitar corrupção de dados;Para mais informações, vejathreadsafetyinstrução de.

• fábrica (Conexão) – Uma subclasse personalizada deConexãopara criar a conexão com, se não o padrãoConexãoaula.
  factory(Conexão) – Se não estiver usando o padrãoConnectionclasse, especifique um personalizadoConnection Subclasse para criar a conexão. Este parâmetro permite personalizar o comportamento da conexão com o banco de dados de acordo com necessidades ou extensões específicas.

• instruções em cache (Inteiro) – O número de afirmações quesqlite3deve armazenar em cache internamente para esta conexão, para evitar sobrecarga de análise. Por padrão, 128 instruções.
  cached_statements(int) – sqlite3 O número de instruções que devem ser armazenadas em cache internamente para esta conexão para evitar sobrecarga de análise. Por padrão, 128 instruções são armazenadas em cache. Este parâmetro permite ajustar o tamanho do cache para otimizar o desempenho ou o uso de memória.

• você (bool) – Se definido comoTrue, base de dadosé interpretado como um URI com um caminho de arquivo e uma string de consulta opcional. A parte do esquemadeveser"file:", e o caminho pode ser relativo ou absoluto. A string de consulta permite passar parâmetros para o SQLite, habilitando váriosComo trabalhar com URIs do SQLite.
  uri(bool) – Se definido paraTrue,masdatabase Interpretado como um URI (Uniform Resource Identifier) ​​com um caminho de arquivo e uma string de consulta opcional. A parte do esquema do URIdeve é "arquivo:", o caminho pode ser relativo ou absoluto. As strings de consulta permitem que parâmetros sejam passados ​​para o SQLite, permitindo várias maneiras de trabalhar com URIs do SQLite. Isso permite opções de conexão de banco de dados mais complexas, como definir o modo somente leitura, especificar o tamanho do cache, etc.

• confirmação automática (bool) - Ao controlePEP 249comportamento de manipulação de transações. VejaConexão.autocommiteControle de transações via atributo autocommitPara maiores informações.confirmação automáticaatualmente o padrão éCONTROLE_DE_TRANSAÇÃO_LEGADO. O padrão mudará paraFalseem uma versão futura do Python.
  autocommit(bool) – Controlar o comportamento de processamento de transações em conformidade com PEP 249.Para mais informações, vejaConnection.autocommit e "Controlando transações através do atributo autocommit." Atualmente,autocommitO valor padrão é definido comoLEGACY_TRANSACTION_CONTROL , o que significa que segue o comportamento legado de controle de transação da especificação da API do banco de dados Python (PEP 249).Entretanto, em uma versão futura do Python, o padrão mudará paraFalse, o que significa que as transações não são confirmadas automaticamente por padrão e exigem que o usuário controle explicitamente o início e o fim da transação.

Observe,*Os parâmetros são usados ​​nas definições de funções como separadores entre argumentos posicionais e de palavras-chave, o que significaautocommitTodos os parâmetros depois disso devem ser parâmetros de palavras-chave.

Tipo de retorno:Tipo de retorno： 

Conexão

Levanta umevento de auditoria sqlite3.connectcom argumentodatabase.
sqlite3.connect: Ao usardatabaseParâmetros lançados ao conectar-se ao banco de dados.

Levanta umevento de auditoria sqlite3.connect/handlecom argumentoconnection_handle.
sqlite3.connect/handle: Quando o identificador de conexão (connection_handle) é lançado quando é criado.

Alterado na versão 3.4: Adicionado ovocêparâmetro.
Na versão 3.4: adicionadouriParâmetro que permite especificar o arquivo do banco de dados utilizando o formato URI.

Alterado na versão 3.7:base de dadosagora também pode ser umobjeto semelhante a um caminho, não apenas uma string.
Na versão 3.7:databaseOs parâmetros agora podem ser um objeto semelhante a um caminho em vez de apenas strings.

Alterado na versão 3.10: Adicionado osqlite3.connect/handleevento de auditoria.
Na versão 3.10: adicionadosqlite3.connect/handleEvento de auditoria, que é acionado quando o identificador de conexão é criado.

Alterado na versão 3.12: Adicionado oconfirmação automáticaparâmetro.
Na versão 3.12: adicionadoautocommitParâmetros que permitem um controle mais preciso sobre o comportamento de confirmação automática das transações.

sqlite3.declaração_completa(declaração)

RetornarTruese a cordadeclaraçãoparece conter uma ou mais instruções SQL completas. Nenhuma verificação sintática ou análise sintática de qualquer tipo é realizada, além de verificar se não há literais de string não fechados e se a instrução é encerrada por um ponto e vírgula.
se stringstatementparece conter uma ou mais instruções SQL completas e, em seguida, retorneTrue . Nenhuma validação ou análise de sintaxe é feita além de verificar se não há literais de string não fechados e se a instrução termina com ponto e vírgula.

Por exemplo:Exemplo

>>>

>>> sqlite3.complete_statement("SELECT foo FROM bar;")
True
>>> sqlite3.complete_statement("SELECT foo")
False

Esta função pode ser útil durante a entrada da linha de comando para determinar se o texto inserido parece formar uma instrução SQL completa ou se uma entrada adicional é necessária antes de chamarexecutar().
Esta função pode ser útil ao digitar na linha de comando, para ajudar a determinar se o texto inserido se parece com uma instrução SQL completa ou ao chamarexecute()Se informações adicionais são necessárias antes.

Verrunsource()emBiblioteca/sqlite3/__main__.pypara uso no mundo real.
Em aplicações práticas, você pode consultarLib/sqlite3/__main__.pymeiorunsource()função para entender seu uso.

sqlite3.enable_callback_tracebacks(bandeira, /)

Habilitar ou desabilitar rastreamentos de retorno de chamada. Por padrão, você não obterá nenhum rastreamento em funções definidas pelo usuário, agregados, conversores, retornos de chamada do autorizador etc. Se quiser depurá-los, você pode chamar esta função combandeiradefinido comoTrue. Depois, você obterá rastreamentos de retornos de chamada emsistema.stderr. UsarFalsepara desabilitar o recurso novamente.
Ative ou desative o rastreamento de retorno de chamada. Por padrão, você não receberá nenhum rastreamento em funções definidas pelo usuário, funções agregadas, conversores, retornos de chamada de autorização, etc.Se quiser depurá-los, você pode chamar esta função e substituirflagDefinir comoTrue .Depois você poderásys.stderr Obtenha informações de rastreamento do retorno de chamada.usarFalsepara desativar esse recurso novamente.

Observação

Erros em retornos de chamada de função definidos pelo usuário são registrados como exceções não geráveis. Use ummanipulador de gancho não elevávelpara introspecção do retorno de chamada com falha.
Erros em retornos de chamada de função definidos pelo usuário são registrados como exceções não capturáveis. Use um manipulador de gancho não acionável para realizar introspecção em retornos de chamada com falha.

 

Isso significa que quando ocorrem erros em retornos de chamada de funções definidas pelo usuário do SQLite (como funções agregadas, funções escalares, etc.), esses erros não são lançados como exceções normais do Python e podem ser detectados por blocos try-except. Em vez disso, eles são capturados pelo SQLite ou pelo módulo sqlite3 do Python e registrados de alguma forma (geralmente gravados no log ou na saída de erro padrão), mas não interrompem a execução do programa (a menos que o erro seja muito sério).

Para inspecionar e depurar essas exceções incapturáveis, você pode configurar um "manipulador de gancho incapturável". Este manipulador é uma função que o Python chama quando ocorre uma exceção não detectada, passando as informações da exceção como parâmetro. Dessa forma, você pode escrever código na função do processador para registrar ou verificar essas exceções para ajudar a diagnosticar o problema.

Observe que a implementação específica pode variar dependendo da versão do Python e dos detalhes de implementação do módulo sqlite3. Portanto, é recomendável consultar a documentação mais recente do Python ou a documentação do módulo sqlite3 para aprender como configurar e usar o manipulador de gancho incapturável.

sqlite3.register_adapter(tipo, adaptador, /)

Registre umadaptador chamávelpara adaptar o tipo Pythontipoem um tipo SQLite. O adaptador é chamado com um objeto Python do tipotipocomo seu único argumento e deve retornar um valor de atipo que o SQLite entende nativamente.
Registre um objeto que pode ser chamado de **adaptador** para converter Pythontype O tipo é adaptado a um tipo que o SQLite pode entender nativamente.Esta função do adaptador leva umtypeUm objeto do tipo é chamado como o único argumento e deve retornar um valor de um tipo que o SQLite suporta nativamente.
 

Deve-se notar que o "typetype" pode ser um pouco enganador, porque normalmente não nos referimos aos recursos integrados do Pythontype Os objetos (ou seja, os próprios tipos) são armazenados diretamente no banco de dados. Mais comumente, queremos adaptar objetos em Python (que podem ser instâncias de tipos personalizados) em um formato que o SQLite possa armazenar.No entanto, tomando a frase literalmente, se você precisar lidar comtypeobjeto em si (embora isso seja raro na prática), você precisará escrever um adaptador para convertê-lo em alguma forma que o SQLite possa armazenar, como uma string representando o nome do tipo.

No entanto, um caso de uso mais comum é para tipos Python personalizados ou tipos integrados, comodatetime、decimal.Decimaletc.) escrevem adaptadores para que possam ser armazenados e recuperados corretamente pelo banco de dados SQLite.

Por exemplo, se você tiver uma classe Python personalizadaMyClass, e deseja armazenar sua instância em um banco de dados SQLite, você pode escrever um adaptador para converter uma instância desta classe em uma string (ou outro tipo) que pode ser armazenada pelo SQLite e, em seguida, escrever um conversor para converter Converter esta string de volta paraMyClassinstância.

No entanto, para esta questão, se você quiser apenas lidar com Pythontypeobjeto (ou seja, os metadados do tipo), você pode escrever um adaptador para retornar o nome do tipo (como uma string), mas isso geralmente não é uma prática comum para armazenar objetos em um banco de dados.

sqlite3.register_converter(Digite o nome, conversor, /)

Registre oconversor chamávelpara converter objetos SQLite do tipoDigite o nomeem um objeto Python de um tipo específico. O conversor é invocado para todos os valores SQLite do tipoDigite o nome; é passado umbytesobjeto e deve retornar um objeto do tipo Python desejado. Consulte o parâmetrodetectar_tiposdeconectar()para obter informações sobre como funciona a detecção de tipo.
Registre um objeto chamável **converter** para converter tipos SQLite emtypename Converte um objeto em um objeto Python de um tipo específico.Para todos os tipostypenameEste conversor é chamado para qualquer valor SQLite que recebe;bytes object como argumento e deve retornar um objeto do tipo Python necessário.Para saber como funciona a detecção de tipo, consulteconnect()Funcionaldetect_typesparâmetro.

Observação:Digite o nomee o nome do tipo na sua consulta são correspondidos sem distinção entre maiúsculas e minúsculas.
Perceber：typenameO nome do tipo na consulta não diferencia maiúsculas de minúsculas durante a correspondência.

Constantes do módulo

sqlite3.CONTROLE_DE_TRANSAÇÃO_LEGADO

Definirconfirmação automáticapara esta constante para selecionar o comportamento de controle de transação de estilo antigo (pré-Python 3.12). VejaControle de transações por meio do atributo isolation_levelPara maiores informações.
Vaiautocommit Defina esta constante para selecionar o comportamento de controle de transação no estilo antigo (pré-Python 3.12).Para obter mais informações, consulte "Passeisolation_levelPropriedades controlam transações".

sqlite3.PARSE_COLNAMES

Passe este valor de sinalizador para odetectar_tiposparâmetro deconectar()para procurar uma função de conversor usando o nome do tipo, analisado a partir do nome da coluna de consulta, como a chave do dicionário do conversor. O nome do tipo deve ser colocado entre colchetes ([]).
Passe esse valor de sinalizador paraconnect()Funcionaldetect_types Parâmetro para localizar a função do conversor consultando o nome do tipo resolvido no nome da coluna como a chave para o dicionário do conversor. Os nomes dos tipos devem ser colocados entre colchetes ([]).

SELECT p as "p [point]" FROM test;  ! will look up converter "point"

Esta bandeira pode ser combinada comANALISAR_DECLTYPESusando o|operador (bit a bit ou).
Esta bandeira pode ser usada|(OR bit a bit) operador ANDPARSE_DECLTYPESEm conjunção com.

sqlite3.PARSE_DECLTYPES

Passe este valor de sinalizador para odetectar_tiposparâmetro deconectar()para procurar uma função conversora usando os tipos declarados para cada coluna. Os tipos são declarados quando a tabela do banco de dados é criada.sqlite3procurará uma função conversora usando a primeira palavra do tipo declarado como a chave do dicionário conversor. Por exemplo:
Passe esse valor de sinalizador paraconnect()Funcionaldetect_types Parâmetros para encontrar a função conversora usando o tipo declarado de cada coluna do banco de dados. Esses tipos são declarados ao criar a tabela do banco de dados.sqlite3 A função conversora será consultada usando a primeira palavra do tipo declarado como chave do dicionário conversor. Por exemplo:

CREATE TABLE test(
   i integer primary key,  ! will look up a converter named "integer"
   p point,                ! will look up a converter named "point"
   n number(10)            ! will look up a converter named "number"
 )

Esta bandeira pode ser combinada comANALISAR_NOMES_DE_COLUNASusando o|operador (bit a bit ou).

sqlite3.SQLITE_OK

sqlite3.SQLITE_DENY

sqlite3.SQLITE_IGNORE

Bandeiras que devem ser devolvidas peloretorno_de_chamada_do_autorizador chamávelpassado paraConexão.set_authorizer(), para indicar se:
Passar paraConnection.set_authorizer()deauthorizer_callbackSinaliza que a função que pode ser chamada deve retornar para indicar:

• O acesso é permitido (SQLITE_OK), o acesso é permitido (SQLITE_OK）

• A instrução SQL deve ser abortada com um erro (SQLITE_DENY)
  A instrução SQL deve ser abortada com um erro (SQLITE_DENY）

• A coluna deve ser tratada como umaNULLvalor (SQLITE_IGNORE)
  As colunas devem ser tratadas como valores NULL (SQLITE_IGNORE）

sqlite3.nível de API

Constante de string que informa o nível de DB-API suportado. Obrigatório pelo DB-API. Codificado para"2.0".
Essas duas constantes de string sãosqlite3Definidos em módulos, eles seguem a especificação Python Database API (DB-API).

sqlite3.estiloparam

Constante de string que indica o tipo de formatação do marcador de parâmetro esperado pelosqlite3módulo. Requerido pela DB-API. Codificado para"qmark".
Esta constante de string especificasqlite3 O tipo de formatação do marcador de parâmetro esperado pelo módulo. Isso é exigido pela especificação DB-API (Database Application Programming Interface).É codificado como"qmark", significa que ao construir consultas SQL, os marcadores de parâmetros devem ser representados por pontos de interrogação (?).

Observação

OnamedO estilo de parâmetro DB-API também é suportado.

sqlite3.sqlite_versão

Número da versão da biblioteca SQLite de tempo de execução como umcorda.
O número da versão da biblioteca de tempo de execução SQLite, expresso em formato de string.

sqlite3.sqlite_versão_info

Número da versão da biblioteca SQLite de tempo de execução como umtupladeinteiros.
O número da versão da biblioteca de tempo de execução SQLite, expresso como uma tupla de números inteiros.

sqlite3.segurança de thread

Constante inteira exigida pelo DB-API 2.0, informando o nível de segurança do threadsqlite3módulo suporta. Este atributo é definido com base no padrãomodo de encadeamentoa biblioteca SQLite subjacente é compilada com. Os modos de threading do SQLite são:
Constante inteira exigida pelo DB-API 2.0, indicandosqlite3 O nível de segurança do thread suportado pelo módulo. Esta propriedade é definida de acordo com o modo de threading padrão com o qual a biblioteca SQLite subjacente foi compilada. Os modos de threading do SQLite incluem:

1. Fio único: Neste modo, todos os mutexes são desabilitados e o SQLite não é seguro para uso em mais de um thread ao mesmo tempo.
   Single-thread: Neste modo, todos os mutexes estão desabilitados e o SQLite não é seguro para ser usado por vários threads ao mesmo tempo.

2. Multi fio: Neste modo, o SQLite pode ser usado com segurança por vários threads, desde que nenhuma conexão de banco de dados seja usada simultaneamente em dois ou mais threads.
   Multi-thread: Neste modo, o SQLite pode ser usado com segurança por vários threads, desde que nenhuma conexão de banco de dados seja usada simultaneamente por dois ou mais threads.

3. Serializado: No modo serializado, o SQLite pode ser usado com segurança por vários threads sem restrições.
   Serializado: No modo serializado, o SQLite pode ser usado com segurança por vários threads sem quaisquer restrições.

Os mapeamentos dos modos de threading do SQLite para os níveis de segurança de thread do DB-API 2.0 são os seguintes:
O mapeamento do modo de thread do SQLite para o nível de segurança de thread do DB-API 2.0 é o seguinte:

Alterado na versão 3.11: Definirsegurança de roscadinamicamente em vez de codificá-lo para1.

sqlite3.versão

Número da versão deste módulo como umcorda. Esta não é a versão da biblioteca SQLite.
O número da versão deste módulo, expresso como uma string.essenãoO número da versão da biblioteca SQLite.

Obsoleto desde a versão 3.12, será removido na versão 3.14: Esta constante é usada para refletir o número da versão dopysqlitepacote, uma biblioteca de terceiros que costumava fazer o upstream de alterações parasqlite3. Hoje, não tem significado nem valor prático.
Obsoleto desde a versão 3.12, para ser removido na versão 3.14: Esta constante foi usada para refletirpysqliteO número da versão do pacote,pysqliteÉ uma biblioteca de terceiros que foi carregada no upstreamsqlite3 Confirme as alterações. Agora, não tem significado real ou valor prático.

sqlite3.versão_info

Número da versão deste módulo como umtupladeinteiros. Esta não é a versão da biblioteca SQLite.

Obsoleto desde a versão 3.12, será removido na versão 3.14: Esta constante é usada para refletir o número da versão dopysqlitepacote, uma biblioteca de terceiros que costumava fazer o upstream de alterações parasqlite3. Hoje, não tem significado nem valor prático.

sqlite3.SQLITE_DBCONFIG_DEFENSIVO

sqlite3.SQLITE_DBCONFIG_DQS_DDL

sqlite3.SQLITE_DBCONFIG_DQS_DML

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY

sqlite3.SQLITE_DBCONFIG_ATIVAR_FTS3_TOKENIZER

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSÃO

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW

sqlite3.SQLITE_DBCONFIG_LEGADO_ALTERAR_TABELA

sqlite3.SQLITE_DBCONFIG_FORMATO_DE_ARQUIVO_LEGADO

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP

sqlite3.SQLITE_DBCONFIG_CONFIÁVEL_ESQUEMA

sqlite3.SQLITE_DBCONFIG_ESQUEMA_GRAVÁVEL

Essas constantes são usadas paraConexão.setconfig()eobter configuração()métodos.
Essas constantes são usadasConnection.setconfig()egetconfig()método.

A disponibilidade dessas constantes varia dependendo da versão do SQLite com a qual o Python foi compilado.
A disponibilidade dessas constantes depende da versão do SQLite com a qual o SQLite Python foi compilado.

Adicionado na versão 3.12.

Veja também

Opções de configuração de conexão de banco de dados

Documentação SQLite: Opções de configuração de conexão de banco de dados

Objetos de conexão

aulasqlite3.Conexão

Cada banco de dados SQLite aberto é representado por umConnectionobjeto, que é criado usandosqlite3.conectar(). Seu principal objetivo é criarCursorobjetos, eControle de transações.

Veja também

• Como usar métodos de atalho de conexão

• Como usar o gerenciador de contexto de conexão

Uma conexão de banco de dados SQLite tem os seguintes atributos e métodos:

cursor(fábrica=Cursor)

Crie e retorne umCursorobjeto. O método cursor aceita um único parâmetro opcionalfábrica. Se fornecido, este deve ser umchamávelretornando uma instância deCursorou suas subclasses.
Cria um e retorna umCursorobjeto.cursorO método aceita um único parâmetro opcionalfactory .Se este parâmetro for fornecido, ele deverá ser um objeto que pode ser chamado e que retorne umCursorou uma instância de sua subclasse.

abrir bolha(mesa, coluna, linha, /, *, somente leitura=Falso, nome='principal')

Abra umManchamanipular um BLOB existente.

Parâmetros:

• mesa (str) – O nome da tabela onde o blob está localizado.
  O nome da tabela que contém dados BLOB.

• coluna (str) – O nome da coluna onde o blob está localizado.
  Nome da coluna contendo dados BLOB.

• linha (str) – O nome da linha onde o blob está localizado.
  O nome da linha (ou mais precisamente o identificador da linha) que contém os dados BLOB.

• somente leitura (bool) - Definido comoTruese o blob deve ser aberto sem permissões de gravação. O padrão éFalse.
  Se definido como True, indica que o BLOB deve ser aberto sem permissão de gravação. O padrão é False, que permite leitura e escrita.

• nome (str) – O nome do banco de dados onde o blob está localizado. O padrão é"main".
  O nome do banco de dados que contém dados BLOB. O padrão é “main”, que é o nome do banco de dados padrão no SQLite.

Levanta:

Erro operacional– Ao tentar abrir um blob em umWITHOUT ROWIDmesa.
Ao tentar semLINHAOcorre quando dados BLOB são abertos na tabela de ID.

Tipo de retorno:

Mancha

Observação

O tamanho do blob não pode ser alterado usando oManchaclasse. Use a função SQLzeroblobpara criar um blob com um tamanho fixo.

Adicionado na versão 3.11.

comprometer-se()

Confirme qualquer transação pendente no banco de dados. Seconfirmação automáticaéTrue, ou não há transação aberta, este método não faz nada. SeautocommitéFalse, uma nova transação é implicitamente aberta se uma transação pendente foi confirmada por este método.
Confirme todas as transações pendentes no banco de dados.seautocommit Se for Verdadeiro ou não houver transação aberta, este método não executa nenhuma operação.seautocommitfor False e este método confirmar uma transação pendente, uma nova transação será iniciada implicitamente.

reverter()

Reverta para o início de qualquer transação pendente. Seconfirmação automáticaéTrue, ou não há transação aberta, este método não faz nada. SeautocommitéFalse, uma nova transação é implicitamente aberta se uma transação pendente foi revertida por este método.
Reverter para o início de quaisquer transações pendentes.seautocommit Se for Verdadeiro ou não houver transação aberta, este método não executa nenhuma operação.seautocommitfor False e este método reverter uma transação pendente, uma nova transação será iniciada implicitamente.

fechar()

Feche a conexão com o banco de dados. Seconfirmação automáticaéFalse, qualquer transação pendente é implicitamente revertida. SeautocommitéTrueouCONTROLE_DE_TRANSAÇÃO_LEGADO, nenhum controle de transação implícito é executado. Certifique-se decomprometer-se()antes de fechar para evitar perder alterações pendentes.
Feche a conexão com o banco de dados.seautocommit Se for falso, quaisquer transações pendentes serão revertidas implicitamente.seautocommité Verdadeiro ouLEGACY_TRANSACTION_CONTROL (controle de transação legado), o controle implícito de transação não será executado.Antes de fechar não se esqueça de ligarcommit()para evitar perder alterações pendentes.

executar(SQL->, parâmetros=(), /)

Crie um novoCursorobjeto e chamadaexecutar()nele com o dadoSQL->eparâmetros. Retorna o novo objeto cursor.
crie um novoCursorobjeto e chamadaexecute()método, passando o dadosql instruções e parâmetros.devolva este novoCursorobjeto.

executarmuitos(SQL->, parâmetros, /)

Crie um novoCursorobjeto e chamadaexecutemuitos()nele com o dadoSQL->eparâmetros. Retorna o novo objeto cursor.
crie um novoCursorobjeto e chamadaexecutemany()método, passando o dadosql Instruções e sequências de parâmetros. Isso permite que vários conjuntos de parâmetros sejam executados ao mesmo tempo.devolva este novoCursorobjeto.

executescript(script_sql, /)

Crie um novoCursorobjeto e chamadaexecutescript()nele com o dadoscript_sql. Retorna o novo objeto cursor.
crie um novoCursorobjeto e chamadaexecutescript() método, passando o script SQL fornecido. Isto permite a execução de múltiplas instruções SQL, separadas por ponto e vírgula no script.devolva este novoCursorobjeto.

criar_função(nome, reclamar, função, *, determinístico=Falso)

Crie ou remova uma função SQL definida pelo usuário.
Crie ou remova uma função SQL definida pelo usuário.

Parâmetros:

• nome (str) – O nome da função SQL.
  name(str) – O nome da função SQL.

• reclamar (Inteiro) – O número de argumentos que a função SQL pode aceitar. Se-1, pode levar qualquer número de argumentos.
  narg (int) – O número de argumentos que a função SQL pode aceitar. Se -1, significa que pode aceitar qualquer número de argumentos.

• função (ligar de volta| Nenhum) – Achamávelque é chamado quando a função SQL é invocada. O chamável deve retornarum tipo suportado nativamente pelo SQLite. Definido comoNonepara remover uma função SQL existente.
  func (callback | None) – Este objeto chamável (callback) será executado quando a função SQL for chamada. Este objeto que pode ser chamado deve retornar um tipo que o SQLite suporte nativamente. Se definido como Nenhum, as funções SQL existentes serão removidas.

• determinístico (bool) - SeTrue, a função SQL criada é marcada comodeterminístico, o que permite que o SQLite execute otimizações adicionais.
  deterministic(bool) – Se True, marca a função SQL criada como determinística, o que permite ao SQLite realizar otimizações adicionais.

Levanta:

Erro não suportado- Sedeterminísticoé usado com versões do SQLite anteriores à 3.8.3.

Alterado na versão 3.8: Adicionado odeterminísticoparâmetro.

Exemplo:

>>>

>>> import hashlib
>>> def md5sum(t):
...     return hashlib.md5(t).hexdigest()
>>> con = sqlite3.connect(":memory:")
>>> con.create_function("md5", 1, md5sum)
>>> for row in con.execute("SELECT md5(?)", (b"foo",)):
...     print(row)
('acbd18db4cc2f85cedef654fccc4a4d8',)
>>> con.close()

criar_agregado(nome, n_arg, classe_agregada)

Crie ou remova uma função de agregação SQL definida pelo usuário.
Crie ou remova uma função agregada SQL definida pelo usuário.

Parâmetros:

• nome (str) – O nome da função de agregação SQL.
       name(str) – O nome da função agregada SQL.

• n_arg (Inteiro) – O número de argumentos que a função SQL agregada pode aceitar. Se-1, pode levar qualquer número de argumentos.
  O número de parâmetros que uma função agregada SQL pode aceitar. Se -1, significa que pode aceitar qualquer número de argumentos.

• classe_agregada (aula| Nenhum) –

  Uma classe deve implementar os seguintes métodos:
  Uma classe deve implementar os seguintes métodos:

  • step(): adicione uma linha ao agregado.

  • finalize(): Retorna o resultado final do agregado comoum tipo suportado nativamente pelo SQLite.
    finalize(): Este método é usado para retornar o resultado final da agregação.

  O número de argumentos que ostep()o método deve aceitar é controlado porn_arg.
  step()O número de parâmetros que um método deve aceitar é dado porn_argao controle.

  Definido comoNonepara remover uma função de agregação SQL existente.
  Definir comoNonepara remover funções agregadas SQL existentes.

Exemplo:

class MySum:
    def __init__(self):
        self.count = 0
 
    def step(self, value):
        self.count += value
 
    def finalize(self):
        return self.count
 
con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.execute("CREATE TABLE test(i)")
cur.execute("INSERT INTO test(i) VALUES(1)")
cur.execute("INSERT INTO test(i) VALUES(2)")
cur.execute("SELECT mysum(i) FROM test")
print(cur.fetchone()[0])
 
con.close()

criar_função_janela(nome, num_params, classe_agregada, /)

Crie ou remova uma função de janela agregada definida pelo usuário.

Parâmetros:

• nome (str) – O nome da função de janela de agregação SQL a ser criada ou removida.

• num_params (Inteiro) – O número de argumentos que a função de janela agregada SQL pode aceitar. Se-1, pode levar qualquer número de argumentos.

• classe_agregada (aula| Nenhum) –

  Uma classe que deve implementar os seguintes métodos:

  • step(): Adicione uma linha à janela atual.

  • value(): Retorna o valor atual do agregado.

  • inverse(): Remove uma linha da janela atual.

  • finalize(): Retorna o resultado final do agregado comoum tipo suportado nativamente pelo SQLite.

  O número de argumentos que ostep()evalue()métodos devem aceitar é controlado pornum_params.

  Definido comoNonepara remover uma função de janela de agregação SQL existente.

Levanta:

Erro não suportado– Se usado com uma versão do SQLite anterior à 3.25.0, que não suporta funções de janela agregadas.

Adicionado na versão 3.11.

Exemplo:

# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc
class WindowSumInt:
    def __init__(self):
        self.count = 0

    def step(self, value):
        """Add a row to the current window."""
        self.count += value

    def value(self):
        """Return the current value of the aggregate."""
        return self.count

    def inverse(self, value):
        """Remove a row from the current window."""
        self.count -= value

    def finalize(self):
        """Return the final value of the aggregate.

        Any clean-up actions should be placed here.
        """
        return self.count


con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE test(x, y)")
values = [
    ("a", 4),
    ("b", 5),
    ("c", 3),
    ("d", 8),
    ("e", 1),
]
cur.executemany("INSERT INTO test VALUES(?, ?)", values)
con.create_window_function("sumint", 1, WindowSumInt)
cur.execute("""
    SELECT x, sumint(y) OVER (
        ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
    ) AS sum_y
    FROM test ORDER BY x
""")
print(cur.fetchall())
con.close()

criar_agrupamento(nome, chamável, /)

Crie uma ordenação chamadanomeusando a função de agrupamentochamável. chamávelpassou doiscordaargumentos e deve retornar uminteiro:

• 1se o primeiro for ordenado mais alto que o segundo

• -1se o primeiro for ordenado menor que o segundo

• 0se forem ordenados iguais

O exemplo a seguir mostra uma ordenação reversa:

def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.execute("CREATE TABLE test(x)")
cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)])
cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse")
for row in cur:
    print(row)
con.close()

Remova uma função de agrupamento definindochamávelparaNone.

Alterado na versão 3.11: O nome da collation pode conter qualquer caractere Unicode. Anteriormente, apenas caracteres ASCII eram permitidos.

interromper()

Chame este método de um thread diferente para abortar quaisquer consultas que possam estar sendo executadas na conexão. Consultas abortadas levantarão umErro operacional.

definir_autorizador(retorno_de_chamada_do_autorizador)

Registrochamável retorno_de_chamada_do_autorizadora ser invocado para cada tentativa de acessar uma coluna de uma tabela no banco de dados. O retorno de chamada deve retornar um dosSQLITE_OK, SQLITE_NEGAR, ouSQLITE_IGNORARpara sinalizar como o acesso à coluna deve ser tratado pela biblioteca SQLite subjacente.

O primeiro argumento para o retorno de chamada significa que tipo de operação deve ser autorizada. O segundo e o terceiro argumentos serão argumentos ouNonedependendo do primeiro argumento. O quarto argumento é o nome do banco de dados (“main”, “temp”, etc.) se aplicável. O quinto argumento é o nome do gatilho ou visualização mais interno que é responsável pela tentativa de acesso ouNonese esta tentativa de acesso for diretamente do código SQL de entrada.

Por favor, consulte a documentação do SQLite sobre os valores possíveis para o primeiro argumento e o significado do segundo e terceiro argumentos dependendo do primeiro. Todas as constantes necessárias estão disponíveis nosqlite3módulo.

PassagemNonecomoretorno_de_chamada_do_autorizadordesabilitará o autorizador.

Alterado na versão 3.11: Adicionado suporte para desabilitar o autorizador usandoNone.

definir_manipulador_de_progresso(manipulador_de_progresso, e)

Registrochamável manipulador_de_progressopara ser invocado para cadaeinstruções da máquina virtual SQLite. Isso é útil se você quiser ser chamado do SQLite durante operações de longa duração, por exemplo, para atualizar uma GUI.

Se você quiser limpar qualquer manipulador de progresso instalado anteriormente, chame o método comNoneparamanipulador_de_progresso.

Retornar um valor diferente de zero da função do manipulador encerrará a consulta em execução no momento e fará com que ela gere umErro de banco de dadosexceção.

set_trace_callback(retorno_de_chamada_de_rastreamento)

Registrochamável retorno_de_chamada_de_rastreamentoa ser invocado para cada instrução SQL que é realmente executada pelo backend SQLite.

O único argumento passado para o retorno de chamada é a declaração (comostr) que está sendo executado. O valor de retorno do retorno de chamada é ignorado. Observe que o backend não executa apenas instruções passadas para oCursor.execute()métodos. Outras fontes incluem ogerenciamento de transaçõesdosqlite3módulo e a execução de gatilhos definidos no banco de dados atual.

PassagemNonecomoretorno_de_chamada_de_rastreamentodesabilitará o retorno de chamada de rastreamento.

Observação

Exceções levantadas no retorno de chamada de rastreamento não são propagadas. Como um auxílio de desenvolvimento e depuração, usehabilitar_rastreamentos_de_retorno_de_chamada()para habilitar a impressão de rastreamentos de exceções geradas no retorno de chamada de rastreamento.

Adicionado na versão 3.3.

enable_load_extension(habilitado, /)

Habilitar o mecanismo SQLite para carregar extensões SQLite de bibliotecas compartilhadas sehabilitadoéTrue; senão, não permita o carregamento de extensões SQLite. Extensões SQLite podem definir novas funções, agregados ou implementações de tabelas virtuais totalmente novas. Uma extensão bem conhecida é a extensão fulltext-search distribuída com SQLite.

Observação

Osqlite3O módulo não é construído com suporte de extensão carregável por padrão, porque algumas plataformas (notavelmente macOS) têm bibliotecas SQLite que são compiladas sem esse recurso. Para obter suporte de extensão carregável, você deve passar o--habilitar-extensões-sqlite-carregáveisopção paraconfigurar.

Levanta umevento de auditoria sqlite3.enable_load_extensioncom argumentosconnection, enabled.

Adicionado na versão 3.2.

Alterado na versão 3.10: Adicionado osqlite3.enable_load_extensionevento de auditoria.

con.enable_load_extension(True)

# Load the fulltext search extension
con.execute("select load_extension('./fts3.so')")

# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")

# disable extension loading again
con.enable_load_extension(False)

# example from SQLite wiki
con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")
con.executescript("""
    INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');
    INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');
    """)
for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):
    print(row)

carregar_extensão(caminho, /, *, ponto de entrada=Nenhum)

Carregue uma extensão SQLite de uma biblioteca compartilhada. Habilite o carregamento de extensão comenable_load_extension()antes de chamar este método.

Parâmetros:

• caminho (str) – O caminho para a extensão SQLite.

• ponto de entrada (str | Nenhum) – Nome do ponto de entrada. SeNone(o padrão), o SQLite criará um nome de ponto de entrada próprio; veja a documentação do SQLiteCarregando uma extensãopara detalhes.

Levanta umevento de auditoria sqlite3.load_extensioncom argumentosconnection, path.

Adicionado na versão 3.2.

Alterado na versão 3.10: Adicionado osqlite3.load_extensionevento de auditoria.

Alterado na versão 3.12: Adicionado oponto de entradaparâmetro.

iterdump()

Retornar umiteradorpara despejar o banco de dados como código-fonte SQL. Útil ao salvar um banco de dados na memória para restauração posterior. Semelhante ao.dumpcomando nosqlite3concha.

Exemplo:

# Convert file example.db to SQL dump file dump.sql
con = sqlite3.connect('example.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%sn' % line)
con.close()

Veja também

Como lidar com codificações de texto não UTF-8

cópia de segurança(alvo, *, páginas=-1, progresso=Nenhum, nome='principal', sono=0,250)

Crie um backup de um banco de dados SQLite.

Funciona mesmo se o banco de dados estiver sendo acessado por outros clientes ou simultaneamente pela mesma conexão.

Parâmetros:

• alvo (Conexão) – A conexão de banco de dados para salvar o backup.

• Páginas (Inteiro) – O número de páginas a serem copiadas por vez. Se for igual ou menor que0, todo o banco de dados é copiado em uma única etapa. O padrão é-1.

• progresso (ligar de volta| Nenhum) – Se definido como umchamável, ele é invocado com três argumentos inteiros para cada iteração de backup: ostatusda última iteração, orestantenúmero de páginas ainda a serem copiadas e ototalnúmero de páginas. O padrão éNone.

• nome (str) – O nome do banco de dados para fazer backup. Ou"main"(o padrão) para o banco de dados principal,"temp"para o banco de dados temporário ou o nome de um banco de dados personalizado conforme anexado usando oATTACH DATABASEInstrução SQL.

• dormir (flutuador) – O número de segundos para dormir entre tentativas sucessivas de fazer backup das páginas restantes.

Exemplo 1, copie um banco de dados existente para outro:

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

src = sqlite3.connect('example.db')
dst = sqlite3.connect('backup.db')
with dst:
    src.backup(dst, pages=1, progress=progress)
dst.close()
src.close()

Exemplo 2, copie um banco de dados existente para uma cópia temporária:

src = sqlite3.connect('example.db')
dst = sqlite3.connect(':memory:')
src.backup(dst)
dst.close()
src.close()

Adicionado na versão 3.7.

Veja também

Como lidar com codificações de texto não UTF-8

obter limite(categoria, /)

Obtenha um limite de tempo de execução da conexão.

Parâmetros:

categoria (Inteiro) - OCategoria de limite do SQLitea ser consultado.

Tipo de retorno:

Inteiro

Levanta:

Erro de programação- Secategorianão é reconhecido pela biblioteca SQLite subjacente.

Exemplo, consulte o comprimento máximo de uma instrução SQL paraConexão con(o padrão é 1000000000):

>>>

>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
1000000000

Adicionado na versão 3.11.

definir limite(categoria, limitee, /)

Defina um limite de tempo de execução de conexão. Tentativas de aumentar um limite acima de seu limite superior rígido são silenciosamente truncadas para o limite superior rígido. Independentemente de o limite ter sido alterado ou não, o valor anterior do limite é retornado.

Parâmetros:

• categoria (Inteiro) - OCategoria de limite do SQLitea ser definido.

• limitee (Inteiro) – O valor do novo limite. Se negativo, o limite atual não é alterado.

Tipo de retorno:

Inteiro

Levanta:

Erro de programação- Secategorianão é reconhecido pela biblioteca SQLite subjacente.

Exemplo, limite o número de bancos de dados anexados a 1 paraConexão con(o limite padrão é 10):

>>>

>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)
10
>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
1

Adicionado na versão 3.11.

obter configuração(op, /)

Consultar uma opção de configuração de conexão booleana.

Parâmetros:

op (Inteiro) - ACódigo SQLITE_DBCONFIG.

Tipo de retorno:

bool

Adicionado na versão 3.12.

definir configuração(op, habilitar=Verdadeiro, /)

Defina uma opção de configuração de conexão booleana.

Parâmetros:

• op (Inteiro) - ACódigo SQLITE_DBCONFIG.

• habilitar (bool) – Truese a opção de configuração deve ser habilitada (padrão);Falsese deve ser desabilitado.

Adicionado na versão 3.12.

serializar(*, nome='principal')

Serializar um banco de dados em umbytesobjeto. Para um arquivo de banco de dados comum em disco, a serialização é apenas uma cópia do arquivo de disco. Para um banco de dados na memória ou um banco de dados “temporário”, a serialização é a mesma sequência de bytes que seria gravada no disco se esse banco de dados fosse copiado para o disco.

Parâmetros:

nome (str) – O nome do banco de dados a ser serializado. O padrão é"main".

Tipo de retorno:

bytes

Observação

Este método só estará disponível se a biblioteca SQLite subjacente tiver a API de serialização.

Adicionado na versão 3.11.

desserializar(dados, /, *, nome='principal')

Desserializar umserializadobanco de dados em umConexão. Este método faz com que a conexão do banco de dados seja desconectada do banco de dadosnome, e reabrirnomecomo um banco de dados na memória baseado na serialização contida emdados.

Parâmetros:

• dados (bytes) – Um banco de dados serializado.

• nome (str) – O nome do banco de dados para desserializar. O padrão é"main".

Levanta:

• Erro operacional– Se a conexão com o banco de dados estiver atualmente envolvida em uma transação de leitura ou uma operação de backup.

• Erro de banco de dados- Sedadosnão contém um banco de dados SQLite válido.

• Erro de estouro- Selen(dados)é maior que2**63 - 1.

Observação

Este método só estará disponível se a biblioteca SQLite subjacente tiver a API de desserialização.

Adicionado na versão 3.11.

confirmação automática

Este atributo controlaPEP 249- comportamento de transação compatível.autocommittem três valores permitidos:

• False: SelecionePEP 249- comportamento de transação compatível, o que implica quesqlite3garante que uma transação esteja sempre aberta. Usecomprometer-se()ereverter()para fechar transações.

  Este é o valor recomendado deautocommit.

• True: Use o SQLitemodo autocommit. comprometer-se()ereverter()não tem efeito neste modo.

• CONTROLE_DE_TRANSAÇÃO_LEGADO: Pré-Python 3.12 (não-PEP 249-controle de transações compatível). Vejanível_de_isolamentopara mais detalhes.

  Este é atualmente o valor padrão deautocommit.

MudandoautocommitparaFalseabrirá uma nova transação e a alterará paraTrueconfirmará qualquer transação pendente.

VerControle de transações via atributo autocommitpara mais detalhes.

Observação

Onível_de_isolamentoatributo não tem efeito a menos queconfirmação automáticaéCONTROLE_DE_TRANSAÇÃO_LEGADO.

Adicionado na versão 3.12.

em_transação

Este atributo somente leitura corresponde ao SQLite de baixo nívelmodo autocommit.

Truese uma transação estiver ativa (há alterações não confirmadas),Falsede outra forma.

Adicionado na versão 3.2.

nível_de_isolamento

Controla omodo de tratamento de transações legadodesqlite3. Se definido comoNone, as transações nunca são abertas implicitamente. Se definido como um dos"DEFERRED", "IMMEDIATE", ou"EXCLUSIVE", correspondendo ao subjacenteComportamento de transação do SQLite, gerenciamento de transações implícitasé desempenhado.

Se não for substituído pelonível_de_isolamentoparâmetro deconectar(), o padrão é"", que é um pseudônimo para"DEFERRED".

Observação

Usandoconfirmação automáticapara controlar o manuseio de transações é recomendado em vez de usarisolation_level. isolation_levelnão tem efeito a menos queconfirmação automáticaestá configurado paraCONTROLE_DE_TRANSAÇÃO_LEGADO(o padrão).

fábrica_de_linhas

A inicialfábrica_de_linhasparaCursorobjetos criados a partir desta conexão. Atribuir a este atributo não afeta orow_factoryde cursores existentes pertencentes a esta conexão, apenas os novos. ÉNonepor padrão, o que significa que cada linha é retornada como umtupla.

VerComo criar e usar fábricas de linhaspara mais detalhes.

fábrica_de_textos

Achamávelque aceita umbytesparâmetro e retorna uma representação de texto dele. O callable é invocado para valores SQLite com oTEXTtipo de dados. Por padrão, esse atributo é definido comostr.

VerComo lidar com codificações de texto não UTF-8para mais detalhes.

total_alterações

Retorna o número total de linhas do banco de dados que foram modificadas, inseridas ou excluídas desde que a conexão com o banco de dados foi aberta.

Objetos cursores

ACursorobjeto representa umcursor de banco de dadosque é usado para executar instruções SQL e gerenciar o contexto de uma operação de busca. Os cursores são criados usandoConexão.cursor(), ou usando qualquer um dosmétodos de atalho de conexão.

Os objetos do cursor sãoiteradores, o que significa que se vocêexecutar()aSELECTconsulta, você pode simplesmente iterar sobre o cursor para buscar as linhas resultantes:

for row in cur.execute("SELECT t FROM data"):
    print(row)

aulasqlite3.Cursor

ACursorinstância tem os seguintes atributos e métodos.

executar(SQL->, parâmetros=(), /)

Execute uma única instrução SQL, opcionalmente vinculando valores Python usandomarcadores de posição.

Parâmetros:

• SQL-> (str) – Uma única instrução SQL.

• parâmetros (ditado | seqüência) – Valores Python para vincular a marcadores de posição emSQL->. Adictse forem usados ​​marcadores de posição nomeados. Uma sequência se forem usados ​​marcadores de posição sem nome. VejaComo usar marcadores de posição para vincular valores em consultas SQL.

Levanta:

Erro de programação- SeSQL->contém mais de uma instrução SQL.

Seconfirmação automáticaéCONTROLE_DE_TRANSAÇÃO_LEGADO, nível_de_isolamentonão éNone, SQL->é umINSERT, UPDATE, DELETE, ouREPLACEdeclaração, e não há nenhuma transação aberta, uma transação é implicitamente aberta antes de ser executadaSQL->.

Obsoleto desde a versão 3.12, será removido na versão 3.14:Aviso de descontinuaçãoé emitido semarcadores de posição nomeadossão usados ​​eparâmetrosé uma sequência em vez de umaditado. A partir do Python 3.14,Erro de programaçãoserá levantado em vez disso.

Usarexecutescript()para executar várias instruções SQL.

executarmuitos(SQL->, parâmetros, /)

Para cada item emparâmetros, execute repetidamente oparametrizadoInstrução SQL DMLSQL->.

Usa o mesmo tratamento de transação implícito queexecutar().

Parâmetros:

• SQL-> (str) – Uma única instrução SQL DML.

• parâmetros (iterável) – Um iterável de parâmetros para vincular aos espaços reservados emSQL->. VerComo usar marcadores de posição para vincular valores em consultas SQL.

Levanta:

Erro de programação- SeSQL->contém mais de uma instrução SQL ou não é uma instrução DML.

Exemplo:

rows = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)

Observação

Todas as linhas resultantes são descartadas, incluindo instruções DML comCláusulas RETORNANDO.

Obsoleto desde a versão 3.12, será removido na versão 3.14:Aviso de descontinuaçãoé emitido semarcadores de posição nomeadossão usados ​​e os itens emparâmetrossão sequências em vez deditados. A partir do Python 3.14,Erro de programaçãoserá levantado em vez disso.

executescript(script_sql, /)

Execute as instruções SQL emscript_sql. Se oconfirmação automáticaéCONTROLE_DE_TRANSAÇÃO_LEGADOe há uma transação pendente, uma implícitaCOMMITa instrução é executada primeiro. Nenhum outro controle de transação implícito é executado; qualquer controle de transação deve ser adicionado ascript_sql.

script_sqldeve ser umcorda.

Exemplo:

# cur is an sqlite3.Cursor object
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")

buscar()

Sefábrica_de_linhaséNone, retorna o próximo conjunto de resultados da consulta de linha como umtupla. Caso contrário, passe-o para a fábrica de linhas e retorne seu resultado. RetorneNonese não houver mais dados disponíveis.

buscarmuitos(tamanho=cursor.arraysize)

Retorna o próximo conjunto de linhas de um resultado de consulta como umlistaaaaaaaa. Retorna uma lista vazia se não houver mais linhas disponíveis.

O número de linhas a serem buscadas por chamada é especificado pelotamanhoparâmetro. Setamanhonão é dado,tamanho da matrizdetermina o número de linhas a serem buscadas. Se menos detamanholinhas estiverem disponíveis, serão retornadas tantas linhas quantas estiverem disponíveis.

Observe que há considerações de desempenho envolvidas com otamanhoparâmetro. Para um desempenho ideal, geralmente é melhor usar o atributo arraysize. Se otamanhoparâmetro for usado, então é melhor que ele retenha o mesmo valor de umbuscarmuitos()ligue para o próximo.

buscar()

Retorna todas as linhas (restantes) de um resultado de consulta como umlistaaaaaaaa. Retorna uma lista vazia se nenhuma linha estiver disponível. Observe que otamanho da matrizatributo pode afetar o desempenho desta operação.

fechar()

Feche o cursor agora (em vez de sempre)__del__é chamado).

O cursor ficará inutilizável a partir deste ponto;Erro de programaçãouma exceção será gerada se qualquer operação for tentada com o cursor.

definir tamanhos de entrada(tamanhos, /)

Exigido pela API do banco de dados. Não faz nada emsqlite3.

definir tamanho de saída(tamanho, coluna=Nenhum, /)

Exigido pela API do banco de dados. Não faz nada emsqlite3.

tamanho da matriz

Atributo de leitura/gravação que controla o número de linhas retornadas porbuscarmuitos(). O valor padrão é 1, o que significa que uma única linha seria buscada por chamada.

conexão

Atributo somente leitura que fornece o banco de dados SQLiteConexãopertencente ao cursor. ACursorobjeto criado pela chamadacon.cursor()terá umconexãoatributo que se refere avigarista:

>>>

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True
>>> con.close()

descrição

Atributo somente leitura que fornece os nomes das colunas da última consulta. Para permanecer compatível com a API do Python DB, ele retorna uma tupla 7 para cada coluna onde os últimos seis itens de cada tupla sãoNone.

Está definido paraSELECTinstruções sem nenhuma linha correspondente também.

última linha

Atributo somente leitura que fornece o id da linha da última linha inserida. Ele só é atualizado após o sucessoINSERTouREPLACEdeclarações usando oexecutar()método. Para outras declarações, apósexecutemuitos()ouexecutescript(), ou se a inserção falhou, o valor delastrowidé deixado inalterado. O valor inicial delastrowidéNone.

Observação

Insere emWITHOUT ROWIDas tabelas não são registradas.

Alterado na versão 3.6: Adicionado suporte para oREPLACEdeclaração.

Contagem de linhas

Atributo somente leitura que fornece o número de linhas modificadas paraINSERT, UPDATE, DELETE, eREPLACEdeclarações; é-1para outras declarações, incluindo consultas CTE. Ele é atualizado apenas peloexecutar()eexecutemuitos()métodos, após a execução da instrução até a conclusão. Isso significa que todas as linhas resultantes devem ser buscadas para querowcountser atualizado.

fábrica_de_linhas

Controle como uma linha é obtida distoCursoré representado. SeNone, uma linha é representada como umatupla. Pode ser definido como incluídosqlite3.Linha; ou umchamávelque aceita dois argumentos, umCursorobjeto e otuplede valores de linha e retorna um objeto personalizado que representa uma linha do SQLite.

O padrão é o quêConexão.row_factoryfoi definido para quando oCursorfoi criado. Atribuir a este atributo não afetaConexão.row_factoryda conexão dos pais.

VerComo criar e usar fábricas de linhaspara mais detalhes.

Objetos de linha

aulasqlite3.Linha

ARowinstância serve como um altamente otimizadofábrica_de_linhasparaConexãoobjetos. Ele suporta iteração, teste de igualdade,comprimento(), emapeamentoacesso por nome de coluna e índice.

DoisRowobjetos são comparados como iguais se tiverem nomes de coluna e valores idênticos.

VerComo criar e usar fábricas de linhaspara mais detalhes.

chaves()

Retornar umlistaaaaaaaade nomes de colunas comocordas. Imediatamente após uma consulta, é o primeiro membro de cada tupla emCursor.descrição.

Alterado na versão 3.5: Adicionado suporte para fatiamento.

Objetos Blob

aulasqlite3.Blob

Adicionado na versão 3.11.

AManchainstância é umaobjeto semelhante a um arquivoque pode ler e escrever dados em um SQLite BLOB. Chamadalen(bolha)para obter o tamanho (número de bytes) do blob. Use índices efatiaspara acesso direto aos dados do blob.

Use oManchacomo umgerenciador de contextopara garantir que a alça do blob esteja fechada após o uso.

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE test(blob_col blob)")
con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# Write to our blob, using two write operations:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # Modify the first and last bytes of our blob
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Read the contents of our blob
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

print(greeting)  # outputs "b'Hello, world!'"
con.close()

fechar()

Feche o blob.

O blob ficará inutilizável a partir deste ponto em diante. UmErro(ou subclasse) uma exceção será gerada se qualquer outra operação for tentada com o blob.

ler(comprimento=-1, /)

Lercomprimentobytes de dados do blob na posição de deslocamento atual. Se o fim do blob for alcançado, os dados até EOF serão retornados. Quandocomprimentonão é especificado ou é negativo,ler()lerei até o final do blob.

escrever(dados, /)

Escreverdadospara o blob no deslocamento atual. Esta função não pode alterar o comprimento do blob. Escrever além do final do blob aumentaráValorErro.

dizer()

Retorna a posição de acesso atual do blob.

procurar(desvio, origem=os.SEEK_SET, /)

Defina a posição de acesso atual do blob paradesvio. Oorigemo argumento padrão éos.SEEK_SET(posicionamento absoluto do blob). Outros valores paraorigemsãoos.SEEK_CUR(procurar em relação à posição atual) eos.SEEK_END(procurar em relação ao fim do blob).

Objetos PrepareProtocol

aulasqlite3.PrepareProtocol

O único propósito do tipo PrepareProtocol é atuar como umPEP 246protocolo de adaptação de estilo para objetos que podemadaptar-separatipos nativos de SQLite.

Exceções

A hierarquia de exceções é definida pela DB-API 2.0 (PEP 249).

exceçãosqlite3.Aviso

Esta exceção não é atualmente levantada pelosqlite3módulo, mas pode ser gerado por aplicativos que usamsqlite3, por exemplo, se uma função definida pelo usuário truncar dados durante a inserção.Warningé uma subclasse deExceção.

exceçãosqlite3.Erro

A classe base das outras exceções neste módulo. Use isso para capturar todos os erros com um únicoexcetodeclaração.Erroré uma subclasse deExceção.

Se a exceção tiver origem na biblioteca SQLite, os dois atributos a seguir serão adicionados à exceção:

sqlite_código_de_erro

O código de erro numérico doAPI do SQLite

Adicionado na versão 3.11.

sqlite_nome_do_erro

O nome simbólico do código de erro numérico doAPI do SQLite

Adicionado na versão 3.11.

exceçãosqlite3.Erro de interface

Exceção gerada por uso indevido da API C de baixo nível do SQLite. Em outras palavras, se essa exceção for gerada, provavelmente indica um bug nosqlite3módulo.InterfaceErroré uma subclasse deErro.

exceçãosqlite3.Erro de banco de dados

Exceção gerada para erros relacionados ao banco de dados. Isso serve como exceção base para vários tipos de erros de banco de dados. Ela é gerada apenas implicitamente por meio de subclasses especializadas.DatabaseErroré uma subclasse deErro.

exceçãosqlite3.Erro de Dados

Exceção gerada para erros causados ​​por problemas com os dados processados, como valores numéricos fora do intervalo e strings muito longas.DataErroré uma subclasse deErro de banco de dados.

exceçãosqlite3.Erro Operacional

Exceção gerada para erros que são relacionados à operação do banco de dados, e não necessariamente sob o controle do programador. Por exemplo, o caminho do banco de dados não foi encontrado, ou uma transação não pôde ser processada.OperationalErroré uma subclasse deErro de banco de dados.

exceçãosqlite3.Erro de integridade

Exceção gerada quando a integridade relacional do banco de dados é afetada, por exemplo, uma verificação de chave estrangeira falha. É uma subclasse deErro de banco de dados.

exceçãosqlite3.Erro Interno

Exceção gerada quando o SQLite encontra um erro interno. Se isso for gerado, pode indicar que há um problema com a biblioteca SQLite de tempo de execução.InternalErroré uma subclasse deErro de banco de dados.

exceçãosqlite3.Erro de programação

Exceção levantada parasqlite3Erros de programação de API, por exemplo, fornecer o número errado de ligações a uma consulta ou tentar operar em uma consulta fechadaConexão. ProgrammingErroré uma subclasse deErro de banco de dados.

exceçãosqlite3.Erro não suportado

Exceção gerada caso um método ou API de banco de dados não seja suportado pela biblioteca SQLite subjacente. Por exemplo, definindodeterminísticoparaTrueemcriar_função(), se a biblioteca SQLite subjacente não suportar funções determinísticas.NotSupportedErroré uma subclasse deErro de banco de dados.

Tipos SQLite e Python

O SQLite oferece suporte nativo aos seguintes tipos:NULL, INTEGER, REAL, TEXT, BLOB.

Os seguintes tipos Python podem ser enviados ao SQLite sem nenhum problema:

É assim que os tipos SQLite são convertidos em tipos Python por padrão:

O sistema de tipos dosqlite3O módulo é extensível de duas maneiras: você pode armazenar tipos Python adicionais em um banco de dados SQLite viaadaptadores de objetos, e você pode deixar osqlite3módulo converte tipos SQLite em tipos Python viaconversores.

Adaptadores e conversores padrão (obsoleto)

Observação

Os adaptadores e conversores padrão estão obsoletos a partir do Python 3.12. Em vez disso, use oReceitas de adaptadores e conversorese adaptá-los às suas necessidades.

Os adaptadores e conversores padrão obsoletos consistem em:

• Um adaptador paradatahora.dataobjetos paracordasemISO 8601formatar.

• Um adaptador paradata e hora.data e horaobjetos para strings no formato ISO 8601.

• Um conversor paradeclaradotipos de “data” paradatahora.dataobjetos.

• Um conversor para tipos de “timestamp” declarados paradata e hora.data e horaobjetos. As partes fracionárias serão truncadas para 6 dígitos (precisão de microssegundos).

Observação

O conversor “timestamp” padrão ignora os deslocamentos UTC no banco de dados e sempre retorna um ingênuodata e hora.data e horaobjeto. Para preservar os deslocamentos UTC em carimbos de data/hora, deixe os conversores desabilitados ou registre um conversor com reconhecimento de deslocamento comregistrar_conversor().

Obsoleto desde a versão 3.12.

Interface da Linha de comando

Osqlite3O módulo pode ser invocado como um script, usando o interpretador-mswitch, para fornecer um shell SQLite simples. A assinatura do argumento é a seguinte:

python -m sqlite3 [-h] [-v] [filename] [sql]

Tipo.quitou CTRL-D para sair do shell.

-h, --ajuda

Imprima a ajuda da CLI.

-v, --versão

Imprima a versão da biblioteca SQLite subjacente.

Adicionado na versão 3.12.

Guias de instruções

Como usar marcadores de posição para vincular valores em consultas SQL

As operações SQL geralmente precisam usar valores de variáveis ​​Python. No entanto, tenha cuidado ao usar operações de string do Python para montar consultas, pois elas são vulneráveis ​​aAtaques de injeção de SQL. Por exemplo, um invasor pode simplesmente fechar a aspa simples e injetarOR TRUEpara selecionar todas as linhas:

>>>

>>> # Never do this -- insecure!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
>>> cur.execute(sql)

Em vez disso, use a substituição de parâmetros da DB-API. Para inserir uma variável em uma string de consulta, use um placeholder na string e substitua os valores reais na consulta, fornecendo-os como umtuplade valores para o segundo argumento do cursorexecutar()método.

Uma instrução SQL pode usar um dos dois tipos de placeholders: pontos de interrogação (estilo qmark) ou placeholders nomeados (estilo nomeado). Para o estilo qmark,parâmetrosdeve ser umseqüênciacujo comprimento deve corresponder ao número de espaços reservados, ou umErro de programaçãoé levantado. Para o estilo nomeado,parâmetrosdeve ser uma instância de umditado(ou uma subclasse), que deve conter chaves para todos os parâmetros nomeados; quaisquer itens extras são ignorados. Aqui está um exemplo de ambos os estilos:

con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE lang(name, first_appeared)")

# This is the named style used with executemany():
data = (
    {"name": "C", "year": 1972},
    {"name": "Fortran", "year": 1957},
    {"name": "Python", "year": 1991},
    {"name": "Go", "year": 2009},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

# This is the qmark style used in a SELECT query:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()

Observação

PEP 249marcadores numéricos sãonãosuportados. Se usados, eles serão interpretados como placeholders nomeados.

Como adaptar tipos Python personalizados aos valores SQLite

O SQLite suporta apenas um conjunto limitado de tipos de dados nativamente. Para armazenar tipos Python personalizados em bancos de dados SQLite,adaptareles para um dosTipos Python que o SQLite entende nativamente.

Existem duas maneiras de adaptar objetos Python aos tipos SQLite: deixar que seu objeto se adapte ou usar umadaptador chamável. O último terá precedência sobre o primeiro. Para uma biblioteca que exporta um tipo personalizado, pode fazer sentido habilitar esse tipo para se adaptar. Como um desenvolvedor de aplicativos, pode fazer mais sentido assumir o controle direto registrando funções de adaptador personalizadas.

Como escrever objetos adaptáveis

Suponha que temos umPointclasse que representa um par de coordenadas,xey, em um sistema de coordenadas cartesianas. O par de coordenadas será armazenado como uma sequência de texto no banco de dados, usando um ponto e vírgula para separar as coordenadas. Isso pode ser implementado adicionando um__conform__(self, protocol)método que retorna o valor adaptado. O objeto passado paraprotocoloserá do tipoPrepararProtocolo.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return f"{self.x};{self.y}"

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()

Como registrar adaptadores chamáveis

A outra possibilidade é criar uma função que converta o objeto Python para um tipo compatível com SQLite. Esta função pode então ser registrada usandoregistrar_adaptador().

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

def adapt_point(point):
    return f"{point.x};{point.y}"

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()

Como converter valores SQLite em tipos Python personalizados

Escrever um adaptador permite que você convertadetipos Python personalizadosparaValores SQLite. Para poder converterdeValores SQLiteparatipos Python personalizados, usamosconversores.

Vamos voltar para oPointclasse. Armazenamos as coordenadas x e y separadas por ponto e vírgula como strings no SQLite.

Primeiro, definiremos uma função conversora que aceita a string como parâmetro e constrói umaPointobjeto dele.

Observação

As funções do conversor sãosemprepassou umbytesobjeto, não importa o tipo de dado SQLite subjacente.

def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)

Agora precisamos contarsqlite3quando deve converter um determinado valor SQLite. Isso é feito ao conectar-se a um banco de dados, usando odetectar_tiposparâmetro deconectar(). Existem três opções:

• Implícito: conjuntodetectar_tiposparaANALISAR_DECLTYPES

• Explícito: conjuntodetectar_tiposparaANALISAR_NOMES_DE_COLUNAS

• Ambos: conjuntodetectar_tiposparasqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES. Os nomes das colunas têm precedência sobre os tipos declarados.

O exemplo a seguir ilustra as abordagens implícita e explícita:

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

def adapt_point(point):
    return f"{point.x};{point.y}"

def convert_point(s):
    x, y = list(map(float, s.split(b";")))
    return Point(x, y)

# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.execute("CREATE TABLE test(p point)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute("SELECT p FROM test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.execute("CREATE TABLE test(p)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute('SELECT p AS "p [point]" FROM test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()

Receitas de adaptadores e conversores

Esta seção mostra receitas para adaptadores e conversores comuns.

import datetime
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return datetime.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return datetime.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return datetime.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)

Como usar métodos de atalho de conexão

Usando oexecutar(), executemuitos(), eexecutescript()métodos doConexãoclasse, seu código pode ser escrito de forma mais concisa porque você não precisa criar o (frequentemente supérfluo)Cursorobjetos explicitamente. Em vez disso, oCursoros objetos são criados implicitamente e esses métodos de atalho retornam os objetos do cursor. Dessa forma, você pode executar umSELECTdeclaração e iterar sobre ela diretamente usando apenas uma única chamada noConexãoobjeto.

# Create and fill the table.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(name, first_appeared)")
data = [
    ("C++", 1985),
    ("Objective-C", 1984),
]
con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

# Print the table contents
for row in con.execute("SELECT name, first_appeared FROM lang"):
    print(row)

print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")

# close() is not a shortcut method and it's not called automatically;
# the connection object should be closed manually
con.close()

Como usar o gerenciador de contexto de conexão

AConexãoobjeto pode ser usado como um gerenciador de contexto que automaticamente confirma ou reverte transações abertas ao sair do corpo do gerenciador de contexto. Se o corpo docomdeclaração termina sem exceções, a transação é confirmada. Se esta confirmação falhar, ou se o corpo dawithdeclaração gera uma exceção não capturada, a transação é revertida. Seconfirmação automáticaéFalse, uma nova transação é implicitamente aberta após a confirmação ou reversão.

Se não houver nenhuma transação aberta ao sair do corpo dowithdeclaração, ou seconfirmação automáticaéTrue, o gerenciador de contexto não faz nada.

Observação

O gerenciador de contexto não abre implicitamente uma nova transação nem fecha a conexão. Se você precisar de um gerenciador de contexto de fechamento, considere usarcontextlib.fechamento().

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() is called after the with block finishes with an exception,
# the exception is still raised and must be caught
try:
    with con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
con.close()

Como trabalhar com URIs do SQLite

Alguns truques úteis de URI incluem:

• Abra um banco de dados no modo somente leitura:

>>>

>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE readonly(data)")
Traceback (most recent call last):
OperationalError: attempt to write a readonly database

• Não crie implicitamente um novo arquivo de banco de dados se ele ainda não existir; isso aumentaráErro operacionalse não for possível criar um novo arquivo:

>>>

>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file

• Crie um banco de dados compartilhado nomeado na memória:

db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
    con1.execute("CREATE TABLE shared(data)")
    con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)

con1.close()
con2.close()

Mais informações sobre esse recurso, incluindo uma lista de parâmetros, podem ser encontradas emDocumentação do URI do SQLite.

Como criar e usar fábricas de linhas

Por padrão,sqlite3representa cada linha como umatupla. Se umtuplenão atende às suas necessidades, você pode usar osqlite3.Linhaclasse ou um costumefábrica_de_linhas.

Enquantorow_factoryexiste como um atributo tanto noCursore aConexão, é recomendável definirConexão.row_factory, então todos os cursores criados a partir da conexão usarão a mesma fábrica de linhas.

Rowfornece acesso nomeado indexado e sem distinção entre maiúsculas e minúsculas às colunas, com sobrecarga de memória mínima e impacto no desempenho em umtuple. UsarRowcomo uma fábrica de linha, atribua-a aorow_factoryatributo:

>>>

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row

As consultas agora retornamRowobjetos:

>>>

>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0]         # Access by index.
'Earth'
>>> row["name"]    # Access by name.
'Earth'
>>> row["RADIUS"]  # Column names are case-insensitive.
6378
>>> con.close()

Observação

OFROMcláusula pode ser omitida noSELECTdeclaração, como no exemplo acima. Nesses casos, o SQLite retorna uma única linha com colunas definidas por expressões, por exemplo, literais, com os aliases fornecidosexpr AS alias.

Você pode criar um personalizadofábrica_de_linhasque retorna cada linha como umditado, com nomes de colunas mapeados para valores:

def dict_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    return {key: value for key, value in zip(fields, row)}

Com ele, as consultas agora retornam umdictem vez de umtuple:

>>>

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
...     print(row)
{'a': 1, 'b': 2}
>>> con.close()

A seguinte fábrica de linhas retorna umtupla nomeada:

from collections import namedtuple

def namedtuple_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    cls = namedtuple("Row", fields)
    return cls._make(row)

namedtuple_factory()pode ser usado da seguinte forma:

>>>

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0]  # Indexed access.
1
>>> row.b   # Attribute access.
2
>>> con.close()

Com alguns ajustes, a receita acima pode ser adaptada para usar umclasse de dados, ou qualquer outra classe personalizada, em vez de umnomeado duplo.

Como lidar com codificações de texto não UTF-8

Por padrão,sqlite3usosstrpara adaptar os valores do SQLite com oTEXTtipo de dados. Isso funciona bem para texto codificado em UTF-8, mas pode falhar para outras codificações e UTF-8 inválido. Você pode usar um personalizadofábrica_de_textospara lidar com tais casos.

Por causa do SQLitedigitação flexível, não é incomum encontrar colunas de tabela com oTEXTtipo de dados contendo codificações não UTF-8, ou mesmo dados arbitrários. Para demonstrar, vamos supor que temos um banco de dados com texto codificado ISO-8859-2 (Latin-2), por exemplo, uma tabela de entradas de dicionário tcheco-inglês. Supondo que agora temos umConexãoinstânciaconconectado a este banco de dados, podemos decodificar o texto codificado em latim-2 usando estefábrica_de_textos:

con.text_factory = lambda data: str(data, encoding="latin2")

Para UTF-8 inválido ou dados arbitrários armazenados emTEXTcolunas da tabela, você pode usar a seguinte técnica, emprestada doUnicode HOWTO:

con.text_factory = lambda data: str(data, errors="surrogateescape")

Observação

Osqlite3A API do módulo não suporta strings contendo substitutos.

Veja também

Unicode HOWTO

Explicação

Controle de transações

sqlite3oferece vários métodos para controlar se, quando e como as transações do banco de dados são abertas e fechadas.Controle de transações via atributo autocommité recomendado, enquantoControle de transações por meio do atributo isolation_levelmantém o comportamento pré-Python 3.12.

Controle de transações viaautocommitatributo

A forma recomendada de controlar o comportamento das transações é por meio deConexão.autocommitatributo, que deve ser preferencialmente definido usando oconfirmação automáticaparâmetro deconectar().

É sugerido definirconfirmação automáticaparaFalse, que implicaPEP 249-controle de transações compatível. Isso significa:

• sqlite3garante que uma transação esteja sempre aberta, portantoconectar(), Conexão.commit(), eConexão.rollback()abrirá implicitamente uma nova transação (imediatamente após fechar a pendente, para as duas últimas).sqlite3usosBEGIN DEFERREDdeclarações ao abrir transações.

• As transações devem ser confirmadas explicitamente usandocommit().

• As transações devem ser revertidas explicitamente usandorollback().

• Uma reversão implícita é executada se o banco de dados estiverfechar()-ed com alterações pendentes.

Definirconfirmação automáticaparaTruepara habilitar o SQLitemodo autocommit. Neste modo,Conexão.commit()eConexão.rollback()não tem efeito. Observe que o modo autocommit do SQLite é diferente doPEP 249-compatívelConexão.autocommitatributo; usarConexão.em_transaçãopara consultar o modo autocommit de baixo nível do SQLite.

Definirconfirmação automáticaparaCONTROLE_DE_TRANSAÇÃO_LEGADOdeixar o comportamento de controle de transações para oConexão.nível_isolamentoatributo. VejaControle de transações por meio do atributo isolation_levelPara maiores informações.

Controle de transações viaisolation_levelatributo

Observação

A forma recomendada de controlar as transações é por meio doconfirmação automáticaatributo. VejaControle de transações via atributo autocommit.

SeConexão.autocommitestá configurado paraCONTROLE_DE_TRANSAÇÃO_LEGADO(o padrão), o comportamento da transação é controlado usando oConexão.nível_isolamentoatributo. Caso contrário,isolation_levelnão tem efeito.

Se o atributo de conexãonível_de_isolamentonão éNone, novas transações são implicitamente abertas antesexecutar()eexecutemuitos()executaINSERT, UPDATE, DELETE, ouREPLACEinstruções; para outras instruções, nenhuma manipulação de transação implícita é realizada. Use ocomprometer-se()ereverter()métodos para confirmar e reverter transações pendentes, respectivamente. Você pode escolher o subjacenteComportamento de transação do SQLite— isto é, se e que tipo deBEGINdeclaraçõessqlite3executa implicitamente – por meio donível_de_isolamentoatributo.

Senível_de_isolamentoestá configurado paraNone, nenhuma transação é implicitamente aberta. Isso deixa a biblioteca SQLite subjacente emmodo autocommit, mas também permite que o usuário execute seu próprio tratamento de transações usando instruções SQL explícitas. O modo autocommit da biblioteca SQLite subjacente pode ser consultado usando oem_transaçãoatributo.

Oexecutescript()O método implicitamente confirma qualquer transação pendente antes da execução do script SQL fornecido, independentemente do valor denível_de_isolamento.

Alterado na versão 3.6:sqlite3usado para implicitamente fazer commit de uma transação aberta antes de instruções DDL. Este não é mais o caso.

Alterado na versão 3.12: A maneira recomendada de controlar transações agora é por meio doconfirmação automáticaatributo.