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

Quellcode: 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 für die interne Datenspeicherung verwenden. Es ist auch möglich, eine Anwendung mit SQLite zu prototyptypisieren und den Code dann auf eine größere Datenbank wie PostgreSQL oder Oracle zu portieren.

Das Modul sqlite3 wurde von Gerhard Häring geschrieben. Es bietet eine SQL-Schnittstelle, die der DB-API 2.0 Spezifikation entspricht, die von PEP 249 beschrieben wird, und erfordert SQLite 3.15.2 oder neuer.

Dieses Dokument enthält vier Hauptabschnitte

• Tutorial lehrt, wie man das Modul sqlite3 verwendet.

• Referenz beschreibt die Klassen und Funktionen, die dieses Modul definiert.

• Anleitungen detailliert, wie spezifische Aufgaben gehandhabt werden.

• Erläuterung bietet tiefgehende Hintergrundinformationen zur Transaktionssteuerung.

Siehe auch

https://www.sqlite.org

Die SQLite-Webseite; die Dokumentation beschreibt die Syntax und die verfügbaren Datentypen für die unterstützte SQL-Dialekt.

https://www.w3schools.com/sql/

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

PEP 249 - Database API Specification 2.0

PEP geschrieben von Marc-André Lemburg.

Tutorial

In diesem Tutorial erstellen Sie eine Datenbank von Monty Python Filmen unter Verwendung grundlegender sqlite3 Funktionalitäten. Es wird ein grundlegendes Verständnis von Datenbankkonzepten vorausgesetzt, einschließlich Cursor und Transaktionen.

Zuerst müssen wir eine neue Datenbank erstellen und eine Datenbankverbindung öffnen, damit sqlite3 damit arbeiten kann. Rufen Sie sqlite3.connect() auf, um eine Verbindung zur Datenbank tutorial.db im aktuellen Arbeitsverzeichnis herzustellen, wobei diese implizit erstellt wird, falls sie nicht existiert.

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

Das zurückgegebene Connection Objekt con repräsentiert die Verbindung zur festplattenbasierten Datenbank.

Um SQL-Anweisungen auszuführen und Ergebnisse aus SQL-Abfragen abzurufen, benötigen wir einen Datenbank-Cursor. Rufen Sie con.cursor() auf, um den Cursor zu erstellen.

cur = con.cursor()

Jetzt, da wir eine Datenbankverbindung und einen Cursor haben, können wir eine Datenbanktabelle movie mit Spalten für Titel, Erscheinungsjahr und Bewertung erstellen. Der Einfachheit halber können wir einfach Spaltennamen in der Tabellendefinition verwenden – dank der flexiblen Typisierung von SQLite ist die Angabe der Datentypen optional. Führen Sie die Anweisung CREATE TABLE 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 die integrierte Tabelle sqlite_master von SQLite abfragen, die nun einen Eintrag für die Definition der movie Tabelle enthalten sollte (siehe The Schema Table für Details). Führen Sie diese Abfrage aus, indem Sie cur.execute(...) aufrufen, das Ergebnis res zuweisen und res.fetchone() aufrufen, um die resultierende Zeile abzurufen.

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

