Condivisione della tecnologia

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

sqlite3 — Interfaccia DB-API 2.0 per database SQLite — Documentazione Python 3.12.4

sqlite3— Interfaccia DB-API 2.0 per database SQLite
sqlite3 — Interfaccia DB-API 2.0 per database SQLite

Codice sorgente: Lib/sqlite3/    Posizione del codice sorgente：Libreria/sqlite3/

SQLite è una libreria C che fornisce un database leggero basato su disco che non richiede un processo server separato e consente di accedere al database utilizzando una variante non standard del linguaggio di query SQL. Alcune applicazioni possono utilizzare SQLite per l'archiviazione interna dei dati. È anche possibile prototipare un'applicazione utilizzando SQLite e quindi trasferire il codice su un database più grande come PostgreSQL o Oracle.
SQLite è una libreria in linguaggio C che fornisce un database leggero basato su disco che non richiede un processo server separato e consente l'accesso al database utilizzando una variante non standard del linguaggio di query SQL. Alcune applicazioni possono utilizzare SQLite per l'archiviazione dei dati interni. Inoltre, puoi utilizzare SQLite per prototipare un'applicazione e quindi migrare il codice su un database di grandi dimensioni come PostgreSQL o Oracle.

ILsqlite3modulo è stato scritto da Gerhard Häring. Fornisce un'interfaccia SQL conforme alla specifica DB-API 2.0 descritta daPEP249e richiede SQLite 3.7.15 o versione successiva.
modulo sqlite3 Scritto da Gerhard Häring. Fornisce un'interfaccia SQL conforme alla specifica DB-API 2.0 descritta da PEP 249 e richiede SQLite versione 3.7.15 o successiva.

Il presente documento comprende quattro sezioni principali: Il presente documento comprende principalmente le seguenti quattro sezioni principali

• Esercitazioneinsegna come usare ilsqlite3modulo.EsercitazioneLa parte insegna come utilizzare il modulo sqlite3.

• Riferimentodescrive le classi e le funzioni definite da questo modulo.
  fare riferimento aLa sezione descrive le classi e le funzioni definite da questo modulo.

• Guide pratichespiega in dettaglio come gestire compiti specifici.
  Guida operativaLe sezioni descrivono in dettaglio come gestire attività specifiche.

• Spiegazionefornisce informazioni approfondite sul controllo delle transazioni.
  spiegareQuesta sezione fornisce un'introduzione approfondita alle conoscenze di base del controllo delle transazioni.

Guarda anche

Italiano: Italiano: https://www.sqlite.org

Pagina web di SQLite; la documentazione descrive la sintassi e i tipi di dati disponibili per il dialetto SQL supportato.
Pagina web di SQLite; la sua documentazione descrive la sintassi dei dialetti SQL supportati e i tipi di dati disponibili.

Esercitazione SQLEsercitazione sull'SQL

Tutorial, riferimenti ed esempi per apprendere la sintassi SQL.
Tutorial, riferimenti ed esempi per apprendere la sintassi SQL.

PEP249- Specifica API del database 2.0 PEP 249 - Specifica API del database 2.0

PEP scritto da Marc-André Lemburg PEP scritto da Marc-André Lemburg.

EsercitazioneEsercitazione

In questo tutorial creerai un database di Film dei Monty Python utilizzando le basisqlite3funzionalità. Presuppone una comprensione fondamentale dei concetti di database, tra cuicursoriEtransazioni.
In questo tutorial utilizzerai le funzionalità di base di sqlite3 per creare un database sui film di Monty Python. Questo tutorial presuppone che tu abbia una conoscenza di base dei concetti di database, inclusi cursori e transazioni.

Per prima cosa, dobbiamo creare un nuovo database e aprire una connessione al database per consentiresqlite3per lavorarci. Chiamasqlite3.connetti()per creare una connessione al databasetutorial.dbnella directory di lavoro corrente, creandolo implicitamente se non esiste:
Per prima cosa dobbiamo creare un nuovo database e aprire una connessione al database in modo che sqlite3 possa interagire con esso. Chiama sqlite3.connect() per creare una connessione al database tutorial.db nella directory di lavoro corrente, creandola implicitamente e delicatamente automaticamente se il database non esiste:

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

Il ritornoConnessioneoggettoconrappresenta la connessione al database su disco.
L'oggetto Connection restituito (denominato con in questo caso) rappresenta la connessione al database su disco.

In modo da eseguire istruzioni SQL Erecuperare i risultati dalle query SQL, dovremo utilizzare un cursore del database. Chiamatacon.cursore()per creare ilCursoreeeeeeeeeeeeeeeeeeeeeeeeeeee:
Per eseguire istruzioni SQL e ottenere risultati dalle query SQL, dobbiamo utilizzare i cursori del database. Chiama con.cursor() per creare un cursore:

cur = con.cursor()

Ora che abbiamo una connessione al database e un cursore, possiamo creare una tabella del databasemoviecon colonne per titolo, anno di rilascio e punteggio di revisione. Per semplicità, possiamo semplicemente usare i nomi delle colonne nella dichiarazione della tabella, grazie adigitazione flessibilecaratteristica di SQLite, la specificazione dei tipi di dati è facoltativa. Eseguire ilCREATE TABLEdichiarazione tramite chiamatacur.esegui(...):
Ora che abbiamo la connessione al database e il cursore, possiamo creare una tabella del database denominata film con colonne come titolo, anno di rilascio e punteggio della recensione. Per semplificare le cose, possiamo utilizzare i nomi delle colonne direttamente nella dichiarazione della tabella: specificare il tipo di dati è facoltativo grazie alla funzionalità di digitazione flessibile di SQLite. Esegui l'istruzione CREATE TABLE chiamando cur.execute(...):

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

Possiamo verificare che la nuova tabella sia stata creata interrogando ilsqlite_mastertabella integrata in SQLite, che ora dovrebbe contenere una voce permoviedefinizione della tabella (vedereLa tabella dello schemaper i dettagli). Eseguire la query chiamandocur.esegui(...), assegna il risultato arese chiamares.fetchone()per recuperare la riga risultante:
Possiamo verificare che la nuova tabella sia stata creata eseguendo una query sulla tabella sqlite_master incorporata di SQLite, che ora dovrebbe contenere voci per la definizione della tabella del film (vedere la tabella dello schema per i dettagli). Esegui la query chiamando cur.execute(...), assegna i risultati a res e chiama res.fetchone() per ottenere le righe dei risultati:

>>>

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

Possiamo vedere che la tabella è stata creata, poiché la query restituisce untuplacontenente il nome della tabella. Se interroghiamosqlite_masterper una tabella inesistentespam, res.fetchone()sarà di ritornoNone:
Possiamo vedere che la tabella è stata creata con successo perché la query ha restituito una tupla contenente il nome della tabella. Se interroghiamo sqlite_master per una tabella inesistente (come spam), res.fetchone() restituirà None.

>>>

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

Ora, aggiungi due righe di dati forniti come letterali SQL eseguendo unINSERTdichiarazione, ancora una volta chiamandocur.esegui(...):
Ora aggiungi due righe di dati, fornite come valori letterali SQL, eseguendo un'istruzione INSERT (chiamando nuovamente cur.execute(...)):

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

ILINSERTistruzione apre implicitamente una transazione, che deve essere confermata prima che le modifiche vengano salvate nel database (vedereControllo delle transazioniper dettagli). Chiamatacon.commit()sull'oggetto di connessione per eseguire il commit della transazione:
L'istruzione INSERT avvia implicitamente e automaticamente una transazione di cui è necessario eseguire il commit prima che le modifiche vengano salvate nel database (vedere Controllo delle transazioni per i dettagli). Chiama con.commit() sull'oggetto connessione per confermare la transazione:

con.commit()

Possiamo verificare che i dati siano stati inseriti correttamente eseguendo unSELECTquery. Usa il ormai familiarecur.esegui(...)per assegnare il risultato arese chiamares.fetchall()per restituire tutte le righe risultanti:
Possiamo verificare che i dati siano stati inseriti correttamente eseguendo una query SELECT. Assegna i risultati a res utilizzando l'ormai familiare cur.execute(...) e chiama res.fetchall() per restituire tutte le righe dei risultati:

>>>

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

Il risultato è unelencodi duetuples, uno per riga, ognuno contenente la rigascorevalore.
Il risultato è un elenco di due tuple, una per ogni riga e ciascuna tupla contenente il valore del punteggio per quella riga.

Ora, inserisci altre tre righe chiamandocur.executemany(...):
Ora inserisci altre tre righe di dati chiamando 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.

Notare che?i segnaposto vengono utilizzati per associaredataalla query. Usa sempre segnaposto invece diformattazione della stringaper associare i valori Python alle istruzioni SQL, per evitareAttacchi di iniezione SQL(VedereCome utilizzare i segnaposto per associare i valori nelle query SQLper ulteriori dettagli).
Tieni presente che il segnaposto ? viene utilizzato per associare i dati alla query. Utilizza sempre i segnaposto invece della formattazione delle stringhe per associare i valori Python nelle istruzioni SQL per evitare attacchi SQL injection (vedi "Come associare valori utilizzando i segnaposto nelle query SQL" per maggiori dettagli).

Possiamo verificare che le nuove righe siano state inserite eseguendo unSELECTquery, questa volta iterando sui risultati della query:
Possiamo verificare che la nuova riga sia stata inserita eseguendo una query SELECT, questa volta itereremo sui risultati della query:

>>>

>>> 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")

Ogni riga è composta da due elementituplaDi(year, title), corrispondenti alle colonne selezionate nella query.
Ogni riga è una tupla contenente due elementi (anno, titolo), che corrisponde alla colonna selezionata nella query.

Infine, verifica che il database sia stato scritto sul disco chiamandocon.chiudi()per chiudere la connessione esistente, aprirne una nuova, creare un nuovo cursore, quindi interrogare il database:
Infine, chiamandocon.close() per chiudere la connessione al database esistente e garantire che il database sia stato scritto su disco. Quindi, apri una nuova connessione, crea un nuovo cursore ed esegui una query sul database per verificare che i dati siano stati scritti correttamente.

>>>

>>> 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()

Ora hai creato un database SQLite utilizzandosqlite3modulo, inseriva dati e recuperava valori da essi in vari modi.
ora hai usatosqlite3 Il modulo crea un database SQLite e inserisce e recupera i dati da esso in vari modi [Retrieve? 】Il valore.

Guarda ancheGuarda anche

• Guide praticheper ulteriori approfondimenti: Come associare i valori utilizzando i segnaposto nelle query SQL:

  • Come utilizzare i segnaposto per associare i valori nelle query SQL
    Come associare i valori utilizzando i segnaposto nelle query SQL:

  • Come adattare i tipi Python personalizzati ai valori SQLite
    Come adattare un tipo Python personalizzato a un valore SQLite:

  • Come convertire i valori SQLite in tipi Python personalizzati
    Come convertire il valore SQLite in un tipo Python personalizzato:

  • Come utilizzare il gestore del contesto di connessione
    Come utilizzare il gestore del contesto di connessione:

  • Come creare e utilizzare le row factory
    Come creare e utilizzare le fabbriche di riga:

• Spiegazioneper informazioni approfondite sul controllo delle transazioni.
  Una spiegazione approfondita del controllo delle transazioni:

RiferimentoDescrizione dei parametri：

Funzioni del modulo

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)

