sqlite3 – DB-API 2.0-Schnittstelle für SQLite-Datenbanken

2024-07-12

sqlite3 – DB-API 2.0-Schnittstelle für SQLite-Datenbanken – Python 3.12.4-Dokumentation

`sqlite3`— DB-API 2.0-Schnittstelle für SQLite-Datenbanken
sqlite3 – DB-API 2.0-Schnittstelle für SQLite-Datenbanken

Quellcode: Lib/sqlite3/ Speicherort des Quellcodes:Lib/sqlite3/

SQLite ist eine C-Bibliothek, die eine leichtgewichtige, festplattenbasierte Datenbank bereitstellt, die keinen separaten Serverprozess erfordert und den Zugriff auf die Datenbank über eine nicht standardmäßige Variante der SQL-Abfragesprache ermöglicht. Einige Anwendungen können SQLite zur internen Datenspeicherung verwenden. Es ist auch möglich, einen Anwendungsprototyp mit SQLite zu erstellen und den Code dann auf eine größere Datenbank wie PostgreSQL oder Oracle zu portieren.
SQLite ist eine C-Sprachbibliothek, die eine schlanke, festplattenbasierte Datenbank bereitstellt, die keinen separaten Serverprozess erfordert und den Zugriff auf die Datenbank über eine nicht standardmäßige Variante der SQL-Abfragesprache ermöglicht. Einige Anwendungen können SQLite zur internen Datenspeicherung verwenden. Darüber hinaus können Sie SQLite verwenden, um einen Prototyp einer Anwendung zu erstellen und den Code dann in eine große Datenbank wie PostgreSQL oder Oracle zu migrieren.

Dersqlite3Das Modul wurde von Gerhard Häring geschrieben. Es bietet eine SQL-Schnittstelle, die der DB-API 2.0-Spezifikation entspricht, die vonPEP 249, und erfordert SQLite 3.7.15 oder neuer.
sqlite3-Modul Geschrieben von Gerhard Häring. Es bietet eine SQL-Schnittstelle, die der in PEP 249 beschriebenen DB-API 2.0-Spezifikation entspricht und SQLite-Version 3.7.15 oder höher erfordert.

Dieses Dokument umfasst vier Hauptabschnitte: Dieses Dokument umfasst hauptsächlich die folgenden vier Hauptabschnitte

Lernprogrammlehrt den Umgang mit demsqlite3Modul.LernprogrammEin Teil lehrt die Verwendung des sqlite3-Moduls.
Referenzbeschreibt die Klassen und Funktionen, die dieses Modul definiert.
beziehen aufDer Abschnitt beschreibt die von diesem Modul definierten Klassen und Funktionen.
Anleitungenbeschreibt, wie bestimmte Aufgaben zu erledigen sind.
BedienerführungIn den Abschnitten wird detailliert beschrieben, wie mit bestimmten Aufgaben umgegangen wird.
Erläuterungbietet ausführliche Hintergrundinformationen zur Transaktionskontrolle.
erklärenDieser Abschnitt bietet eine ausführliche Einführung in das Hintergrundwissen der Transaktionssteuerung.

Siehe auch

https://www.sqlite.org

Die SQLite-Webseite; die Dokumentation beschreibt die Syntax und die verfügbaren Datentypen für den unterstützten SQL-Dialekt.
Die Webseite von SQLite beschreibt die Syntax der unterstützten SQL-Dialekte und die verfügbaren Datentypen.

SQL-LernprogrammSQL-Tutorial

Tutorial, Referenz und Beispiele zum Erlernen der SQL-Syntax.
Tutorials, Referenzen und Beispiele zum Erlernen der SQL-Syntax.

PEP 249- Datenbank-API-Spezifikation 2.0 PEP 249 - Datenbank-API-Spezifikation 2.0

PEP geschrieben von Marc-André Lemburg. PEP geschrieben von Marc-André Lemburg.

LernprogrammLernprogramm

In diesem Tutorial erstellen Sie eine Datenbank mit Monty Python-Filme mit grundlegendensqlite3Funktionalität. Es setzt ein grundlegendes Verständnis von Datenbankkonzepten voraus, einschließlichCursorUndTransaktionen.
In diesem Tutorial verwenden Sie die grundlegende SQLite3-Funktionalität, um eine Datenbank über Monty Python-Filme zu erstellen. Für dieses Tutorial wird davon ausgegangen, dass Sie über Grundkenntnisse der Datenbankkonzepte, einschließlich Cursor und Transaktionen, verfügen.

Zuerst müssen wir eine neue Datenbank erstellen und eine Datenbankverbindung öffnen, umsqlite3um damit zu arbeiten. Rufen Siesqlite3.connect()um eine Verbindung zur Datenbank herzustellentutorial.dbim aktuellen Arbeitsverzeichnis, implizites Erstellen, wenn es nicht existiert:
Zuerst müssen wir eine neue Datenbank erstellen und eine Datenbankverbindung öffnen, damit sqlite3 mit ihr interagieren kann. Rufen Sie sqlite3.connect() auf, um eine Verbindung zur Datenbank „tutorial.db“ im aktuellen Arbeitsverzeichnis herzustellen und diese implizit und sanft automatisch zu erstellen, wenn sie nicht vorhanden ist:


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

Die zurückgekehrtenVerbindungObjektconstellt die Verbindung zur Datenbank auf der Festplatte dar.
Das zurückgegebene Connection-Objekt (in diesem Fall con genannt) stellt eine Verbindung zur Datenbank auf der Festplatte dar.

Um zu Ausführen von SQL-Anweisungen UndErgebnisse aus SQL-Abfragen abrufenmüssen wir einen Datenbankcursor verwenden. Anrufcon.cursor()zur Erstellung derMauszeiger:
Um SQL-Anweisungen auszuführen und Ergebnisse aus SQL-Abfragen zu erhalten, müssen wir Datenbankcursor verwenden. Rufen Sie con.cursor() auf, um einen Cursor zu erstellen:

cur = con.cursor()

Nachdem wir nun eine Datenbankverbindung und einen Cursor haben, können wir eine Datenbanktabelle erstellenmoviemit Spalten für Titel, Erscheinungsjahr und Bewertung. Der Einfachheit halber können wir in der Tabellendeklaration einfach Spaltennamen verwenden – dank derflexibles TippenFunktion von SQLite, die Angabe der Datentypen ist optional. Führen Sie denCREATE TABLEErklärung durch Anrufaktuell.execute(...):
Nachdem wir nun die Datenbankverbindung und den Cursor haben, können wir eine Datenbanktabelle namens „movie“ mit Spalten wie Titel, Erscheinungsjahr und Rezensionsergebnis erstellen. Zur Vereinfachung können wir Spaltennamen direkt in der Tabellendeklaration verwenden – die Angabe des Datentyps ist aufgrund der flexiblen Typisierungsfunktion von SQLite optional. Führen Sie die CREATE TABLE-Anweisung aus, indem Sie cur.execute(...) aufrufen:

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

Wir können überprüfen, ob die neue Tabelle erstellt wurde, indem wir diesqlite_masterTabelle, die in SQLite integriert ist und nun einen Eintrag für diemovieTabellendefinition (sieheDie Schematabellefür Details). Führen Sie diese Abfrage aus, indem Sieaktuell.execute(...), weisen Sie das Ergebnis zures, und Ruf anres.fetchone()um die resultierende Zeile abzurufen:
Wir können überprüfen, ob die neue Tabelle erstellt wurde, indem wir die in SQLite integrierte Tabelle „sqlite_master“ abfragen, die nun Einträge für die Definition der Filmtabelle enthalten sollte (Einzelheiten finden Sie in der Schematabelle). Führen Sie die Abfrage aus, indem Sie cur.execute(...) aufrufen, weisen Sie die Ergebnisse res zu und rufen Sie res.fetchone() auf, um die Ergebniszeilen abzurufen:

>>>


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

Wir können sehen, dass die Tabelle erstellt wurde, da die Abfrage einTupelenthält den Namen der Tabelle. Wenn wir abfragensqlite_masterfür eine nicht vorhandene Tabellespam, res.fetchone()wird zurückkehrenNone:
Wir können sehen, dass die Tabelle erfolgreich erstellt wurde, weil die Abfrage ein Tupel zurückgegeben hat, das den Tabellennamen enthält. Wenn wir sqlite_master nach einer nicht vorhandenen Tabelle (z. B. Spam) abfragen, gibt res.fetchone() None zurück.

>>>


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