Wir sehen, dass die Tabelle erstellt wurde, da die Abfrage ein Tupel mit dem Namen der Tabelle zurückgibt. Wenn wir sqlite_master für eine nicht existierende Tabelle 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 als SQL-Literale hinzu, indem Sie eine INSERT-Anweisung ausführen, wiederum durch 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)
""")

Die INSERT-Anweisung öffnet implizit eine Transaktion, die committet werden muss, bevor Änderungen in der Datenbank gespeichert werden (siehe Transaktionssteuerung für Details). Rufen Sie con.commit() auf dem Connection-Objekt auf, um die Transaktion zu committen.

con.commit()

Wir können überprüfen, ob die Daten korrekt eingefügt wurden, indem wir eine SELECT-Abfrage ausführen. Verwenden Sie das nun bekannte cur.execute(...), um das Ergebnis res zuzuweisen, und rufen Sie res.fetchall() auf, um alle resultierenden Zeilen zurückzugeben.

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

Das Ergebnis ist eine Liste von zwei Tupeln, eines pro Zeile, das jeweils den score-Wert dieser Zeile enthält.

Fügen Sie nun drei weitere Zeilen 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.

Beachten Sie, dass ?-Platzhalter verwendet werden, um data an die Abfrage zu binden. Verwenden Sie immer Platzhalter anstelle von String-Formatierung, um Python-Werte an SQL-Anweisungen zu binden, um SQL-Injection-Angriffe zu vermeiden (weitere Details finden Sie unter Wie man Platzhalter verwendet, um Werte in SQL-Abfragen zu binden).

Wir können überprüfen, ob die neuen Zeilen eingefügt wurden, indem wir eine SELECT-Abfrage ausführen und diesmal über die Ergebnisse der Abfrage iterieren.

>>> 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 ist ein zweielementiges Tupel von (year, title), das den in der Abfrage ausgewählten Spalten entspricht.

Schließlich überprüfen wir, ob die Datenbank auf die Festplatte geschrieben wurde, indem wir con.close() aufrufen, um die bestehende Verbindung zu schließen, eine neue zu öffnen, einen neuen Cursor zu erstellen und dann die Datenbank abzufragen.

>>> 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 mit dem Modul sqlite3 erstellt, Daten eingefügt und Werte auf verschiedene Weise daraus abgerufen.

Siehe auch

• Anleitungen zum Weiterlesen

  • Verwendung von Platzhaltern zum Binden von Werten in SQL-Abfragen

  • Anpassen benutzerdefinierter Python-Typen an SQLite-Werte

  • Konvertieren von SQLite-Werten in benutzerdefinierte Python-Typen

  • Verwendung des Verbindungs-Context-Managers

  • Erstellen und Verwenden von Zeilenfabriken

• Erläuterung für tiefgehende Hintergrundinformationen zur Transaktionssteuerung.

Referenz

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)

Öffnet eine Verbindung zu einer SQLite-Datenbank.

Parameter:

• database (Pfadähnliches Objekt) – Der Pfad zur zu öffnenden Datenbankdatei. Sie können ":memory:" übergeben, um eine nur im Speicher existierende SQLite-Datenbank zu erstellen und eine Verbindung dazu zu öffnen.

• timeout (float) – Wie viele Sekunden die Verbindung warten soll, bevor ein OperationalError ausgelöst wird, wenn eine Tabelle gesperrt ist. Wenn eine andere Verbindung eine Transaktion öffnet, um eine Tabelle zu ändern, wird diese Tabelle bis zur Bestätigung der Transaktion gesperrt. Standardmäßig fünf Sekunden.

• detect_types (int) – Steuert, ob und wie Datentypen, die nicht nativ von SQLite unterstützt werden, zur Konvertierung in Python-Typen gesucht werden, indem die mit register_converter() registrierten Konverter verwendet werden. Setzen Sie ihn auf eine beliebige Kombination (mit |, bitweiser ODER) von PARSE_DECLTYPES und PARSE_COLNAMES, um dies zu aktivieren. Spaltennamen haben Vorrang vor deklarierten Typen, wenn beide Flags gesetzt sind. Standardmäßig (0) ist die Typenerkennung deaktiviert.

• isolation_level (str | None) – Steuert das Verhalten der Legacy-Transaktionsverwaltung. Weitere Informationen finden Sie unter Connection.isolation_level und Transaktionssteuerung über das isolation_level-Attribut. Kann "DEFERRED" (Standard), "EXCLUSIVE" oder "IMMEDIATE" sein; oder None, um das implizite Öffnen von Transaktionen zu deaktivieren. Hat keine Auswirkung, es sei denn, Connection.autocommit ist auf LEGACY_TRANSACTION_CONTROL (Standard) gesetzt.

• check_same_thread (bool) – Wenn True (Standard), wird ein ProgrammingError ausgelöst, wenn die Datenbankverbindung von einem anderen Thread als dem, der sie erstellt hat, verwendet wird. Wenn False, kann auf die Verbindung in mehreren Threads zugegriffen werden; Schreiboperationen müssen möglicherweise vom Benutzer serialisiert werden, um Datenkorruption zu vermeiden. Siehe threadsafety für weitere Informationen.

• factory (Connection) – Eine benutzerdefinierte Unterklasse von Connection, mit der die Verbindung hergestellt werden soll, wenn nicht die Standardklasse Connection verwendet wird.

• cached_statements (int) – Die Anzahl der Anweisungen, die sqlite3 intern für diese Verbindung cachen soll, um Parsing-Overhead zu vermeiden. Standardmäßig 128 Anweisungen.

• uri (bool) – Wenn auf True gesetzt, wird database als URI mit einem Dateipfad und einer optionalen Abfragezeichenfolge interpretiert. Der Schemateil muss "file:" sein, und der Pfad kann relativ oder absolut sein. Die Abfragezeichenfolge ermöglicht die Übergabe von Parametern an SQLite und ermöglicht verschiedene Wie man mit SQLite-URIs arbeitet.

• autocommit (bool) – Steuert das Transaktionsverhalten gemäß PEP 249. Weitere Informationen finden Sie unter Connection.autocommit und Transaktionssteuerung über das autocommit-Attribut. autocommit ist derzeit standardmäßig LEGACY_TRANSACTION_CONTROL. Der Standardwert wird in einer zukünftigen Python-Version auf False geändert.

Rückgabetyp:

Connection

Löst ein Auditing-Ereignis sqlite3.connect mit dem Argument database aus.

Löst ein Auditing-Ereignis sqlite3.connect/handle mit dem Argument connection_handle aus.

Geändert in Version 3.4: Der Parameter uri wurde hinzugefügt.

Geändert in Version 3.7: database kann nun auch ein pfadähnliches Objekt sein, nicht nur ein String.

Geändert in Version 3.10: Das Auditing-Ereignis sqlite3.connect/handle wurde hinzugefügt.

Geändert in Version 3.12: Der Parameter autocommit wurde hinzugefügt.

Geändert in Version 3.13: Die positionale Verwendung der Parameter timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements und uri ist veraltet. Sie werden in Python 3.15 zu schlüsselwortbasierten Parametern.

sqlite3.complete_statement(statement)

Gibt True zurück, wenn der String statement eine oder mehrere vollständige SQL-Anweisungen zu enthalten scheint. Es wird keine syntaktische Überprüfung oder Parsen jeglicher Art durchgeführt, außer der Überprüfung, ob es keine ungeschlossenen Zeichenfolgenliterale gibt und die Anweisung mit einem Semikolon beendet ist.

Zum Beispiel

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

Diese Funktion kann während der Eingabe über die Kommandozeile nützlich sein, um zu bestimmen, ob der eingegebene Text eine vollständige SQL-Anweisung zu bilden scheint oder ob weitere Eingaben erforderlich sind, bevor execute() aufgerufen wird.

Siehe runsource() in Lib/sqlite3/__main__.py für die reale Anwendung.

sqlite3.enable_callback_tracebacks(flag, /)

Callback-Tracebacks aktivieren oder deaktivieren. Standardmäßig erhalten Sie keine Tracebacks in benutzerdefinierten Funktionen, Aggregaten, Konvertern, Autorisierungs-Callbacks usw. Wenn Sie diese debuggen möchten, können Sie diese Funktion mit flag auf True setzen. Danach erhalten Sie Tracebacks von Callbacks auf sys.stderr. Verwenden Sie False, um die Funktion wieder zu deaktivieren.

Hinweis

Fehler in benutzerdefinierten Funktions-Callbacks werden als nicht aufrufbare Ausnahmen protokolliert. Verwenden Sie einen unraisable hook handler zur Introspektion des fehlgeschlagenen Callbacks.

sqlite3.register_adapter(type, adapter, /)

Registriert einen adapter aufrufbaren, um den Python-Typ type in einen SQLite-Typ zu konvertieren. Der Adapter wird mit einem Python-Objekt vom Typ type als einzigem Argument aufgerufen und muss einen Wert eines Typs zurückgeben, den SQLite nativ versteht.

sqlite3.register_converter(typename, converter, /)

Registriert den converter aufrufbaren, um SQLite-Objekte vom Typ typename in ein Python-Objekt eines bestimmten Typs zu konvertieren. Der Konverter wird für alle SQLite-Werte vom Typ typename aufgerufen; er erhält ein Bytes-Objekt und sollte ein Objekt des gewünschten Python-Typs zurückgeben. Informationen zur Funktionsweise der Typenerkennung finden Sie im Parameter detect_types von connect().

Hinweis: typename und der Name des Typs in Ihrer Abfrage werden nicht zwischen Groß- und Kleinschreibung unterschieden.

Modulkonstanten

sqlite3.LEGACY_TRANSACTION_CONTROL

Setzen Sie autocommit auf diese Konstante, um das alte Transaktionssteuerungsverhalten (vor Python 3.12) auszuwählen. Weitere Informationen finden Sie unter Transaktionssteuerung über das isolation_level-Attribut.

sqlite3.PARSE_DECLTYPES

Übergeben Sie diesen Flag-Wert an den Parameter detect_types von connect(), um eine Konverterfunktion anhand der deklarierten Typen für jede Spalte nachzuschlagen. Die Typen werden bei der Erstellung der Datenbanktabelle deklariert. sqlite3 sucht nach einer Konverterfunktion, indem es das erste Wort des deklarierten Typs als Schlüssel im Konverter-Dictionary verwendet. 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"
 )

Dieses Flag kann mit PARSE_COLNAMES unter Verwendung des Operators | (bitwise oder) kombiniert werden.

Hinweis

Generierte Felder (z.B. MAX(p)) werden als str zurückgegeben. Verwenden Sie PARSE_COLNAMES, um Typen für solche Abfragen zu erzwingen.

sqlite3.PARSE_COLNAMES

Übergeben Sie diesen Flag-Wert an den Parameter detect_types von connect(), um eine Konverterfunktion nachzuschlagen, indem Sie den Typnamen, der aus dem Spaltennamen der Abfrage geparst wird, als Schlüssel im Konverter-Dictionary verwenden. Der Spaltenname der Abfrage muss in doppelte Anführungszeichen (") eingeschlossen sein und der Typname muss in eckige Klammern ([]) eingeschlossen sein.

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

Dieses Flag kann mit PARSE_DECLTYPES unter Verwendung des Operators | (bitwise oder) kombiniert werden.

sqlite3.SQLITE_OK

sqlite3.SQLITE_DENY

sqlite3.SQLITE_IGNORE

Flags, die von der authorizer_callback aufrufbaren, die an Connection.set_authorizer() übergeben wird, zurückgegeben werden sollten, um anzuzeigen, ob

• Der Zugriff erlaubt ist (SQLITE_OK),

• Die SQL-Anweisung mit einem Fehler abgebrochen werden soll (SQLITE_DENY)

• Die Spalte als NULL-Wert behandelt werden soll (SQLITE_IGNORE)

sqlite3.apilevel

String-Konstante, die das unterstützte DB-API-Level angibt. Erforderlich durch die DB-API. Fest codiert auf "2.0".

sqlite3.paramstyle

String-Konstante, die die Art der Parameter-Marker-Formatierung angibt, die vom Modul sqlite3 erwartet wird. Erforderlich durch die DB-API. Fest codiert auf "qmark".

Hinweis

Der named DB-API-Parameterstil wird ebenfalls unterstützt.

sqlite3.sqlite_version

Versionsnummer der Laufzeit-SQLite-Bibliothek als String.

sqlite3.sqlite_version_info

Versionsnummer der Laufzeit-SQLite-Bibliothek als Tupel von Ganzzahlen.

sqlite3.threadsafety

Integer-Konstante, die von der DB-API 2.0 erforderlich ist und das Thread-Sicherheitslevel angibt, das das Modul sqlite3 unterstützt. Dieses Attribut wird basierend auf dem Standard-Thread-Modus der kompilierten zugrundeliegenden SQLite-Bibliothek gesetzt. Die SQLite-Thread-Modi sind

1. Einzel-Thread: In diesem Modus sind alle Mutexe deaktiviert und SQLite darf nicht gleichzeitig in mehr als einem Thread verwendet werden.

2. Mehr-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.

3. Serialisiert: Im serialisierten Modus kann SQLite sicher von mehreren Threads ohne Einschränkung verwendet werden.

Die Zuordnungen von SQLite-Thread-Modi zu DB-API 2.0 Threadsafety-Levels sind wie folgt:

SQLite-Thread-Modus	threadsafety	SQLITE_THREADSAFE	Bedeutung von DB-API 2.0
single-thread	0	0	Threads dürfen das Modul nicht gemeinsam nutzen
multi-thread	1	2	Threads dürfen das Modul gemeinsam nutzen, aber keine Verbindungen
serialized	3	1	Threads dürfen das Modul, Verbindungen und Cursors gemeinsam nutzen

Geändert in Version 3.11: Setzt threadsafety dynamisch, anstatt es fest auf 1 zu codieren.

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 für die Methoden Connection.setconfig() und getconfig() verwendet.

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

Hinzugefügt in Version 3.12.

Siehe auch

https://www.sqlite.org/c3ref/c_dbconfig_defensive.html

SQLite Doku: Datenbankverbindungs-Konfigurationsoptionen

Veraltet seit Version 3.12, entfernt in Version 3.14: Die Konstanten version und version_info.

Verbindungsobjekte

class sqlite3.Connection

Jede offene SQLite-Datenbank wird durch ein Connection-Objekt dargestellt, das mit sqlite3.connect() erstellt wird. Ihr Hauptzweck ist die Erstellung von Cursor-Objekten und die Transaktionssteuerung.

Siehe auch

• Verwendung von Verbindungs-Shortcut-Methoden

• Verwendung des Verbindungs-Context-Managers

Geändert in Version 3.13: Ein ResourceWarning wird ausgegeben, wenn close() nicht aufgerufen wird, bevor ein Connection-Objekt gelöscht wird.

Eine SQLite-Datenbankverbindung hat die folgenden Attribute und Methoden

cursor(factory=Cursor)

Erstellt und gibt ein Cursor-Objekt zurück. Die Cursor-Methode akzeptiert einen einzelnen optionalen Parameter factory. Wenn dieser angegeben ist, muss es sich um einen aufrufbaren handeln, der eine Instanz von Cursor oder seine Unterklassen zurückgibt.

blobopen(table, column, rowid, /, *, readonly=False, name='main')

Öffnet ein Blob-Handle für ein vorhandenes BLOB.

Parameter:

• table (str) – Der Name der Tabelle, in der sich das Blob befindet.

• column (str) – Der Name der Spalte, in der sich das Blob befindet.

• rowid (int) – Die Zeilen-ID, in der sich das Blob befindet.

• readonly (bool) – Auf True setzen, wenn das Blob schreibgeschützt geöffnet werden soll. Standardwert ist False.

• name (str) – Der Name der Datenbank, in der sich das Blob befindet. Standardwert ist "main".

Löst aus:

OperationalError – Beim Versuch, ein Blob in einer WITHOUT ROWID-Tabelle zu öffnen.

Rückgabetyp:

Blob

Hinweis

Die Blob-Größe kann nicht mit der Klasse Blob geändert werden. Verwenden Sie die SQL-Funktion zeroblob, um ein Blob mit fester Größe zu erstellen.

Hinzugefügt in Version 3.11.

commit()

Bestätigt alle ausstehenden Transaktionen in der Datenbank. Wenn autocommit auf True gesetzt ist oder keine offene Transaktion vorhanden ist, tut diese Methode nichts. Wenn autocommit auf False gesetzt ist, wird eine neue Transaktion implizit geöffnet, wenn durch diese Methode eine ausstehende Transaktion bestätigt wurde.

rollback()

Macht alle ausstehenden Transaktionen rückgängig. Wenn autocommit auf True gesetzt ist oder keine offene Transaktion vorhanden ist, tut diese Methode nichts. Wenn autocommit auf False gesetzt ist, wird eine neue Transaktion implizit geöffnet, wenn durch diese Methode eine ausstehende Transaktion zurückgerollt wurde.

close()

Schließt die Datenbankverbindung. Wenn autocommit auf False gesetzt ist, werden alle ausstehenden Transaktionen implizit zurückgerollt. Wenn autocommit auf True oder LEGACY_TRANSACTION_CONTROL gesetzt ist, werden keine impliziten Transaktionssteuerungen ausgeführt. Stellen Sie sicher, dass Sie vor dem Schließen commit() aufrufen, um verlorene Änderungen zu vermeiden.

execute(sql, parameters=(), /)

Erstellt ein neues Cursor-Objekt und ruft execute() mit den übergebenen sql und parameters auf. Gibt das neue Cursor-Objekt zurück.

executemany(sql, parameters, /)

Erstellt ein neues Cursor-Objekt und ruft executemany() mit den übergebenen sql und parameters auf. Gibt das neue Cursor-Objekt zurück.

executescript(sql_script, /)

Erstellt ein neues Cursor-Objekt und ruft executescript() mit dem übergebenen sql_script auf. Gibt das neue Cursor-Objekt zurück.

create_function(name, narg, func, *, deterministic=False)

Erstellt oder entfernt eine benutzerdefinierte SQL-Funktion.

Parameter:

• name (str) – Der Name der SQL-Funktion.

• narg (int) – Die Anzahl der Argumente, die die SQL-Funktion akzeptieren kann. Wenn -1, kann sie eine beliebige Anzahl von Argumenten akzeptieren.

• func (Callback | None) – Ein aufrufbarer, der aufgerufen wird, wenn die SQL-Funktion aufgerufen wird. Der aufrufbare muss einen von SQLite nativ unterstützten Typ zurückgeben. Auf None setzen, um eine vorhandene SQL-Funktion zu entfernen.

• deterministic (bool) – Wenn True, wird die erstellte SQL-Funktion als deterministisch markiert, was SQLite zusätzliche Optimierungen ermöglicht.

Geändert in Version 3.8: Der Parameter deterministic wurde hinzugefügt.

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

Geändert in Version 3.13: Die Übergabe von name, narg und func als Schlüsselwortargumente ist veraltet. Diese Parameter werden in Python 3.15 positionsgebunden.

create_aggregate(name, n_arg, aggregate_class)

Erstellt oder entfernt eine benutzerdefinierte SQL-Aggregatfunktion.

Parameter:

• name (str) – Der Name der SQL-Aggregatfunktion.

• n_arg (int) – Die Anzahl der Argumente, die die SQL-Aggregatfunktion akzeptieren kann. Wenn -1, kann sie eine beliebige Anzahl von Argumenten akzeptieren.

• aggregate_class (Klasse | None) –

  Eine Klasse muss die folgenden Methoden implementieren

  • step(): Fügt eine Zeile zum Aggregat hinzu.

  • finalize(): Gibt das Endergebnis des Aggregats als von SQLite nativ unterstützten Typ zurück.

  Die Anzahl der Argumente, die die Methode step() akzeptieren muss, wird durch n_arg gesteuert.

  Auf None setzen, um eine vorhandene SQL-Aggregatfunktion 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()

Geändert in Version 3.13: Die Übergabe von name, n_arg und aggregate_class als Schlüsselwortargumente ist veraltet. Diese Parameter werden in Python 3.15 positionsgebunden.

create_window_function(name, num_params, aggregate_class, /)

Erstellt oder entfernt eine benutzerdefinierte Aggregat-Fensterfunktion.

Parameter:

• name (str) – Der Name der zu erstellenden oder zu entfernenden SQL-Aggregat-Fensterfunktion.

• num_params (int) – Die Anzahl der Argumente, die die SQL-Aggregat-Fensterfunktion akzeptieren kann. Wenn -1, kann sie eine beliebige Anzahl von Argumenten akzeptieren.

• aggregate_class (Klasse | None) –

  Eine Klasse, die die folgenden Methoden implementieren muss

  • step(): Fügt eine Zeile zum aktuellen Fenster hinzu.

  • value(): Gibt den aktuellen Wert des Aggregats zurück.

  • inverse(): Entfernt eine Zeile aus dem aktuellen Fenster.

  • finalize(): Gibt das Endergebnis des Aggregats als von SQLite nativ unterstützten Typ zurück.

  Die Anzahl der Argumente, die die Methoden step() und value() akzeptieren müssen, wird durch num_params gesteuert.

  Auf None setzen, um eine vorhandene SQL-Aggregat-Fensterfunktion zu entfernen.

Löst aus:

NotSupportedError – Wenn mit einer SQLite-Version älter als 3.25.0 verwendet, die keine Aggregat-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()

create_collation(name, callable, /)

Erstellt eine Sortierfunktion namens name mit der Sortierfunktion callable. callable erhält zwei String-Argumente und sollte einen Integer zurückgeben

• 1 wenn der erste höher geordnet ist als der zweite

• -1 wenn der erste niedriger geordnet ist als der zweite

• 0 wenn sie gleich geordnet sind

Das folgende Beispiel zeigt eine Rückwärts-Sortierfunktion

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

Entfernt eine Sortierfunktion, indem callable auf None gesetzt wird.

Geändert in Version 3.11: Der Name der Sortierfunktion kann jedes Unicode-Zeichen enthalten. Zuvor waren nur ASCII-Zeichen erlaubt.

interrupt()

Rufen Sie diese Methode von einem anderen Thread auf, um alle Abfragen abzubrechen, die möglicherweise auf der Verbindung ausgeführt werden. Abgebrochene Abfragen lösen einen OperationalError aus.

set_authorizer(authorizer_callback)

Registriert den aufrufbaren authorizer_callback, der für jeden Versuch, auf eine Spalte einer Tabelle in der Datenbank zuzugreifen, aufgerufen wird. Der Callback sollte einen der Werte SQLITE_OK, SQLITE_DENY oder SQLITE_IGNORE zurückgeben, um zu signalisieren, wie auf die Spalte zugegriffen werden soll. Die zugrundeliegende SQLite-Bibliothek behandelt den Zugriff.

Das erste Argument des Callbacks gibt die Art des zu autorisierenden Vorgangs an. Das zweite und dritte Argument sind Argumente oder None, abhängig vom ersten Argument. Das 4. Argument ist der Name der Datenbank („main“, „temp“ usw.), falls zutreffend. Das 5. Argument ist der Name des innersten Triggers oder der View, der für den Zugriffsversuch verantwortlich ist, oder None, wenn der Zugriffsversuch direkt aus dem eingegebenen SQL-Code stammt.

Bitte konsultieren Sie die SQLite-Dokumentation zu den möglichen Werten für das erste Argument und der Bedeutung des zweiten und dritten Arguments in Abhängigkeit vom ersten. Alle notwendigen Konstanten sind im Modul sqlite3 verfügbar.

Die Übergabe von None als authorizer_callback deaktiviert den Authorizer.

Geändert in Version 3.11: Unterstützung für die Deaktivierung des Authorizers mit None hinzugefügt.

Geändert in Version 3.13: Die Übergabe von authorizer_callback als Schlüsselwortargument ist veraltet. Der Parameter wird in Python 3.15 positionsgebunden.

set_progress_handler(progress_handler, n)

Registriert den aufrufbaren progress_handler, der für jede n Anweisung der SQLite-virtuellen Maschine aufgerufen wird. Dies ist nützlich, wenn Sie während langlaufender Operationen von SQLite aufgerufen werden möchten, z. B. um eine GUI zu aktualisieren.

Wenn Sie einen zuvor installierten Fortschritts-Handler löschen möchten, rufen Sie die Methode mit None für progress_handler auf.

Die Rückgabe eines Nicht-Null-Werts aus der Handler-Funktion beendet die aktuell ausgeführte Abfrage und bewirkt, dass sie eine DatabaseError-Ausnahme auslöst.

Geändert in Version 3.13: Die Übergabe von progress_handler als Schlüsselwortargument ist veraltet. Der Parameter wird in Python 3.15 positionsgebunden.

set_trace_callback(trace_callback)

Registriert den aufrufbaren trace_callback, der für jede SQL-Anweisung aufgerufen wird, die tatsächlich von der SQLite-Backend ausgeführt wird.

Das einzige an den Callback übergebene Argument ist die Anweisung (als str), die ausgeführt wird. Der Rückgabewert des Callbacks wird ignoriert. Beachten Sie, dass das Backend nicht nur Anweisungen ausführt, die an die Methoden Cursor.execute() übergeben werden. Andere Quellen umfassen die Transaktionsverwaltung des Moduls sqlite3 und die Ausführung von Triggern, die in der aktuellen Datenbank definiert sind.

Die Übergabe von None als trace_callback deaktiviert den Trace-Callback.

Hinweis

Ausnahmen, die im Trace-Callback ausgelöst werden, werden nicht weitergegeben. Als Entwicklungs- und Debugging-Hilfe können Sie enable_callback_tracebacks() verwenden, um Tracebacks von Ausnahmen zu aktivieren, die im Trace-Callback ausgelöst werden.

Hinzugefügt in Version 3.3.

Geändert in Version 3.13: Die Übergabe von trace_callback als Schlüsselwortargument ist veraltet. Der Parameter wird in Python 3.15 positionsgebunden.

enable_load_extension(enabled, /)

Ermöglicht der SQLite-Engine das Laden von SQLite-Erweiterungen aus gemeinsam genutzten Bibliotheken, wenn enabled auf True gesetzt ist; andernfalls wird das Laden von SQLite-Erweiterungen verboten. SQLite-Erweiterungen können neue Funktionen, Aggregate oder komplett neue virtuelle Tabellenimplementierungen definieren. Eine bekannte Erweiterung ist die Volltextsuch-Erweiterung, die mit SQLite vertrieben wird.

Hinweis

Das Modul sqlite3 ist standardmäßig nicht mit Ladeunterstützung für Erweiterungen kompiliert, da einige Plattformen (insbesondere macOS) SQLite-Bibliotheken haben, die ohne diese Funktion kompiliert wurden. Um die Ladeunterstützung für Erweiterungen zu erhalten, müssen Sie die Option --enable-loadable-sqlite-extensions an configure übergeben.

Löst ein Audit-Ereignis sqlite3.enable_load_extension mit den Argumenten connection, enabled aus.

Hinzugefügt in Version 3.2.

Geändert in Version 3.10: Das Audit-Ereignis sqlite3.enable_load_extension wurde hinzugefügt.

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)

load_extension(path, /, *, entrypoint=None)

Lädt eine SQLite-Erweiterung aus einer gemeinsam genutzten Bibliothek. Aktivieren Sie das Laden von Erweiterungen mit enable_load_extension(), bevor Sie diese Methode aufrufen.

Parameter:

• path (str) – Der Pfad zur SQLite-Erweiterung.

• entrypoint (str | None) – Name des Einstiegspunkts. Wenn None (Standard), wird SQLite einen eigenen Einstiegspunktnamen finden. Weitere Details finden Sie in der SQLite-Dokumentation unter Loading an Extension.

Löst ein Audit-Ereignis sqlite3.load_extension mit den Argumenten connection, path aus.

Hinzugefügt in Version 3.2.

Geändert in Version 3.10: Das Audit-Ereignis sqlite3.load_extension wurde hinzugefügt.

Geändert in Version 3.12: Der Parameter entrypoint wurde hinzugefügt.

iterdump(*, filter=None)

Gibt einen Iterator zurück, um die Datenbank als SQL-Quellcode zu dumpen. Nützlich zum Speichern einer In-Memory-Datenbank zur späteren Wiederherstellung. Ähnlich wie der Befehl .dump in der sqlite3-Shell.

Parameter:

filter (str | None) – Ein optionales Muster (LIKE) für Datenbankobjekte, die gedumpt werden sollen, z. B. prefix_%. Wenn None (Standard), werden alle Datenbankobjekte eingeschlossen.

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('%s\n' % line)
con.close()

Siehe auch

Umgang mit Nicht-UTF-8-Textkodierungen

Geändert in Version 3.13: Der Parameter filter wurde hinzugefügt.

backup(target, *, pages=-1, progress=None, name='main', sleep=0.250)

Erstellt ein Backup einer SQLite-Datenbank.

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

Parameter:

• target (Connection) – Die Datenbankverbindung, in die das Backup gespeichert werden soll.

• pages (int) – Die Anzahl der Seiten, die auf einmal kopiert werden sollen. Wenn gleich oder kleiner als 0, wird die gesamte Datenbank in einem einzigen Schritt kopiert. Standardmäßig -1.

• progress (Callback | None) – Wenn auf ein Callable gesetzt, wird es bei jeder Backup-Iteration mit drei Integer-Argumenten aufgerufen: dem Status der letzten Iteration, der verbleibenden Anzahl von Seiten, die noch kopiert werden müssen, und der Gesamtanzahl der Seiten. Standardmäßig None.

• name (str) – Der Name der zu sichernden Datenbank. Entweder "main" (Standard) für die Hauptdatenbank, "temp" für die temporäre Datenbank oder der Name einer benutzerdefinierten Datenbank, wie sie mit der SQL-Anweisung ATTACH DATABASE angehängt wurde.

• sleep (float) – Die Anzahl der Sekunden, die zwischen aufeinanderfolgenden Versuchen, verbleibende Seiten zu sichern, gewartet werden soll.

Beispiel 1: Eine vorhandene 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: Eine vorhandene Datenbank in eine transiente Kopie kopieren

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 Nicht-UTF-8-Textkodierungen

getlimit(category, /)

Ruft ein Laufzeitlimit einer Verbindung ab.

Parameter:

category (int) – Die abzufragende SQLite-Limitkategorie.

Rückgabetyp:

int

Löst aus:

ProgrammingError – Wenn category von der zugrunde liegenden SQLite-Bibliothek nicht erkannt wird.

Beispiel: Maximale Länge einer SQL-Anweisung für Connection con abfragen (Standard ist 1000000000)

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

Hinzugefügt in Version 3.11.

setlimit(category, limit, /)

Setzt ein Laufzeitlimit einer Verbindung. 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:

• category (int) – Die zu setzende SQLite-Limitkategorie.

• limit (int) – Der Wert des neuen Limits. Wenn negativ, bleibt das aktuelle Limit unverändert.

Rückgabetyp:

int

Löst aus:

ProgrammingError – Wenn category von der zugrunde liegenden SQLite-Bibliothek nicht erkannt wird.

Beispiel: Begrenzung der Anzahl der angehängten Datenbanken auf 1 für Connection con (Standardlimit ist 10)

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

Hinzugefügt in Version 3.11.

getconfig(op, /)

Fragt eine boolesche Konfigurationsoption der Verbindung ab.

Parameter:

op (int) – Ein SQLITE_DBCONFIG-Code.

Rückgabetyp:

bool

Hinzugefügt in Version 3.12.

setconfig(op, enable=True, /)

Setzt eine boolesche Konfigurationsoption der Verbindung.

Parameter:

• op (int) – Ein SQLITE_DBCONFIG-Code.

• enable (bool) – True, wenn die Konfigurationsoption aktiviert werden soll (Standard); False, wenn sie deaktiviert werden soll.

Hinzugefügt in Version 3.12.

serialize(*, name='main')

Serialisiert eine Datenbank in ein bytes-Objekt. Für eine normale Datenbankdatei auf der Festplatte ist die Serialisierung lediglich eine Kopie der Festplattendatei. Für eine In-Memory-Datenbank oder eine "temp"-Datenbank ist die Serialisierung dieselbe Byte-Sequenz, die auf die Festplatte geschrieben würde, wenn diese Datenbank auf die Festplatte gesichert würde.

Parameter:

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

Rückgabetyp:

bytes

Hinweis

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

Hinzugefügt in Version 3.11.

deserialize(data, /, *, name='main')

Deserialisiert eine serialisierte Datenbank in eine Connection. Diese Methode bewirkt, dass die Datenbankverbindung von der Datenbank name getrennt und name als In-Memory-Datenbank basierend auf der in data enthaltenen Serialisierung wieder geöffnet wird.

Parameter:

• data (bytes) – Eine serialisierte Datenbank.

• name (str) – Der Name der zu deserialisierenden Datenbank. Standardmäßig "main".

Löst aus:

• OperationalError – Wenn die Datenbankverbindung derzeit an einer Lesetransaktion oder einem Backup-Vorgang beteiligt ist.

• DatabaseError – Wenn data keine gültige SQLite-Datenbank enthält.

• OverflowError – Wenn len(data) größer als 2**63 - 1 ist.

Hinweis

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

Hinzugefügt in Version 3.11.

autocommit

Dieses Attribut steuert das PEP 249-konforme Transaktionsverhalten. autocommit hat drei zulässige Werte

• False: Wählen Sie das PEP 249-konforme Transaktionsverhalten, was bedeutet, dass sqlite3 sicherstellt, dass immer eine Transaktion geöffnet ist. Verwenden Sie commit() und rollback(), um Transaktionen zu schließen.

  Dies ist der empfohlene Wert für autocommit.

• True: Verwenden Sie den Autocommit-Modus von SQLite. commit() und rollback() haben in diesem Modus keine Auswirkungen.

• LEGACY_TRANSACTION_CONTROL: Vor Python 3.12 (nicht PEP 249-konforme) Transaktionssteuerung. Siehe isolation_level für weitere Details.

  Dies ist derzeit der Standardwert für autocommit.

Das Ändern von autocommit auf False öffnet eine neue Transaktion, und das Ändern auf True committet jede ausstehende Transaktion.

Siehe Transaktionssteuerung über das Attribut autocommit für weitere Details.

Hinweis

Das Attribut isolation_level hat keine Auswirkung, es sei denn, autocommit ist auf LEGACY_TRANSACTION_CONTROL gesetzt.

Hinzugefügt in Version 3.12.

in_transaction

Dieses schreibgeschützte Attribut entspricht dem Low-Level Autocommit-Modus von SQLite.

True, wenn eine Transaktion aktiv ist (es gibt unbestätigte Änderungen), andernfalls False.

Hinzugefügt in Version 3.2.

isolation_level

Steuert den Legacy-Transaktionsbehandlungsmodus von sqlite3. Wenn auf None gesetzt, werden Transaktionen nie implizit geöffnet. Wenn auf einen der Werte "DEFERRED", "IMMEDIATE" oder "EXCLUSIVE" gesetzt, die dem zugrunde liegenden SQLite-Transaktionsverhalten entsprechen, wird eine implizite Transaktionsverwaltung durchgeführt.

Wenn nicht durch den Parameter isolation_level von connect() überschrieben, ist der Standardwert "", was ein Alias für "DEFERRED" ist.

Hinweis

Die Verwendung von autocommit zur Steuerung der Transaktionsbehandlung wird gegenüber der Verwendung von isolation_level empfohlen. isolation_level hat keine Auswirkung, es sei denn, autocommit ist auf LEGACY_TRANSACTION_CONTROL (Standard) gesetzt.

row_factory

Die anfängliche row_factory für Cursor-Objekte, die von dieser Verbindung erstellt werden. Die Zuweisung zu diesem Attribut hat keinen Einfluss auf die row_factory vorhandener Cursor, die zu dieser Verbindung gehören, sondern nur auf neue. Ist standardmäßig None, was bedeutet, dass jede Zeile als tuple zurückgegeben wird.

Siehe Wie man Row-Factories erstellt und verwendet für weitere Details.

text_factory

Ein Callable, das einen bytes-Parameter akzeptiert und eine Textdarstellung davon zurückgibt. Das Callable wird für SQLite-Werte mit dem Datentyp TEXT aufgerufen. Standardmäßig ist dieses Attribut auf str gesetzt.

Siehe Wie man mit Nicht-UTF-8-Textkodierungen umgeht für weitere Details.

total_changes

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

Cursor-Objekte

Ein Cursor-Objekt repräsentiert einen Datenbank-Cursor, der zum Ausführen von SQL-Anweisungen und zur Verwaltung des Kontexts einer Abfrageoperation verwendet wird. Cursor werden mit Connection.cursor() oder durch Verwendung einer der Verbindungs-Shortcut-Methoden erstellt.

Cursor-Objekte sind Iteratoren, was bedeutet, dass Sie, wenn Sie eine SELECT-Abfrage mit execute() ausführen, einfach über den Cursor iterieren können, um die resultierenden Zeilen abzurufen.

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

class sqlite3.Cursor

Eine Cursor-Instanz hat die folgenden Attribute und Methoden.

execute(sql, parameters=(), /)

Führt eine einzelne SQL-Anweisung aus und bindet optional Python-Werte über Platzhalter.

Parameter:

• sql (str) – Eine einzelne SQL-Anweisung.

• parameters (dict | Sequenz) – Python-Werte, die an Platzhalter in sql gebunden werden. Ein dict, wenn benannte Platzhalter verwendet werden. Eine Sequenz, wenn unbenannte Platzhalter verwendet werden. Siehe Wie man Platzhalter verwendet, um Werte in SQL-Abfragen zu binden.

Löst aus:

ProgrammingError – Wenn sql mehr als eine SQL-Anweisung enthält. Wenn benannte Platzhalter verwendet werden und parameters eine Sequenz anstelle eines dict ist.

Wenn autocommit auf LEGACY_TRANSACTION_CONTROL gesetzt ist, isolation_level nicht None ist, sql eine INSERT-, UPDATE-, DELETE- oder REPLACE-Anweisung ist und keine offene Transaktion besteht, wird vor der Ausführung von sql implizit eine Transaktion geöffnet.

Geändert in Version 3.14: ProgrammingError wird ausgelöst, wenn benannte Platzhalter verwendet werden und parameters eine Sequenz anstelle eines dict ist.

Verwenden Sie executescript(), um mehrere SQL-Anweisungen auszuführen.

executemany(sql, parameters, /)

Für jedes Element in parameters wird die parametrisierte DML-SQL-Anweisung sql wiederholt ausgeführt.

Verwendet die gleiche implizite Transaktionsbehandlung wie execute().

Parameter:

• sql (str) – Eine einzelne SQL-DML-Anweisung.

• parameters (Iterable) – Eine Iterable von Parametern, die mit den Platzhaltern in sql gebunden werden. Siehe Wie man Platzhalter verwendet, um Werte in SQL-Abfragen zu binden.

Löst aus:

ProgrammingError – Wenn sql mehr als eine SQL-Anweisung enthält oder keine DML-Anweisung ist, Wenn benannte Platzhalter verwendet werden und die Elemente in parameters Sequenzen anstelle von dicts sind.

Beispiel

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

Hinweis

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

Geändert in Version 3.14: ProgrammingError wird ausgelöst, wenn benannte Platzhalter verwendet werden und die Elemente in parameters Sequenzen anstelle von dicts sind.

executescript(sql_script, /)

Führt die SQL-Anweisungen in sql_script aus. Wenn autocommit auf LEGACY_TRANSACTION_CONTROL gesetzt ist und eine ausstehende Transaktion besteht, wird zuerst eine implizite COMMIT-Anweisung ausgeführt. Es wird keine weitere implizite Transaktionskontrolle durchgeführt; jede Transaktionskontrolle muss zu sql_script hinzugefügt werden.

sql_script muss ein String sein.

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

Wenn row_factory None ist, wird die nächste Zeile des Abfrageergebnisses als tuple zurückgegeben. Andernfalls wird sie an die Zeilenfabrik übergeben und deren Ergebnis zurückgegeben. Gibt None zurück, wenn keine weiteren Daten verfügbar sind.

fetchmany(size=cursor.arraysize)

Gibt die nächste Gruppe von Zeilen eines Abfrageergebnisses als list zurück. Gibt eine leere Liste zurück, wenn keine weiteren Zeilen verfügbar sind.

Die Anzahl der pro Aufruf abzurufenden Zeilen wird durch den Parameter size bestimmt. Wenn size nicht angegeben ist, bestimmt arraysize die Anzahl der abzurufenden Zeilen. Wenn weniger als size Zeilen verfügbar sind, werden so viele Zeilen wie verfügbar zurückgegeben.

Beachten Sie, dass der Parameter size Leistungsauswirkungen hat. Für optimale Leistung ist es normalerweise am besten, das Attribut arraysize zu verwenden. Wenn der Parameter size verwendet wird, ist es am besten, diesen von einem fetchmany()-Aufruf zum nächsten beizubehalten.

Geändert in Version 3.14.0 (unreleased): Negative size-Werte werden durch Auslösen von ValueError abgelehnt.

fetchall()

Gibt alle (verbleibenden) Zeilen eines Abfrageergebnisses als list zurück. Gibt eine leere Liste zurück, wenn keine Zeilen verfügbar sind. Beachten Sie, dass das Attribut arraysize die Leistung dieser Operation beeinflussen kann.

close()

Schließt den Cursor jetzt (anstatt wenn __del__ aufgerufen wird).

Der Cursor ist ab diesem Zeitpunkt unbrauchbar; eine ProgrammingError-Ausnahme wird ausgelöst, wenn ein Vorgang mit dem Cursor versucht wird.

setinputsizes(sizes, /)

Erforderlich für die DB-API. Tut in sqlite3 nichts.

setoutputsize(size, column=None, /)

Erforderlich für die DB-API. Tut in sqlite3 nichts.

arraysize

Lese-/Schreibattribut, das die von fetchmany() zurückgegebene Anzahl von Zeilen steuert. Der Standardwert ist 1, was bedeutet, dass pro Aufruf eine einzelne Zeile abgerufen würde.

Geändert in Version 3.14.0 (unreleased): Negative Werte werden durch Auslösen von ValueError abgelehnt.

connection

Schreibgeschütztes Attribut, das die SQLite-Datenbank Connection bereitstellt, die zum Cursor gehört. Ein Cursor-Objekt, das durch Aufruf von con.cursor() erstellt wurde, verfügt über ein connection-Attribut, das auf con verweist.

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

description

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 Tupels None sind.

Es wird auch für SELECT-Anweisungen ohne übereinstimmende Zeilen gesetzt.

lastrowid

Schreibgeschütztes Attribut, das die Zeilen-ID der zuletzt eingefügten Zeile bereitstellt. Es wird nur nach erfolgreichen INSERT- oder REPLACE-Anweisungen aktualisiert, die mit der Methode execute() ausgeführt wurden. Für andere Anweisungen, nach executemany() oder executescript() oder wenn die Einfügung fehlgeschlagen ist, bleibt der Wert von lastrowid unverändert. Der Anfangswert von lastrowid ist None.

Hinweis

Einfügungen in Tabellen OHNE ROWID werden nicht aufgezeichnet.

Geändert in Version 3.6: Unterstützung für die REPLACE-Anweisung hinzugefügt.

rowcount

Schreibgeschütztes Attribut, das die Anzahl der geänderten Zeilen für INSERT, UPDATE, DELETE und REPLACE-Anweisungen bereitstellt; ist -1 für andere Anweisungen, einschließlich CTE-Abfragen. Es wird nur von den Methoden execute() und executemany() aktualisiert, nachdem die Anweisung abgeschlossen ist. Das bedeutet, dass alle resultierenden Zeilen abgerufen werden müssen, damit rowcount aktualisiert wird.

row_factory

Steuert, wie eine von diesem Cursor abgerufene Zeile dargestellt wird. Wenn None, wird eine Zeile als tuple dargestellt. Kann auf die enthaltene sqlite3.Row gesetzt werden; oder ein aufrufbares Objekt, das zwei Argumente akzeptiert: ein Cursor-Objekt und das tuple der Zeilenwerte, und ein benutzerdefiniertes Objekt zurückgibt, das eine SQLite-Zeile darstellt.

Standardmäßig wird der Wert verwendet, mit dem Connection.row_factory beim Erstellen des Cursor gesetzt wurde. Das Zuweisen zu diesem Attribut hat keine Auswirkungen auf Connection.row_factory der übergeordneten Verbindung.

Siehe Wie man Row-Factories erstellt und verwendet für weitere Details.

Zeilenobjekte

class sqlite3.Row

Eine Row-Instanz dient als hochoptimierte row_factory für Connection-Objekte. Sie unterstützt Iteration, Gleichheitstests, len() und Mapping-Zugriff nach Spaltennamen und Index.

Zwei Row-Objekte sind gleich, wenn sie identische Spaltennamen und Werte haben.

Siehe Wie man Row-Factories erstellt und verwendet für weitere Details.

keys()

Gibt eine Liste von Spaltennamen als Strings zurück. Unmittelbar nach einer Abfrage ist dies das erste Element jedes Tupels in Cursor.description.

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

Blob-Objekte

class sqlite3.Blob

Hinzugefügt in Version 3.11.

Eine Blob-Instanz ist ein dateiähnliches Objekt, das Daten in einem SQLite BLOB lesen und schreiben kann. Rufen Sie len(blob) auf, um die Größe (Anzahl der Bytes) des Blobs zu erhalten. Verwenden Sie Indizes und Slices für den direkten Zugriff auf die Blob-Daten.

Verwenden Sie Blob als Kontextmanager, um sicherzustellen, dass das Blob-Handle nach Gebrauch 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()

close()

Schließt den Blob.

Der Blob ist von diesem Zeitpunkt an nicht mehr verwendbar. Eine Error-Ausnahme (oder eine Unterklasse) wird ausgelöst, wenn ein weiterer Vorgang mit dem Blob versucht wird.

read(length=-1, /)

Liest length Bytes aus dem Blob an der aktuellen Offset-Position. Wenn das Ende des Blobs erreicht ist, werden die Daten bis zum EOF zurückgegeben. Wenn length nicht angegeben ist oder negativ ist, liest read() bis zum Ende des Blobs.

write(data, /)

Schreibt data an der aktuellen Offset-Position in den Blob. Diese Funktion kann die Blob-Länge nicht ändern. Schreiben über das Ende des Blobs hinaus löst einen ValueError aus.

tell()

Gibt die aktuelle Zugriffsposition des Blobs zurück.

seek(offset, origin=os.SEEK_SET, /)

Setzt die aktuelle Zugriffsposition des Blobs auf offset. Das Argument origin hat standardmäßig os.SEEK_SET (absolute Blob-Positionierung). Andere Werte für origin sind os.SEEK_CUR (relativ zur aktuellen Position suchen) und os.SEEK_END (relativ zum Ende des Blobs suchen).

PrepareProtocol-Objekte

class sqlite3.PrepareProtocol

Der Zweck des PrepareProtocol-Typs ist es, als PEP 246-konformes Anpassungsprotokoll für Objekte zu dienen, die sich selbst an native SQLite-Typen anpassen können.

Ausnahmen

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

exception sqlite3.Warning

Diese Ausnahme wird derzeit nicht vom Modul sqlite3 ausgelöst, kann aber von Anwendungen, die sqlite3 verwenden, ausgelöst werden, z. B. wenn eine benutzerdefinierte Funktion Daten beim Einfügen abschneidet. Warning ist eine Unterklasse von Exception.

exception sqlite3.Error

Die Basisklasse der anderen Ausnahmen in diesem Modul. Verwenden Sie dies, um alle Fehler mit einer einzigen except-Anweisung abzufangen. Error ist eine Unterklasse von Exception.

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

sqlite_errorcode

Der numerische Fehlercode von der SQLite API

Hinzugefügt in Version 3.11.

sqlite_errorname

Der symbolische Name des numerischen Fehlercodes von der SQLite API

Hinzugefügt in Version 3.11.

exception sqlite3.InterfaceError

Ausnahme, die bei Missbrauch der Low-Level SQLite C API ausgelöst wird. Mit anderen Worten, wenn diese Ausnahme ausgelöst wird, deutet dies wahrscheinlich auf einen Fehler im Modul sqlite3 hin. InterfaceError ist eine Unterklasse von Error.

exception sqlite3.DatabaseError

Ausnahme, die bei Fehlern im Zusammenhang mit der Datenbank ausgelöst wird. Dies dient als Basis-Ausnahme für verschiedene Arten von Datenbankfehlern. Sie wird nur implizit über die spezialisierten Unterklassen ausgelöst. DatabaseError ist eine Unterklasse von Error.

exception sqlite3.DataError

Ausnahme, die bei Fehlern aufgrund von Problemen mit den verarbeiteten Daten ausgelöst wird, wie z. B. Zahlenwerte außerhalb des Bereichs und zu lange Zeichenketten. DataError ist eine Unterklasse von DatabaseError.

exception sqlite3.OperationalError

Ausnahme, die bei Fehlern im Zusammenhang mit dem Betrieb der Datenbank ausgelöst wird und nicht unbedingt unter der Kontrolle des Programmierers steht. Zum Beispiel ist der Datenbankpfad nicht gefunden oder eine Transaktion konnte nicht verarbeitet werden. OperationalError ist eine Unterklasse von DatabaseError.

exception sqlite3.IntegrityError

Ausnahme, die ausgelöst wird, wenn die relationale Integrität der Datenbank beeinträchtigt wird, z. B. eine Fremdschlüsselprüfung fehlschlägt. Sie ist eine Unterklasse von DatabaseError.

exception sqlite3.InternalError

Ausnahme, die ausgelöst wird, wenn SQLite auf einen internen Fehler stößt. Wenn dies ausgelöst wird, kann dies darauf hindeuten, dass die SQLite-Laufzeitbibliothek ein Problem hat. InternalError ist eine Unterklasse von DatabaseError.

exception sqlite3.ProgrammingError

Ausnahme, die bei API-Programmierfehlern in sqlite3 ausgelöst wird, z. B. bei Angabe der falschen Anzahl von Bindungen für eine Abfrage oder beim Versuch, eine geschlossene Connection zu verwenden. ProgrammingError ist eine Unterklasse von DatabaseError.

exception sqlite3.NotSupportedError

Ausnahme, die ausgelöst wird, wenn eine Methode oder Datenbank-API von der zugrundeliegenden SQLite-Bibliothek nicht unterstützt wird. Zum Beispiel das Setzen von deterministic auf True in create_function(), wenn die zugrundeliegende SQLite-Bibliothek keine deterministischen Funktionen unterstützt. NotSupportedError ist eine Unterklasse von DatabaseError.

SQLite- und Python-Typen

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

Die folgenden Python-Typen können daher ohne Probleme an SQLite gesendet werden

Python Typ	SQLite-Typ
None	NULL
int	INTEGER
float	REAL
str	TEXT
bytes	BLOB

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

SQLite-Typ	Python Typ
NULL	None
INTEGER	int
REAL	float
TEXT	hängt von text_factory ab, standardmäßig str
BLOB	bytes

Das Typsystem des Moduls sqlite3 ist auf zwei Arten erweiterbar: Sie können zusätzliche Python-Typen über Objektadapter in einer SQLite-Datenbank speichern, und Sie können das Modul sqlite3 so konfigurieren, dass es SQLite-Typen über Konverter in Python-Typen umwandelt.

Standardadapter und -konverter (veraltet)

Hinweis

Die Standardadapter und Konverter sind ab Python 3.12 veraltet. Verwenden Sie stattdessen die Rezepte für Adapter und Konverter und passen Sie diese an Ihre Bedürfnisse an.

Die veralteten Standardadapter und Konverter bestehen aus

• Ein Adapter für datetime.date-Objekte in Strings im ISO 8601-Format.

• Ein Adapter für datetime.datetime-Objekte in Strings im ISO 8601-Format.

• Ein Konverter für deklarierte "date"-Typen in datetime.date-Objekte.

• Ein Konverter für deklarierte "timestamp"-Typen in datetime.datetime-Objekte. Bruchteile werden auf 6 Stellen (Mikrosekundenpräzision) abgeschnitten.

Hinweis

Der Standard-"timestamp"-Konverter ignoriert UTC-Offsets in der Datenbank und gibt immer ein naives datetime.datetime-Objekt zurück. Um UTC-Offsets in Zeitstempeln beizubehalten, lassen Sie Konverter deaktiviert oder registrieren Sie einen Offset-fähigen Konverter mit register_converter().

Veraltet seit Version 3.12.

Kommandozeilenschnittstelle

Das Modul sqlite3 kann als Skript über den Schalter -m des Interpreters aufgerufen werden, um eine einfache SQLite-Shell bereitzustellen. Die Argumente sind wie folgt:

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

Geben Sie .quit oder STRG-D ein, um die Shell zu beenden.

-h, --help

CLI-Hilfe anzeigen.

-v, --version

Version der zugrundeliegenden SQLite-Bibliothek anzeigen.

Hinzugefügt in Version 3.12.

Anleitungen

Anleitung zur Verwendung von Platzhaltern 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 für SQL-Injection-Angriffe sind. Ein Angreifer kann beispielsweise einfach den einfachen Anführungsstrich schließen und OR TRUE injizieren, um 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 Parameter-Substitution 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, indem Sie sie als Tupel von Werten im zweiten Argument der execute()-Methode des Cursors bereitstellen.

Eine SQL-Anweisung kann einen von zwei Arten von Platzhaltern verwenden: Fragezeichen (Qmark-Stil) oder benannte Platzhalter (benannter Stil). Für den Qmark-Stil muss parameters eine Sequenz sein, deren Länge der Anzahl der Platzhalter entsprechen muss, andernfalls wird eine ProgrammingError ausgelöst. Für den benannten Stil muss parameters eine Instanz eines dict (oder einer Unterklasse) sein, die Schlüssel für alle benannten Parameter enthalten muss; zusätzliche 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()

Hinweis

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

Anleitung zur Anpassung benutzerdefinierter Python-Typen an SQLite-Werte

SQLite unterstützt nativ nur eine begrenzte Anzahl von Datentypen. Um benutzerdefinierte Python-Typen in SQLite-Datenbanken zu speichern, müssen Sie sie an einen der Python-Typen anpassen, die SQLite nativ versteht.

Es gibt zwei Möglichkeiten, Python-Objekte an SQLite-Typen anzupassen: Ihr Objekt passt sich selbst an oder Sie verwenden einen Adapter-Aufruf. Letzteres hat Vorrang. Für eine Bibliothek, die einen benutzerdefinierten Typ exportiert, kann es sinnvoll sein, diesen Typ anpassungsfähig zu machen. Als Anwendungsentwickler kann es sinnvoller sein, die direkte Kontrolle zu übernehmen, indem benutzerdefinierte Adapterfunktionen registriert werden.

Anleitung zum Schreiben von anpassungsfähigen Objekten

Angenommen, wir haben eine Point-Klasse, die ein Koordinatenpaar, x und y, in einem kartesischen Koordinatensystem darstellt. Das Koordinatenpaar wird als Textzeichenfolge in der Datenbank gespeichert, wobei ein Semikolon zur Trennung der Koordinaten verwendet wird. Dies kann durch Hinzufügen einer __conform__(self, protocol)-Methode implementiert werden, die den angepassten Wert zurückgibt. Das an protocol übergebene Objekt hat den Typ PrepareProtocol.

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

Anleitung zur Registrierung von Adapter-Aufrufen

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 register_adapter() registriert werden.

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

Anleitung zur Konvertierung von SQLite-Werten in benutzerdefinierte Python-Typen

Das Schreiben eines Adapters ermöglicht die Konvertierung von benutzerdefinierten Python-Typen in SQLite-Werte. Um von SQLite-Werten in benutzerdefinierte Python-Typen konvertieren zu können, verwenden wir Konverter.

Gehen wir zurück zur Point-Klasse. Wir haben die x- und y-Koordinaten, getrennt durch Semikolons, als Zeichenfolgen in SQLite gespeichert.

Zuerst definieren wir eine Konverterfunktion, die die Zeichenfolge als Parameter akzeptiert und ein Point-Objekt daraus erstellt.

Hinweis

Konverterfunktionen erhalten immer ein bytes-Objekt, unabhängig vom zugrundeliegenden SQLite-Datentyp.

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

Wir müssen sqlite3 nun mitteilen, wann es einen bestimmten SQLite-Wert konvertieren soll. Dies geschieht bei der Verbindung zur Datenbank unter Verwendung des Parameters detect_types von connect(). Es gibt drei Optionen:

• Implizit: Setzen Sie detect_types auf PARSE_DECLTYPES

• Explizit: Setzen Sie detect_types auf PARSE_COLNAMES

• Beides: Setzen Sie detect_types auf sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES. Spaltennamen haben Vorrang vor deklarierten Typen.

Das folgende Beispiel veranschaulicht den impliziten und expliziten Ansatz.

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

Rezepte für Adapter und Konverter

Dieser Abschnitt zeigt Rezepte für gängige Adapter und Konverter.

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.replace(tzinfo=None).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)

Anleitung zur Verwendung von Verbindungs-Shortcut-Methoden

Mit den Methoden execute(), executemany() und executescript() der Klasse Connection kann Ihr Code prägnanter geschrieben werden, da Sie die (oft überflüssigen) Cursor-Objekte nicht explizit erstellen müssen. Stattdessen werden die Cursor-Objekte implizit erstellt und diese Kurzmethoden geben die Cursor-Objekte zurück. Auf diese Weise können Sie eine SELECT-Anweisung ausführen und direkt mit einem einzigen Aufruf des Connection-Objekts darüber iterieren.

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

Verwendung des Connection-Kontextmanagers

Ein Connection-Objekt kann als Kontextmanager verwendet werden, der offene Transaktionen automatisch committet oder zurückrollt, wenn der Körper des Kontextmanagers verlassen wird. Wenn der Körper der with-Anweisung ohne Ausnahmen endet, wird die Transaktion committet. Wenn dieses Commit fehlschlägt oder wenn der Körper der with-Anweisung eine nicht abgefangene Ausnahme auslöst, wird die Transaktion zurückgerollt. Wenn autocommit False ist, wird nach dem Commit oder Rollback implizit eine neue Transaktion geöffnet.

Wenn beim Verlassen des Körpers der with-Anweisung keine Transaktion offen ist oder wenn autocommit True ist, tut der Kontextmanager nichts.

Hinweis

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

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

Arbeiten mit SQLite-URIs

Einige nützliche URI-Tricks sind

• Öffnen einer Datenbank im Nur-Lese-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
>>> con.close()

• Erstellen Sie keine neue Datenbankdatei implizit, wenn sie noch nicht existiert; löst OperationalError aus, wenn eine neue Datei nicht 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 einer gemeinsamen benannten 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 diesem Feature, einschließlich einer Liste von Parametern, finden Sie in der SQLite URI-Dokumentation.

Erstellen und Verwenden von Zeilenfabriken

Standardmäßig repräsentiert sqlite3 jede Zeile als tuple. Wenn ein tuple nicht Ihren Anforderungen entspricht, können Sie die Klasse sqlite3.Row oder eine benutzerdefinierte row_factory verwenden.

Während row_factory sowohl als Attribut des Cursor als auch der Connection existiert, wird empfohlen, Connection.row_factory zu setzen, damit alle von der Verbindung erstellten Cursor dieselbe Zeilenfabrik verwenden.

Row bietet indizierten und fallunabhängigen benannten Zugriff auf Spalten mit minimalem Speicheraufwand und geringem Leistungseinfluss im Vergleich zu einem tuple. Um Row als Zeilenfabrik zu verwenden, weisen Sie es dem Attribut row_factory zu

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

Abfragen geben jetzt Row-Objekte zurück

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

Hinweis

Die FROM-Klausel kann in der SELECT-Anweisung weggelassen werden, wie im obigen Beispiel. In solchen Fällen gibt SQLite eine einzelne Zeile mit Spalten zurück, die durch Ausdrücke definiert sind, z. B. Literale, mit den gegebenen Aliasen expr AS alias.

Sie können eine benutzerdefinierte row_factory erstellen, die jede Zeile als dict zurückgibt, wobei 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)}

Damit geben Abfragen nun ein dict anstelle eines tuple zurück

>>> 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 ein benanntes Tupel zurück

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 anstelle eines namedtuple eine dataclass oder eine andere benutzerdefinierte Klasse zu verwenden.

Umgang mit Nicht-UTF-8-Textkodierungen

Standardmäßig verwendet sqlite3 str, um SQLite-Werte mit dem Datentyp TEXT anzupassen. Dies funktioniert gut für UTF-8-kodierten Text, kann aber für andere Kodierungen und ungültiges UTF-8 fehlschlagen. Sie können eine benutzerdefinierte text_factory verwenden, um solche Fälle zu behandeln.

Aufgrund der flexiblen Typisierung von SQLite ist es nicht ungewöhnlich, dass Spalten mit dem Datentyp TEXT Nicht-UTF-8-Kodierungen oder sogar beliebige Daten enthalten. Um dies zu demonstrieren, nehmen wir an, wir haben eine Datenbank mit ISO-8859-2 (Lateinisch-2) kodiertem Text, zum Beispiel eine Tabelle mit tschechisch-englischen Wörterbucheinträgen. Angenommen, wir haben nun eine Connection-Instanz con, die mit dieser Datenbank verbunden ist, können wir den lateinisch-2-kodierten Text mit dieser text_factory dekodieren

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

Für ungültiges UTF-8 oder beliebige Daten, die in TEXT-Tabellenspalten gespeichert sind, können Sie die folgende Technik verwenden, die aus dem Unicode HOWTO entlehnt wurde

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

Hinweis

Die API des Moduls sqlite3 unterstützt keine Zeichenketten, die Surrogatzeichen enthalten.

Siehe auch

Unicode HOWTO

Erläuterung

Transaktionskontrolle

sqlite3 bietet mehrere Methoden zur Steuerung, ob, wann und wie Datenbanktransaktionen geöffnet und geschlossen werden. Die Transaktionskontrolle über das Autocommit-Attribut wird empfohlen, während die Transaktionskontrolle über das Isolation_level-Attribut das Verhalten vor Python 3.12 beibehält.

Transaktionskontrolle über das autocommit-Attribut

Die empfohlene Methode zur Steuerung des Transaktionsverhaltens ist das Attribut Connection.autocommit, das vorzugsweise über den Parameter autocommit von connect() gesetzt werden sollte.

Es wird empfohlen, autocommit auf False zu setzen, was eine PEP 249-konforme Transaktionskontrolle impliziert. Das bedeutet

• sqlite3 verwendet BEGIN DEFERRED-Anweisungen beim Öffnen von Transaktionen.

• Transaktionen sollten explizit mit commit() committet werden.

• Transaktionen sollten explizit mit rollback() zurückgerollt werden.

• Ein impliziter Rollback wird durchgeführt, wenn die Datenbank mit ausstehenden Änderungen close()d wird.

Setzen Sie autocommit auf True, um den Autocommit-Modus von SQLite zu aktivieren. In diesem Modus haben Connection.commit() und Connection.rollback() keine Wirkung. Beachten Sie, dass der Autocommit-Modus von SQLite von dem PEP 249-konformen Attribut Connection.autocommit getrennt ist; verwenden Sie Connection.in_transaction, um den Low-Level-SQLite-Autocommit-Modus abzufragen.

Setzen Sie autocommit auf LEGACY_TRANSACTION_CONTROL, um das Transaktionskontrollverhalten dem Attribut Connection.isolation_level zu überlassen. Weitere Informationen finden Sie unter Transaktionskontrolle über das isolation_level-Attribut.

Transaktionskontrolle über das isolation_level-Attribut

Hinweis

Die empfohlene Methode zur Transaktionskontrolle ist über das Attribut autocommit. Siehe Transaktionskontrolle über das Autocommit-Attribut.

Wenn Connection.autocommit auf LEGACY_TRANSACTION_CONTROL (Standard) gesetzt ist, wird das Transaktionsverhalten über das Attribut Connection.isolation_level gesteuert. Andernfalls hat isolation_level keine Auswirkung.

Wenn das Verbindungsattribut isolation_level nicht None ist, werden vor der Ausführung von INSERT-, UPDATE-, DELETE- oder REPLACE-Anweisungen durch execute() und executemany() implizit neue Transaktionen geöffnet; für andere Anweisungen erfolgt keine implizite Transaktionsbehandlung. Verwenden Sie die Methoden commit() und rollback(), um ausstehende Transaktionen zu committen bzw. zurückzurollen. Sie können das zugrunde liegende SQLite-Transaktionsverhalten – d. h. ob und welche Art von BEGIN-Anweisungen sqlite3 implizit ausführt – über das Attribut isolation_level steuern.

Wenn isolation_level auf None gesetzt ist, werden überhaupt keine Transaktionen implizit geöffnet. Dies belässt die zugrunde liegende SQLite-Bibliothek im Autocommit-Modus, ermöglicht es dem Benutzer aber auch, eigene Transaktionsbehandlungen mit expliziten SQL-Anweisungen durchzuführen. Der Autocommit-Modus der zugrunde liegenden SQLite-Bibliothek kann über das Attribut in_transaction abgefragt werden.

Die Methode executescript() committet implizit jede ausstehende Transaktion vor der Ausführung des gegebenen SQL-Skripts, unabhängig vom Wert von isolation_level.

Geändert in Version 3.6: sqlite3 committete früher implizit eine offene Transaktion vor DDL-Anweisungen. Dies ist nicht mehr der Fall.

Geändert in Version 3.12: Die empfohlene Methode zur Transaktionskontrolle ist nun über das Attribut autocommit.