Apri una connessione a un database SQLite Questa funzione viene utilizzata per aprire una connessione a un database SQLite.

Parametri:

• Banca dati (oggetto simile a un percorso) – Il percorso del file di database da aprire. È possibile passare":memory:"per creare unDatabase SQLite esistente solo in memoriae aprire una connessione ad esso.database (path-like object) 
  database (oggetto simile a un percorso) — Questo è il percorso del file di database da aprire.Puoi passare":memory:"per creare un database SQLite in memoria e aprire un .database (oggetto simile a un percorso) ad esso collegato.

• tempo scaduto (galleggiante) – Quanti secondi la connessione deve attendere prima di sollevare unErrore operativoquando una tabella è bloccata. Se un'altra connessione apre una transazione per modificare una tabella, quella tabella sarà bloccata finché la transazione non verrà confermata. Cinque predefiniti secondi.timeout (float) — La connessione si interrompe quando il tavolo è bloccatoOperationalError Quanti secondi bisogna aspettare prima. Se un'altra connessione apre una transazione per modificare la tabella, la tabella verrà bloccata finché la transazione non verrà confermata. Il valore predefinito è cinque secondi.

• rileva_tipi (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) – Controllare se e come tipi di dati nonsupportato nativamente da SQLitevengono cercati per essere convertiti in tipi Python, utilizzando i convertitori registrati conregistro_convertitore()Impostalo su qualsiasi combinazione (utilizzando|, bit a bit o) diPARSE_DECLTYPESEPARSE_NOMI_COLLper abilitarlo. Nomi delle colonne ha la precedenza sutipi dichiarati se entrambi i flag sono impostati. I tipi non possono essere rilevati per i campi generati (ad esempiomax(data)), anche quando ilrileva_tipiil parametro è impostato;strverrà restituito invece. Per impostazione predefinita (0), il rilevamento del tipo è disabilitato.
  detect_types (int)— Controlla se e come vengono trovati per l'uso i tipi di dati che SQLite non supporta nativamenteregister_converter() I convertitori registrati li convertono in tipi Python.impostarlo suPARSE_DECLTYPESEPARSE_COLNAMESqualsiasi combinazione di (utilizzando bit per bit o| ) per abilitare questa funzione.Se entrambi i flag sono impostati, alloraElenco avrà la precedenzadichiarazione tipo.Per le regioni generate, questi tipi non possono essere rilevati (ad es.max(data)), anche se impostatodetect_typesparametri; invece ritorneràstr tipo. Per impostazione predefinita (0), il rilevamento del tipo è disabilitato.

Inseriscilo qui
In questo paragrafo inglese, chi è il soggetto di "sono ammirati"?
In questo paragrafo inglese, l'argomento "sono ammirati" sono quei "tipi di dati non supportati nativamente da SQLite (tipi di dati non supportati nativamente da SQLite)".Questa frase significa che utilizzandoregister_converter() Convertitori registrati per trovare e convertire tipi di dati non supportati nativamente da SQLite in tipi Python. Pertanto, i soggetti sono quei tipi di dati specifici che devono essere trovati e convertiti.

• livello di isolamento (str | Nessuno) – Controlla il comportamento di gestione delle transazioni legacy. VedereConnessione.livello_isolamentoEControllo delle transazioni tramite l'attributo isolation_levelper maggiori informazioni. Può essere"DEFERRED"(predefinito),"EXCLUSIVE"O"IMMEDIATE"; ONoneper disabilitare implicitamente l'apertura delle transazioni. Non ha effetto a meno cheConnessione.autocommitè impostato perCONTROLLO_TRANSAZIONE_LEGACY(il predefinito).
  isolation_level(Stringa | Nessuno) – Controllare il comportamento di elaborazione delle transazioni legacy.Per ulteriori informazioni, vedereConnection.isolation_levele "passare".isolation_levelTransazione di controllo della proprietà". Può essere"DEFERRED"(valore di default),"EXCLUSIVE"O"IMMEDIATE";o impostare suNone per disabilitare l'apertura implicita delle transazioni in modo implicito.Salvo cheConnection.autocommitImpostato comeLEGACY_TRANSACTION_CONTROL(impostazione predefinita), altrimenti questa impostazione non ha alcun effetto.

• controlla_stesso_thread (bollo) - SeTrue(predefinito),Errore di programmazioneverrà sollevato se la connessione al database è utilizzata da un thread diverso da quello che l'ha creata. SeFalse, la connessione può essere accessibile in più thread; le operazioni di scrittura potrebbero dover essere serializzate dall'utente per evitare il danneggiamento dei dati. Vederesicurezza del filoper maggiori informazioni.
  check_same_thread(Valore booleano) – Se impostato suTrue(impostazione predefinita), verrà generato quando la connessione al database viene utilizzata da un thread diverso da quello che l'ha creata.ProgrammingError anormale.Se impostato suFalse , più thread possono accedere alla connessione; ma gli utenti potrebbero dover serializzare (continuamente) le operazioni di scrittura per evitare il danneggiamento dei dati.Per ulteriori informazioni, vederethreadsafetyistruzione di.

• fabbrica (Connessione) – Una sottoclasse personalizzata diConnessioneper creare la connessione con, se non è quella predefinitaConnessioneclasse.
  factory(Connessione) – Se non si utilizza l'impostazione predefinitaConnectionclasse, specificare una customConnection Sottoclasse per creare la connessione. Questo parametro permette di personalizzare il comportamento della connessione al database in base a specifiche esigenze o estensioni.

• istruzioni memorizzate nella cache (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) – Il numero di affermazioni chesqlite3dovrebbe memorizzare nella cache interna questa connessione, per evitare un sovraccarico di analisi. Per impostazione predefinita, 128 istruzioni.
  cached_statements(interno) – sqlite3 Il numero di istruzioni che devono essere memorizzate nella cache internamente per questa connessione per evitare il sovraccarico di analisi. Per impostazione predefinita, vengono memorizzate nella cache 128 istruzioni. Questo parametro consente di regolare la dimensione della cache per ottimizzare le prestazioni o l'utilizzo della memoria.

• l'uomo (bollo) – Se impostato suTrue, Banca dativiene interpretato come un URI con un percorso file e una stringa di query facoltativa. La parte dello schemadovereEssere"file:", e il percorso può essere relativo o assoluto. La stringa di query consente di passare parametri a SQLite, abilitando variCome lavorare con gli URI SQLite.
  uri(bollo) – Se impostato suTrue,Madatabase Interpretato come URI (Uniform Resource Identifier) ​​con un percorso file e una stringa di query facoltativa. La parte dello schema dell'URIdovere è "file:", il percorso può essere relativo o assoluto. Le stringhe di query consentono di passare i parametri a SQLite, consentendo vari modi di lavorare con gli URI SQLite. Ciò consente opzioni di connessione al database più complesse, come l'impostazione della modalità di sola lettura, la specifica della dimensione della cache, ecc.

• autocommissione (bollo) - ControlloPEP249comportamento di gestione delle transazioni. VedereConnessione.autocommitEControllo delle transazioni tramite l'attributo autocommitper maggiori informazioni.autocommissioneattualmente il valore predefinito èCONTROLLO_TRANSAZIONE_LEGACYL'impostazione predefinita cambierà inFalsein una futura versione di Python.
  autocommit(bollo) – Controllare il comportamento di elaborazione delle transazioni in conformità con PEP 249.Per ulteriori informazioni, vedereConnection.autocommit e "Controllo delle transazioni tramite l'attributo autocommit". attualmente,autocommitIl valore predefinito è impostato suLEGACY_TRANSACTION_CONTROL , il che significa che segue il comportamento di controllo delle transazioni legacy della specifica API del database Python (PEP 249).Tuttavia, in una versione futura di Python, l'impostazione predefinita cambierà inFalse, il che significa che le transazioni non vengono confermate automaticamente per impostazione predefinita e richiedono all'utente di controllare esplicitamente l'inizio e la fine della transazione.

Notare che,*I parametri vengono utilizzati nelle definizioni di funzioni come separatori tra argomenti posizionali e parole chiave, significatoautocommitTutti i parametri successivi devono essere parametri parola chiave.

Tipo di ritorno:Tipo di reso： 

Connessione

Solleva unevento di verifica sqlite3.connectcon argomentodatabase.
sqlite3.connect: Quando si usadatabaseParametri generati durante la connessione al database.

Solleva unevento di verifica sqlite3.connect/handlecon argomentoconnection_handle.
sqlite3.connect/handle: Quando la maniglia di connessione (connection_handle) viene generato quando viene creato.

Modificato nella versione 3.4: Aggiunto ill'uomoparametro.
Nella versione 3.4: aggiuntouriParametro che consente di specificare il file di database utilizzando il formato URI.

Modificato nella versione 3.7:Banca datipuò ora essere anche unoggetto simile a un percorso, non solo una stringa.
Nella versione 3.7:databaseI parametri ora possono essere oggetti simili a percorsi invece che semplici stringhe.

Modificato nella versione 3.10: Aggiunto ilsqlite3.connect/handleevento di verifica.
Nella versione 3.10: aggiuntosqlite3.connect/handleEvento di controllo, che viene attivato quando viene creato l'handle di connessione.

Modificato nella versione 3.12: Aggiunto ilautocommissioneparametro.
Nella versione 3.12: aggiuntoautocommitParametri che consentono un controllo più preciso sul comportamento di commit automatico delle transazioni.

istruzione_completa_sqlite3(dichiarazione)

RitornoTruese la stringadichiarazionesembra contenere una o più istruzioni SQL complete. Non viene eseguita alcuna verifica sintattica o analisi di alcun tipo, a parte il controllo che non ci siano stringhe letterali non chiuse e che l'istruzione sia terminata da un punto e virgola.
se stringastatementsembra contenere una o più istruzioni SQL complete, quindi restituisceTrue . Non viene eseguita alcuna convalida o analisi della sintassi oltre al controllo che non vi siano stringhe letterali non chiuse e che l'istruzione termini con un punto e virgola.

Per esempio:Esempio

>>>

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

Questa funzione può essere utile durante l'input dalla riga di comando per determinare se il testo immesso sembra formare un'istruzione SQL completa o se è necessario un input aggiuntivo prima della chiamataeseguire().
Questa funzione può essere utile quando si digita dalla riga di comando, per aiutare a determinare se il testo inserito assomiglia a un'istruzione SQL completa o quando si chiamaexecute()Se è necessario prima un input aggiuntivo.

Vedererunsource()InLib/sqlite3/__main__.pyper un utilizzo nel mondo reale.
Nelle applicazioni pratiche, è possibile fare riferimento aLib/sqlite3/__main__.pymezzorunsource()funzione per comprenderne l'utilizzo.

sqlite3.abilita_callback_tracebacks(bandiera, /)