Fügen Sie nun zwei Datenzeilen hinzu, die als SQL-Literale bereitgestellt werden, indem Sie Folgendes ausführen:INSERTAussage, noch einmal durch den Aufrufaktuell.execute(...):
Fügen Sie nun zwei Datenzeilen hinzu, die als SQL-Literale bereitgestellt werden, indem Sie eine INSERT-Anweisung ausführen (durch erneuten Aufruf von 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)
""")

DerINSERT-Anweisung öffnet implizit eine Transaktion, die bestätigt werden muss, bevor Änderungen in der Datenbank gespeichert werden (sieheTransaktionskontrollefür Details). Anrufcon.commit()auf dem Verbindungsobjekt, um die Transaktion festzuschreiben:
Die INSERT-Anweisung startet implizit und automatisch eine Transaktion, die festgeschrieben werden muss, bevor Änderungen in der Datenbank gespeichert werden (Einzelheiten finden Sie unter Transaktionssteuerung). Rufen Sie con.commit() für das Verbindungsobjekt auf, um die Transaktion festzuschreiben:

con.commit()

Wir können überprüfen, ob die Daten korrekt eingefügt wurden, indem wirSELECTAbfrage. Verwenden Sie die mittlerweile bekannteaktuell.execute(...)das Ergebnis zuordnenres, und Ruf anres.fetchall()um alle resultierenden Zeilen zurückzugeben:
Wir können überprüfen, ob die Daten korrekt eingefügt wurden, indem wir eine SELECT-Abfrage ausführen. Weisen Sie die Ergebnisse mithilfe des mittlerweile bekannten Befehls cur.execute(...) res zu und rufen Sie res.fetchall() auf, um alle Ergebniszeilen zurückzugeben:

>>>


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

Das Ergebnis ist einListevon zweituples, eines pro Zeile, jedes enthält diescoreWert.
Das Ergebnis ist eine Liste mit zwei Tupeln, eines für jede Zeile, und jedes Tupel enthält den Bewertungswert für diese Zeile.

Fügen Sie nun drei weitere Zeilen ein, indem Siecur.executemany(...):
Fügen Sie nun drei weitere Datenzeilen ein, indem Sie cur.executemany(...) aufrufen:


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.

Beachte das?Platzhalter dienen zum Bindendatazur Abfrage. Verwenden Sie immer Platzhalter anstelle vonZeichenfolgenformatierungum Python-Werte an SQL-Anweisungen zu binden, um zu vermeidenSQL-Injection-Angriffe(sehenSo verwenden Sie Platzhalter zum Binden von Werten in SQL-Abfragenfür mehr Details).
Beachten Sie, dass der Platzhalter ? zum Binden der Daten in die Abfrage verwendet wird. Verwenden Sie immer Platzhalter anstelle von Zeichenfolgenformatierungen, um Python-Werte in SQL-Anweisungen zu binden, um SQL-Injection-Angriffe zu vermeiden (weitere Einzelheiten finden Sie unter „So binden Sie Werte mithilfe von Platzhaltern in SQL-Abfragen“).

Wir können überprüfen, ob die neuen Zeilen eingefügt wurden, indem wir Folgendes ausführen:SELECTAbfrage, wobei dieses Mal die Ergebnisse der Abfrage durchlaufen werden:
Wir können überprüfen, ob die neue Zeile eingefügt wurde, indem wir eine SELECT-Abfrage ausführen. Dieses Mal werden wir die Abfrageergebnisse durchlaufen:

>>>


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

Jede Zeile besteht aus zwei ElementenTupelvon(year, title), passend zu den in der Abfrage ausgewählten Spalten.
Jede Zeile ist ein Tupel mit zwei Elementen (Jahr, Titel), das mit der in der Abfrage ausgewählten Spalte übereinstimmt.

Überprüfen Sie abschließend, ob die Datenbank auf die Festplatte geschrieben wurde. Rufen Sie dazucon.schließen()um die bestehende Verbindung zu schließen, eine neue zu öffnen, einen neuen Cursor zu erstellen und dann die Datenbank abzufragen:
Zum Schluss per Anrufcon.close() um die bestehende Datenbankverbindung zu schließen und sicherzustellen, dass die Datenbank auf die Festplatte geschrieben wurde. Öffnen Sie dann eine neue Verbindung, erstellen Sie einen neuen Cursor und fragen Sie die Datenbank ab, um zu überprüfen, ob die Daten erfolgreich geschrieben wurden.

>>>


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

Sie haben nun eine SQLite-Datenbank erstellt mit demsqlite3Modul, fügte Daten ein und rief auf verschiedene Weise Werte daraus ab.
Sie haben jetzt verwendetsqlite3 Das Modul erstellt eine SQLite-Datenbank und fügt auf verschiedene Weise Daten aus dieser ein und ruft sie ab [Abrufen? 】Der Wert.

Siehe auchSiehe auch

Anleitungenzum Weiterlesen: So binden Sie Werte mithilfe von Platzhaltern in SQL-Abfragen:
- So verwenden Sie Platzhalter zum Binden von Werten in SQL-Abfragen
  So binden Sie Werte mithilfe von Platzhaltern in SQL-Abfragen:
- So passen Sie benutzerdefinierte Python-Typen an SQLite-Werte an
  So passen Sie einen benutzerdefinierten Python-Typ an einen SQLite-Wert an:
- So konvertieren Sie SQLite-Werte in benutzerdefinierte Python-Typen
  So konvertieren Sie einen SQLite-Wert in einen benutzerdefinierten Python-Typ:
- So verwenden Sie den Verbindungskontext-Manager
  So verwenden Sie den Verbindungskontextmanager:
- So erstellen und verwenden Sie Zeilenfabriken
  So erstellen und verwenden Sie Zeilenfabriken:
Erläuterungfür ausführliche Hintergrundinformationen zur Transaktionskontrolle.
Eine ausführliche Hintergrunderklärung zur Transaktionskontrolle:

ReferenzParameterbeschreibung：

Modulfunktionen

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)

Öffnen Sie eine Verbindung zu einer SQLite-Datenbank. Mit dieser Funktion wird eine Verbindung zu einer SQLite-Datenbank geöffnet.

Parameter:

Datenbank (pfadähnliches Objekt) – Der Pfad zur zu öffnenden Datenbankdatei. Sie können":memory:"zur Erstellung einesSQLite-Datenbank, die nur im Speicher vorhanden ist, und öffnen Sie eine Verbindung dazu.database (path-like object)
Datenbank (pfadähnliches Objekt) – Dies ist der Pfad zur Datenbankdatei, die geöffnet werden soll.Du kannst passieren":memory:"um eine speicherinterne SQLite-Datenbank zu erstellen und eine damit verbundene .database (pfadähnliches Objekt) zu öffnen.
Auszeit (schweben) – Wie viele Sekunden soll die Verbindung warten, bevor eineBetriebsfehlerwenn eine Tabelle gesperrt ist. Wenn eine andere Verbindung eine Transaktion öffnet, um eine Tabelle zu ändern, wird diese Tabelle gesperrt, bis die Transaktion festgeschrieben wird. Standardmäßig fünf Sekunden.timeout (float) — Die Verbindung wird unterbrochen, wenn die Tabelle gesperrt istOperationalError Wie viele Sekunden sollte vorher gewartet werden. Wenn eine andere Verbindung eine Transaktion öffnet, um die Tabelle zu ändern, wird die Tabelle gesperrt, bis die Transaktion festgeschrieben wird. Der Standardwert beträgt fünf Sekunden.
Typen erkennen (int) – Kontrollieren Sie, ob und wie Datentypen nichtwird nativ von SQLite unterstütztwerden zur Konvertierung in Python-Typen gesucht, mit den Konvertern, die bei registriert sindregister_converter(). Stellen Sie es auf eine beliebige Kombination ein (mit|, bitweises oder) vonPARSE_DECLTYPESUndPARSE_COLNAMESum dies zu ermöglichen. Spaltennamen hat Vorrang vordeklarierte Typen wenn beide Flags gesetzt sind. Für generierte Felder können keine Typen erkannt werden (z.B.max(data)), selbst wenn dieTypen erkennenParameter ist gesetzt;strwird stattdessen zurückgegeben. Standardmäßig (0), ist die Typerkennung deaktiviert.
detect_types (int)– Steuert, ob und wie Datentypen, die SQLite nicht nativ unterstützt, zur Verwendung gefunden werdenregister_converter() Registrierte Konverter konvertieren sie in Python-Typen.stellen Sie es einPARSE_DECLTYPESUndPARSE_COLNAMESjede Kombination von (mit bitweiser oder| ), um diese Funktion zu aktivieren.Wenn beide Flags gesetzt sind, dannAufführen wird Vorrang habenStellungnahme Typ.Für generierte Regionen können diese Typen nicht erkannt werden (z. B.max(data)), auch wenn es gesetzt istdetect_typesParameter; stattdessen wird es zurückgegebenstr Typ. Standardmäßig (0) ist die Typerkennung deaktiviert.

Fügen Sie es hier ein
Wer ist in diesem englischen Absatz das Thema „zu dem aufgeschaut wird“?
In diesem englischen Absatz bezieht sich das Thema „werden nachgeschlagen“ auf die „Datentypen, die von SQLite nicht nativ unterstützt werden (Datentypen, die von SQLite nicht nativ unterstützt werden)“.Dies bedeutet, dass durch die Verwendungregister_converter() Registrierte Konverter zum Suchen und Konvertieren von Datentypen, die von SQLite nicht nativ unterstützt werden, in Python-Typen. Subjekte sind also die spezifischen Datentypen, die gefunden und konvertiert werden müssen.

Isolationsstufe (str | Keiner) – Kontrollieren Sie das Verhalten der herkömmlichen Transaktionsverarbeitung. SieheVerbindungsisolationsebeneUndTransaktionskontrolle über das isolation_level-Attributfür weitere Informationen. Kann"DEFERRED"(Standard),"EXCLUSIVE"oder"IMMEDIATE"; oderNoneum das Öffnen von Transaktionen implizit zu deaktivieren. Hat keine Auswirkung, es sei dennVerbindung.autocommitist eingestellt aufLegacy-Transaktionssteuerung(der Standard).
isolation_level(Zeichenfolge | Keine) – Kontrollieren Sie das Verhalten bei der Verarbeitung älterer Transaktionen.Weitere Informationen finden Sie unterConnection.isolation_levelund „passieren“.isolation_levelEigentumskontrolltransaktion". Kann sein"DEFERRED"(Standardwert),"EXCLUSIVE"oder"IMMEDIATE";oder auf setzenNone um das implizite Öffnen von Transaktionen zu deaktivieren.Es sei dennConnection.autocommitFestlegen alsLEGACY_TRANSACTION_CONTROL(Standard), andernfalls hat diese Einstellung keine Auswirkung.
check_same_thread (bool) - WennTrue(Standard),Programmierfehlerwird ausgelöst, wenn die Datenbankverbindung von einem anderen Thread als dem verwendet wird, der sie erstellt hat. WennFalse, die Verbindung kann in mehreren Threads aufgerufen werden; Schreibvorgänge müssen möglicherweise vom Benutzer serialisiert werden, um Datenbeschädigungen zu vermeiden. SieheThreadsicherheitfür mehr Informationen.
check_same_thread(Boolescher Wert) – Wenn eingestelltTrue(Standard) wird ausgelöst, wenn die Datenbankverbindung von einem anderen Thread als dem Thread verwendet wird, der sie erstellt hat.ProgrammingError abnormal.Wenn eingestellt aufFalse , können mehrere Threads auf die Verbindung zugreifen, aber Benutzer müssen möglicherweise (kontinuierlich) Schreibvorgänge selbst serialisieren, um Datenbeschädigungen zu vermeiden.Weitere Informationen finden Sie unterthreadsafetyAnweisung von.
Fabrik (Verbindung) – Eine benutzerdefinierte Unterklasse vonVerbindungmit dem die Verbindung hergestellt werden soll, wenn dies nicht der Standardwert istVerbindungKlasse.
factory(Verbindung) – Wenn nicht die Standardeinstellung verwendet wirdConnectionKlasse, geben Sie einen benutzerdefinierten Wert anConnection Unterklasse zum Erstellen der Verbindung. Mit diesem Parameter können Sie das Verhalten der Datenbankverbindung entsprechend spezifischer Anforderungen oder Erweiterungen anpassen.
zwischengespeicherte_Anweisungen (int) – Die Anzahl der Aussagen, diesqlite3sollte für diese Verbindung intern zwischengespeichert werden, um einen Analyseaufwand zu vermeiden. Standardmäßig 128 Anweisungen.
cached_statements(int) – sqlite3 Die Anzahl der Anweisungen, die für diese Verbindung intern zwischengespeichert werden sollten, um einen Mehraufwand beim Parsen zu vermeiden. Standardmäßig werden 128 Anweisungen zwischengespeichert. Mit diesem Parameter können Sie die Cachegröße anpassen, um die Leistung oder Speichernutzung zu optimieren.
uri (bool) – Wenn eingestellt aufTrue, Datenbankwird als URI mit einem Dateipfad und einer optionalen Abfragezeichenfolge interpretiert. Der SchemateilmussSei"file:"und der Pfad kann relativ oder absolut sein. Die Abfragezeichenfolge ermöglicht die Übergabe von Parametern an SQLite, wodurch verschiedeneSo arbeiten Sie mit SQLite-URIs.
uri(bool) – Wenn eingestelltTrue,Aberdatabase Wird als Uniform Resource Identifier (URI) mit einem Dateipfad und einer optionalen Abfragezeichenfolge interpretiert. Der Schemateil des URImuss ist „file:“, der Pfad kann relativ oder absolut sein. Abfragezeichenfolgen ermöglichen die Übergabe von Parametern an SQLite und ermöglichen so verschiedene Arten der Arbeit mit SQLite-URIs. Dies ermöglicht komplexere Datenbankverbindungsoptionen wie das Festlegen des schreibgeschützten Modus, das Festlegen der Cache-Größe usw.
automatisches Festschreiben (bool) - KontrollePEP 249Verhalten bei der Transaktionsabwicklung. SieheVerbindung.autocommitUndTransaktionssteuerung über das Autocommit-Attributfür mehr Informationen.automatisches Festschreibenderzeit standardmäßigLegacy-TransaktionssteuerungDie Standardeinstellung ändert sich zuFalsein einer zukünftigen Python-Version.
autocommit(bool) – Kontrollieren Sie das Transaktionsverarbeitungsverhalten gemäß PEP 249.Weitere Informationen finden Sie unterConnection.autocommit und „Transaktionen über das Autocommit-Attribut steuern.“ derzeit,autocommitDer Standardwert ist auf eingestelltLEGACY_TRANSACTION_CONTROL , was bedeutet, dass es dem alten Transaktionskontrollverhalten der Python-Datenbank-API-Spezifikation (PEP 249) folgt.In einer zukünftigen Version von Python wird sich die Standardeinstellung jedoch in ändernFalseDies bedeutet, dass Transaktionen nicht standardmäßig automatisch festgeschrieben werden und der Benutzer den Start und das Ende der Transaktion explizit steuern muss.

Bitte beachten Sie,*Parameter werden in Funktionsdefinitionen als Trennzeichen zwischen Positions- und Schlüsselwortargumenten verwendetautocommitAlle Parameter danach müssen Schlüsselwortparameter sein.

Rückgabetyp:Rückgabetyp：

Verbindung

Wirft einAuditierungsereignis sqlite3.connectmit Argumentdatabase.
sqlite3.connect: Beim BenutzendatabaseParameter, die beim Herstellen einer Verbindung zur Datenbank ausgelöst werden.

Wirft einAuditierungsereignis sqlite3.connect/handlemit Argumentconnection_handle.
sqlite3.connect/handle: Wenn das Verbindungshandle (connection_handle) wird beim Erstellen ausgelöst.

Geändert in Version 3.4: Hinzugefügt wurde dieuriParameter.
In Version 3.4: hinzugefügturiParameter, der die Angabe der Datenbankdatei im URI-Format ermöglicht.

Geändert in Version 3.7:Datenbankkann jetzt auch einpfadähnliches Objekt, nicht nur eine Zeichenfolge.
In Version 3.7:databaseParameter können jetzt ein pfadähnliches Objekt statt nur Zeichenfolgen sein.

Geändert in Version 3.10: Hinzugefügt wurde diesqlite3.connect/handleAuditierungsereignis.
In Version 3.10: hinzugefügtsqlite3.connect/handleAudit-Ereignis, das ausgelöst wird, wenn das Verbindungshandle erstellt wird.

Geändert in Version 3.12: Hinzugefügt wurde dieautomatisches FestschreibenParameter.
In Version 3.12: hinzugefügtautocommitParameter, die eine genauere Kontrolle über das Auto-Commit-Verhalten von Transaktionen ermöglichen.

sqlite3.complete_statement(Stellungnahme)

ZurückkehrenTruewenn die ZeichenfolgeStellungnahmescheint eine oder mehrere vollständige SQL-Anweisungen zu enthalten. Es wird keine syntaktische Überprüfung oder Analyse irgendeiner Art durchgeführt, außer dass geprüft wird, dass keine offenen Zeichenfolgenliterale vorhanden sind und die Anweisung durch ein Semikolon abgeschlossen wird.
wenn Zeichenfolgestatementscheint eine oder mehrere vollständige SQL-Anweisungen zu enthalten, dann kehren Sie zurückTrue . Es wird keine Syntaxvalidierung oder Syntaxanalyse durchgeführt, außer dass überprüft wird, ob keine nicht geschlossenen Zeichenfolgenliterale vorhanden sind und die Anweisung mit einem Semikolon endet.

Zum Beispiel:Beispiel

>>>


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

Diese Funktion kann bei der Eingabe in die Befehlszeile hilfreich sein, um festzustellen, ob der eingegebene Text eine vollständige SQL-Anweisung zu bilden scheint oder ob vor dem Aufruf zusätzliche Eingaben erforderlich sind.ausführen().
Diese Funktion kann bei der Eingabe in der Befehlszeile nützlich sein, um festzustellen, ob der eingegebene Text wie eine vollständige SQL-Anweisung aussieht oder ob er aufgerufen wirdexecute()Ob zuvor zusätzliche Eingaben erforderlich sind.

Sehenrunsource()InLib/sqlite3/__main__.pyfür den Einsatz in der realen Welt.
Auf praktische Anwendungen können Sie sich beziehenLib/sqlite3/__main__.pyMitterunsource()Funktion, um ihre Verwendung zu verstehen.

sqlite3.enable_callback_tracebacks(Flagge, /)

Aktivieren oder deaktivieren Sie Callback-Tracebacks. Standardmäßig erhalten Sie keine Tracebacks in benutzerdefinierten Funktionen, Aggregaten, Konvertern, Authorizer-Callbacks usw. Wenn Sie sie debuggen möchten, können Sie diese Funktion mit aufrufenFlaggeeinstellenTrue. Anschließend erhalten Sie Tracebacks von Callbacks aufsys.stderr. VerwendenFalseum die Funktion wieder zu deaktivieren.
Aktivieren oder deaktivieren Sie die Rückrufverfolgung. Standardmäßig erhalten Sie keine Tracebacks in benutzerdefinierten Funktionen, Aggregatfunktionen, Konvertern, Autorisierungsrückrufen usw.Wenn Sie sie debuggen möchten, können Sie diese Funktion aufrufen und ersetzenflagFestlegen alsTrue .Danach wird es Ihnen möglich seinsys.stderr Rufen Sie Ablaufverfolgungsinformationen aus dem Rückruf ab.verwendenFalseum diese Funktion wieder zu deaktivieren.

Notiz

Fehler in benutzerdefinierten Funktionsrückrufen werden als nicht auslösbare Ausnahmen protokolliert. Verwenden Sie einenNicht ausfahrbarer Hook-Handlerzur Selbstprüfung des fehlgeschlagenen Rückrufs.
Fehler in benutzerdefinierten Funktionsrückrufen werden als nicht abfangbare Ausnahmen protokolliert. Verwenden Sie einen nicht auslösbaren Hook-Handler, um eine Selbstprüfung bei fehlgeschlagenen Rückrufen durchzuführen.

Das bedeutet, dass bei Fehlern in Rückrufen der benutzerdefinierten Funktionen von SQLite (z. B. Aggregatfunktionen, Skalarfunktionen usw.) diese Fehler nicht wie normale Python-Ausnahmen ausgelöst werden und von Try-Except-Blöcken abgefangen werden können. Stattdessen werden sie von SQLite oder dem sqlite3-Modul von Python erfasst und auf irgendeine Weise protokolliert (normalerweise in das Protokoll oder die Standardfehlerausgabe geschrieben), unterbrechen jedoch nicht die Ausführung des Programms (es sei denn, der Fehler ist sehr schwerwiegend).

Um diese nicht abfangbaren Ausnahmen zu untersuchen und zu debuggen, können Sie einen „unabfangbaren Hook-Handler“ einrichten. Dieser Handler ist eine Funktion, die Python aufruft, wenn eine nicht abgefangene Ausnahme auftritt, und die Ausnahmeinformationen als Parameter übergibt. Auf diese Weise können Sie Code in die Prozessorfunktion schreiben, um diese Ausnahmen zu protokollieren oder nach ihnen zu suchen und so das Problem zu diagnostizieren.

Bitte beachten Sie, dass die spezifische Implementierung je nach Python-Version und den Implementierungsdetails des sqlite3-Moduls variieren kann. Daher wird empfohlen, die neueste Python-Dokumentation oder die Dokumentation des sqlite3-Moduls zu konsultieren, um zu erfahren, wie der uncatchable Hook-Handler eingerichtet und verwendet wird.

**sqlite3.register_adapter(Typ, Adapter, /)**

Registrieren Sie einAdapter abrufbarum den Python-Typ anzupassenTypin einen SQLite-Typ. Der Adapter wird mit einem Python-Objekt vom TypTypals einziges Argument und muss einen Wert von a zurückgebenTyp, den SQLite nativ versteht.
Registrieren Sie ein aufrufbares **Adapter**-Objekt zum Konvertieren von Pythonstype Der Typ wird an einen Typ angepasst, den SQLite nativ verstehen kann.Diese Adapterfunktion dauert atypeEin Objekt vom Typ wird als einziges Argument aufgerufen und muss einen Wert eines Typs zurückgeben, den SQLite nativ unterstützt.

Es ist zu beachten, dass „typeTyp“ kann etwas irreführend sein, da wir uns normalerweise nicht auf die integrierte Python-Funktion beziehentype Die Objekte (d. h. die Typen selbst) werden direkt in der Datenbank gespeichert. Häufiger möchten wir Objekte in Python (bei denen es sich möglicherweise um Instanzen benutzerdefinierter Typen handelt) in ein Format umwandeln, das SQLite speichern kann.Nehmen Sie den Satz jedoch wörtlich, wenn Sie sich damit auseinandersetzen müssentypeObjekt selbst (obwohl dies in der Praxis selten vorkommt), müssen Sie einen Adapter schreiben, um es in eine Form zu konvertieren, die SQLite speichern kann, beispielsweise eine Zeichenfolge, die den Namen des Typs darstellt.

Ein häufigerer Anwendungsfall sind jedoch benutzerdefinierte Python-Typen oder integrierte Typen wiedatetime、decimal.Decimalusw.) schreiben Adapter, damit sie von der SQLite-Datenbank korrekt gespeichert und abgerufen werden können.

Wenn Sie beispielsweise eine benutzerdefinierte Python-Klasse habenMyClassund seine Instanz in einer SQLite-Datenbank speichern möchten, können Sie einen Adapter schreiben, um eine Instanz dieser Klasse in eine Zeichenfolge (oder einen anderen Typ) umzuwandeln, die von SQLite gespeichert werden kann, und dann einen Konverter schreiben, um diese Zeichenfolge zurückzukonvertieren ZuMyClassBeispiel.

Für diese Frage gilt jedoch, dass man sich nur mit Python befassen möchtetypeWenn Sie ein Objekt (d. h. die Metadaten des Typs) verwenden, schreiben Sie möglicherweise einen Adapter, um den Namen des Typs (als Zeichenfolge) zurückzugeben. Dies ist jedoch im Allgemeinen keine gängige Praxis zum Speichern von Objekten in einer Datenbank.

sqlite3.register_converter(Modellname, Konverter, /)

Registrieren Sie dieKonverter abrufbarzum Konvertieren von SQLite-Objekten des TypsModellnamein ein Python-Objekt eines bestimmten Typs. Der Konverter wird für alle SQLite-Werte vom Typ aufgerufenModellname; es wird einBytesObjekt und sollte ein Objekt des gewünschten Python-Typs zurückgeben. Konsultieren Sie den ParameterTypen erkennenvonverbinden()für Informationen zur Funktionsweise der Typerkennung.
Registrieren Sie ein aufrufbares **Konverter**-Objekt zum Konvertieren von SQLite-Typentypename Konvertiert ein Objekt in ein Python-Objekt eines bestimmten Typs.Für alle TypentypenameDieser Konverter wird für jeden SQLite-Wert aufgerufen, den er empfängtbytes Objekt als Argument und sollte ein Objekt des erforderlichen Python-Typs zurückgeben.Informationen zur Funktionsweise der Typerkennung finden Sie unterconnect()Funktionaldetect_typesParameter.

Notiz:Modellnameund der Name des Typs in Ihrer Abfrage werden ohne Berücksichtigung der Groß-/Kleinschreibung abgeglichen.
Beachten：typenameBeim Namen des Typs in der Abfrage wird beim Abgleich die Groß-/Kleinschreibung nicht beachtet.

Modulkonstanten

sqlite3.LEGACY_TRANSACTION_CONTROL

Satzautomatisches Festschreibenzu dieser Konstante, um das Transaktionssteuerungsverhalten im alten Stil (vor Python 3.12) auszuwählen. SieheTransaktionskontrolle über das isolation_level-Attributfür mehr Informationen.
Willeautocommit Legen Sie diese Konstante fest, um das Verhalten der Transaktionssteuerung im alten Stil (vor Python 3.12) auszuwählen.Weitere Informationen finden Sie unter „Passisolation_level„Eigenschaften steuern Transaktionen“.

sqlite3.PARSE_COLNAMES

Übergeben Sie diesen Flagwert an denTypen erkennenParameter vonverbinden()um eine Konverterfunktion zu suchen, indem der Typname, der aus dem Abfragespaltennamen analysiert wurde, als Konverterwörterbuchschlüssel verwendet wird. Der Typname muss in eckige Klammern ([]).
Übergeben Sie diesen Flag-Wert anconnect()Funktionaldetect_types Parameter zum Suchen der Konverterfunktion durch Abfrage des aufgelösten Typnamens im Spaltennamen als Schlüssel zum Konverterwörterbuch. Typnamen müssen in eckige Klammern ([]) eingeschlossen werden.

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

Diese Flagge kann kombiniert werden mitPARSE_DECLTYPESVerwendung der|(bitweiser Oder)-Operator.
Dieses Flag kann verwendet werden|(bitweises ODER) Operator ANDPARSE_DECLTYPESIn Verbindung mit.

sqlite3.PARSE_DECLTYPES

Übergeben Sie diesen Flagwert an denTypen erkennenParameter vonverbinden()um eine Konverterfunktion unter Verwendung der deklarierten Typen für jede Spalte nachzuschlagen. Die Typen werden beim Erstellen der Datenbanktabelle deklariert.sqlite3sucht eine Konverterfunktion unter Verwendung des ersten Wortes des deklarierten Typs als Konverterwörterbuchschlüssel. Beispiel:
Übergeben Sie diesen Flag-Wert anconnect()Funktionaldetect_types Parameter zum Suchen der Konverterfunktion anhand des deklarierten Typs jeder Spalte in der Datenbank. Diese Typen werden beim Erstellen der Datenbanktabelle deklariert.sqlite3 Die Konverterfunktion wird mithilfe des ersten Worts im deklarierten Typ als Schlüssel des Konverterwörterbuchs gesucht. Zum Beispiel:


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

Diese Flagge kann kombiniert werden mitPARSE_COLNAMESVerwendung der|(bitweiser Oder)-Operator.

sqlite3.SQLITE_OK

sqlite3.SQLITE_DENY

sqlite3.SQLITE_IGNORE

Flags, die zurückgegeben werden sollen vonAutorisierer_Rückruf abrufbarweitergereicht anVerbindung.set_authorizer(), um anzugeben, ob:
Übergeben anConnection.set_authorizer()vonauthorizer_callbackFlags, die die aufrufbare Funktion zurückgeben soll, um Folgendes anzuzeigen:

Der Zugriff ist erlaubt (SQLITE_OK), der Zugriff ist erlaubt (SQLITE_OK）
Die SQL-Anweisung sollte mit einem Fehler abgebrochen werden (SQLITE_DENY)
Die SQL-Anweisung sollte mit einem Fehler abgebrochen werden (SQLITE_DENY）
Die Spalte sollte behandelt werden alsNULLWert (SQLITE_IGNORE)
Spalten sollten als NULL-Werte behandelt werden (SQLITE_IGNORE）

sqlite3.apilevel

String-Konstante, die die unterstützte DB-API-Ebene angibt. Wird von der DB-API benötigt. Fest codiert auf"2.0".
Diese beiden String-Konstanten sindsqlite3Sie sind in Modulen definiert und folgen der Python Database API-Spezifikation (DB-API).

sqlite3.paramstyle

String-Konstante, die den Typ der Parametermarkerformatierung angibt, die vomsqlite3Modul. Wird von der DB-API benötigt. Fest codiert auf"qmark".
Diese String-Konstante gibt ansqlite3 Der vom Modul erwartete Typ der Parametermarkierungsformatierung. Dies ist in der DB-API-Spezifikation (Database Application Programming Interface) erforderlich.Es ist fest codiert als"qmark"bedeutet, dass beim Erstellen von SQL-Abfragen Parametermarkierungen durch Fragezeichen (?) dargestellt werden sollten.

Notiz

DernamedDer DB-API-Parameterstil wird ebenfalls unterstützt.

sqlite3.sqlite_version

Versionsnummer der SQLite-Laufzeitbibliothek alsSchnur.
Die Versionsnummer der SQLite-Laufzeitbibliothek, ausgedrückt in Zeichenfolgenform.

sqlite3.sqlite_version_info

Versionsnummer der SQLite-Laufzeitbibliothek alsTupelvonGanzzahlen.
Die Versionsnummer der SQLite-Laufzeitbibliothek, ausgedrückt als Tupel von Ganzzahlen.

sqlite3.threadsafety

Von der DB-API 2.0 benötigte Integer-Konstante, die den Grad der Thread-Sicherheit angibt,sqlite3Modul unterstützt. Dieses Attribut wird basierend auf dem Standardwert festgelegtThreading-Modusdie zugrunde liegende SQLite-Bibliothek wird mit kompiliert. Die SQLite-Threading-Modi sind:
Von DB-API 2.0 benötigte Ganzzahlkonstante, die angibtsqlite3 Die vom Modul unterstützte Thread-Sicherheitsstufe. Diese Eigenschaft wird entsprechend dem Standard-Threading-Modus festgelegt, mit dem die zugrunde liegende SQLite-Bibliothek kompiliert wurde. Zu den Threading-Modi von SQLite gehören:

Einzelthread: In diesem Modus sind alle Mutexe deaktiviert und die gleichzeitige Verwendung von SQLite in mehr als einem Thread ist unsicher.
Single-Thread: In diesem Modus sind alle Mutexe deaktiviert und SQLite kann nicht sicher von mehreren Threads gleichzeitig verwendet werden.
Multi Thread: In diesem Modus kann SQLite sicher von mehreren Threads verwendet werden, vorausgesetzt, dass keine einzelne Datenbankverbindung gleichzeitig in zwei oder mehr Threads verwendet wird.
Multithread: In diesem Modus kann SQLite sicher von mehreren Threads verwendet werden, vorausgesetzt, dass keine einzelne Datenbankverbindung gleichzeitig von zwei oder mehr Threads verwendet wird.
Serialisiert: Im serialisierten Modus kann SQLite ohne Einschränkung sicher von mehreren Threads verwendet werden.
Serialisiert: Im serialisierten Modus kann SQLite ohne Einschränkungen sicher von mehreren Threads verwendet werden.

Die Zuordnungen von SQLite-Threading-Modi zu DB-API 2.0-Threadsicherheitsebenen lauten wie folgt:
Die Zuordnung des Thread-Modus von SQLite zur Thread-Sicherheitsstufe DB-API 2.0 ist wie folgt:

SQLite-Threading-Modus	Threadsicherheit	SQLITE_THREADSAFE	Bedeutung von DB-API 2.0
Einzelthread	0	0	Threads dürfen das Modul nicht gemeinsam nutzen
Multi Thread	1	2	Threads können das Modul gemeinsam nutzen, aber keine Verbindungen
serialisiert	3	1	Threads können das Modul, die Verbindungen und die Cursor gemeinsam nutzen

Geändert in Version 3.11: SetThreadsicherheitdynamisch statt fest zu codieren1.

sqlite3.version

Versionsnummer dieses Moduls alsSchnur. Dies ist nicht die Version der SQLite-Bibliothek.
Die Versionsnummer dieses Moduls, ausgedrückt als Zeichenfolge.DasNEINDie Versionsnummer der SQLite-Bibliothek.

Veraltet seit Version 3.12, wird in Version 3.14 entfernt: Diese Konstante spiegelte früher die Versionsnummer despysqlitePaket, eine Drittanbieter-Bibliothek, die Upstream-Änderungen ansqlite3Heute hat es weder Bedeutung noch praktischen Wert.
Seit Version 3.12 veraltet, wird in Version 3.14 entfernt: Diese Konstante wurde zur Reflektion verwendetpysqliteDie Versionsnummer des Pakets,pysqliteEs handelt sich um eine Bibliothek eines Drittanbieters, die in den Upstream hochgeladen wurdesqlite3 Übernehmen Sie die Änderungen. Jetzt hat es keine wirkliche Bedeutung oder keinen praktischen Wert.

sqlite3.version_info

Versionsnummer dieses Moduls alsTupelvonGanzzahlen. Dies ist nicht die Version der SQLite-Bibliothek.

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_TRUSTED_SCHEMA

sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

Diese Konstanten werden verwendet für dieVerbindung.setconfig()Undgetconfig()Methoden.
Diese Konstanten werden verwendetConnection.setconfig()Undgetconfig()Methode.

Die Verfügbarkeit dieser Konstanten variiert je nach der SQLite-Version, mit der Python kompiliert wurde.
Die Verfügbarkeit dieser Konstanten hängt von der SQLite-Version ab, mit der SQLite Python kompiliert wurde.

Hinzugefügt in Version 3.12.

Siehe auch

Konfigurationsoptionen für die Datenbankverbindung

SQLite-Dokumente: Konfigurationsoptionen für die Datenbankverbindung

Verbindungsobjekte

Klassesqlite3.Verbindung

Jede geöffnete SQLite-Datenbank wird repräsentiert durch eineConnectionObjekt, das erstellt wird mitsqlite3.connect()Ihr Hauptzweck ist die SchaffungMauszeigerObjekte undTransaktionskontrolle.

Siehe auch

Eine SQLite-Datenbankverbindung hat die folgenden Attribute und Methoden:

Mauszeiger(Fabrik=Cursor)

Erstellen und zurückgeben einesMauszeigerObjekt. Die Cursor-Methode akzeptiert einen einzigen optionalen ParameterFabrik. Falls angegeben, muss es sich um eineabrufbarRückgabe einer Instanz vonMauszeigeroder seine Unterklassen.
Erstellt a und gibt a zurückCursorObjekt.cursorDie Methode akzeptiert einen optionalen einzelnen Parameterfactory .Wenn dieser Parameter angegeben wird, muss es sich um ein aufrufbares Objekt handeln, das a zurückgibtCursoroder eine Instanz seiner Unterklasse.

bloböffnen(Tisch, Spalte, Reihe, /, , schreibgeschützt=Falsch, Name = "Haupt"*)

Öffne einKlecksHandle zu einem vorhandenen BLOB.

Parameter:

Tisch (str) – Der Name der Tabelle, in der sich der Blob befindet.
Der Name der Tabelle, die BLOB-Daten enthält.
Spalte (str) – Der Name der Spalte, in der sich der Blob befindet.
Spaltenname, der BLOB-Daten enthält.
Reihe (str) – Der Name der Zeile, in der sich der Blob befindet.
Der Name der Zeile (oder genauer gesagt der Bezeichner der Zeile), die die BLOB-Daten enthält.
schreibgeschützt (bool) - EinstellenTruewenn der Blob ohne Schreibberechtigung geöffnet werden soll. Der Standardwert istFalse.
Wenn es auf „True“ gesetzt ist, bedeutet dies, dass das BLOB ohne Schreibberechtigung geöffnet werden soll. Der Standardwert ist False, was Lesen und Schreiben ermöglicht.
Name (str) – Der Name der Datenbank, in der sich der Blob befindet. Der Standardwert ist"main".
Der Name der Datenbank, die BLOB-Daten enthält. Der Standardwert ist „main“, der Standarddatenbankname in SQLite.

Erhöht:

Betriebsfehler– Beim Versuch, einen Blob in einemWITHOUT ROWIDTisch.
Beim Versuch ohneREIHETritt auf, wenn BLOB-Daten in der ID-Tabelle geöffnet werden.

Rückgabetyp:

Klecks

Notiz

Die Blobgröße kann nicht mit demKlecksKlasse. Verwenden Sie die SQL-Funktionzeroblobum einen Blob mit einer festen Größe zu erstellen.

Hinzugefügt in Version 3.11.

begehen()

Übernehmen Sie alle ausstehenden Transaktionen in die Datenbank. Wennautomatisches FestschreibenIstTrueoder es ist keine offene Transaktion vorhanden, dann tut diese Methode nichts. WennautocommitIstFalse, wird implizit eine neue Transaktion geöffnet, wenn eine ausstehende Transaktion mit dieser Methode festgeschrieben wurde.
Übertragen Sie alle ausstehenden Transaktionen in die Datenbank.Wennautocommit Ist True oder es gibt keine offene Transaktion, führt diese Methode keine Operation aus.WennautocommitFalsch ist und diese Methode eine ausstehende Transaktion festschreibt, wird implizit eine neue Transaktion gestartet.

Rollback()

Gehen Sie zum Anfang einer ausstehenden Transaktion zurück. Wennautomatisches FestschreibenIstTrueoder es ist keine offene Transaktion vorhanden, dann tut diese Methode nichts. WennautocommitIstFalse, wird implizit eine neue Transaktion geöffnet, wenn eine ausstehende Transaktion mit dieser Methode zurückgesetzt wurde.
Führen Sie einen Rollback zum Anfang aller ausstehenden Transaktionen durch.Wennautocommit Ist True oder es gibt keine offene Transaktion, führt diese Methode keine Operation aus.WennautocommitFalsch ist und diese Methode eine ausstehende Transaktion zurücksetzt, wird implizit eine neue Transaktion gestartet.

schließen()

Schließen Sie die Datenbankverbindung. Wennautomatisches FestschreibenIstFalsewird jede ausstehende Transaktion implizit zurückgesetzt. WennautocommitIstTrueoderLegacy-Transaktionssteuerungwird keine implizite Transaktionskontrolle durchgeführt. Stellen Sie sicher, dassbegehen()vor dem Schließen, um den Verlust ausstehender Änderungen zu vermeiden.
Schließen Sie die Datenbankverbindung.Wennautocommit Bei False werden alle ausstehenden Transaktionen implizit zurückgesetzt.Wennautocommitist wahr oderLEGACY_TRANSACTION_CONTROL (Legacy-Transaktionskontrolle), eine implizite Transaktionskontrolle wird nicht durchgeführt.Bevor Sie schließen, rufen Sie unbedingt ancommit()um zu vermeiden, dass ausstehende Änderungen verloren gehen.

ausführen(SQL-Befehle, Parameter=(), /)

Erstelle eine neueMauszeigerObjekt und Anrufausführen()darauf mit dem gegebenenSQL-BefehleUndParameter. Gibt das neue Cursorobjekt zurück.
erstelle eine neueCursorObjekt und rufe es anexecute()Methode, die das Gegebene übergibtsql Anweisungen und Parameter.gib das neu zurückCursorObjekt.

viele ausführen(SQL-Befehle, Parameter, /)

Erstelle eine neueMauszeigerObjekt und Anrufviele ausführen()darauf mit dem gegebenenSQL-BefehleUndParameter. Gibt das neue Cursorobjekt zurück.
erstelle eine neueCursorObjekt und rufe es anexecutemany()Methode, die das Gegebene übergibtsql Anweisungen und Parametersequenzen. Dadurch können mehrere Parametersätze gleichzeitig ausgeführt werden.gib das neu zurückCursorObjekt.

ausführenscript(sql_skript, /)

Erstelle eine neueMauszeigerObjekt und AnrufExecuteScript()darauf mit dem gegebenensql_skript. Gibt das neue Cursorobjekt zurück.
erstelle eine neueCursorObjekt und rufe es anexecutescript() Methode, die das angegebene SQL-Skript übergibt. Dies ermöglicht die Ausführung mehrerer SQL-Anweisungen, getrennt durch Semikolon im Skript.gib das neu zurückCursorObjekt.

Funktion erstellen(Name, narg, Funktion, , deterministisch=Falsch*)

Erstellen oder entfernen Sie eine benutzerdefinierte SQL-Funktion.
Erstellen oder entfernen Sie eine benutzerdefinierte SQL-Funktion.

Parameter:

Name (str) – Der Name der SQL-Funktion.
name(str) – Der Name der SQL-Funktion.
narg (int) – Die Anzahl der Argumente, die die SQL-Funktion akzeptieren kann. Wenn-1, es kann eine beliebige Anzahl von Argumenten annehmen.
narg (int) – Die Anzahl der Argumente, die die SQL-Funktion akzeptieren kann. Bei -1 bedeutet dies, dass eine beliebige Anzahl von Argumenten akzeptiert werden kann.
Funktion (Ruf zurück| Keine) – Aabrufbardas aufgerufen wird, wenn die SQL-Funktion aufgerufen wird. Das aufrufbare Objekt mussein Typ, der nativ von SQLite unterstützt wird. EinstellenNoneum eine vorhandene SQL-Funktion zu entfernen.
func (Rückruf | Keine) – Dieses aufrufbare Objekt (Rückruf) wird ausgeführt, wenn die SQL-Funktion aufgerufen wird. Dieses aufrufbare Objekt muss einen von SQLite nativ unterstützten Typ zurückgeben. Bei der Einstellung „Keine“ werden vorhandene SQL-Funktionen entfernt.
deterministisch (bool) - WennTruewird die erstellte SQL-Funktion markiert alsdeterministisch, wodurch SQLite zusätzliche Optimierungen durchführen kann.
deterministic(bool) – Wenn True, markiert die erstellte SQL-Funktion als deterministisch, wodurch SQLite zusätzliche Optimierungen durchführen kann.

Erhöht:

Nicht unterstützter Fehler- Wenndeterministischwird mit SQLite-Versionen älter als 3.8.3 verwendet.

Geändert in Version 3.8: Hinzugefügt wurde diedeterministischParameter.

Beispiel:

>>>


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

Aggregat erstellen(Name, n_arg, Aggregatklasse)

Erstellen oder entfernen Sie eine benutzerdefinierte SQL-Aggregatfunktion.
Erstellen oder entfernen Sie eine benutzerdefinierte SQL-Aggregatfunktion.

Parameter:

Name (str) – Der Name der SQL-Aggregatfunktion.
name(str) – Der Name der SQL-Aggregatfunktion.
n_arg (int) – Die Anzahl der Argumente, die die SQL-Aggregatfunktion akzeptieren kann. Wenn-1, es kann eine beliebige Anzahl von Argumenten annehmen.
Die Anzahl der Parameter, die eine SQL-Aggregatfunktion akzeptieren kann. Bei -1 bedeutet dies, dass eine beliebige Anzahl von Argumenten akzeptiert werden kann.
Aggregatklasse (Klasse| Keine) –

Eine Klasse muss die folgenden Methoden implementieren:
Eine Klasse muss die folgenden Methoden implementieren:
- step(): Dem Aggregat eine Zeile hinzufügen.
- finalize(): Gibt das Endergebnis des Aggregats zurück alsein Typ, der nativ von SQLite unterstützt wird.
  finalize(): Diese Methode wird verwendet, um das Endergebnis der Aggregation zurückzugeben.
Die Anzahl der Argumente, die derstep()Methode muss akzeptieren wird gesteuert durchn_arg.
step()Die Anzahl der Parameter, die eine Methode akzeptieren muss, wird durch angegebenn_argKontrolle.

EinstellenNoneum eine vorhandene SQL-Aggregatfunktion zu entfernen.
Festlegen alsNoneum vorhandene SQL-Aggregatfunktionen zu entfernen.

Beispiel:


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

Fensterfunktion erstellen(Name, Anzahl_Parameter, Aggregatklasse, /)

Erstellen oder entfernen Sie eine benutzerdefinierte Aggregatfensterfunktion.

Parameter:

Name (str) – Der Name der zu erstellenden oder zu entfernenden SQL-Aggregatfensterfunktion.
Anzahl_Parameter (int) – Die Anzahl der Argumente, die die SQL-Aggregatfensterfunktion akzeptieren kann. Wenn-1, es kann eine beliebige Anzahl von Argumenten annehmen.
Aggregatklasse (Klasse| Keine) –

Eine Klasse, die die folgenden Methoden implementieren muss:
- step(): Fügt dem aktuellen Fenster eine Zeile hinzu.
- value(): Gibt den aktuellen Wert des Aggregats zurück.
- inverse(): Entfernt eine Zeile aus dem aktuellen Fenster.
- finalize(): Gibt das Endergebnis des Aggregats zurück alsein Typ, der nativ von SQLite unterstützt wird.
Die Anzahl der Argumente, die derstep()Undvalue()Methoden müssen akzeptieren, wird kontrolliert durchAnzahl_Parameter.

EinstellenNoneum eine vorhandene SQL-Aggregatfensterfunktion zu entfernen.

Erhöht:

Nicht unterstützter Fehler– Bei Verwendung mit einer SQLite-Version älter als 3.25.0, die keine aggregierten Fensterfunktionen unterstützt.

Hinzugefügt in Version 3.11.

Beispiel:

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

Sortierung erstellen(Name, abrufbar, /)

Erstellen Sie eine Sortierung mit dem NamenNameVerwenden der Sortierfunktionabrufbar. abrufbarist zweiSchnurArgumente, und es sollte eineganze Zahl:

1wenn der erste höher als der zweite angeordnet ist
-1wenn der erste niedriger als der zweite angeordnet ist
0wenn sie gleich angeordnet sind

Das folgende Beispiel zeigt eine umgekehrte Sortierung:

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

Entfernen Sie eine Sortierfunktion durch FestlegenabrufbarZuNone.

Geändert in Version 3.11: Der Sortierungsname kann beliebige Unicode-Zeichen enthalten. Früher waren nur ASCII-Zeichen zulässig.

unterbrechen()

Rufen Sie diese Methode von einem anderen Thread aus auf, um alle Abfragen abzubrechen, die möglicherweise über die Verbindung ausgeführt werden. Abgebrochene Abfragen führen zu einerBetriebsfehler.

Autorisierungselement festlegen(Autorisierer_Rückruf)

Registrierenabrufbar Autorisierer_Rückrufsoll bei jedem Versuch aufgerufen werden, auf eine Spalte einer Tabelle in der Datenbank zuzugreifen. Der Callback sollte einen der folgenden Werte zurückgeben:SQLITE_OK, SQLITE_DENY, oderSQLITE_IGNOREum zu signalisieren, wie der Zugriff auf die Spalte von der zugrunde liegenden SQLite-Bibliothek gehandhabt werden soll.

Das erste Argument des Callbacks gibt an, welche Art von Operation autorisiert werden soll. Das zweite und dritte Argument sind Argumente oderNoneabhängig vom ersten Argument. Das vierte Argument ist der Name der Datenbank („main“, „temp“ usw.), falls zutreffend. Das fünfte Argument ist der Name des innersten Triggers oder der Ansicht, die für den Zugriffsversuch verantwortlich ist, oderNonewenn dieser Zugriffsversuch direkt vom eingegebenen SQL-Code erfolgt.

Bitte konsultieren Sie die SQLite-Dokumentation über die möglichen Werte für das erste Argument und die Bedeutung des zweiten und dritten Arguments, abhängig vom ersten. Alle notwendigen Konstanten finden Sie in dersqlite3Modul.

VorbeigehenNonealsAutorisierer_Rückrufdeaktiviert den Autorisierer.

Geändert in Version 3.11: Unterstützung für die Deaktivierung des Autorisierers hinzugefügt mitNone.

set_progress_handler(Fortschrittshandler, N)

Registrierenabrufbar Fortschrittshandlerfür jedenNAnweisungen der SQLite-VM. Dies ist nützlich, wenn Sie bei lang andauernden Vorgängen von SQLite aufgerufen werden möchten, beispielsweise um eine GUI zu aktualisieren.

Wenn Sie einen zuvor installierten Fortschrittshandler löschen möchten, rufen Sie die Methode mitNonefürFortschrittshandler.

Die Rückgabe eines Wertes ungleich Null durch die Handlerfunktion beendet die aktuell ausgeführte Abfrage und führt zu einemDatenbankfehlerAusnahme.

set_trace_callback(Trace_Rückruf)

Registrierenabrufbar Trace_Rückrufsoll für jede SQL-Anweisung aufgerufen werden, die tatsächlich vom SQLite-Backend ausgeführt wird.

Das einzige Argument, das an den Rückruf übergeben wird, ist die Anweisung (alsstr), die ausgeführt wird. Der Rückgabewert des Callbacks wird ignoriert. Beachten Sie, dass das Backend nicht nur Anweisungen ausführt, die an denCursor.execute()Methoden. Weitere Quellen sind dieTransaktionsmanagementdessqlite3Modul und die Ausführung von Triggern, die in der aktuellen Datenbank definiert sind.

VorbeigehenNonealsTrace_Rückrufdeaktiviert den Trace-Rückruf.

Notiz

Ausnahmen, die im Trace-Callback ausgelöst werden, werden nicht weitergegeben. Verwenden Sie als Entwicklungs- und Debugging-Hilfeenable_callback_tracebacks()um das Drucken von Tracebacks von Ausnahmen zu aktivieren, die im Trace-Callback ausgelöst wurden.

Hinzugefügt in Version 3.3.

Erweiterung_laden_aktivieren(ermöglicht, /)

Aktivieren Sie die SQLite-Engine, um SQLite-Erweiterungen aus gemeinsam genutzten Bibliotheken zu laden, wennermöglichtIstTrue; andernfalls wird das Laden von SQLite-Erweiterungen untersagt. SQLite-Erweiterungen können neue Funktionen, Aggregate oder ganz neue virtuelle Tabellenimplementierungen definieren. Eine bekannte Erweiterung ist die mit SQLite verteilte Volltextsucherweiterung.

Notiz

Dersqlite3Das Modul wird standardmäßig nicht mit ladbarer Erweiterungsunterstützung erstellt, da einige Plattformen (insbesondere macOS) SQLite-Bibliotheken haben, die ohne diese Funktion kompiliert werden. Um Unterstützung für ladbare Erweiterungen zu erhalten, müssen Sie das--enable-loadable-sqlite-extensionsMöglichkeit,konfigurieren.

Wirft einAuditierungsereignis sqlite3.enable_load_extensionmit Argumentenconnection, enabled.

Hinzugefügt in Version 3.2.

Geändert in Version 3.10: Hinzugefügt wurde diesqlite3.enable_load_extensionAuditierungsereignis.

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)

Erweiterung laden(Weg, /, *, Einstiegspunkt=Keiner)

Laden Sie eine SQLite-Erweiterung aus einer gemeinsam genutzten Bibliothek. Aktivieren Sie das Laden von Erweiterungen mitErweiterung_laden_aktivieren()bevor Sie diese Methode aufrufen.

Parameter:

Weg (str) – Der Pfad zur SQLite-Erweiterung.
Einstiegspunkt (str | Keiner) – Name des Einstiegspunkts. WennNone(Standard), SQLite erstellt einen eigenen Einstiegspunktnamen; siehe die SQLite-DokumentationLaden einer Erweiterungfür Details.

Wirft einAuditierungsereignis sqlite3.load_extensionmit Argumentenconnection, path.

Hinzugefügt in Version 3.2.

Geändert in Version 3.10: Hinzugefügt wurde diesqlite3.load_extensionAuditierungsereignis.

Geändert in Version 3.12: Hinzugefügt wurde dieEinstiegspunktParameter.

iterdump()

RückgabeIteratorum die Datenbank als SQL-Quellcode zu sichern. Nützlich, wenn eine Datenbank im Arbeitsspeicher für eine spätere Wiederherstellung gespeichert wird. Ähnlich wie bei.dumpBefehl imsqlite3Hülse.

Beispiel:

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

Siehe auch

Umgang mit Textkodierungen, die nicht UTF-8 sind

Sicherung(Ziel, *, Seiten=-1, Fortschritt=Keiner, Name = "Haupt", Schlaf = 0,250)

Erstellen Sie ein Backup einer SQLite-Datenbank.

Funktioniert auch, wenn von anderen Clients oder gleichzeitig über die gleiche Verbindung auf die Datenbank zugegriffen wird.

Parameter:

Ziel (Verbindung) – Die Datenbankverbindung, in der das Backup gespeichert werden soll.
Seiten (int) – Die Anzahl der Seiten, die gleichzeitig kopiert werden sollen. Wenn gleich oder kleiner als0wird die gesamte Datenbank in einem einzigen Schritt kopiert. Der Standardwert ist-1.
Fortschritt (Ruf zurück| Keine) – Wenn auf a gesetztabrufbarwird es mit drei ganzzahligen Argumenten für jede Backup-Iteration aufgerufen: demStatusder letzten Iteration, dieübrigAnzahl der noch zu kopierenden Seiten und diegesamtAnzahl der Seiten. StandardmäßigNone.
Name (str) – Der Name der zu sichernden Datenbank. Entweder"main"(Standard) für die Hauptdatenbank,"temp"für die temporäre Datenbank oder den Namen einer benutzerdefinierten Datenbank, die mit demATTACH DATABASESQL-Anweisung.
schlafen (schweben) – Die Anzahl der Sekunden, die zwischen aufeinanderfolgenden Versuchen, die verbleibenden Seiten zu sichern, geruht werden soll.

Beispiel 1, eine bestehende Datenbank in eine andere kopieren:

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

Beispiel 2, Kopieren einer vorhandenen Datenbank in eine vorübergehende Kopie:

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

Hinzugefügt in Version 3.7.

Siehe auch

Umgang mit Textkodierungen, die nicht UTF-8 sind

getlimit(Kategorie, /)

Erhalten Sie ein Laufzeitlimit für die Verbindung.

Parameter:

Kategorie (int) - DerSQLite-Limitkategorieabgefragt werden.

Rückgabetyp:

int

Erhöht:

Programmierfehler- WennKategoriewird von der zugrunde liegenden SQLite-Bibliothek nicht erkannt.

Beispiel: Abfrage der maximalen Länge einer SQL-Anweisung fürVerbindung con(der Standardwert ist 1000000000):

>>>

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

Hinzugefügt in Version 3.11.

setzeGrenze(Kategorie, Grenze, /)

Legen Sie ein Laufzeitlimit für die Verbindung fest. Versuche, ein Limit über seine harte Obergrenze hinaus zu erhöhen, werden stillschweigend auf die harte Obergrenze gekürzt. Unabhängig davon, ob das Limit geändert wurde oder nicht, wird der vorherige Wert des Limits zurückgegeben.

Parameter:

Kategorie (int) - DerSQLite-Limitkategorieeingestellt werden.
Grenze (int) – Der Wert des neuen Limits. Wenn negativ, bleibt das aktuelle Limit unverändert.

Rückgabetyp:

int

Erhöht:

Programmierfehler- WennKategoriewird von der zugrunde liegenden SQLite-Bibliothek nicht erkannt.

Beispiel: Begrenzen Sie die Anzahl der angehängten Datenbanken auf 1 fürVerbindung con(die Standardgrenze liegt bei 10):

>>>

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

Hinzugefügt in Version 3.11.

getconfig(op, /)

Fragen Sie eine boolesche Verbindungskonfigurationsoption ab.

Parameter:

op (int) - ASQLITE_DBCONFIG-Code.

Rückgabetyp:

bool

Hinzugefügt in Version 3.12.

setconfig(op, aktivieren=Wahr, /)

Legen Sie eine boolesche Verbindungskonfigurationsoption fest.

Parameter:

op (int) - ASQLITE_DBCONFIG-Code.
aktivieren (bool) – Trueob die Konfigurationsoption aktiviert werden soll (Standard);Falseob es deaktiviert werden soll.

Hinzugefügt in Version 3.12.

serialisieren(*, Name = "Haupt")

Serialisieren einer Datenbank in eineBytesObjekt. Bei einer normalen Datenbankdatei auf der Festplatte ist die Serialisierung lediglich eine Kopie der Festplattendatei. Bei einer In-Memory-Datenbank oder einer „temp“-Datenbank ist die Serialisierung dieselbe Bytefolge, die auf die Festplatte geschrieben würde, wenn diese Datenbank auf der Festplatte gesichert würde.

Parameter:

Name (str) – Der zu serialisierende Datenbankname. Standardmäßig"main".

Rückgabetyp:

Bytes

Notiz

Diese Methode ist nur verfügbar, wenn die zugrunde liegende SQLite-Bibliothek über die Serialisierungs-API verfügt.

Hinzugefügt in Version 3.11.

deserialisieren(Daten, /, *, Name = "Haupt")

Deserialisieren Sie eineserialisiertDatenbank in eineVerbindung. Diese Methode bewirkt, dass die Datenbankverbindung zur Datenbank getrennt wirdNameund öffnen Sie es erneutNameals In-Memory-Datenbank basierend auf der Serialisierung inDaten.

Parameter:

Daten (Bytes) – Eine serialisierte Datenbank.
Name (str) – Der Name der Datenbank, in die deserialisiert werden soll. Der Standardwert ist"main".

Erhöht:

Betriebsfehler– Wenn die Datenbankverbindung aktuell an einer Lesetransaktion oder einem Sicherungsvorgang beteiligt ist.
Datenbankfehler- WennDatenenthält keine gültige SQLite-Datenbank.
Überlauffehler- WennLänge (Daten)ist größer als2**63 - 1.

Notiz

Diese Methode ist nur verfügbar, wenn die zugrunde liegende SQLite-Bibliothek über die Deserialisierungs-API verfügt.

Hinzugefügt in Version 3.11.

automatisches Festschreiben

Dieses Attribut steuertPEP 249-konformes Transaktionsverhalten.autocommithat drei zulässige Werte:

False: WählenPEP 249-konformes Transaktionsverhalten, was bedeutet, dasssqlite3stellt sicher, dass eine Transaktion immer offen ist. Verwenden Siebegehen()UndRollback()um Transaktionen abzuschließen.

Dies ist der empfohlene Wert vonautocommit.
True: Verwenden Sie SQLite'sAutocommit-Modus. begehen()UndRollback()haben in diesem Modus keine Wirkung.
Legacy-Transaktionssteuerung: Vor Python 3.12 (nicht-PEP 249-konforme) Transaktionskontrolle. SieheIsolationsstufefür mehr Details.

Dies ist derzeit der Standardwert vonautocommit.

ÄndernautocommitZuFalseöffnet eine neue Transaktion und ändert sie inTruewird alle ausstehenden Transaktionen ausführen.

SehenTransaktionssteuerung über das Autocommit-Attributfür mehr Details.

Notiz

DerIsolationsstufeAttribut hat keine Wirkung, es sei denn,automatisches FestschreibenIstLegacy-Transaktionssteuerung.

Hinzugefügt in Version 3.12.

in_Transaktion

Dieses schreibgeschützte Attribut entspricht dem Low-Level-SQLiteAutocommit-Modus.

Trueob eine Transaktion aktiv ist (es liegen noch nicht festgeschriebene Änderungen vor),Falseansonsten.

Hinzugefügt in Version 3.2.

Isolationsstufe

Steuert dieLegacy-Transaktionsbehandlungsmodusvonsqlite3Wenn eingestellt aufNone, Transaktionen werden nie implizit geöffnet. Wenn diese Einstellung auf einen der folgenden Werte gesetzt ist:"DEFERRED", "IMMEDIATE", oder"EXCLUSIVE", entsprechend der zugrunde liegendenSQLite-Transaktionsverhalten, implizites Transaktionsmanagementist durchgeführt.

Wenn nicht überschrieben durchIsolationsstufeParameter vonverbinden(), der Standardwert ist"", ein Alias für"DEFERRED".

Notiz

Verwenden vonautomatisches Festschreibenzur Steuerung der Transaktionsabwicklung wird gegenüber der Verwendung vonisolation_level. isolation_levelhat keine Wirkung, es sei denn,automatisches Festschreibenist eingestellt aufLegacy-Transaktionssteuerung(der Standard).

Zeilenfabrik

Die anfänglicheZeilenfabrikfürMauszeigerObjekte, die aus dieser Verbindung erstellt werden. Die Zuweisung zu diesem Attribut hat keine Auswirkung aufrow_factoryvon den bestehenden Cursorn, die zu dieser Verbindung gehören, nur neue. IstNonestandardmäßig, d.h. jede Zeile wird zurückgegeben alsTupel.

SehenSo erstellen und verwenden Sie Zeilenfabrikenfür mehr Details.

text_factory

Aabrufbardas akzeptiert eineBytesParameter und gibt eine Textdarstellung davon zurück. Das aufrufbare Objekt wird für SQLite-Werte mit demTEXTDatentyp. Standardmäßig ist dieses Attribut aufstr.

SehenUmgang mit Textkodierungen, die nicht UTF-8 sindfür mehr Details.

Gesamtänderungen

Gibt die Gesamtzahl der Datenbankzeilen zurück, die seit dem Öffnen der Datenbankverbindung geändert, eingefügt oder gelöscht wurden.

Cursorobjekte

ACursorObjekt stellt einDatenbankcursorDies wird verwendet, um SQL-Anweisungen auszuführen und den Kontext einer Fetch-Operation zu verwalten. Cursor werden erstellt mitVerbindung.cursor()oder mithilfe einer derMethoden zur Verbindungsverknüpfung.

Cursorobjekte sindIteratoren, das heißt, wenn Sieausführen()ASELECTAbfrage können Sie einfach über den Cursor iterieren, um die resultierenden Zeilen abzurufen:
for row in cur.execute("SELECT t FROM data"):
    print(row)

Klassesqlite3.Cursor

AMauszeigerInstanz hat die folgenden Attribute und Methoden.

ausführen(SQL-Befehle, Parameter=(), /)

Führen Sie eine einzelne SQL-Anweisung aus und binden Sie optional Python-Werte mitPlatzhalter.

Parameter:

SQL-Befehle (str) – Eine einzelne SQL-Anweisung.
Parameter (diktieren | Reihenfolge) – Python-Werte zum Binden an Platzhalter inSQL-Befehle. Adictwenn benannte Platzhalter verwendet werden. Eine Sequenz, wenn unbenannte Platzhalter verwendet werden. SieheSo verwenden Sie Platzhalter zum Binden von Werten in SQL-Abfragen.

Erhöht:

Programmierfehler- WennSQL-Befehleenthält mehr als eine SQL-Anweisung.

Wennautomatisches FestschreibenIstLegacy-Transaktionssteuerung, Isolationsstufeist nichtNone, SQL-Befehleist einINSERT, UPDATE, DELETE, oderREPLACE-Anweisung und es ist keine offene Transaktion vorhanden, wird vor der Ausführung implizit eine Transaktion geöffnet.SQL-Befehle.

Veraltet seit Version 3.12, wird in Version 3.14 entfernt:Warnung vor veralteter Versionwird ausgegeben, wennBenannte Platzhalterwerden verwendet undParameterist eine Sequenz statt einerdiktierenAb Python 3.14Programmierfehlerwird stattdessen ausgelöst.

VerwendenExecuteScript()um mehrere SQL-Anweisungen auszuführen.

viele ausführen(SQL-Befehle, Parameter, /)

Für jeden Artikel inParameter, führen Sie dieparametrisiertDML-SQL-AnweisungSQL-Befehle.

Verwendet die gleiche implizite Transaktionsbehandlung wieausführen().

Parameter:

SQL-Befehle (str) – Eine einzelne SQL-DML-Anweisung.
Parameter (wiederholbar) – Ein Iterable von Parametern, die mit den Platzhaltern in verknüpft werden sollenSQL-Befehle. SehenSo verwenden Sie Platzhalter zum Binden von Werten in SQL-Abfragen.

Erhöht:

Programmierfehler- WennSQL-Befehleenthält mehr als eine SQL-Anweisung oder ist keine DML-Anweisung.

Beispiel:

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

Notiz

Alle resultierenden Zeilen werden verworfen, einschließlich DML-Anweisungen mitRETURNING-Klauseln.

Veraltet seit Version 3.12, wird in Version 3.14 entfernt:Warnung vor veralteter Versionwird ausgegeben, wennBenannte Platzhalterverwendet werden und die Elemente inParametersind Sequenzen stattdiktierens. Ab Python 3.14Programmierfehlerwird stattdessen ausgelöst.

ausführenscript(sql_skript, /)

Führen Sie die SQL-Anweisungen aus insql_skriptWenn dieautomatisches FestschreibenIstLegacy-Transaktionssteuerungund es liegt eine schwebende Transaktion vor, eine impliziteCOMMIT-Anweisung wird zuerst ausgeführt. Es wird keine andere implizite Transaktionskontrolle durchgeführt; jede Transaktionskontrolle muss hinzugefügt werden zusql_skript.

sql_skriptmuss ein seinSchnur.

Beispiel:

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

WennZeilenfabrikIstNone, gibt den nächsten Zeilenabfrageergebnissatz alsTupel. Andernfalls übergeben Sie es an die Zeilenfabrik und geben Sie deren Ergebnis zurück. ReturnNonewenn keine Daten mehr verfügbar sind.

viele holen(Größe=Cursor.Arraygröße)

Gibt den nächsten Satz von Zeilen eines Abfrageergebnisses zurück alsListe. Gibt eine leere Liste zurück, wenn keine Zeilen mehr verfügbar sind.

Die Anzahl der pro Aufruf abzurufenden Zeilen wird festgelegt durchGrößeParameter. WennGrößeist nicht gegeben,Arraygrößebestimmt die Anzahl der abzurufenden Zeilen. Wenn weniger alsGrößeZeilen sind verfügbar, es werden so viele Zeilen zurückgegeben wie verfügbar sind.

Beachten Sie, dass es Leistungsaspekte gibt, die mit derGrößeParameter. Für optimale Leistung ist es normalerweise am besten, das Arraysize-Attribut zu verwenden. Wenn derGrößeParameter verwendet wird, ist es am besten, wenn er den gleichen Wert von einemfetchmany()Ruf zum nächsten.

fetchall()

Gibt alle (restlichen) Zeilen eines Abfrageergebnisses zurück alsListe. Gibt eine leere Liste zurück, wenn keine Zeilen verfügbar sind. Beachten Sie, dass dieArraygrößeAttribut kann die Leistung dieses Vorgangs beeinträchtigen.

schließen()

Schließen Sie den Cursor jetzt (und nicht jedes Mal, wenn__del__wird genannt).

Der Cursor ist ab diesem Zeitpunkt nicht mehr verwendbar.ProgrammierfehlerWenn mit dem Cursor eine beliebige Operation versucht wird, wird eine Ausnahme ausgelöst.

Eingabegrößen festlegen(Größen, /)

Wird von der DB-API benötigt. Tut nichts insqlite3.

Ausgabegröße festlegen(Größe, Spalte=Keine, /)

Wird von der DB-API benötigt. Tut nichts insqlite3.

Arraygröße

Lese-/Schreibattribut, das die Anzahl der zurückgegebenen Zeilen steuert vonfetchmany(). Der Standardwert ist 1, was bedeutet, dass pro Aufruf eine einzelne Zeile abgerufen wird.

Verbindung

Schreibgeschütztes Attribut, das die SQLite-Datenbank bereitstelltVerbindungzum Cursor gehörend. EinMauszeigerObjekt, das durch den Aufruf erstellt wurdecon.cursor()wird eineVerbindungAttribut, das sich bezieht aufMit:

>>>

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

Beschreibung

Schreibgeschütztes Attribut, das die Spaltennamen der letzten Abfrage bereitstellt. Um mit der Python DB API kompatibel zu bleiben, gibt es für jede Spalte ein 7-Tupel zurück, wobei die letzten sechs Elemente jedes TupelsNone.

Es ist eingestellt fürSELECTAnweisungen ohne übereinstimmende Zeilen ebenfalls.

letztes

Schreibgeschütztes Attribut, das die Zeilen-ID der zuletzt eingefügten Zeile angibt. Es wird nur nach erfolgreichemINSERToderREPLACEAnweisungen mit demausführen()Methode. Für andere Anweisungen nachviele ausführen()oderExecuteScript()oder, falls das Einfügen fehlgeschlagen ist, der Wert vonlastrowidbleibt unverändert. Der Anfangswert vonlastrowidIstNone.

Notiz

Einfügungen inWITHOUT ROWIDTabellen werden nicht aufgezeichnet.

Geändert in Version 3.6: Unterstützung für dieREPLACEStellungnahme.

Reihenanzahl

Schreibgeschütztes Attribut, das die Anzahl der geänderten Zeilen angibt fürINSERT, UPDATE, DELETE, UndREPLACEAussagen; ist-1für andere Anweisungen, einschließlich CTE-Abfragen. Es wird nur von derausführen()Undviele ausführen()-Methoden, nachdem die Anweisung vollständig ausgeführt wurde. Dies bedeutet, dass alle resultierenden Zeilen abgerufen werden müssen, damitrowcountaktualisiert werden.

Zeilenfabrik

Kontrollieren Sie, wie eine Zeile aus diesem abgerufen wirdCursordargestellt wird. WennNonewird eine Zeile dargestellt alsTupel. Kann auf die enthaltenesqlite3.Zeile; oder einabrufbardas zwei Argumente akzeptiert, einMauszeigerObjekt und dietuplevon Zeilenwerten und gibt ein benutzerdefiniertes Objekt zurück, das eine SQLite-Zeile darstellt.

Standardmäßig wasVerbindung.row_factorywurde eingestellt, wenn dieCursorwurde erstellt. Die Zuweisung zu diesem Attribut hat keine AuswirkungVerbindung.row_factoryder übergeordneten Verbindung.

SehenSo erstellen und verwenden Sie Zeilenfabrikenfür mehr Details.

Zeilenobjekte

Klassesqlite3.Zeile

ARowInstanz dient als hochoptimierteZeilenfabrikfürVerbindungObjekte. Es unterstützt Iteration, Gleichheitstests,länge(), UndKartierungZugriff über Spaltenname und Index.

ZweiRowObjekte werden verglichen, wenn sie identische Spaltennamen und -werte haben.

SehenSo erstellen und verwenden Sie Zeilenfabrikenfür mehr Details.

Schlüssel()

Rückgabe einesListevon Spaltennamen alsSaitenUnmittelbar nach einer Abfrage ist es das erste Mitglied jedes Tupels inCursor.Beschreibung.

Geändert in Version 3.5: Unterstützung für Slicing hinzugefügt.

Blob-Objekte

Klassesqlite3.Blob

Hinzugefügt in Version 3.11.

AKlecksInstanz ist einedateiähnliches Objektdas Daten in einem SQLite BLOB lesen und schreiben kann. Rufen SieLänge (Blob)um die Größe (Anzahl der Bytes) des Blobs zu erhalten. Verwenden Sie Indizes undScheibenfür den direkten Zugriff auf die Blob-Daten.

Verwenden Sie dieKlecksAls einKontext-Managerum sicherzustellen, dass der Blob-Handle nach der Verwendung geschlossen wird.

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

schließen()

Schließen Sie den Blob.

Ab diesem Zeitpunkt ist der Blob nicht mehr verwendbar.Fehler(oder Unterklassen-)Ausnahme wird ausgelöst, wenn ein weiterer Vorgang mit dem Blob versucht wird.

lesen(Länge=-1, /)

LesenLängeBytes an Daten aus dem Blob an der aktuellen Offset-Position. Wenn das Ende des Blobs erreicht ist, werden die Daten bis zum EOF zurückgegeben. WennLängenicht angegeben oder negativ ist,lesen()wird bis zum Ende des Blobs gelesen.

schreiben(Daten, /)

SchreibenDatenzum Blob am aktuellen Offset. Diese Funktion kann die Bloblänge nicht ändern. Wenn über das Ende des Blobs hinaus geschrieben wird,Wertfehler.

erzählen()

Gibt die aktuelle Zugriffsposition des Blobs zurück.

suchen(Versatz, Herkunft=os.SEEK_SET, /)

Setzen Sie die aktuelle Zugriffsposition des Blobs aufVersatz. DerHerkunftArgument ist standardmäßigos.SEEK_SET(absolute Blob-Positionierung). Andere Werte fürHerkunftSindos.SEEK_CUR(Suche relativ zur aktuellen Position) undos.SEEK_END(relativ zum Blob-Ende suchen).

PrepareProtocol-Objekte

Klassesqlite3.PrepareProtocol

Der einzige Zweck des Typs PrepareProtocol besteht darin, alsPEP 246Stilanpassungsprotokoll für Objekte, diepassen sich anZunative SQLite-Typen.

Ausnahmen

Die Ausnahmehierarchie wird durch die DB-API 2.0 definiert (PEP 249).

Ausnahmesqlite3.Warnung

Diese Ausnahme wird derzeit nicht ausgelöst durchsqlite3Modul, kann aber von Anwendungen ausgelöst werden, diesqlite3, beispielsweise wenn eine benutzerdefinierte Funktion beim Einfügen Daten abschneidet.Warningist eine Unterklasse vonAusnahme.

Ausnahmesqlite3.Fehler

Die Basisklasse der anderen Ausnahmen in diesem Modul. Verwenden Sie diese, um alle Fehler mit einer einzigenaußerStellungnahme.Errorist eine Unterklasse vonAusnahme.

Wenn die Ausnahme aus der SQLite-Bibliothek stammt, werden der Ausnahme die folgenden beiden Attribute hinzugefügt:

sqlite_fehlercode

Der numerische Fehlercode aus demSQLite-API

Hinzugefügt in Version 3.11.

sqlite_fehlername

Der symbolische Name des numerischen Fehlercodes aus derSQLite-API

Hinzugefügt in Version 3.11.

Ausnahmesqlite3.InterfaceError

Ausnahme wegen Missbrauchs der Low-Level-SQLite-C-API. Mit anderen Worten, wenn diese Ausnahme auftritt, deutet dies wahrscheinlich auf einen Fehler in dersqlite3Modul.InterfaceErrorist eine Unterklasse vonFehler.

Ausnahmesqlite3.Datenbankfehler

Ausnahme, die für Fehler ausgelöst wird, die mit der Datenbank in Zusammenhang stehen. Dies dient als Basisausnahme für mehrere Arten von Datenbankfehlern. Sie wird nur implizit durch die spezialisierten Unterklassen ausgelöst.DatabaseErrorist eine Unterklasse vonFehler.

Ausnahmesqlite3.DataError

Eine Ausnahme wird für Fehler ausgelöst, die durch Probleme mit den verarbeiteten Daten verursacht werden, wie etwa numerische Werte außerhalb des gültigen Bereichs und zu lange Zeichenfolgen.DataErrorist eine Unterklasse vonDatenbankfehler.

Ausnahmesqlite3.OperationalError

Ausnahmen werden für Fehler ausgelöst, die mit dem Betrieb der Datenbank zusammenhängen und nicht unbedingt unter der Kontrolle des Programmierers stehen. Beispielsweise kann der Datenbankpfad nicht gefunden werden oder eine Transaktion konnte nicht verarbeitet werden.OperationalErrorist eine Unterklasse vonDatenbankfehler.

Ausnahmesqlite3.IntegrityError

Ausnahme, die ausgelöst wird, wenn die relationale Integrität der Datenbank beeinträchtigt ist, z. B. wenn eine Fremdschlüsselprüfung fehlschlägt. Es handelt sich um eine Unterklasse vonDatenbankfehler.

Ausnahmesqlite3.Interner Fehler

Ausnahme, die ausgelöst wird, wenn SQLite auf einen internen Fehler stößt. Wenn diese Ausnahme ausgelöst wird, kann dies darauf hinweisen, dass ein Problem mit der SQLite-Laufzeitbibliothek vorliegt.InternalErrorist eine Unterklasse vonDatenbankfehler.

Ausnahmesqlite3.ProgrammingError

Ausnahme ausgelöst fürsqlite3API-Programmierfehler, z. B. die Angabe einer falschen Anzahl von Bindungen zu einer Abfrage oder der Versuch, eine geschlosseneVerbindung. ProgrammingErrorist eine Unterklasse vonDatenbankfehler.

Ausnahmesqlite3.NichtunterstützterFehler

Ausnahme wird ausgelöst, wenn eine Methode oder Datenbank-API von der zugrunde liegenden SQLite-Bibliothek nicht unterstützt wird. Zum Beispiel:deterministischZuTrueInFunktion erstellen(), wenn die zugrunde liegende SQLite-Bibliothek keine deterministischen Funktionen unterstützt.NotSupportedErrorist eine Unterklasse vonDatenbankfehler.

SQLite- und Python-Typen

SQLite unterstützt nativ die folgenden Typen:NULL, INTEGER, REAL, TEXT, BLOB.

Folgende Python-Typen können somit problemlos an SQLite übergeben werden:

Python-Typ	SQLite-Typ
`None`	`NULL`
int	`INTEGER`
schweben	`REAL`
str	`TEXT`
Bytes	`BLOB`

So werden SQLite-Typen standardmäßig in Python-Typen konvertiert:

SQLite-Typ	Python-Typ
`NULL`	`None`
`INTEGER`	int
`REAL`	schweben
`TEXT`	kommt drauf antext_factory, strstandardmäßig
`BLOB`	Bytes

Das Typsystem dersqlite3Das Modul ist auf zwei Arten erweiterbar: Sie können zusätzliche Python-Typen in einer SQLite-Datenbank speichern überObjektadapter, und Sie können diesqlite3Modul konvertiert SQLite-Typen in Python-Typen überKonverter.

Standardadapter und -konverter (veraltet)

Notiz

Die Standardadapter und -konverter sind ab Python 3.12 veraltet. Verwenden Sie stattdessen dieAdapter- und Konverterrezepteund passen Sie sie an Ihre Bedürfnisse an.

Die veralteten Standardadapter und -konverter bestehen aus:

Ein Adapter fürDatumUhrzeit.DatumObjekte zuSaitenInISO 8601Format.
Ein Adapter fürDatumUhrzeit.DatumUhrzeitObjekte in Zeichenfolgen im ISO 8601-Format.
Ein Konverter fürerklärt„Datums“-Typen zuDatumUhrzeit.DatumObjekte.
Ein Konverter für deklarierte „Zeitstempel“-Typen inDatumUhrzeit.DatumUhrzeitObjekte. Dezimalstellen werden auf 6 Ziffern gekürzt (Mikrosekundengenauigkeit).

Notiz

Der standardmäßige „Zeitstempel“-Konverter ignoriert UTC-Offsets in der Datenbank und gibt immer einen naivenDatumUhrzeit.DatumUhrzeitObjekt. Um UTC-Offsets in Zeitstempeln beizubehalten, lassen Sie entweder die Konverter deaktiviert oder registrieren Sie einen Offset-fähigen Konverter mitregister_converter().

Seit Version 3.12 veraltet.

Befehlszeilenschnittstelle

Dersqlite3Das Modul kann als Skript aufgerufen werden, mit Hilfe des-MSchalter, um eine einfache SQLite-Shell bereitzustellen. Die Argumentsignatur lautet wie folgt:

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

Typ.quitoder STRG-D, um die Shell zu verlassen.

-h, --help

CLI-Hilfe drucken.

-v, --version

Drucken Sie die Version der zugrunde liegenden SQLite-Bibliothek.

Hinzugefügt in Version 3.12.

Anleitungen

So verwenden Sie Platzhalter zum Binden von Werten in SQL-Abfragen

SQL-Operationen müssen normalerweise Werte aus Python-Variablen verwenden. Seien Sie jedoch vorsichtig bei der Verwendung von Python-String-Operationen zum Zusammenstellen von Abfragen, da diese anfällig sind fürSQL-Injection-Angriffe. Ein Angreifer kann beispielsweise einfach das einfache Anführungszeichen schließen undOR TRUEum alle Zeilen auszuwählen:

>>>

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

Verwenden Sie stattdessen die Parameterersetzung der DB-API. Um eine Variable in eine Abfragezeichenfolge einzufügen, verwenden Sie einen Platzhalter in der Zeichenfolge und ersetzen Sie die tatsächlichen Werte in der Abfrage, indem Sie sie alsTupelvon Werten an das zweite Argument des Cursorsausführen()Methode.

Eine SQL-Anweisung kann eine von zwei Arten von Platzhaltern verwenden: Fragezeichen (qmark-Stil) oder benannte Platzhalter (benannter Stil). Für den qmark-Stil gilt:Parametermuss ein seinReihenfolgederen Länge der Anzahl der Platzhalter entsprechen muss, oder einProgrammierfehlerwird ausgelöst. Für den genannten StilParametermuss eine Instanz vondiktieren(oder eine Unterklasse), die Schlüssel für alle benannten Parameter enthalten muss; alle zusätzlichen Elemente werden ignoriert. Hier ist ein Beispiel für beide Stile:

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

Notiz

PEP 249numerische Platzhalter sindnichtunterstützt. Wenn sie verwendet werden, werden sie als benannte Platzhalter interpretiert.

So passen Sie benutzerdefinierte Python-Typen an SQLite-Werte an

SQLite unterstützt nativ nur eine begrenzte Anzahl von Datentypen. Um benutzerdefinierte Python-Typen in SQLite-Datenbanken zu speichern,anpassensie zu einem derPython-Typen, die SQLite nativ versteht.

Es gibt zwei Möglichkeiten, Python-Objekte an SQLite-Typen anzupassen: Entweder Sie lassen Ihr Objekt sich selbst anpassen oder Sie verwenden einAdapter aufrufbar. Letzteres hat Vorrang vor Ersterem. Für eine Bibliothek, die einen benutzerdefinierten Typ exportiert, kann es sinnvoll sein, diesem Typ die Möglichkeit zu geben, sich selbst anzupassen. Als Anwendungsentwickler kann es sinnvoller sein, die direkte Kontrolle zu übernehmen, indem Sie benutzerdefinierte Adapterfunktionen registrieren.

So schreiben Sie anpassbare Objekte

Angenommen, wir haben einePointKlasse, die ein Koordinatenpaar darstellt,xUndy, in einem kartesischen Koordinatensystem. Das Koordinatenpaar wird als Textzeichenfolge in der Datenbank gespeichert, wobei die Koordinaten durch ein Semikolon getrennt werden. Dies kann durch Hinzufügen eines__conform__(self, protocol)Methode, die den angepassten Wert zurückgibt. Das anProtokollwird vom Typ seinProtokoll vorbereiten.

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

So registrieren Sie aufrufbare Adapter

Die andere Möglichkeit besteht darin, eine Funktion zu erstellen, die das Python-Objekt in einen SQLite-kompatiblen Typ konvertiert. Diese Funktion kann dann mit registriert werdenregister_adapter().

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

So konvertieren Sie SQLite-Werte in benutzerdefinierte Python-Typen

Durch das Schreiben eines Adapters können Sieausbenutzerdefinierte Python-TypenZuSQLite-Werte. Um konvertieren zu könnenausSQLite-WerteZubenutzerdefinierte Python-Typen, wir verwendenKonverter.

Kommen wir zurück zumPointKlasse. Wir haben die x- und y-Koordinaten durch Semikolon getrennt als Strings in SQLite gespeichert.

Zuerst definieren wir eine Konverterfunktion, die den String als Parameter akzeptiert und einePointObjekt daraus.

Notiz

Konverterfunktionen sindstetsbestandenBytesObjekt, unabhängig vom zugrunde liegenden SQLite-Datentyp.

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

Wir müssen jetzt sagensqlite3wann ein bestimmter SQLite-Wert konvertiert werden soll. Dies geschieht beim Herstellen einer Verbindung zu einer Datenbank mithilfe desTypen erkennenParameter vonverbinden()Es gibt drei Möglichkeiten:

Implizit: gesetztTypen erkennenZuPARSE_DECLTYPES
Explizit: gesetztTypen erkennenZuPARSE_COLNAMES
Beide: gesetztTypen erkennenZusqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES. Spaltennamen haben Vorrang vor deklarierten Typen.

Das folgende Beispiel veranschaulicht die impliziten und expliziten Ansätze:

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

Adapter- und Konverterrezepte

In diesem Abschnitt werden Rezepte für gängige Adapter und Konverter gezeigt.

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)

So verwenden Sie Verbindungsverknüpfungsmethoden

Verwendung derausführen(), viele ausführen(), UndExecuteScript()Methoden derVerbindungKlasse kann Ihr Code präziser geschrieben werden, da Sie die (oft überflüssigen)MauszeigerObjekte explizit. StattdessenMauszeigerObjekte werden implizit erstellt und diese Shortcut-Methoden geben die Cursor-Objekte zurück. Auf diese Weise können Sie eineSELECTAnweisung und iterieren Sie direkt darüber mit nur einem einzigen Aufruf derVerbindungObjekt.

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

So verwenden Sie den Verbindungskontext-Manager

AVerbindungObjekt kann als Kontextmanager verwendet werden, der offene Transaktionen automatisch festschreibt oder zurücksetzt, wenn er den Hauptteil des Kontextmanagers verlässt. Wenn der Hauptteil desmitAnweisung ohne Ausnahmen beendet wird, wird die Transaktion festgeschrieben. Wenn dieses Festschreiben fehlschlägt oder wenn der Hauptteil derwith-Anweisung eine nicht abgefangene Ausnahme auslöst, wird die Transaktion zurückgesetzt. Wennautomatisches FestschreibenIstFalse, nach dem Commit oder Rollback wird implizit eine neue Transaktion geöffnet.

Wenn beim Verlassen des Hauptteils deswithAnweisung, oder wennautomatisches FestschreibenIstTrue, der Kontextmanager tut nichts.

Notiz

Der Kontextmanager öffnet weder implizit eine neue Transaktion noch schließt er die Verbindung. Wenn Sie einen schließenden Kontextmanager benötigen, verwenden Siecontextlib.closing().

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

So arbeiten Sie mit SQLite-URIs

Einige nützliche URI-Tricks sind:

Öffnen Sie eine Datenbank im schreibgeschützten Modus:

>>>

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

Erstellen Sie nicht implizit eine neue Datenbankdatei, wenn diese noch nicht existiert. Dies führt zuBetriebsfehlerwenn keine neue Datei erstellt werden kann:

>>>

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

Erstellen Sie eine gemeinsam genutzte benannte In-Memory-Datenbank:

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

Weitere Informationen zu dieser Funktion, einschließlich einer Liste der Parameter, finden Sie imSQLite-URI-Dokumentation.

So erstellen und verwenden Sie Zeilenfabriken

Standardmäßig,sqlite3stellt jede Zeile dar alsTupel. Wenn eintuplenicht Ihren Bedürfnissen entspricht, können Sie diesqlite3.ZeileKlasse oder eine benutzerdefinierteZeilenfabrik.

Währendrow_factoryexistiert als Attribut sowohl auf derMauszeigerund dasVerbindungwird empfohlen,Verbindung.row_factory, sodass alle aus der Verbindung erstellten Cursor dieselbe Zeilenfabrik verwenden.

Rowbietet indexierten und case-insensitiven benannten Zugriff auf Spalten mit minimalem Speicheraufwand und Leistungseinbußen über einentuple. BenutzenRowals Zeilenfabrik, ordnen Sie sie derrow_factoryAttribut:

>>>

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

Abfragen kehren jetzt zurückRowObjekte:

>>>

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

Notiz

DerFROMKlausel kann weggelassen werden in derSELECTAnweisung, wie im obigen Beispiel. In solchen Fällen gibt SQLite eine einzelne Zeile mit Spalten zurück, die durch Ausdrücke, z. B. Literale, mit den angegebenen Aliasnamen definiert sind.expr AS alias.

Sie können eine benutzerdefinierteZeilenfabrikdas jede Zeile zurückgibt alsdiktieren, wobei die Spaltennamen den Werten zugeordnet sind:

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

Mithilfe dieser Funktion geben Abfragen nun einedictanstelle einertuple:

>>>

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

Die folgende Zeilenfabrik gibt einebenanntes Tupel:

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()kann wie folgt verwendet werden:

>>>

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

Mit einigen Anpassungen kann das obige Rezept angepasst werden, um eineDatenklasseoder eine beliebige andere benutzerdefinierte Klasse anstelle einerbenanntes Tupel.

Umgang mit Textkodierungen, die nicht UTF-8 sind

Standardmäßig,sqlite3Verwendetstrzur Anpassung von SQLite-Werten mit demTEXTDatentyp. Dies funktioniert gut für UTF-8-kodierten Text, kann aber bei anderen Kodierungen und ungültigem UTF-8 fehlschlagen. Sie können einen benutzerdefiniertentext_factoryum solche Fälle zu behandeln.

Aufgrund von SQLiteflexibles Tippenist es nicht ungewöhnlich, Tabellenspalten mit demTEXTDatentyp, der nicht-UTF-8-Kodierungen oder sogar beliebige Daten enthält. Zur Veranschaulichung nehmen wir an, wir haben eine Datenbank mit ISO-8859-2 (Latin-2) kodiertem Text, zum Beispiel eine Tabelle mit tschechisch-englischen Wörterbucheinträgen. Angenommen, wir haben jetzt eineVerbindungBeispielconMit dieser Datenbank verbunden, können wir den in Latin-2 kodierten Text mit diesem dekodierentext_factory:

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

Für ungültiges UTF-8 oder beliebige Daten inTEXTTabellenspalten können Sie die folgende Technik verwenden, die aus demUnicode-Anleitung:

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

Notiz

Dersqlite3Die Modul-API unterstützt keine Zeichenfolgen, die Ersatzzeichen enthalten.

Siehe auch

Unicode-Anleitung

Erläuterung

Transaktionskontrolle

sqlite3bietet mehrere Methoden zur Steuerung, ob, wann und wie Datenbanktransaktionen geöffnet und geschlossen werden.Transaktionssteuerung über das Autocommit-Attributwird empfohlen, währendTransaktionskontrolle über das isolation_level-Attributbehält das Verhalten vor Python 3.12 bei.

Transaktionskontrolle über die`autocommit`Attribut

Die empfohlene Methode zur Steuerung des Transaktionsverhaltens ist dieVerbindung.autocommitAttribut, das vorzugsweise mit demautomatisches FestschreibenParameter vonverbinden().

Es wird empfohlen,automatisches FestschreibenZuFalse, was impliziertPEP 249-konforme Transaktionskontrolle. Das bedeutet:

sqlite3stellt sicher, dass eine Transaktion immer offen ist,verbinden(), Verbindung.commit(), UndVerbindung.rollback()öffnet implizit eine neue Transaktion (bei den letzten beiden unmittelbar nach dem Schließen der ausstehenden Transaktion).sqlite3VerwendetBEGIN DEFERREDKontoauszüge beim Öffnen von Transaktionen.
Transaktionen sollten explizit festgeschrieben werden mitcommit().
Transaktionen sollten explizit zurückgesetzt werden mitrollback().
Ein implizites Rollback wird durchgeführt, wenn die Datenbankschließen()-ed mit ausstehenden Änderungen.

Satzautomatisches FestschreibenZuTruezum Aktivieren von SQLiteAutocommit-ModusIn diesem ModusVerbindung.commit()UndVerbindung.rollback()haben keine Wirkung. Beachten Sie, dass der Autocommit-Modus von SQLite sich von demPEP 249-konformVerbindung.autocommitAttribut; VerwendungVerbindung.in_Transaktionum den Low-Level-SQLite-Autocommit-Modus abzufragen.

Satzautomatisches FestschreibenZuLegacy-Transaktionssteuerungdas Transaktionskontrollverhalten denVerbindungsisolationsebeneAttribut. SieheTransaktionskontrolle über das isolation_level-Attributfür mehr Informationen.

Transaktionskontrolle über die`isolation_level`Attribut

Notiz

Die empfohlene Art der Transaktionssteuerung erfolgt über dieautomatisches FestschreibenAttribut. SieheTransaktionssteuerung über das Autocommit-Attribut.

WennVerbindung.autocommitist eingestellt aufLegacy-Transaktionssteuerung(Standard) wird das Transaktionsverhalten gesteuert durchVerbindungsisolationsebeneAttribut. Andernfallsisolation_levelhat keine Wirkung.

Wenn das VerbindungsattributIsolationsstufeist nichtNone, neue Transaktionen werden implizit eröffnet, bevorausführen()Undviele ausführen()führt ausINSERT, UPDATE, DELETE, oderREPLACE-Anweisungen; für andere Anweisungen wird keine implizite Transaktionsbehandlung durchgeführt. Verwenden Sie diebegehen()UndRollback()Methoden, um ausstehende Transaktionen festzuschreiben bzw. rückgängig zu machen. Sie können die zugrunde liegendeSQLite-Transaktionsverhalten— das heißt, ob und welche Art vonBEGINAussagensqlite3implizit ausführt – über dieIsolationsstufeAttribut.

WennIsolationsstufeist eingestellt aufNonewerden implizit überhaupt keine Transaktionen geöffnet. Dies lässt die zugrunde liegende SQLite-Bibliothek inAutocommit-Modus, sondern ermöglicht dem Benutzer auch die Durchführung eigener Transaktionen mithilfe expliziter SQL-Anweisungen. Der zugrunde liegende Autocommit-Modus der SQLite-Bibliothek kann mithilfe desin_TransaktionAttribut.

DerExecuteScript()Methode führt implizit eine Commits aller ausstehenden Transaktionen vor der Ausführung des angegebenen SQL-Skripts aus, unabhängig vom Wert vonIsolationsstufe.

Geändert in Version 3.6:sqlite3wurde verwendet, um eine offene Transaktion vor DDL-Anweisungen implizit festzuschreiben. Dies ist nicht mehr der Fall.

Geändert in Version 3.12: Die empfohlene Art der Transaktionssteuerung ist nun über dieautomatisches FestschreibenAttribut.

Technologieaustausch