Abilita o disabilita i traceback di callback. Per impostazione predefinita non otterrai alcun traceback nelle funzioni definite dall'utente, negli aggregati, nei convertitori, nei callback di autorizzazione ecc. Se vuoi eseguirne il debug, puoi chiamare questa funzione conbandieraimpostatoTrue. Successivamente, otterrai i traceback dai callback susistema stderr. UtilizzoFalseper disattivare nuovamente la funzione.
Abilita o disabilita il tracciamento delle richiamate. Per impostazione predefinita, non otterrai alcun traceback nelle funzioni definite dall'utente, nelle funzioni aggregate, nei convertitori, nei callback di autorizzazione, ecc.Se vuoi eseguirne il debug, puoi chiamare questa funzione e sostituireflagImpostato comeTrue .Successivamente, sarai in grado di farlosys.stderr Ottieni informazioni sulla traccia dalla richiamata.utilizzoFalseper disattivare nuovamente questa funzionalità.

Nota

Gli errori nei callback di funzioni definite dall'utente vengono registrati come eccezioni non sollevabili. Utilizzare ungestore del gancio non sollevabileper l'introspezione del callback non riuscito.
Gli errori nei callback delle funzioni definite dall'utente vengono registrati come eccezioni non rilevabili. Utilizzare un gestore di hook non sollevabile per eseguire l'introspezione sui callback non riusciti.

 

Ciò significa che quando si verificano errori nei callback delle funzioni definite dall'utente di SQLite (come funzioni aggregate, funzioni scalari, ecc.), questi errori non vengono generati come le normali eccezioni Python e possono essere rilevati dai blocchi try-eccetto. Invece, vengono catturati da SQLite o dal modulo sqlite3 di Python e registrati in qualche modo (solitamente scritti nel log o nell'output dell'errore standard), ma non interrompono l'esecuzione del programma (a meno che l'errore non sia molto grave).

Per ispezionare ed eseguire il debug di queste eccezioni non catturabili, è possibile impostare un "gestore di hook non catturabili". Questo gestore è una funzione che Python chiama quando si verifica un'eccezione non rilevata, passando le informazioni sull'eccezione come parametro. In questo modo, puoi scrivere codice nella funzione del processore per registrare o verificare queste eccezioni per facilitare la diagnosi del problema.

Tieni presente che l'implementazione specifica può variare a seconda della versione di Python e dei dettagli di implementazione del modulo sqlite3. Pertanto, si consiglia di consultare la documentazione Python più recente o la documentazione del modulo sqlite3 per imparare come impostare e utilizzare il gestore di hook uncatchable.

sqlite3.register_adapter(tipo, adattatore, /)

Registra unadattatore richiamabileper adattare il tipo Pythontipoin un tipo SQLite. L'adattatore viene chiamato con un oggetto Python di tipotipocome unico argomento e deve restituire un valore di atipo che SQLite comprende in modo nativo.
Registra un oggetto richiamabile **adattatore** per la conversione di Pythontype Il tipo è adattato a un tipo che SQLite può comprendere in modo nativo.Questa funzione dell'adattatore richiede atypeUn oggetto di tipo viene chiamato come unico argomento e deve restituire un valore di un tipo supportato nativamente da SQLite.
 

Da notare che il"typetype" potrebbe essere un po' fuorviante, perché in genere non ci riferiamo al file built-in di Pythontype Gli oggetti (ovvero i tipi stessi) vengono archiviati direttamente nel database. Più comunemente, vogliamo adattare oggetti in Python (che potrebbero essere istanze di tipi personalizzati) in un formato che SQLite possa archiviare.Tuttavia, prendendo la frase alla lettera, se ne ha bisognotypeoggetto stesso (anche se questo è raro nella pratica), dovrai scrivere un adattatore per convertirlo in una forma che SQLite possa archiviare, ad esempio una stringa che rappresenta il nome del tipo.

Tuttavia, un caso d'uso più comune riguarda i tipi Python personalizzati o i tipi incorporati comedatetime、decimal.Decimalecc.) scrivere adattatori in modo che possano essere archiviati e recuperati correttamente dal database SQLite.

Ad esempio, se hai una classe Python personalizzataMyClasse desideri archiviare la sua istanza in un database SQLite, puoi scrivere un adattatore per convertire un'istanza di questa classe in una stringa (o altro tipo) che può essere archiviata da SQLite, quindi scrivere un convertitore per convertire Converti di nuovo questa stringa AMyClassesempio.

Tuttavia, per questa domanda, se vuoi occuparti solo di Pythontypeoggetto (ovvero i metadati del tipo), potresti scrivere un adattatore per restituire il nome del tipo (come una stringa), ma questa non è generalmente una pratica comune per archiviare oggetti in un database.

convertitore_register_sqlite3(nometipo, convertitore, /)

Registrare ilconvertitore richiamabileper convertire oggetti SQLite di tiponometipoin un oggetto Python di un tipo specifico. Il convertitore viene invocato per tutti i valori SQLite di tiponometipo; è passato unbyteobject e dovrebbe restituire un oggetto del tipo Python desiderato. Consulta il parametrorileva_tipiDiCollegare()per informazioni su come funziona il rilevamento del tipo.
Registra un oggetto richiamabile **convertitore** in cui convertire i tipi SQLitetypename Converte un oggetto in un oggetto Python di un tipo specifico.Per tutti i tipitypenameQuesto convertitore viene chiamato per qualsiasi valore SQLite riceve un filebytes object come argomento e dovrebbe restituire un oggetto del tipo Python richiesto.Per sapere come funziona il rilevamento del tipo, fare riferimento aconnect()Funzionaledetect_typesparametro.

Nota:nometipoe il nome del tipo nella query vengono confrontati senza distinzione tra maiuscole e minuscole.
Avviso：typenameIl nome del tipo nella query non fa distinzione tra maiuscole e minuscole durante la corrispondenza.

Costanti del modulo

sqlite3.LEGACY_TRANSACTION_CONTROL

Impostatoautocommissionea questa costante per selezionare il comportamento di controllo delle transazioni in stile vecchio (pre-Python 3.12). VedereControllo delle transazioni tramite l'attributo isolation_levelper maggiori informazioni.
Volereautocommit Imposta questa costante per selezionare il comportamento di controllo delle transazioni vecchio stile (precedente a Python 3.12).Per ulteriori informazioni consultare la sezione "Passisolation_levelTransazioni di controllo delle proprietà".

sqlite3.PARSE_COLNAMES

Passare questo valore del flag alrileva_tipiparametro diCollegare()per cercare una funzione di conversione utilizzando il nome del tipo, analizzato dal nome della colonna di query, come chiave del dizionario di conversione. Il nome del tipo deve essere racchiuso tra parentesi quadre ([]).
Passa questo valore di flag aconnect()Funzionaledetect_types Parametro per trovare la funzione del convertitore interrogando il nome del tipo risolto nel nome della colonna come chiave del dizionario del convertitore. I nomi dei tipi devono essere racchiusi tra parentesi quadre ([]).

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

Questa bandiera può essere combinata conPARSE_DECLTYPESusando il|operatore (OR bit a bit).
Questa bandiera può essere utilizzata|(OR bit a bit) operatore ANDPARSE_DECLTYPESInsieme a.

sqlite3.PARSE_DECLTYPES

Passare questo valore del flag alrileva_tipiparametro diCollegare()per cercare una funzione di conversione usando i tipi dichiarati per ogni colonna. I tipi vengono dichiarati quando viene creata la tabella del database.sqlite3cercherà una funzione di conversione usando la prima parola del tipo dichiarato come chiave del dizionario di conversione. Ad esempio:
Passa questo valore di flag aconnect()Funzionaledetect_types Parametri per trovare la funzione del convertitore utilizzando il tipo dichiarato di ciascuna colonna nel database. Questi tipi vengono dichiarati durante la creazione della tabella del database.sqlite3 La funzione del convertitore verrà cercata utilizzando la prima parola nel tipo dichiarato come chiave del dizionario del convertitore. Per esempio:

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"
 )

Questa bandiera può essere combinata conPARSE_NOMI_COLLusando il|operatore (OR bit a bit).

sqlite3.SQLITE_OK

sqlite3.SQLITE_DENY

sqlite3.SQLITE_IGNORA

Flag che dovrebbero essere restituiti dalautorizz_richiamata richiamabilepassato aConnessione.set_authorizer(), per indicare se:
Passare aConnection.set_authorizer()Diauthorizer_callbackFlag che la funzione richiamabile dovrebbe restituire per indicare:

• L'accesso è consentito (SQLITE_OK), l'accesso è consentito (SQLITE_OK）

• L'istruzione SQL dovrebbe essere interrotta con un errore (SQLITE_DENY)
  L'istruzione SQL dovrebbe essere interrotta con un errore (SQLITE_DENY）

• La colonna dovrebbe essere trattata come unaNULLvalore (SQLITE_IGNORE)
  Le colonne devono essere trattate come valori NULL (SQLITE_IGNORE）

livelloapi

Costante stringa che indica il livello DB-API supportato. Richiesto da DB-API. Hard-coded per"2.0".
Queste due costanti di stringa sonosqlite3Definiti in moduli, seguono la specifica API del database Python (DB-API).

sqlite3.paramstyle

Costante stringa che indica il tipo di formattazione del marcatore del parametro previsto dalsqlite3modulo. Richiesto dal DB-API. Hard-coded per"qmark".
Questa costante di stringa specificasqlite3 Il tipo di formattazione dell'indicatore di parametro prevista dal modulo. Ciò è richiesto dalla specifica DB-API (Database Application Programming Interface).È hardcoded come"qmark", significa che quando si costruiscono query SQL, i contrassegni dei parametri devono essere rappresentati da punti interrogativi (?).

Nota

ILnamedÈ supportato anche lo stile dei parametri DB-API.

versione_sqlite3.sqlite

Numero di versione della libreria SQLite runtime comecorda.
Il numero di versione della libreria runtime SQLite, espresso in forma di stringa.

sqlite3.sqlite_version_info

Numero di versione della libreria SQLite runtime cometuplaDinumeri interi.
Il numero di versione della libreria runtime SQLite, espresso come tupla di numeri interi.

sicurezza dei thread di sqlite3

Costante intera richiesta da DB-API 2.0, che indica il livello di sicurezza del threadsqlite3supporta il modulo. Questo attributo è impostato in base al valore predefinitomodalità di filettaturala libreria SQLite sottostante è compilata con. Le modalità di threading di SQLite sono:
Costante intera richiesta da DB-API 2.0, che indicasqlite3 Il livello di sicurezza del thread supportato dal modulo. Questa proprietà viene impostata in base alla modalità di threading predefinita con cui è stata compilata la libreria SQLite sottostante. Le modalità di threading di SQLite includono:

1. Singolo filo: In questa modalità, tutti i mutex sono disabilitati e non è sicuro utilizzare SQLite in più thread contemporaneamente.
   Thread singolo: in questa modalità, tutti i mutex sono disabilitati e SQLite non può essere utilizzato in modo sicuro da più thread contemporaneamente.

2. Multi thread: In questa modalità, SQLite può essere utilizzato in modo sicuro da più thread, a condizione che nessuna connessione al database venga utilizzata contemporaneamente in due o più thread.
   Multi-thread: in questa modalità, SQLite può essere utilizzato in sicurezza da più thread, a condizione che nessuna singola connessione al database venga utilizzata contemporaneamente da due o più thread.

3. Serializzato: In modalità serializzata, SQLite può essere utilizzato in tutta sicurezza da più thread senza alcuna restrizione.
   Serializzato: in modalità serializzata, SQLite può essere utilizzato in modo sicuro da più thread senza alcuna restrizione.

I mapping dalle modalità di threading di SQLite ai livelli di threadsafety di DB-API 2.0 sono i seguenti:
La mappatura della modalità thread di SQLite al livello di sicurezza del thread DB-API 2.0 è la seguente:

Modificato nella versione 3.11: Impostatosicurezza del filodinamicamente invece di codificarlo in modo rigido1.

sqlite3.versione

Numero di versione di questo modulo comecordaQuesta non è la versione della libreria SQLite.
Il numero di versione di questo modulo, espresso come stringa.QuestoNOIl numero di versione della libreria SQLite.

Obsoleto dalla versione 3.12, verrà rimosso nella versione 3.14: questa costante veniva utilizzata per riflettere il numero di versione delpysqlitepacchetto, una libreria di terze parti utilizzata per apportare modifiche a montesqlite3Oggi non ha più alcun significato o valore pratico.
Deprecato dalla versione 3.12, sarà rimosso nella versione 3.14: questa costante veniva utilizzata per rifletterepysqliteIl numero di versione del pacchetto,pysqliteÈ una libreria di terze parti che è stata caricata nell'upstreamsqlite3 Impegna le modifiche. Ora, non ha alcun significato reale o valore pratico.

informazioni sulla versione di sqlite3

Numero di versione di questo modulo cometuplaDinumeri interiQuesta non è la versione della libreria SQLite.

Obsoleto dalla versione 3.12, verrà rimosso nella versione 3.14: questa costante veniva utilizzata per riflettere il numero di versione delpysqlitepacchetto, una libreria di terze parti utilizzata per apportare modifiche a montesqlite3Oggi non ha più alcun significato o valore pratico.

sqlite3.SQLITE_DBCONFIG_DEFENSIVE

sqlite3.SQLITE_DBCONFIG_DQS_DDL

sqlite3.SQLITE_DBCONFIG_DQS_DML

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY

sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW

sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE

sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP

sqlite3.SQLITE_DBCONFIG_SCHEMA_TRUSTED

sqlite3.SQLITE_DBCONFIG_SCHEMA_SCRIVIBILE

Queste costanti vengono utilizzate perConnessione.setconfig()Eottieniconfigurazione()metodi.
Vengono utilizzate queste costantiConnection.setconfig()Egetconfig()metodo.

La disponibilità di queste costanti varia a seconda della versione di SQLite con cui è stato compilato Python.
La disponibilità di queste costanti dipende dalla versione di SQLite con cui è stato compilato SQLite Python.

Aggiunto nella versione 3.12.

Guarda anche

Opzioni di configurazione della connessione al database

Documentazione SQLite: Opzioni di configurazione della connessione al database

Oggetti di connessione

classesqlite3.Connessione

Ogni database SQLite aperto è rappresentato da unConnectionoggetto, che viene creato utilizzandosqlite3.connetti()Il loro scopo principale è creareCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetti eControllo delle transazioni.

Guarda anche

• Come utilizzare i metodi di collegamento rapido

• Come utilizzare il gestore del contesto di connessione

Una connessione al database SQLite ha i seguenti attributi e metodi:

cursore(fabbrica=Cursore)

Crea e restituisci unCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetto. Il metodo cursore accetta un singolo parametro facoltativofabbricaSe fornito, deve essere unrichiamabilerestituendo un'istanza diCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeo le sue sottoclassi.
Crea a e restituisce aCursoroggetto.cursorIl metodo accetta un singolo parametro facoltativofactory .Se questo parametro viene fornito, deve essere un oggetto richiamabile che restituisce aCursoro un'istanza della sua sottoclasse.

blobaperto(tavolo, colonna, riga, /, *, sola lettura=Falso, nome='principale')

Aprire unMacchiagestire un BLOB esistente.

Parametri:

• tavolo (str) – Il nome della tabella in cui si trova il blob.
  Il nome della tabella contenente i dati BLOB.

• colonna (str) – Il nome della colonna in cui si trova il blob.
  Nome della colonna contenente dati BLOB.

• riga (str) – Il nome della riga in cui si trova il blob.
  Il nome della riga (o più precisamente l'identificatore della riga) che contiene i dati BLOB.

• sola lettura (bollo) - ImpostatoTruese il blob deve essere aperto senza permessi di scrittura. Il valore predefinito èFalse.
  Se impostato su True, indica che il BLOB deve essere aperto senza autorizzazione di scrittura. Il valore predefinito è False, che consente la lettura e la scrittura.

• nome (str) – Il nome del database in cui si trova il blob. Il valore predefinito è"main".
  Il nome del database contenente i dati BLOB. Il valore predefinito è "main", che è il nome del database predefinito in SQLite.

Aumenti:

Errore operativo– Quando si tenta di aprire un blob in unWITHOUT ROWIDtavolo.
Quando si prova senzaRIGASi verifica quando i dati BLOB vengono aperti nella tabella degli ID.

Tipo di ritorno:

Macchia

Nota

La dimensione del blob non può essere modificata utilizzandoMacchiaclasse. Utilizzare la funzione SQLzeroblobper creare un blob di dimensione fissa.

Aggiunto nella versione 3.11.

commettere()

Invia qualsiasi transazione in sospeso al database. SeautocommissioneÈTrue, o non c'è alcuna transazione aperta, questo metodo non fa nulla. SeautocommitÈFalse, una nuova transazione viene aperta implicitamente se una transazione in sospeso è stata eseguita tramite questo metodo.
Impegna eventuali transazioni in sospeso nel database.Seautocommit È vero o non c'è alcuna transazione aperta, questo metodo non esegue alcuna operazione.Seautocommitè False e questo metodo conferma una transazione in sospeso, una nuova transazione verrà avviata implicitamente.

ripristinare()

Esegui il rollback all'inizio di qualsiasi transazione in sospeso. SeautocommissioneÈTrue, o non c'è alcuna transazione aperta, questo metodo non fa nulla. SeautocommitÈFalse, viene aperta implicitamente una nuova transazione se una transazione in sospeso è stata annullata da questo metodo.
Torna all'inizio di qualsiasi transazione in sospeso.Seautocommit È vero o non c'è alcuna transazione aperta, questo metodo non esegue alcuna operazione.Seautocommitè False e questo metodo ripristina una transazione in sospeso, una nuova transazione verrà avviata implicitamente.

vicino()

Chiudere la connessione al database. SeautocommissioneÈFalse, qualsiasi transazione in sospeso viene implicitamente annullata. SeautocommitÈTrueOCONTROLLO_TRANSAZIONE_LEGACY, non viene eseguito alcun controllo implicito delle transazioni. Assicurati dicommettere()prima di chiudere per evitare di perdere le modifiche in sospeso.
Chiudere la connessione al database.Seautocommit Se False, tutte le transazioni in sospeso verranno implicitamente ripristinate.Seautocommitè vero oLEGACY_TRANSACTION_CONTROL (controllo delle transazioni legacy), il controllo implicito delle transazioni non verrà eseguito.Prima di chiudere assicuratevi di chiamarecommit()per evitare di perdere le modifiche in sospeso.

eseguire(codice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql, parametri=(), /)

Crea un nuovoCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetto e chiamataeseguire()su di esso con il datocodice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sqlEparametriRestituisce il nuovo oggetto cursore.
crearne uno nuovoCursoroggetto e chiamataexecute()metodo, passando nel datosql dichiarazioni e parametri.restituiscilo nuovoCursoroggetto.

eseguire molti(codice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql, parametri, /)

Crea un nuovoCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetto e chiamataesegui molti()su di esso con il datocodice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sqlEparametriRestituisce il nuovo oggetto cursore.
crearne uno nuovoCursoroggetto e chiamataexecutemany()metodo, passando nel datosql Istruzioni e sequenze di parametri. Ciò consente di eseguire più set di parametri contemporaneamente.restituiscilo nuovoCursoroggetto.

eseguiscript(script_sql, /)

Crea un nuovoCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetto e chiamataeseguiscript()su di esso con il datoscript_sqlRestituisce il nuovo oggetto cursore.
crearne uno nuovoCursoroggetto e chiamataexecutescript() metodo, passando lo script SQL specificato. Ciò consente l'esecuzione di più istruzioni SQL, separate da punto e virgola nello script.restituiscilo nuovoCursoroggetto.

crea_funzione(nome, narghilèhilè, funzione, *, deterministico=Falso)

Crea o rimuovi una funzione SQL definita dall'utente.
Creare o rimuovere una funzione SQL definita dall'utente.

Parametri:

• nome (str) – Il nome della funzione SQL.
  name(str) – Il nome della funzione SQL.

• narghilèhilè (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) – Il numero di argomenti che la funzione SQL può accettare. Se-1, potrebbe accettare un numero qualsiasi di argomenti.
  narg (int) – Il numero di argomenti che la funzione SQL può accettare. Se -1, significa che può accettare qualsiasi numero di argomenti.

• funzione (richiamare| Nessuno) – Arichiamabileche viene chiamato quando viene invocata la funzione SQL. Il callable deve restituireun tipo supportato nativamente da SQLite. ImpostatoNoneper rimuovere una funzione SQL esistente.
  func (callback | None) – Questo oggetto richiamabile (callback) verrà eseguito quando viene chiamata la funzione SQL. Questo oggetto richiamabile deve restituire un tipo supportato nativamente da SQLite. Se impostato su Nessuno, le funzioni SQL esistenti verranno rimosse.

• deterministicoooooo (bollo) - SeTrue, la funzione SQL creata è contrassegnata comedeterministicoooooo, che consente a SQLite di eseguire ulteriori ottimizzazioni.
  deterministic(bool) – Se True, contrassegna la funzione SQL creata come deterministica, consentendo a SQLite di eseguire ottimizzazioni aggiuntive.

Aumenti:

Errore non supportato- Sedeterministicooooooviene utilizzato con versioni di SQLite precedenti alla 3.8.3.

Modificato nella versione 3.8: Aggiunto ildeterministicooooooparametro.

Esempio:

>>>

>>> 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()

crea_aggregato(nome, n_argomentoomentoomento, classe_aggregata)

Crea o rimuovi una funzione di aggregazione SQL definita dall'utente.
Creare o rimuovere una funzione di aggregazione SQL definita dall'utente.

Parametri:

• nome (str) – Il nome della funzione di aggregazione SQL.
       name(str) – Il nome della funzione di aggregazione SQL.

• n_argomentoomentoomento (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) – Il numero di argomenti che la funzione di aggregazione SQL può accettare. Se-1, potrebbe accettare un numero qualsiasi di argomenti.
  Il numero di parametri che una funzione di aggregazione SQL può accettare. Se -1, significa che può accettare qualsiasi numero di argomenti.

• classe_aggregata (classeeee| Nessuno) –

  Una classe deve implementare i seguenti metodi:
  Una classe deve implementare i seguenti metodi:

  • step(): aggiunge una riga all'aggregato.

  • finalize(): Restituisce il risultato finale dell'aggregato comeun tipo supportato nativamente da SQLite.
    finalize(): questo metodo viene utilizzato per restituire il risultato finale dell'aggregazione.

  Il numero di argomenti che ilstep()il metodo deve accettare è controllato dan_argomentoomentoomento.
  step()È dato il numero di parametri che un metodo deve accettaren_argcontrollo.

  ImpostatoNoneper rimuovere una funzione di aggregazione SQL esistente.
  Impostato comeNoneper rimuovere le funzioni di aggregazione SQL esistenti.

Esempio:

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()

crea_funzione_finestra(nome, numero_parametri, classe_aggregata, /)

Crea o rimuovi una funzione finestra aggregata definita dall'utente.

Parametri:

• nome (str) – Nome della funzione finestra di aggregazione SQL da creare o rimuovere.

• numero_parametri (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) – Il numero di argomenti che la funzione finestra di aggregazione SQL può accettare. Se-1, potrebbe accettare un numero qualsiasi di argomenti.

• classe_aggregata (classeeee| Nessuno) –

  Una classe che deve implementare i seguenti metodi:

  • step(): Aggiunge una riga alla finestra corrente.

  • value(): Restituisce il valore corrente dell'aggregato.

  • inverse(): Rimuove una riga dalla finestra corrente.

  • finalize(): Restituisce il risultato finale dell'aggregato comeun tipo supportato nativamente da SQLite.

  Il numero di argomenti che ilstep()Evalue()i metodi devono accettare è controllato danumero_parametri.

  ImpostatoNoneper rimuovere una funzione finestra di aggregazione SQL esistente.

Aumenti:

Errore non supportato– Se utilizzato con una versione di SQLite precedente alla 3.25.0, che non supporta le funzioni di finestra aggregate.

Aggiunto nella versione 3.11.

Esempio:

# 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()

crea_collazione(nome, richiamabile, /)

Crea una collazione denominatanomeutilizzando la funzione di collazionerichiamabile. richiamabileè passato duecordaargomenti e dovrebbe restituire unnumero intero:

• 1se il primo è ordinato più in alto del secondo

• -1se il primo è ordinato più in basso del secondo

• 0se sono ordinati uguali

L'esempio seguente mostra una collazione di ordinamento inverso:

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()

Rimuovi una funzione di collazione impostandorichiamabileANone.

Modificato nella versione 3.11: il nome della collazione può contenere qualsiasi carattere Unicode. In precedenza, erano consentiti solo caratteri ASCII.

interrompere()

Chiama questo metodo da un thread diverso per annullare qualsiasi query che potrebbe essere in esecuzione sulla connessione. Le query annullate solleveranno unErrore operativo.

imposta_autorizzazione(autorizz_richiamata)

Registratirichiamabile autorizz_richiamatada richiamare per ogni tentativo di accesso a una colonna di una tabella nel database. Il callback dovrebbe restituire uno diSQLITE_OK, SQLITE_DENY, OSQLITE_IGNORAper segnalare come l'accesso alla colonna deve essere gestito dalla libreria SQLite sottostante.

Il primo argomento del callback indica quale tipo di operazione deve essere autorizzata. Il secondo e il terzo argomento saranno argomenti oNonea seconda del primo argomento. Il 4° argomento è il nome del database ("main", "temp", ecc.) se applicabile. Il 5° argomento è il nome del trigger o della vista più interna che è responsabile del tentativo di accesso oNonese questo tentativo di accesso avviene direttamente dal codice SQL di input.

Si prega di consultare la documentazione di SQLite sui possibili valori per il primo argomento e sul significato del secondo e terzo argomento a seconda del primo. Tutte le costanti necessarie sono disponibili insqlite3modulo.

PassandoNoneCOMEautorizz_richiamatadisabiliterà l'autorizzatore.

Modificato nella versione 3.11: Aggiunto supporto per la disabilitazione dell'autorizzatore tramiteNone.

imposta_gestore_avanzamento(gestore_di_progressi, N)

Registratirichiamabile gestore_di_progressida invocare per ogniNistruzioni della macchina virtuale SQLite. Questo è utile se vuoi essere chiamato da SQLite durante operazioni di lunga durata, ad esempio per aggiornare una GUI.

Se si desidera cancellare qualsiasi gestore di avanzamento installato in precedenza, chiamare il metodo conNonepergestore_di_progressi.

La restituzione di un valore diverso da zero dalla funzione del gestore terminerà la query in esecuzione e causerà la generazione di unErrore di Databaseeccezione.

imposta_traccia_callback(traccia_richiamata)

Registratirichiamabile traccia_richiamatada richiamare per ogni istruzione SQL effettivamente eseguita dal backend SQLite.

L'unico argomento passato al callback è l'istruzione (comestr) che viene eseguito. Il valore di ritorno del callback viene ignorato. Nota che il backend non esegue solo le istruzioni passate alCursore.esegui()metodi. Altre fonti includono ilgestione delle transazionidelsqlite3modulo e l'esecuzione dei trigger definiti nel database corrente.

PassandoNoneCOMEtraccia_richiamatadisabiliterà il callback di traccia.

Nota

Le eccezioni sollevate nel callback di traccia non vengono propagate. Come ausilio per lo sviluppo e il debug, utilizzareabilita_callback_traceback()per abilitare la stampa dei traceback dalle eccezioni sollevate nel callback di traccia.

Aggiunto nella versione 3.3.

abilita_estensione_carica(abilitato, /)

Abilitare il motore SQLite per caricare le estensioni SQLite dalle librerie condivise seabilitatoÈTrue; altrimenti, non consentire il caricamento delle estensioni SQLite. Le estensioni SQLite possono definire nuove funzioni, aggregati o implementazioni di tabelle virtuali completamente nuove. Un'estensione ben nota è l'estensione di ricerca fulltext distribuita con SQLite.

Nota

ILsqlite3il modulo non è compilato con il supporto per le estensioni caricabili di default, perché alcune piattaforme (in particolare macOS) hanno librerie SQLite che sono compilate senza questa funzionalità. Per ottenere il supporto per le estensioni caricabili, devi passare il--abilita-estensioni-sqlite-caricabiliopzione perconfigurare.

Solleva unevento di verifica sqlite3.enable_load_extensioncon argomenticonnection, enabled.

Aggiunto nella versione 3.2.

Modificato nella versione 3.10: Aggiunto ilsqlite3.enable_load_extensionevento di verifica.

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)

carica_estensione(sentiero, /, *, punto di ingresso=Nessuno)

Carica un'estensione SQLite da una libreria condivisa. Abilita il caricamento dell'estensione conabilita_estensione_carico()prima di chiamare questo metodo.

Parametri:

• sentiero (str) – Il percorso verso l'estensione SQLite.

• punto d'entrata (str | Nessuno) – Nome del punto di ingresso. SeNone(predefinito), SQLite creerà un nome di punto di ingresso proprio; vedere la documentazione di SQLiteCaricamento di un'estensioneper dettagli.

Solleva unevento di verifica sqlite3.load_extensioncon argomenticonnection, path.

Aggiunto nella versione 3.2.

Modificato nella versione 3.10: Aggiunto ilsqlite3.load_extensionevento di verifica.

Modificato nella versione 3.12: Aggiunto ilpunto d'entrataparametro.

scaricare iter()

Restituisci uniteratoreeper scaricare il database come codice sorgente SQL. Utile quando si salva un database in memoria per un ripristino successivo. Simile a.dumpcomando nelsqlite3conchiglia.

Esempio:

# 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()

Guarda anche

Come gestire le codifiche di testo non UTF-8

backup(bersaglio, *, pagine=-1, progresso=Nessuno, nome='principale', dormire=0,250)

Creare un backup di un database SQLite.

Funziona anche se il database è utilizzato da altri client o contemporaneamente dalla stessa connessione.

Parametri:

• bersaglio (Connessione) – La connessione al database su cui salvare il backup.

• pagine (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) – Il numero di pagine da copiare alla volta. Se uguale o inferiore a0, l'intero database viene copiato in un unico passaggio. Per impostazione predefinita, è-1.

• progresso (richiamare| Nessuno) – Se impostato su arichiamabile, viene invocato con tre argomenti interi per ogni iterazione di backup:statodell'ultima iterazione, ilresiduonumero di pagine ancora da copiare etotalenumero di pagine. Il valore predefinito èNone.

• nome (str) – Il nome del database di cui eseguire il backup. O"main"(il valore predefinito) per il database principale,"temp"per il database temporaneo o il nome di un database personalizzato come allegato utilizzandoATTACH DATABASEIstruzione SQL.

• sonno (galleggiante) – Numero di secondi di sospensione tra tentativi successivi di backup delle pagine rimanenti.

Esempio 1, copia un database esistente in un altro:

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()

Esempio 2, copia di un database esistente in una copia temporanea:

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

Aggiunto nella versione 3.7.

Guarda anche

Come gestire le codifiche di testo non UTF-8

ottienilimite(categoria, /)

Ottieni un limite di tempo di esecuzione della connessione.

Parametri:

categoria (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) - ILCategoria limite SQLiteda interrogare.

Tipo di ritorno:

internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno

Aumenti:

Errore di programmazione- Secategorianon è riconosciuto dalla libreria SQLite sottostante.

Ad esempio, interrogare la lunghezza massima di un'istruzione SQL perConnessione con(il valore predefinito è 1000000000):

>>>

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

Aggiunto nella versione 3.11.

impostalimite(categoria, limitee, /)

Imposta un limite di runtime di connessione. I tentativi di aumentare un limite oltre il suo limite superiore rigido vengono troncati silenziosamente al limite superiore rigido. Indipendentemente dal fatto che il limite sia stato modificato o meno, viene restituito il valore precedente del limite.

Parametri:

• categoria (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) - ILCategoria limite SQLiteda impostare.

• limitee (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) – Il valore del nuovo limite. Se negativo, il limite attuale non cambia.

Tipo di ritorno:

internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno

Aumenti:

Errore di programmazione- Secategorianon è riconosciuto dalla libreria SQLite sottostante.

Ad esempio, limitare il numero di database allegati a 1 perConnessione con(il limite predefinito è 10):

>>>

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

Aggiunto nella versione 3.11.

ottieniconfigurazione(operazioneerazioneerazioneerazione, /)

Richiede un'opzione di configurazione della connessione booleana.

Parametri:

operazioneerazioneerazioneerazione (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) - UNCodice SQLITE_DBCONFIG.

Tipo di ritorno:

bollo

Aggiunto nella versione 3.12.

impostaconfigurazione(operazioneerazioneerazioneerazione, abilita=Vero, /)

Imposta un'opzione di configurazione della connessione booleana.

Parametri:

• operazioneerazioneerazioneerazione (internoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoernoerno) - UNCodice SQLITE_DBCONFIG.

• abilitare (bollo) – Truese l'opzione di configurazione deve essere abilitata (predefinita);Falsese dovesse essere disabilitato.

Aggiunto nella versione 3.12.

serializzare(*, nome='principale')

Serializzare un database in unbyteoggetto. Per un normale file di database su disco, la serializzazione è solo una copia del file su disco. Per un database in memoria o un database "temp", la serializzazione è la stessa sequenza di byte che verrebbe scritta su disco se il database venisse sottoposto a backup su disco.

Parametri:

nome (str) – Il nome del database da serializzare. Il valore predefinito è"main".

Tipo di ritorno:

byte

Nota

Questo metodo è disponibile solo se la libreria SQLite sottostante dispone dell'API serialize.

Aggiunto nella versione 3.11.

deserializzare(dati, /, *, nome='principale')

Deserializzare unserializzatodatabase in unConnessioneQuesto metodo determina la disconnessione della connessione al database dal databasenome, e riaprirenomecome un database in memoria basato sulla serializzazione contenuta indati.

Parametri:

• dati (byte) – Un database serializzato.

• nome (str) – Il nome del database in cui effettuare la deserializzazione. Il valore predefinito è"main".

Aumenti:

• Errore operativo– Se la connessione al database è attualmente coinvolta in una transazione di lettura o in un'operazione di backup.

• Errore di Database- Sedatinon contiene un database SQLite valido.

• Errore di overflow- Selen(dati)è più grande di2**63 - 1.

Nota

Questo metodo è disponibile solo se la libreria SQLite sottostante dispone dell'API deserialize.

Aggiunto nella versione 3.11.

autocommissione

Questo attributo controllaPEP249-comportamento transazionale conforme.autocommitha tre valori consentiti:

• False: SelezionarePEP249-comportamento transazionale conforme, il che implica chesqlite3assicura che una transazione sia sempre aperta. Utilizzarecommettere()Eripristinare()per chiudere le transazioni.

  Questo è il valore consigliato diautocommit.

• True: Usa SQLitemodalità autocommit. commettere()Eripristinare()non hanno alcun effetto in questa modalità.

• CONTROLLO_TRANSAZIONE_LEGACY: Pre-Python 3.12 (non-PEP249-compliant) controllo delle transazioni. Vederelivello di isolamentoper ulteriori dettagli.

  Questo è attualmente il valore predefinito diautocommit.

MutevoleautocommitAFalseaprirà una nuova transazione e la cambierà inTrueeseguirà qualsiasi transazione in sospeso.

VedereControllo delle transazioni tramite l'attributo autocommitper ulteriori dettagli.

Nota

ILlivello di isolamentol'attributo non ha effetto a meno cheautocommissioneÈCONTROLLO_TRANSAZIONE_LEGACY.

Aggiunto nella versione 3.12.

in_transazione

Questo attributo di sola lettura corrisponde al SQLite di basso livellomodalità autocommit.

Truese una transazione è attiva (ci sono modifiche non confermate),FalseAltrimenti.

Aggiunto nella versione 3.2.

livello di isolamento

Controlla ilmodalità di gestione delle transazioni legacyDisqlite3Se impostato suNone, le transazioni non vengono mai aperte implicitamente. Se impostato su uno di"DEFERRED", "IMMEDIATE", O"EXCLUSIVE", corrispondente al sottostanteComportamento delle transazioni SQLite, gestione delle transazioni impliciteviene eseguita.

Se non sovrascritto dallivello di isolamentoparametro diCollegare(), il valore predefinito è"", che è un alias per"DEFERRED".

Nota

Utilizzandoautocommissioneper controllare la gestione delle transazioni si consiglia di utilizzareisolation_level. isolation_levelnon ha effetto a meno cheautocommissioneè impostato perCONTROLLO_TRANSAZIONE_LEGACY(il predefinito).

riga_fabbrica

L'inizialeriga_fabbricaperCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetti creati da questa connessione. L'assegnazione a questo attributo non influisce sullarow_factorydei cursori esistenti appartenenti a questa connessione, solo quelli nuovi. ÈNoneper impostazione predefinita, il che significa che ogni riga viene restituita cometupla.

VedereCome creare e utilizzare le row factoryper ulteriori dettagli.

testo_fabbrica

UNrichiamabileche accetta unbyteparametro e ne restituisce una rappresentazione testuale. Il callable viene invocato per i valori SQLite con ilTEXTtipo di dati. Per impostazione predefinita, questo attributo è impostato sustr.

VedereCome gestire le codifiche di testo non UTF-8per ulteriori dettagli.

modifiche_totali

Restituisce il numero totale di righe del database modificate, inserite o eliminate dall'apertura della connessione al database.

Oggetti cursore

UNCursorl'oggetto rappresenta uncursore del databaseche viene utilizzato per eseguire istruzioni SQL e gestire il contesto di un'operazione di recupero. I cursori vengono creati utilizzandoConnessione.cursore(), oppure utilizzando uno qualsiasi deimetodi di collegamento rapido.

Gli oggetti cursore sonoiteratori, il che significa che se tueseguire()UNSELECTquery, puoi semplicemente scorrere il cursore per recuperare le righe risultanti:

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

classesqlite3.Cursore

UNCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeel'istanza ha i seguenti attributi e metodi.

eseguire(codice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql, parametri=(), /)

Eseguire una singola istruzione SQL, associando facoltativamente i valori Python utilizzandosegnaposto.

Parametri:

• codice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql (str) – Una singola istruzione SQL.

• parametri (ditto | sequenza) – Valori Python da associare ai segnaposto incodice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql. UNdictse vengono utilizzati segnaposto denominati. Una sequenza se vengono utilizzati segnaposto senza nome. VedereCome utilizzare i segnaposto per associare i valori nelle query SQL.

Aumenti:

Errore di programmazione- Secodice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sqlcontiene più di un'istruzione SQL.

SeautocommissioneÈCONTROLLO_TRANSAZIONE_LEGACY, livello di isolamentonon èNone, codice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sqlè unINSERT, UPDATE, DELETE, OREPLACEistruzione, e non c'è alcuna transazione aperta, una transazione viene implicitamente aperta prima dell'esecuzionecodice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql.

Obsoleto dalla versione 3.12, verrà rimosso nella versione 3.14:Avviso di deprecazioneviene emesso sesegnaposto denominatisono usati eparametriè una sequenza invece di unadittoA partire da Python 3.14,Errore di programmazioneverrà invece aumentato.

Utilizzoeseguiscript()per eseguire più istruzioni SQL.

eseguire molti(codice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql, parametri, /)

Per ogni articolo inparametri, eseguire ripetutamente ilparametrizzatoIstruzione SQL DMLcodice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql.

Utilizza la stessa gestione implicita delle transazioni dieseguire().

Parametri:

• codice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql (str) – Una singola istruzione SQL DML.

• parametri (iterabile) – Un iterabile di parametri da associare ai segnaposto incodice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sql. VedereCome utilizzare i segnaposto per associare i valori nelle query SQL.

Aumenti:

Errore di programmazione- Secodice codice codice codice codice codice codice codice codice codice codice codice codice codice codice sqlcontiene più di un'istruzione SQL oppure non è un'istruzione DML.

Esempio:

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

Nota

Tutte le righe risultanti vengono scartate, comprese le istruzioni DML conClausole di RITORNO.

Obsoleto dalla versione 3.12, verrà rimosso nella versione 3.14:Avviso di deprecazioneviene emesso sesegnaposto denominativengono utilizzati e gli elementi inparametrisono sequenze invece didittos. A partire da Python 3.14,Errore di programmazioneverrà invece aumentato.

eseguiscript(script_sql, /)

Eseguire le istruzioni SQL inscript_sql. Se laautocommissioneÈCONTROLLO_TRANSAZIONE_LEGACYe c'è una transazione in sospeso, un implicitoCOMMITistruzione viene eseguita per prima. Non viene eseguito nessun altro controllo implicito della transazione; qualsiasi controllo della transazione deve essere aggiunto ascript_sql.

script_sqldeve essere uncorda.

Esempio:

# 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;
""")

fetchone()

Seriga_fabbricaÈNone, restituisce il set di risultati della query della riga successiva cometupla. Altrimenti, passalo alla factory di righe e restituisci il suo risultato. RestituisciNonese non sono disponibili altri dati.

recuperare molti(dimensione=cursore.dimensione array)

Restituisce il set successivo di righe di un risultato di query comeelencoRestituisce un elenco vuoto se non sono disponibili altre righe.

Il numero di righe da recuperare per chiamata è specificato damisurareparametro. Semisurarenon è dato,dimensione matricedetermina il numero di righe da recuperare. Se meno dimisuraresono disponibili righe, vengono restituite tutte le righe disponibili.

Si noti che sono coinvolte considerazioni sulle prestazioni con ilmisurareparametro. Per prestazioni ottimali, di solito è meglio usare l'attributo arraysize. Se ilmisurareviene utilizzato un parametro, allora è meglio che mantenga lo stesso valore da unorecuperare molti()chiamare il prossimo.

recupera tutto()

Restituisce tutte le righe (rimanenti) di un risultato di query comeelenco. Restituisce un elenco vuoto se non sono disponibili righe. Nota che ildimensione matriceL'attributo può influire sulle prestazioni di questa operazione.

vicino()

Chiudi il cursore ora (piuttosto che ogni volta che__del__è chiamato).

Da questo momento in poi il cursore non sarà più utilizzabile;Errore di programmazioneverrà generata un'eccezione se si tenta un'operazione con il cursore.

impostadimensioniinput(dimensioni, /)

Richiesto dal DB-API. Non fa nulla insqlite3.

impostadimensioneoutput(misurare, colonna=Nessuno, /)

Richiesto dal DB-API. Non fa nulla insqlite3.

dimensione matrice

Attributo di lettura/scrittura che controlla il numero di righe restituite darecuperare molti()Il valore predefinito è 1, il che significa che verrà recuperata una singola riga per chiamata.

connessione

Attributo di sola lettura che fornisce il database SQLiteConnessioneappartenente al cursore. UnCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetto creato chiamandocon.cursore()avrà unconnessioneattributo che si riferisce acontro:

>>>

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

descrizione

Attributo di sola lettura che fornisce i nomi delle colonne dell'ultima query. Per rimanere compatibile con la Python DB API, restituisce una tupla di 7 elementi per ogni colonna in cui sono presenti gli ultimi sei elementi di ogni tupla.None.

È impostato perSELECTanche le istruzioni senza alcuna riga corrispondente.

ultima volta

Attributo di sola lettura che fornisce l'ID riga dell'ultima riga inserita. Viene aggiornato solo dopo l'inserimento riuscitoINSERTOREPLACEdichiarazioni utilizzando ileseguire()metodo. Per altre dichiarazioni, dopoesegui molti()Oeseguiscript(), oppure se l'inserimento non è riuscito, il valore dilastrowidrimane invariato. Il valore iniziale dilastrowidÈNone.

Nota

Inserisce inWITHOUT ROWIDle tabelle non vengono registrate.

Modificato nella versione 3.6: Aggiunto supporto per ilREPLACEdichiarazione.

conteggio delle righe

Attributo di sola lettura che fornisce il numero di righe modificate perINSERT, UPDATE, DELETE, EREPLACEdichiarazioni; è-1per altre dichiarazioni, comprese le query CTE. Viene aggiornato solo daleseguire()Eesegui molti()metodi, dopo che l'istruzione è stata eseguita fino al completamento. Ciò significa che tutte le righe risultanti devono essere recuperate affinchérowcountda aggiornare.

riga_fabbrica

Controlla come una riga viene recuperata da questoCursorè rappresentato. SeNone, una riga è rappresentata come unatuplaPuò essere impostato su inclusosqlite3.Riga; o unrichiamabileche accetta due argomenti, aCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetto e iltupledi valori di riga e restituisce un oggetto personalizzato che rappresenta una riga SQLite.

Di default è cosaConnessione.row_factoryè stato impostato quando ilCursorè stato creato. L'assegnazione a questo attributo non influisceConnessione.row_factorydella connessione padre.

VedereCome creare e utilizzare le row factoryper ulteriori dettagli.

Oggetti riga

classesqlite3.Riga

UNRowl'istanza funge da altamente ottimizzatariga_fabbricaperConnessioneoggetti. Supporta iterazione, test di uguaglianza,lunghezza(), EMappaturaaccesso tramite nome di colonna e indice.

DueRowgli oggetti sono uguali se hanno nomi di colonna e valori identici.

VedereCome creare e utilizzare le row factoryper ulteriori dettagli.

chiavi()

Restituisci unelencodei nomi delle colonne comestringhe. Subito dopo una query, è il primo membro di ogni tupla inCursore.descrizione.

Modificato nella versione 3.5: Aggiunto il supporto per lo slicing.

Oggetti blob

classesqlite3.Blob

Aggiunto nella versione 3.11.

UNMacchial'istanza è unaoggetto simile a un fileche può leggere e scrivere dati in un BLOB SQLite. Chiamalen(macchia)per ottenere la dimensione (numero di byte) del blob. Utilizzare indici efetteper l'accesso diretto ai dati del blob.

Usa ilMacchiacome ungestore del contestoper garantire che la maniglia del blob sia chiusa dopo l'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()

vicino()

Chiudere il blob.

Da questo momento in poi il blob non sarà più utilizzabile.Erroreeeeee(o sottoclasse) verrà generata un'eccezione se verrà tentata un'ulteriore operazione con il blob.

Leggere(lunghezza=-1, /)

Leggerelunghezzabyte di dati dal blob alla posizione di offset corrente. Se viene raggiunta la fine del blob, verranno restituiti i dati fino a EOF. Quandolunghezzanon è specificato, oppure è negativo,Leggere()verrà letto fino alla fine del blob.

scrivere(dati, /)

Scriveredatial blob all'offset corrente. Questa funzione non può modificare la lunghezza del blob. Scrivere oltre la fine del blob solleveràErrore di valore.

raccontare()

Restituisce la posizione di accesso corrente del blob.

cercare(compensare, origine=os.SEEK_SET, /)

Imposta la posizione di accesso corrente del blob sucompensare. ILorigineel'argomento è impostato di default suos.SEEK_SET(posizionamento assoluto del blob). Altri valori perorigineeSonoos.SEEK_CUR(cerca relativa alla posizione corrente) eos.SEEK_END(cerca relativa all'estremità del blob).

Oggetti PrepareProtocol

classesqlite3.PrepareProtocol

L'unico scopo del tipo PrepareProtocol è quello di agire come unPEP246protocollo di adattamento dello stile per oggetti che possonoadattarsiAtipi SQLite nativi.

Eccezioni

La gerarchia delle eccezioni è definita da DB-API 2.0 (PEP249).

eccezionesqlite3.Avviso

Questa eccezione non è attualmente sollevata dall'sqlite3modulo, ma può essere sollevato dalle applicazioni che utilizzanosqlite3, ad esempio se una funzione definita dall'utente tronca i dati durante l'inserimento.Warningè una sottoclasse diEccezione.

eccezionesqlite3.Errore

La classe base delle altre eccezioni in questo modulo. Usala per catturare tutti gli errori con un singolotrannedichiarazione.Errorè una sottoclasse diEccezione.

Se l'eccezione ha avuto origine all'interno della libreria SQLite, all'eccezione vengono aggiunti i due attributi seguenti:

codice_errore_sqlite

Il codice di errore numerico dalAPI di SQLite

Aggiunto nella versione 3.11.

nome_errore_sqlite

Il nome simbolico del codice di errore numerico dalAPI di SQLite

Aggiunto nella versione 3.11.

eccezioneErrore di interfaccia sqlite3.

Eccezione sollevata per uso improprio dell'API SQLite C di basso livello. In altre parole, se questa eccezione viene sollevata, probabilmente indica un bug nelsqlite3modulo.InterfaceErrorè una sottoclasse diErroreeeeee.

eccezioneErrore di database sqlite3.

Eccezione sollevata per errori correlati al database. Serve come eccezione di base per diversi tipi di errori del database. Viene sollevata solo implicitamente tramite le sottoclassi specializzate.DatabaseErrorè una sottoclasse diErroreeeeee.

eccezioneErrore di dati sqlite3.

Eccezione sollevata per errori causati da problemi con i dati elaborati, come valori numerici fuori intervallo e stringhe troppo lunghe.DataErrorè una sottoclasse diErrore di Database.

eccezioneErrore operativo di sqlite3.

Eccezione sollevata per errori correlati al funzionamento del database e non necessariamente sotto il controllo del programmatore. Ad esempio, il percorso del database non è stato trovato o una transazione non è stata elaborata.OperationalErrorè una sottoclasse diErrore di Database.

eccezioneErrore di integrità di sqlite3.

Eccezione sollevata quando l'integrità relazionale del database è influenzata, ad esempio un controllo di chiave esterna fallisce. È una sottoclasse diErrore di Database.

eccezioneErrore interno di sqlite3.

Eccezione sollevata quando SQLite incontra un errore interno. Se viene sollevata, potrebbe indicare che c'è un problema con la libreria SQLite runtime.InternalErrorè una sottoclasse diErrore di Database.

eccezionesqlite3.Errore di programmazione

Eccezione sollevata persqlite3Errori di programmazione dell'API, ad esempio la fornitura di un numero errato di associazioni a una query o il tentativo di operare su un'API chiusaConnessione. ProgrammingErrorè una sottoclasse diErrore di Database.

eccezioneErrore sqlite3.NotSupportedError

Eccezione sollevata nel caso in cui un metodo o un'API del database non sia supportato dalla libreria SQLite sottostante. Ad esempio, l'impostazionedeterministicooooooATrueIncrea_funzione(), se la libreria SQLite sottostante non supporta funzioni deterministiche.NotSupportedErrorè una sottoclasse diErrore di Database.

Tipi SQLite e Python

SQLite supporta nativamente i seguenti tipi:NULL, INTEGER, REAL, TEXT, BLOB.

I seguenti tipi Python possono quindi essere inviati a SQLite senza alcun problema:

Ecco come i tipi SQLite vengono convertiti in tipi Python per impostazione predefinita:

Il sistema di tipo delsqlite3il modulo è estensibile in due modi: puoi memorizzare tipi Python aggiuntivi in ​​un database SQLite tramiteadattatori di oggetti, e puoi lasciare che ilsqlite3modulo converte i tipi SQLite in tipi Python tramiteconvertitori.

Adattatori e convertitori predefiniti (obsoleti)

Nota

Gli adattatori e i convertitori predefiniti sono deprecati a partire da Python 3.12. Al loro posto, utilizzareRicette per adattatori e convertitorie personalizzarli in base alle tue esigenze.

Gli adattatori e i convertitori predefiniti deprecati sono costituiti da:

• Un adattatore perdata e ora.dataoggetti astringheInNorma Norma ISO 8601formato.

• Un adattatore perdata e ora.data e oraoggetti in stringhe nel formato ISO 8601.

• Un convertitore perdichiaratotipi di "data" adata e ora.dataoggetti.

• Un convertitore per i tipi "timestamp" dichiarati indata e ora.data e oraoggetti. Le parti frazionarie saranno troncate a 6 cifre (precisione in microsecondi).

Nota

Il convertitore "timestamp" predefinito ignora gli offset UTC nel database e restituisce sempre un valore ingenuodata e ora.data e oraoggetto. Per preservare gli offset UTC nei timestamp, lasciare i convertitori disabilitati o registrare un convertitore che riconosce gli offset conregistro_convertitore().

Obsoleto dalla versione 3.12.

Interfaccia a riga di comando

ILsqlite3il modulo può essere richiamato come uno script, utilizzando l'interprete-Mswitch, per fornire una semplice shell SQLite. La firma dell'argomento è la seguente:

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

Tipo.quitoppure CTRL-D per uscire dalla shell.

-h, --aiuto

Stampa la guida CLI.

-v, --versione

Stampa la versione della libreria SQLite sottostante.

Aggiunto nella versione 3.12.

Guide pratiche

Come utilizzare i segnaposto per associare i valori nelle query SQL

Le operazioni SQL solitamente devono usare valori da variabili Python. Tuttavia, fai attenzione a usare le operazioni stringa di Python per assemblare query, poiché sono vulnerabili aAttacchi di iniezione SQLAd esempio, un aggressore può semplicemente chiudere l'apostrofo singolo e iniettareOR TRUEper selezionare tutte le righe:

>>>

>>> # 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)

Invece, usa la sostituzione dei parametri della DB-API. Per inserire una variabile in una stringa di query, usa un segnaposto nella stringa e sostituisci i valori effettivi nella query fornendoli cometupladi valori al secondo argomento del cursoreeseguire()metodo.

Un'istruzione SQL può utilizzare uno dei due tipi di segnaposto: punti interrogativi (stile qmark) o segnaposto denominati (stile denominato). Per lo stile qmark,parametrideve essere unsequenzala cui lunghezza deve corrispondere al numero di segnaposto, oppure aErrore di programmazioneviene sollevato. Per lo stile denominato,parametrideve essere un'istanza di unditto(o una sottoclasse), che deve contenere chiavi per tutti i parametri denominati; qualsiasi elemento extra viene ignorato. Ecco un esempio di entrambi gli stili:

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()

Nota

PEP249i segnaposto numerici sonononsupportati. Se utilizzati, verranno interpretati come segnaposto denominati.

Come adattare i tipi Python personalizzati ai valori SQLite

SQLite supporta solo un set limitato di tipi di dati in modo nativo. Per memorizzare tipi Python personalizzati nei database SQLite,adattareloro a uno deiTipi Python che SQLite comprende in modo nativo.

Esistono due modi per adattare gli oggetti Python ai tipi SQLite: lasciare che l'oggetto si adatti da solo o utilizzare unadattatore richiamabile. Quest'ultimo avrà la precedenza sul primo. Per una libreria che esporta un tipo personalizzato, potrebbe avere senso abilitare quel tipo ad adattarsi. Come sviluppatore di applicazioni, potrebbe avere più senso assumere il controllo diretto registrando funzioni di adattatore personalizzate.

Come scrivere oggetti adattabili

Supponiamo di avere unPointclasse che rappresenta una coppia di coordinate,xEy, in un sistema di coordinate cartesiane. La coppia di coordinate verrà memorizzata come stringa di testo nel database, utilizzando un punto e virgola per separare le coordinate. Questo può essere implementato aggiungendo un__conform__(self, protocol)metodo che restituisce il valore adattato. L'oggetto passato aprotocollosarà di tipoPreparare il protocollo.

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()

Come registrare i callable dell'adattatore

L'altra possibilità è quella di creare una funzione che converta l'oggetto Python in un tipo compatibile con SQLite. Questa funzione può quindi essere registrata usandoregistra_adattatore().

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()

Come convertire i valori SQLite in tipi Python personalizzati

Scrivere un adattatore consente di convertiredatipi Python personalizzatiAValori SQLite. Per poter convertiredaValori SQLiteAtipi Python personalizzati, utilizziamoconvertitori.

Torniamo alPointclasse. Abbiamo memorizzato le coordinate x e y separate da punto e virgola come stringhe in SQLite.

Per prima cosa, definiremo una funzione di conversione che accetta la stringa come parametro e costruisce unPointoggetto da esso.

Nota

Le funzioni del convertitore sonoSempreha superato unbyteoggetto, indipendentemente dal tipo di dati SQLite sottostante.

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

Ora dobbiamo dirlosqlite3quando deve convertire un dato valore SQLite. Questo avviene quando ci si connette a un database, utilizzando ilrileva_tipiparametro diCollegare()Ci sono tre opzioni:

• Implicito: impostarerileva_tipiAPARSE_DECLTYPES

• Esplicito: setrileva_tipiAPARSE_NOMI_COLL

• Entrambi: setrileva_tipiAsqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMESI nomi delle colonne hanno la precedenza sui tipi dichiarati.

L'esempio seguente illustra gli approcci implicito ed esplicito:

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()

Ricette per adattatori e convertitori

Questa sezione mostra le ricette per adattatori e convertitori più comuni.

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)

Come utilizzare i metodi di collegamento rapido

Usando ileseguire(), esegui molti(), Eeseguiscript()metodi diConnessioneclasse, il tuo codice può essere scritto in modo più conciso perché non devi creare (spesso superfluo)Cursoreeeeeeeeeeeeeeeeeeeeeeeeeeeeoggetti esplicitamente. Invece, ilCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeegli oggetti vengono creati implicitamente e questi metodi di scelta rapida restituiscono gli oggetti cursore. In questo modo, puoi eseguire unSELECTistruzione e iterare su di essa direttamente utilizzando solo una singola chiamata suConnessioneoggetto.

# 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()

Come utilizzare il gestore del contesto di connessione

UNConnessionel'oggetto può essere utilizzato come gestore di contesto che esegue automaticamente il commit o il rollback delle transazioni aperte quando si esce dal corpo del gestore di contesto. Se il corpo delconistruzione termina senza eccezioni, la transazione viene eseguita. Se questo commit fallisce, o se il corpo dellawithistruzione solleva un'eccezione non rilevata, la transazione viene annullata. SeautocommissioneÈFalse, una nuova transazione viene aperta implicitamente dopo il commit o il rollback.

Se non c'è alcuna transazione aperta all'uscita dal corpo delwithdichiarazione, o seautocommissioneÈTrue, il gestore del contesto non fa nulla.

Nota

Il gestore del contesto non apre implicitamente una nuova transazione né chiude la connessione. Se hai bisogno di un gestore del contesto di chiusura, prendi in considerazione l'utilizzo dicontestolib.chiusura().

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()

Come lavorare con gli URI SQLite

Ecco alcuni utili trucchi per gli URI:

• Aprire un database in modalità di sola lettura:

>>>

>>> 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

• Non creare implicitamente un nuovo file di database se non esiste già; verrà sollevatoErrore operativose non è possibile creare un nuovo file:

>>>

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

• Crea un database condiviso in memoria con nome:

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()

Ulteriori informazioni su questa funzionalità, incluso un elenco dei parametri, sono disponibili inDocumentazione URI SQLite.

Come creare e utilizzare le row factory

Per impostazione predefinita,sqlite3rappresenta ogni riga come unatupla. Se untuplenon soddisfa le tue esigenze, puoi utilizzare ilsqlite3.Rigaclasse o personalizzatariga_fabbrica.

Mentrerow_factoryesiste come attributo sia sulCursoreeeeeeeeeeeeeeeeeeeeeeeeeeeee ilConnessione, si consiglia di impostareConnessione.row_factory, quindi tutti i cursori creati dalla connessione utilizzeranno la stessa riga factory.

Rowfornisce un accesso denominato indicizzato e senza distinzione tra maiuscole e minuscole alle colonne, con un sovraccarico di memoria minimo e un impatto minimo sulle prestazioni su untuple. UsareRowcome una fabbrica di righe, assegnarla arow_factoryattributo:

>>>

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

Le query ora restituisconoRowoggetti:

>>>

>>> 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()

Nota

ILFROMla clausola può essere omessa nellaSELECTistruzione, come nell'esempio precedente. In tali casi, SQLite restituisce una singola riga con colonne definite da espressioni, ad esempio letterali, con gli alias specificatiexpr AS alias.

Puoi creare un personalizzatoriga_fabbricache restituisce ogni riga comeditto, con i nomi delle colonne mappati ai valori:

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

Utilizzandolo, le query ora restituiscono undictinvece di untuple:

>>>

>>> 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()

La seguente riga di fabbrica restituisce untupla denominata:

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()può essere utilizzato come segue:

>>>

>>> 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()

Con alcuni accorgimenti, la ricetta sopra può essere adattata per utilizzare unclasse di dati, o qualsiasi altra classe personalizzata, invece di unadenominatotupla.

Come gestire le codifiche di testo non UTF-8

Per impostazione predefinita,sqlite3usistrper adattare i valori SQLite conTEXTtipo di dati. Funziona bene per il testo codificato UTF-8, ma potrebbe non funzionare per altre codifiche e UTF-8 non valido. Puoi usare untesto_fabbricaper gestire casi del genere.

A causa di SQLitedigitazione flessibile, non è raro incontrare colonne di tabelle con l'TEXTtipo di dati contenente codifiche non UTF-8 o anche dati arbitrari. Per dimostrare, supponiamo di avere un database con testo codificato ISO-8859-2 (Latino-2), ad esempio una tabella di voci di dizionario ceco-inglese. Supponendo di avere ora unConnessioneesempioconconnesso a questo database, possiamo decodificare il testo codificato Latin-2 utilizzando questotesto_fabbrica:

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

Per UTF-8 non valido o dati arbitrari memorizzati inTEXTcolonne della tabella, è possibile utilizzare la seguente tecnica, presa in prestito daCOME FARE con Unicode:

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

Nota

ILsqlite3l'API del modulo non supporta stringhe contenenti surrogati.

Guarda anche

COME FARE con Unicode

Spiegazione

Controllo delle transazioni

sqlite3offre molteplici metodi per controllare se, quando e come le transazioni del database vengono aperte e chiuse.Controllo delle transazioni tramite l'attributo autocommitè consigliato, mentreControllo delle transazioni tramite l'attributo isolation_levelmantiene il comportamento precedente a Python 3.12.

Controllo delle transazioni tramiteautocommitattributo

Il modo consigliato per controllare il comportamento delle transazioni è attraverso ilConnessione.autocommitattributo, che dovrebbe essere impostato preferibilmente utilizzando l'autocommissioneparametro diCollegare().

Si suggerisce di impostareautocommissioneAFalse, il che implicaPEP249- controllo delle transazioni conforme. Ciò significa:

• sqlite3assicura che una transazione sia sempre aperta, quindiCollegare(), Connessione.commit(), EConnessione.rollback()aprirà implicitamente una nuova transazione (subito dopo la chiusura di quella in sospeso, per le ultime due).sqlite3usiBEGIN DEFERREDdichiarazioni all'apertura delle transazioni.

• Le transazioni devono essere eseguite in modo esplicito utilizzandocommit().

• Le transazioni dovrebbero essere annullate esplicitamente utilizzandorollback().

• Un rollback implicito viene eseguito se il database èvicino()-ed con modifiche in sospeso.

ImpostatoautocommissioneATrueper abilitare SQLitemodalità autocommitIn questa modalità,Connessione.commit()EConnessione.rollback()non hanno alcun effetto. Nota che la modalità autocommit di SQLite è distinta dallaPEP249-conformeConnessione.autocommitattributo; usoConnessione in_transazioneper interrogare la modalità autocommit di SQLite di basso livello.

ImpostatoautocommissioneACONTROLLO_TRANSAZIONE_LEGACYlasciare il comportamento di controllo delle transazioni alConnessione.livello_isolamentoattributo. VediControllo delle transazioni tramite l'attributo isolation_levelper maggiori informazioni.

Controllo delle transazioni tramiteisolation_levelattributo

Nota

Il metodo consigliato per controllare le transazioni è tramiteautocommissioneattributo. VediControllo delle transazioni tramite l'attributo autocommit.

SeConnessione.autocommitè impostato perCONTROLLO_TRANSAZIONE_LEGACY(predefinito), il comportamento della transazione è controllato utilizzandoConnessione.livello_isolamentoattributo. Altrimenti,isolation_levelnon ha alcun effetto.

Se l'attributo di connessionelivello di isolamentonon èNone, le nuove transazioni vengono aperte implicitamente primaeseguire()Eesegui molti()esegueINSERT, UPDATE, DELETE, OREPLACEistruzioni; per altre istruzioni, non viene eseguita alcuna gestione implicita delle transazioni. Utilizzarecommettere()Eripristinare()metodi per rispettivamente eseguire il commit e il rollback delle transazioni in sospeso. Puoi scegliere il metodo sottostanteComportamento delle transazioni SQLite— vale a dire, se e quale tipo diBEGINdichiarazionisqlite3esegue implicitamente – tramite illivello di isolamentoattributo.

Selivello di isolamentoè impostato perNone, nessuna transazione viene aperta implicitamente. Ciò lascia la libreria SQLite sottostante inmodalità autocommit, ma consente anche all'utente di gestire le proprie transazioni utilizzando istruzioni SQL esplicite. La modalità autocommit della libreria SQLite sottostante può essere interrogata utilizzandoin_transazioneattributo.

ILeseguiscript()il metodo esegue implicitamente il commit di qualsiasi transazione in sospeso prima dell'esecuzione dello script SQL specificato, indipendentemente dal valore dilivello di isolamento.

Modificato nella versione 3.6:sqlite3utilizzato per eseguire implicitamente il commit di una transazione aperta prima delle istruzioni DDL. Non è più così.

Modificato nella versione 3.12: il modo consigliato per controllare le transazioni è ora tramiteautocommissioneattributo.