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

Quellcode: Lib/sqlite3/

SQLite ist eine C-Bibliothek, die eine schlanke, dateibasierte Datenbank bereitstellt, die keinen eigenen Serverprozess benötigt und den Zugriff auf die Datenbank über eine nicht standardisierte Variante der Abfragesprache SQL erlaubt. Manche Anwendungen können SQLite zur internen Datenspeicherung verwenden. Man kann eine Anwendung auch mit SQLite als Prototyp bauen und den Code später auf eine größere Datenbank wie PostgreSQL oder Oracle portieren.

Das Modul sqlite3 wurde von Gerhard Häring geschrieben. Es stellt eine SQL-Schnittstelle bereit, die der in PEP 249 beschriebenen DB-API-2.0-Spezifikation entspricht, und benötigt die Fremdbibliothek SQLite.

Dies ist ein optionales Modul. Falls es in deiner Kopie von CPython fehlt, suche in der Dokumentation deines Distributors (also demjenigen, der dir Python zur Verfügung gestellt hat). Falls du selbst der Distributor bist, siehe Voraussetzungen für optionale Module.

Dieses Dokument hat vier Hauptteile:

  • Tutorial zeigt, wie das Modul sqlite3 verwendet wird.

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

  • Anleitungen erläutert im Einzelnen, wie bestimmte Aufgaben zu erledigen sind.

  • Erklärung liefert ausführliche Hintergründe zur Transaktionssteuerung.

Siehe auch

https://www.sqlite.org

Die Webseite von SQLite. Die Dokumentation beschreibt die Syntax und die verfügbaren Datentypen des unterstützten SQL-Dialekts.

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 erstellst du mit den Grundfunktionen von sqlite3 eine Datenbank mit Monty-Python-Filmen. Es setzt ein grundlegendes Verständnis von Datenbankbegriffen voraus, darunter cursors und transactions.

Zuerst müssen wir eine neue Datenbank erstellen und eine Datenbankverbindung öffnen, damit sqlite3 mit ihr arbeiten kann. Rufe sqlite3.connect() auf, um eine Verbindung zur Datenbank tutorial.db im aktuellen Arbeitsverzeichnis herzustellen. Sie wird dabei stillschweigend angelegt, falls es sie noch nicht gibt:

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

Das zurückgegebene Connection-Objekt con stellt die Verbindung zur Datenbank auf der Festplatte dar.

Um SQL-Anweisungen auszuführen und Ergebnisse aus SQL-Abfragen zu holen, brauchen wir einen Datenbankcursor. Rufe con.cursor() auf, um den Cursor zu erzeugen:

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 anlegen. Der Einfachheit halber können wir in der Tabellendeklaration nur die Spaltennamen angeben – dank der flexible typing-Eigenschaft von SQLite ist die Angabe der Datentypen wahlfrei. Führe die CREATE TABLE-Anweisung aus, indem du cur.execute(...) aufrufst:

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

Dass die neue Tabelle angelegt wurde, können wir überprüfen, indem wir die in SQLite integrierte Tabelle sqlite_master abfragen, die nun einen Eintrag für die Definition der Tabelle movie enthalten sollte (Einzelheiten unter The Schema Table). Führe diese Abfrage mit cur.execute(...) aus, weise das Ergebnis res zu und rufe res.fetchone() auf, um die sich ergebende Zeile zu holen:

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

Wir sehen, dass die Tabelle angelegt wurde, denn die Abfrage gibt ein tuple mit dem Namen der Tabelle zurück. Fragen wir sqlite_master nach einer nicht vorhandenen Tabelle spam ab, gibt res.fetchone() None zurück:

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

Füge nun zwei Datenzeilen hinzu, die als SQL-Literale angegeben werden, indem du eine INSERT-Anweisung ausführst, wieder über 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 stillschweigend eine Transaktion, die committet werden muss, bevor die Änderungen in der Datenbank gespeichert sind (Einzelheiten unter Transaktionssteuerung). Rufe auf dem Verbindungsobjekt con.commit() auf, um die Transaktion zu committen:

con.commit()

Dass die Daten richtig eingefügt wurden, können wir mit einer SELECT-Abfrage überprüfen. Verwende das inzwischen vertraute cur.execute(...), um das Ergebnis res zuzuweisen, und rufe res.fetchall() auf, um alle sich ergebenden Zeilen zurückzugeben:

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

Das Ergebnis ist eine list aus zwei tuples, eines je Zeile, die jeweils den Wert score dieser Zeile enthalten.

Füge jetzt drei weitere Zeilen ein, indem du cur.executemany(...) aufrufst:

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()  # Denk daran, die Transaktion nach dem INSERT zu committen.

Beachte, dass ?-Platzhalter verwendet werden, um data an die Abfrage zu binden. Verwende immer Platzhalter statt Zeichenkettenformatierung, um Python-Werte an SQL-Anweisungen zu binden, damit SQL injection attacks vermieden werden (weitere Einzelheiten unter Platzhalter verwenden, um Werte in SQL-Abfragen zu binden).

Dass die neuen Zeilen eingefügt wurden, können wir mit einer SELECT-Abfrage überprüfen, diesmal, indem wir ü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 tuple aus (year, title), passend zu den in der Abfrage ausgewählten Spalten.

Überprüfe schließlich, dass die Datenbank auf die Festplatte geschrieben wurde: Rufe con.close() auf, um die bestehende Verbindung zu schließen, öffne eine neue, erzeuge einen neuen Cursor und frage dann die Datenbank ab:

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

Du hast jetzt mit dem Modul sqlite3 eine SQLite-Datenbank angelegt, Daten eingefügt und auf mehreren Wegen Werte daraus geholt.

Siehe auch

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 (path-like object) – Der Pfad zur zu öffnenden Datenbankdatei. Du kannst ":memory:" übergeben, um eine nur im Arbeitsspeicher bestehende SQLite-Datenbank zu erzeugen und eine Verbindung zu ihr zu öffnen.

  • timeout (float) – Wie viele Sekunden die Verbindung warten soll, bevor sie einen OperationalError auslöst, wenn eine Tabelle gesperrt ist. Öffnet eine andere Verbindung eine Transaktion, um eine Tabelle zu ändern, bleibt diese Tabelle gesperrt, bis die Transaktion committet ist. Voreingestellt sind fünf Sekunden.

  • detect_types (int) – Steuert, ob und wie Datentypen, die SQLite nicht von Haus aus unterstützt, nachgeschlagen werden, um sie über die mit register_converter() registrierten Konverter in Python-Typen umzuwandeln. Setze es auf eine beliebige Kombination (mit |, bitweises Oder) aus PARSE_DECLTYPES und PARSE_COLNAMES, um das einzuschalten. Sind beide Flags gesetzt, haben Spaltennamen Vorrang vor deklarierten Typen. Voreingestellt (0) ist die Typerkennung abgeschaltet.

  • isolation_level (str | None) – Steuert das überkommene Verhalten bei der Transaktionsbehandlung. Weitere Informationen stehen unter Connection.isolation_level und Transaktionssteuerung über das Attribut isolation_level. Möglich sind "DEFERRED" (Voreinstellung), "EXCLUSIVE" oder "IMMEDIATE" sowie None, um das stillschweigende Öffnen von Transaktionen abzuschalten. Hat keine Wirkung, solange Connection.autocommit nicht auf LEGACY_TRANSACTION_CONTROL (die Voreinstellung) gesetzt ist.

  • check_same_thread (bool) – Ist es True (die Voreinstellung), wird ein ProgrammingError ausgelöst, wenn die Datenbankverbindung von einem anderen Thread als dem erzeugenden verwendet wird. Ist es False, darf auf die Verbindung aus mehreren Threads zugegriffen werden; Schreibvorgänge musst du dann unter Umständen selbst serialisieren, um Datenverfälschung zu vermeiden. Weitere Informationen stehen unter threadsafety.

  • factory (Connection) – Eine eigene Unterklasse von Connection, mit der die Verbindung erzeugt werden soll, falls nicht die voreingestellte Klasse Connection verwendet wird.

  • cached_statements (int) – Die Anzahl der Anweisungen, die sqlite3 für diese Verbindung intern zwischenspeichern soll, um Aufwand beim Zerlegen zu sparen. Voreingestellt sind 128 Anweisungen.

  • uri (bool) – Ist es auf True gesetzt, wird database als URI mit einem Dateipfad und einer wahlfreien Abfragezeichenkette ausgelegt. Der Schemateil muss "file:" sein, und der Pfad darf relativ oder absolut sein. Über die Abfragezeichenkette lassen sich Parameter an SQLite übergeben, was verschiedene Mit SQLite-URIs arbeiten ermöglicht.

  • autocommit (bool) – Steuert das Verhalten der Transaktionsbehandlung nach PEP 249. Weitere Informationen stehen unter Connection.autocommit und Transaktionssteuerung über das Attribut autocommit. autocommit ist derzeit auf LEGACY_TRANSACTION_CONTROL voreingestellt. Die Voreinstellung wird sich in einer künftigen Python-Veröffentlichung zu False ändern.

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 darf jetzt auch ein pfadartiges Objekt sein, nicht nur eine Zeichenkette.

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.15: Alle Parameter außer database sind jetzt nur über Schlüsselwort angebbar.

sqlite3.complete_statement(statement)

Gibt True zurück, wenn die Zeichenkette statement eine oder mehrere vollständige SQL-Anweisungen zu enthalten scheint. Es findet keinerlei syntaktische Überprüfung oder Zerlegung statt, außer der Prüfung, dass keine Zeichenkettenliterale offen sind und die Anweisung mit einem Semikolon endet.

Zum Beispiel:

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

Diese Funktion kann bei der Eingabe auf der Befehlszeile nützlich sein, um festzustellen, ob der eingegebene Text eine vollständige SQL-Anweisung zu bilden scheint oder ob vor dem Aufruf von execute() weitere Eingaben nötig sind.

Ein Beispiel aus der Praxis ist runsource() in Lib/sqlite3/__main__.py.

sqlite3.enable_callback_tracebacks(flag, /)

Schaltet Tracebacks aus Callbacks ein oder aus. Voreingestellt bekommst du keinerlei Tracebacks aus selbst definierten Funktionen, Aggregaten, Konvertern, Authorizer-Callbacks und so weiter. Willst du sie fehlersuchen, kannst du diese Funktion mit flag auf True aufrufen. Danach bekommst du Tracebacks aus Callbacks auf sys.stderr. Mit False schaltest du die Eigenschaft wieder ab.

Bemerkung

Fehler in Callbacks selbst definierter Funktionen werden als nicht auslösbare Ausnahmen protokolliert. Verwende einen Hook für nicht auslösbare Ausnahmen, um das fehlgeschlagene Callback zu untersuchen.

sqlite3.register_adapter(type, adapter, /)

Registriert ein aufrufbares adapter, das den Python-Typ type in einen SQLite-Typ anpasst. Der Adapter wird mit einem Python-Objekt vom Typ type als einzigem Argument aufgerufen und muss einen Wert eines Typs zurückgeben, den SQLite von Haus aus versteht.

sqlite3.register_converter(typename, converter, /)

Registriert das aufrufbare converter, das SQLite-Objekte vom Typ typename in ein Python-Objekt eines bestimmten Typs umwandelt. Der Konverter wird für alle SQLite-Werte vom Typ typename aufgerufen. Ihm wird ein bytes-Objekt übergeben, und er sollte ein Objekt des gewünschten Python-Typs zurückgeben. Wie die Typerkennung arbeitet, steht beim Parameter detect_types von connect().

Beachte: typename und der Name des Typs in deiner Abfrage werden ohne Rücksicht auf Groß- und Kleinschreibung verglichen.

Modulkonstanten

sqlite3.LEGACY_TRANSACTION_CONTROL

Setze autocommit auf diese Konstante, um das alte Verhalten der Transaktionssteuerung (vor Python 3.12) zu wählen. Weitere Informationen stehen unter Transaktionssteuerung über das Attribut isolation_level.

sqlite3.PARSE_DECLTYPES

Übergib diesen Flag-Wert an den Parameter detect_types von connect(), um eine Konverterfunktion über die deklarierten Typen jeder Spalte nachzuschlagen. Die Typen werden deklariert, wenn die Datenbanktabelle angelegt wird. sqlite3 schlägt eine Konverterfunktion nach, wobei das erste Wort des deklarierten Typs als Schlüssel im Konverter-Dictionary dient. Zum Beispiel:

CREATE TABLE test(
   i integer primary key,  ! schlägt einen Konverter namens "integer" nach
   p point,                ! schlägt einen Konverter namens "point" nach
   n number(10)            ! schlägt einen Konverter namens "number" nach
 )

Dieses Flag lässt sich über den Operator | (bitweises Oder) mit PARSE_COLNAMES verbinden.

Bemerkung

Erzeugte Felder (zum Beispiel MAX(p)) werden als str zurückgegeben. Verwende PARSE_COLNAMES, um für solche Abfragen Typen zu erzwingen.

sqlite3.PARSE_COLNAMES

Übergib diesen Flag-Wert an den Parameter detect_types von connect(), um eine Konverterfunktion über den Typnamen nachzuschlagen, der aus dem Spaltennamen der Abfrage gewonnen wird und als Schlüssel im Konverter-Dictionary dient. Der Spaltenname der Abfrage muss in doppelte Anführungszeichen (") und der Typname in eckige Klammern ([]) gesetzt werden.

SELECT MAX(p) as "p [point]" FROM test;  ! schlägt den Konverter "point" nach

Dieses Flag lässt sich über den Operator | (bitweises Oder) mit PARSE_DECLTYPES verbinden.

sqlite3.SQLITE_OK
sqlite3.SQLITE_DENY
sqlite3.SQLITE_IGNORE

Flags, die das an Connection.set_authorizer() übergebene aufrufbare authorizer_callback zurückgeben sollte, 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

Zeichenkettenkonstante, die die unterstützte DB-API-Stufe angibt. Von der DB-API verlangt. Fest auf "2.0" eingetragen.

sqlite3.paramstyle

Zeichenkettenkonstante, die angibt, welche Formatierung von Parametermarkierungen das Modul sqlite3 erwartet. Von der DB-API verlangt. Fest auf "qmark" eingetragen.

Bemerkung

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

sqlite3.sqlite_version

Versionsnummer der zur Laufzeit verwendeten SQLite-Bibliothek als Zeichenkette.

sqlite3.sqlite_version_info

Versionsnummer der zur Laufzeit verwendeten SQLite-Bibliothek als tuple von ganzen Zahlen.

sqlite3.SQLITE_KEYWORDS

Ein tuple mit allen SQLite-Schlüsselwörtern.

Diese Konstante ist nur verfügbar, wenn Python mit SQLite 3.24.0 oder neuer kompiliert wurde.

Added in version 3.15.

sqlite3.threadsafety

Ganzzahlige Konstante, die die DB-API 2.0 verlangt und die angibt, welchen Grad an Threadsicherheit das Modul sqlite3 unterstützt. Dieses Attribut wird anhand des voreingestellten Threading-Modus gesetzt, mit dem die zugrunde liegende SQLite-Bibliothek kompiliert wurde. Die Threading-Modi von SQLite sind:

  1. Single-thread: In diesem Modus sind alle Mutexe abgeschaltet, und SQLite kann nicht gefahrlos in mehr als einem Thread gleichzeitig verwendet werden.

  2. Multi-thread: In diesem Modus kann SQLite gefahrlos von mehreren Threads verwendet werden, sofern keine einzelne Datenbankverbindung gleichzeitig in zwei oder mehr Threads benutzt wird.

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

Die Threading-Modi von SQLite werden folgendermaßen auf die Threadsicherheitsstufen der DB-API 2.0 abgebildet:

Threading-Modus von SQLite

threadsafety

SQLITE_THREADSAFE

Bedeutung in der DB-API 2.0

single-thread

0

0

Threads dürfen sich das Modul nicht teilen

multi-thread

1

2

Threads dürfen sich das Modul teilen, aber keine Verbindungen

serialized

3

1

Threads dürfen sich Modul, Verbindungen und Cursor teilen

Geändert in Version 3.11: threadsafety wird jetzt dynamisch gesetzt, statt fest auf 1 eingetragen zu sein.

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.

Welche dieser Konstanten verfügbar sind, hängt von der SQLite-Version ab, mit der Python kompiliert wurde.

Added in version 3.12.

Siehe auch

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

SQLite-Dokumentation: Konfigurationsoptionen der Datenbankverbindung

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

Connection-Objekte

class sqlite3.Connection

Jede offene SQLite-Datenbank wird durch ein Connection-Objekt dargestellt, das über sqlite3.connect() erzeugt wird. Ihr Hauptzweck ist es, Cursor-Objekte zu erzeugen und die Transaktionssteuerung zu übernehmen.

Siehe auch

Geändert in Version 3.13: Es wird eine ResourceWarning 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)

Erzeugt ein Cursor-Objekt und gibt es zurück. Die Methode cursor nimmt einen einzigen wahlfreien Parameter factory an. Ist er angegeben, muss er ein aufrufbares Objekt sein, das eine Instanz von Cursor oder einer seiner Unterklassen zurückgibt.

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

Öffnet ein Blob-Handle auf ein vorhandenes BLOB.

Parameter:

  • table (str) – Der Name der Tabelle, in der der Blob liegt.

  • column (str) – Der Name der Spalte, in der der Blob liegt.

  • rowid (int) – Die Zeilen-ID, unter der der Blob liegt.

  • readonly (bool) – Auf True setzen, wenn der Blob ohne Schreibrechte geöffnet werden soll. Voreingestellt ist False.

  • name (str) – Der Name der Datenbank, in der der Blob liegt. Voreingestellt ist "main".

Verursacht:

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

Rückgabetyp:

Blob

Bemerkung

Die Größe des Blobs lässt sich über die Klasse Blob nicht ändern. Verwende die SQL-Funktion zeroblob, um einen Blob fester Größe zu erzeugen.

Added in version 3.11.

commit()

Committet jede anstehende Transaktion in die Datenbank. Ist autocommit True oder ist keine Transaktion offen, tut diese Methode nichts. Ist autocommit False, wird stillschweigend eine neue Transaktion geöffnet, sofern diese Methode eine anstehende Transaktion committet hat.

rollback()

Setzt auf den Anfang jeder anstehenden Transaktion zurück. Ist autocommit True oder ist keine Transaktion offen, tut diese Methode nichts. Ist autocommit False, wird stillschweigend eine neue Transaktion geöffnet, sofern diese Methode eine anstehende Transaktion zurückgesetzt hat.

close()

Schließt die Datenbankverbindung. Ist autocommit False, wird jede anstehende Transaktion stillschweigend zurückgesetzt. Ist autocommit True oder LEGACY_TRANSACTION_CONTROL, findet keine stillschweigende Transaktionssteuerung statt. Achte darauf, vor dem Schließen commit() aufzurufen, damit keine anstehenden Änderungen verloren gehen.

execute(sql, parameters=(), /)

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

executemany(sql, parameters, /)

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

executescript(sql_script, /)

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

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

Erzeugt oder entfernt eine selbst definierte SQL-Funktion.

Parameter:

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

  • narg (int) – Die Anzahl der Argumente, die die SQL-Funktion annehmen kann. Bei -1 darf sie beliebig viele Argumente annehmen.

  • func (callback | None) – Ein aufrufbares Objekt, das aufgerufen wird, wenn die SQL-Funktion aufgerufen wird. Das aufrufbare Objekt muss einen Typ zurückgeben, den SQLite von Haus aus unterstützt. Auf None setzen, um eine vorhandene SQL-Funktion zu entfernen.

  • deterministic (bool) – Ist es True, wird die erzeugte SQL-Funktion als deterministisch gekennzeichnet, was SQLite zusätzliche Optimierungen erlaubt.

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

Geändert in Version 3.15: Die ersten drei Parameter sind jetzt nur über die Position angebbar.

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()
create_aggregate(name, n_arg, aggregate_class, /)

Erzeugt oder entfernt eine selbst definierte SQL-Aggregatfunktion.

Parameter:

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

  • n_arg (int) – Die Anzahl der Argumente, die die SQL-Aggregatfunktion annehmen kann. Bei -1 darf sie beliebig viele Argumente annehmen.

  • aggregate_class (class | None) – Eine Klasse muss die folgenden Methoden umsetzen: * step(): fügt dem Aggregat eine Zeile hinzu. * finalize(): gibt das Endergebnis des Aggregats als Typ zurück, den SQLite von Haus aus unterstützt. Wie viele Argumente die Methode step() annehmen muss, steuert n_arg. Auf None setzen, um eine vorhandene SQL-Aggregatfunktion zu entfernen.

Geändert in Version 3.15: Alle drei Parameter sind jetzt nur über die Position angebbar.

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()
create_window_function(name, num_params, aggregate_class, /)

Erzeugt oder entfernt eine selbst definierte Aggregat-Fensterfunktion.

Parameter:

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

  • num_params (int) – Die Anzahl der Argumente, die die SQL-Aggregat-Fensterfunktion annehmen kann. Bei -1 darf sie beliebig viele Argumente annehmen.

  • aggregate_class (class | None) – Eine Klasse, die die folgenden Methoden umsetzen 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 als Typ zurück, den SQLite von Haus aus unterstützt. Wie viele Argumente die Methoden step() und value() annehmen müssen, steuert num_params. Auf None setzen, um eine vorhandene SQL-Aggregat-Fensterfunktion zu entfernen.

Verursacht:

NotSupportedError – Bei Verwendung mit einer SQLite-Version älter als 3.25.0, die Aggregat-Fensterfunktionen nicht unterstützt.

Added in version 3.11.

Beispiel:

# Beispiel entnommen aus 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, /)

Erzeugt eine Sortierfolge namens name über die Vergleichsfunktion callable. callable werden zwei Zeichenketten-Argumente übergeben, und es sollte eine ganze Zahl zurückgeben:

  • 1, wenn die erste höher einsortiert wird als die zweite

  • -1, wenn die erste niedriger einsortiert wird als die zweite

  • 0, wenn beide gleich einsortiert werden

Das folgende Beispiel zeigt eine Sortierfolge mit umgekehrter Reihenfolge:

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 Sortierfolge darf jedes Unicode-Zeichen enthalten. Früher waren nur ASCII-Zeichen erlaubt.

interrupt()

Rufe diese Methode aus einem anderen Thread auf, um alle Abfragen abzubrechen, die gerade auf der Verbindung laufen könnten. Abgebrochene Abfragen lösen einen OperationalError aus.

set_authorizer(authorizer_callback, /)

Registriert das aufrufbare authorizer_callback, damit es bei jedem Versuch aufgerufen wird, auf eine Spalte einer Tabelle in der Datenbank zuzugreifen. Das Callback sollte SQLITE_OK, SQLITE_DENY oder SQLITE_IGNORE zurückgeben, um anzuzeigen, wie die zugrunde liegende SQLite-Bibliothek den Zugriff auf die Spalte behandeln soll.

Das erste Argument des Callbacks gibt an, welche Art von Vorgang zu autorisieren ist. Das zweite und dritte Argument sind je nach erstem Argument Argumente oder None. Das vierte Argument ist der Name der Datenbank („main“, „temp“ und so weiter), sofern zutreffend. Das fünfte Argument ist der Name des innersten Triggers oder der innersten View, der oder die für den Zugriffsversuch verantwortlich ist, oder None, wenn dieser Zugriffsversuch unmittelbar aus eingegebenem SQL-Code stammt.

Welche Werte für das erste Argument möglich sind und was das zweite und dritte Argument je nach erstem bedeuten, steht in der SQLite-Dokumentation. Alle nötigen Konstanten sind im Modul sqlite3 verfügbar.

None als authorizer_callback zu übergeben schaltet den Authorizer ab.

Geändert in Version 3.11: Unterstützung dafür hinzugefügt, den Authorizer über None abzuschalten.

Geändert in Version 3.15: Der einzige Parameter ist jetzt nur über die Position angebbar.

set_progress_handler(progress_handler, /, n)

Registriert das aufrufbare progress_handler, damit es alle n Anweisungen der virtuellen Maschine von SQLite aufgerufen wird. Das ist nützlich, wenn du während lange laufender Vorgänge von SQLite aufgerufen werden willst, etwa um eine Oberfläche zu aktualisieren.

Willst du einen zuvor eingerichteten Fortschritts-Handler löschen, rufe die Methode mit None für progress_handler auf.

Gibt die Handler-Funktion einen Wert ungleich null zurück, wird die gerade laufende Abfrage beendet und löst eine DatabaseError-Ausnahme aus.

Geändert in Version 3.15: Der erste Parameter ist jetzt nur über die Position angebbar.

set_trace_callback(trace_callback, /)

Registriert das aufrufbare trace_callback, damit es für jede SQL-Anweisung aufgerufen wird, die das SQLite-Backend tatsächlich ausführt.

Das einzige Argument, das dem Callback übergeben wird, ist die Anweisung (als str), die gerade ausgeführt wird. Der Rückgabewert des Callbacks wird nicht beachtet. Beachte, dass das Backend nicht nur Anweisungen ausführt, die den Methoden Cursor.execute() übergeben wurden. Weitere Quellen sind die Transaktionsverwaltung des Moduls sqlite3 und die Ausführung von Triggern, die in der aktuellen Datenbank definiert sind.

None als trace_callback zu übergeben schaltet das Trace-Callback ab.

Bemerkung

Ausnahmen, die im Trace-Callback ausgelöst werden, werden nicht weitergegeben. Als Hilfe bei Entwicklung und Fehlersuche kannst du mit enable_callback_tracebacks() einschalten, dass Tracebacks von Ausnahmen aus dem Trace-Callback ausgegeben werden.

Added in version 3.3.

Geändert in Version 3.15: Der erste Parameter ist jetzt nur über die Position angebbar.

enable_load_extension(enabled, /)

Erlaubt der SQLite-Engine, SQLite-Erweiterungen aus gemeinsam genutzten Bibliotheken zu laden, wenn enabled True ist, sonst wird das Laden von SQLite-Erweiterungen untersagt. SQLite-Erweiterungen können neue Funktionen, Aggregate oder ganz neue Umsetzungen virtueller Tabellen festlegen. Eine bekannte Erweiterung ist die mit SQLite ausgelieferte Volltextsuche.

Bemerkung

Das Modul sqlite3 wird voreingestellt ohne Unterstützung für ladbare Erweiterungen gebaut, weil manche Plattformen (besonders macOS) SQLite-Bibliotheken mitbringen, die ohne diese Eigenschaft kompiliert sind. Um Unterstützung für ladbare Erweiterungen zu bekommen, musst du configure die Option --enable-loadable-sqlite-extensions übergeben.

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

Added in version 3.2.

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

con.enable_load_extension(True)

# Die Volltextsuche-Erweiterung laden
con.execute("select load_extension('./fts3.so')")

# alternativ kannst du die Erweiterung über einen API-Aufruf laden:
# con.load_extension("./fts3.so")

# das Laden von Erweiterungen wieder abschalten
con.enable_load_extension(False)

# Beispiel aus dem 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. Schalte das Laden von Erweiterungen mit enable_load_extension() ein, bevor du diese Methode aufrufst.

Parameter:

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

  • entrypoint (str | None) – Name des Einsprungpunkts. Ist er None (die Voreinstellung), denkt sich SQLite selbst einen Namen für den Einsprungpunkt aus; Einzelheiten stehen in der SQLite-Dokumentation unter Loading an Extension.

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

Added in version 3.2.

Geändert in Version 3.10: Das Auditing-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, der die Datenbank als SQL-Quelltext ausgibt. Nützlich, um eine Datenbank aus dem Arbeitsspeicher für eine spätere Wiederherstellung zu sichern. Ähnlich dem Befehl .dump in der sqlite3-Shell.

Parameter:

filter (str | None) – Ein wahlfreies LIKE-Muster für die auszugebenden Datenbankobjekte, etwa prefix_%. Ist es None (die Voreinstellung), werden alle Datenbankobjekte einbezogen.

Beispiel:

# Die Datei example.db in die SQL-Ausgabedatei dump.sql umwandeln
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

Mit Textkodierungen umgehen, die nicht UTF-8 sind

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

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

Erzeugt eine Sicherung einer SQLite-Datenbank.

Funktioniert auch dann, wenn andere Clients oder gleichzeitig dieselbe Verbindung auf die Datenbank zugreifen.

Parameter:

  • target (Connection) – Die Datenbankverbindung, in die die Sicherung geschrieben wird.

  • pages (int) – Die Anzahl der Seiten, die auf einmal kopiert werden. Ist sie gleich 0 oder kleiner, wird die gesamte Datenbank in einem Schritt kopiert. Voreingestellt ist -1.

  • progress (callback | None) – Ist es auf ein aufrufbares Objekt gesetzt, wird dieses bei jedem Sicherungsdurchlauf mit drei ganzzahligen Argumenten aufgerufen: dem status des letzten Durchlaufs, der Anzahl der noch zu kopierenden Seiten (remaining) und der Gesamtzahl der Seiten (total). Voreingestellt ist None.

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

  • sleep (float) – Die Anzahl der Sekunden, die zwischen aufeinanderfolgenden Versuchen geschlafen wird, die restlichen Seiten zu sichern.

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 flüchtige Kopie kopieren:

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

Added in version 3.7.

Siehe auch

Mit Textkodierungen umgehen, die nicht UTF-8 sind

getlimit(category, /)

Liest eine Laufzeitgrenze der Verbindung aus.

Parameter:

category (int) – Die abzufragende SQLite limit category.

Rückgabetyp:

int

Verursacht:

ProgrammingError – Wenn die zugrunde liegende SQLite-Bibliothek category nicht kennt.

Beispiel – die größte Länge einer SQL-Anweisung für die Connection con abfragen (voreingestellt ist 1000000000):

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

Added in version 3.11.

setlimit(category, limit, /)

Setzt eine Laufzeitgrenze der Verbindung. Versuche, eine Grenze über ihre harte Obergrenze hinaus anzuheben, werden stillschweigend auf die harte Obergrenze gekappt. Unabhängig davon, ob die Grenze geändert wurde, wird der vorherige Wert der Grenze zurückgegeben.

Parameter:

  • category (int) – Die zu setzende SQLite limit category.

  • limit (int) – Der Wert der neuen Grenze. Ist er negativ, bleibt die aktuelle Grenze unverändert.

Rückgabetyp:

int

Verursacht:

ProgrammingError – Wenn die zugrunde liegende SQLite-Bibliothek category nicht kennt.

Beispiel – die Anzahl angehängter Datenbanken für die Connection con auf 1 begrenzen (voreingestellt ist die Grenze 10):

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

Added in version 3.11.

getconfig(op, /)

Fragt eine boolesche Konfigurationsoption der Verbindung ab.

Parameter:

op (int) – Ein SQLITE_DBCONFIG-Code.

Rückgabetyp:

bool

Added 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 eingeschaltet werden soll (die Voreinstellung), False, wenn sie abgeschaltet werden soll.

Added in version 3.12.

serialize(*, name='main')

Serialisiert eine Datenbank in ein bytes-Objekt. Bei einer gewöhnlichen Datenbankdatei auf der Festplatte ist die Serialisierung einfach eine Kopie dieser Datei. Bei einer Datenbank im Arbeitsspeicher oder einer „temp“-Datenbank ist die Serialisierung dieselbe Bytefolge, die auf die Festplatte geschrieben würde, wenn diese Datenbank dorthin gesichert würde.

Parameter:

name (str) – Der Name der zu serialisierenden Datenbank. Voreingestellt ist "main".

Rückgabetyp:

bytes

Bemerkung

Diese Methode ist nur verfügbar, wenn die zugrunde liegende SQLite-Bibliothek die serialize-API hat.

Added in version 3.11.

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

Deserialisiert eine serialisierte Datenbank in eine Connection. Diese Methode trennt die Datenbankverbindung von der Datenbank name und öffnet name erneut als Datenbank im Arbeitsspeicher, aufbauend auf der Serialisierung in data.

Parameter:

  • data (bytes) – Eine serialisierte Datenbank.

  • name (str) – Der Name der Datenbank, in die deserialisiert wird. Voreingestellt ist "main".

Verursacht:

  • OperationalError – Wenn die Datenbankverbindung gerade an einer Lesetransaktion oder einem Sicherungsvorgang beteiligt ist.

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

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

Bemerkung

Diese Methode ist nur verfügbar, wenn die zugrunde liegende SQLite-Bibliothek die deserialize-API hat.

Added in version 3.11.

autocommit

Dieses Attribut steuert das Transaktionsverhalten nach PEP 249. autocommit hat drei zulässige Werte:

  • False: wählt das Transaktionsverhalten nach PEP 249, was bedeutet, dass sqlite3 dafür sorgt, dass immer eine Transaktion offen ist. Verwende commit() und rollback(), um Transaktionen zu schließen.

    Das ist der empfohlene Wert für autocommit.

  • True: verwendet den autocommit mode von SQLite. commit() und rollback() haben in diesem Modus keine Wirkung.

  • LEGACY_TRANSACTION_CONTROL: Transaktionssteuerung von vor Python 3.12 (nicht nach PEP 249). Weitere Einzelheiten stehen unter isolation_level.

    Das ist derzeit der voreingestellte Wert von autocommit.

autocommit auf False zu ändern öffnet eine neue Transaktion, es auf True zu ändern committet jede anstehende Transaktion.

Weitere Einzelheiten stehen unter Transaktionssteuerung über das Attribut autocommit.

Bemerkung

Das Attribut isolation_level hat keine Wirkung, solange autocommit nicht LEGACY_TRANSACTION_CONTROL ist.

Added in version 3.12.

in_transaction

Dieses nur lesbare Attribut entspricht dem autocommit mode von SQLite auf unterer Ebene.

True, wenn eine Transaktion aktiv ist (es gibt Änderungen ohne Commit), sonst False.

Added in version 3.2.

isolation_level

Steuert den überkommenen Modus der Transaktionsbehandlung von sqlite3. Ist es auf None gesetzt, werden Transaktionen nie stillschweigend geöffnet. Ist es auf "DEFERRED", "IMMEDIATE" oder "EXCLUSIVE" gesetzt, entsprechend dem zugrunde liegenden SQLite transaction behaviour, findet stillschweigende Transaktionsverwaltung statt.

Wird es nicht vom Parameter isolation_level von connect() übergangen, ist "" voreingestellt, ein Alias für "DEFERRED".

Bemerkung

Es wird empfohlen, die Transaktionsbehandlung über autocommit statt über isolation_level zu steuern. isolation_level hat keine Wirkung, solange autocommit nicht auf LEGACY_TRANSACTION_CONTROL (die Voreinstellung) gesetzt ist.

row_factory

Die anfängliche row_factory für Cursor-Objekte, die aus dieser Verbindung erzeugt werden. Diesem Attribut etwas zuzuweisen wirkt sich nicht auf die row_factory vorhandener Cursor dieser Verbindung aus, sondern nur auf neue. Voreingestellt ist None, was bedeutet, dass jede Zeile als tuple zurückgegeben wird.

Weitere Einzelheiten stehen unter Row-Factorys erzeugen und verwenden.

Geändert in Version 3.15: Das Attribut row_factory zu löschen ist nicht mehr erlaubt.

text_factory

Ein aufrufbares Objekt, das einen bytes-Parameter annimmt und eine Textdarstellung davon zurückgibt. Es wird für SQLite-Werte mit dem Datentyp TEXT aufgerufen. Voreingestellt ist dieses Attribut auf str gesetzt.

Weitere Einzelheiten stehen unter Mit Textkodierungen umgehen, die nicht UTF-8 sind.

Geändert in Version 3.15: Das Attribut text_factory zu löschen ist nicht mehr erlaubt.

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 stellt einen database cursor dar, über den SQL-Anweisungen ausgeführt und der Zusammenhang eines Abrufvorgangs verwaltet wird. Cursor werden über Connection.cursor() erzeugt oder über eine der Abkürzungsmethoden der Verbindung.

Cursor-Objekte sind Iteratoren. Führst du also mit execute() eine SELECT-Abfrage aus, kannst du einfach über den Cursor iterieren, um die sich ergebenden Zeilen zu holen:

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 dabei wahlweise Python-Werte über Platzhalter.

Parameter:
Verursacht:

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

Ist autocommit LEGACY_TRANSACTION_CONTROL, ist isolation_level nicht None, ist sql eine INSERT-, UPDATE-, DELETE- oder REPLACE-Anweisung und ist keine Transaktion offen, wird vor dem Ausführen von sql stillschweigend eine Transaktion geöffnet.

Geändert in Version 3.14: Ein ProgrammingError wird ausgegeben, wenn benannte Platzhalter verwendet werden und parameters eine Sequenz statt eines dict ist.

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

executemany(sql, parameters, /)

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

Verwendet dieselbe stillschweigende Transaktionsbehandlung wie execute().

Parameter:
Verursacht:

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 statt dicts sind.

Beispiel:

rows = [
    ("row1",),
    ("row2",),
]
# cur ist ein sqlite3.Cursor-Objekt
cur.executemany("INSERT INTO data VALUES(?)", rows)

Bemerkung

Sich ergebende Zeilen werden verworfen, auch bei DML-Anweisungen mit RETURNING clauses.

Geändert in Version 3.14: Ein ProgrammingError wird ausgegeben, wenn benannte Platzhalter verwendet werden und die Elemente in parameters Sequenzen statt dicts sind.

executescript(sql_script, /)

Führt die SQL-Anweisungen in sql_script aus. Ist autocommit LEGACY_TRANSACTION_CONTROL und steht eine Transaktion an, wird zuerst stillschweigend eine COMMIT-Anweisung ausgeführt. Weitere stillschweigende Transaktionssteuerung findet nicht statt. Jede Transaktionssteuerung muss sql_script selbst enthalten.

sql_script muss eine Zeichenkette sein.

Beispiel:

# cur ist ein sqlite3.Cursor-Objekt
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")
fetchone()

Ist row_factory None, wird die nächste Zeile der Ergebnismenge der Abfrage als tuple zurückgegeben. Sonst wird sie an die Row-Factory übergeben und deren Ergebnis zurückgegeben. Gibt None zurück, wenn keine Daten mehr 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 Zeilen mehr verfügbar sind.

Wie viele Zeilen je Aufruf geholt werden, gibt der Parameter size an. Ist size nicht angegeben, bestimmt arraysize die Anzahl der zu holenden Zeilen. Sind weniger als size Zeilen verfügbar, werden so viele Zeilen zurückgegeben, wie verfügbar sind.

Beachte, dass beim Parameter size Überlegungen zur Leistung hineinspielen. Für die beste Leistung ist es meist am besten, das Attribut arraysize zu verwenden. Wird der Parameter size verwendet, behält er am besten von einem Aufruf von fetchmany() zum nächsten denselben Wert.

Geändert in Version 3.15: Negative Werte für size werden mit einem ValueError abgelehnt.

fetchall()

Gibt alle (restlichen) Zeilen eines Abfrageergebnisses als list zurück. Gibt eine leere Liste zurück, wenn keine Zeilen verfügbar sind. Beachte, dass das Attribut arraysize die Leistung dieses Vorgangs beeinflussen kann.

close()

Schließt den Cursor sofort (statt erst dann, wenn __del__ aufgerufen wird).

Der Cursor ist von diesem Punkt an unbrauchbar. Wird mit ihm ein Vorgang versucht, wird eine ProgrammingError-Ausnahme ausgelöst.

setinputsizes(sizes, /)

Von der DB-API verlangt. Tut in sqlite3 nichts.

setoutputsize(size, column=None, /)

Von der DB-API verlangt. Tut in sqlite3 nichts.

arraysize

Les- und schreibbares Attribut, das steuert, wie viele Zeilen fetchmany() zurückgibt. Voreingestellt ist 1, was bedeutet, dass je Aufruf eine einzelne Zeile geholt wird.

Geändert in Version 3.15: Negative Werte werden mit einem ValueError abgelehnt.

connection

Nur lesbares Attribut, das die SQLite-Datenbank-Connection liefert, zu der der Cursor gehört. Ein Cursor-Objekt, das durch einen Aufruf von con.cursor() erzeugt wurde, hat ein Attribut connection, das auf con verweist:

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

Nur lesbares Attribut, das die Spaltennamen der letzten Abfrage liefert. Um mit der Python-DB-API verträglich zu bleiben, gibt es für jede Spalte ein 7-Tupel zurück, in dem die letzten sechs Elemente jeweils None sind.

Es wird auch bei SELECT-Anweisungen gesetzt, auf die keine Zeile passt.

lastrowid

Nur lesbares Attribut, das die Zeilen-ID der zuletzt eingefügten Zeile liefert. Es wird nur nach erfolgreichen INSERT- oder REPLACE-Anweisungen über die Methode execute() aktualisiert. Bei anderen Anweisungen, nach executemany() oder executescript() oder wenn das Einfügen fehlschlug, bleibt der Wert von lastrowid unverändert. Der Anfangswert von lastrowid ist None.

Bemerkung

Einfügungen in WITHOUT ROWID-Tabellen werden nicht aufgezeichnet.

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

rowcount

Nur lesbares Attribut, das die Anzahl der geänderten Zeilen für INSERT-, UPDATE-, DELETE- und REPLACE-Anweisungen liefert. Bei anderen Anweisungen ist es -1, auch bei CTE-Abfragen. Es wird nur von den Methoden execute() und executemany() aktualisiert, und zwar erst, nachdem die Anweisung vollständig gelaufen ist. Das bedeutet, dass sich ergebende Zeilen geholt werden müssen, damit rowcount aktualisiert wird.

row_factory

Steuert, wie eine aus diesem Cursor geholte Zeile dargestellt wird. Bei None wird eine Zeile als tuple dargestellt. Lässt sich auf die mitgelieferte sqlite3.Row setzen oder auf ein aufrufbares Objekt, das zwei Argumente annimmt – ein Cursor-Objekt und das tuple der Zeilenwerte – und ein eigenes Objekt zurückgibt, das eine SQLite-Zeile darstellt.

Voreingestellt ist das, worauf Connection.row_factory beim Erzeugen des Cursor gesetzt war. Diesem Attribut etwas zuzuweisen wirkt sich nicht auf Connection.row_factory der übergeordneten Verbindung aus.

Weitere Einzelheiten stehen unter Row-Factorys erzeugen und verwenden.

Geändert in Version 3.15: Das Attribut row_factory zu löschen ist nicht mehr erlaubt.

Row-Objekte

class sqlite3.Row

Eine Row-Instanz dient als hoch optimierte row_factory für Connection-Objekte. Sie unterstützt Iteration, Gleichheitsprüfung, len() und den Zugriff als Mapping über Spaltennamen und Index.

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

Weitere Einzelheiten stehen unter Row-Factorys erzeugen und verwenden.

keys()

Gibt eine list der Spaltennamen als Zeichenketten zurück. Unmittelbar nach einer Abfrage ist das jeweils 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

Added in version 3.11.

Eine Blob-Instanz ist ein dateiartiges Objekt, das Daten in einem SQLite-BLOB lesen und schreiben kann. Rufe len(blob) auf, um die Größe (Anzahl der Bytes) des Blobs zu bekommen. Verwende Indizes und Slices für den unmittelbaren Zugriff auf die Blob-Daten.

Verwende den Blob als Kontextmanager, damit das Blob-Handle nach der Verwendung sicher geschlossen wird.

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

# In unseren Blob schreiben, mit zwei Schreibvorgängen:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # Das erste und das letzte Byte unseres Blobs ändern
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Den Inhalt unseres Blobs lesen
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

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

Schließt den Blob.

Der Blob ist von diesem Punkt an unbrauchbar. Wird mit ihm ein weiterer Vorgang versucht, wird eine Error-Ausnahme (oder eine Unterklasse davon) ausgelöst.

read(length=-1, /)

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

write(data, /)

Schreibt data an den aktuellen Versatz in den Blob. Diese Funktion kann die Länge des Blobs nicht ändern. Über das Ende des Blobs hinaus zu schreiben 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 ist auf os.SEEK_SET voreingestellt (absolute Positionierung im Blob). Weitere 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 einzige Zweck des Typs PrepareProtocol ist es, als Anpassungsprotokoll im Stil von PEP 246 für Objekte zu dienen, die sich selbst anpassen können, und zwar an native SQLite-Typen.

Ausnahmen

Die Ausnahmehierarchie legt die DB-API 2.0 (PEP 249) fest.

exception sqlite3.Warning

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

exception sqlite3.Error

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

Stammt die Ausnahme aus der SQLite-Bibliothek, werden der Ausnahme die folgenden zwei Attribute hinzugefügt:

sqlite_errorcode

Der numerische Fehlercode aus der SQLite-API

Added in version 3.11.

sqlite_errorname

Der symbolische Name des numerischen Fehlercodes aus der SQLite-API

Added in version 3.11.

exception sqlite3.InterfaceError

Ausnahme, die bei falscher Verwendung der SQLite-C-API auf unterer Ebene ausgelöst wird. Mit anderen Worten: Wird diese Ausnahme ausgelöst, deutet das wahrscheinlich auf einen Fehler im Modul sqlite3 hin. InterfaceError ist eine Unterklasse von Error.

exception sqlite3.DatabaseError

Ausnahme, die bei Fehlern rund um die Datenbank ausgelöst wird. Sie dient als Basisausnahme für mehrere Arten von Datenbankfehlern. Sie wird nur stillschweigend über die spezialisierten Unterklassen ausgelöst. DatabaseError ist eine Unterklasse von Error.

exception sqlite3.DataError

Ausnahme, die bei Fehlern durch Probleme mit den verarbeiteten Daten ausgelöst wird, etwa bei Zahlenwerten außerhalb des Bereichs oder bei zu langen Zeichenketten. DataError ist eine Unterklasse von DatabaseError.

exception sqlite3.OperationalError

Ausnahme, die bei Fehlern rund um den Betrieb der Datenbank ausgelöst wird, die nicht unbedingt vom Programmierer beeinflussbar sind. Zum Beispiel, wenn der Datenbankpfad nicht gefunden wird oder eine Transaktion nicht verarbeitet werden konnte. OperationalError ist eine Unterklasse von DatabaseError.

exception sqlite3.IntegrityError

Ausnahme, die ausgelöst wird, wenn die relationale Integrität der Datenbank betroffen ist, etwa wenn 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. Wird sie ausgelöst, kann das auf ein Problem mit der zur Laufzeit verwendeten SQLite-Bibliothek hindeuten. InternalError ist eine Unterklasse von DatabaseError.

exception sqlite3.ProgrammingError

Ausnahme, die bei Programmierfehlern in der API von sqlite3 ausgelöst wird, etwa wenn einer Abfrage die falsche Anzahl von Bindungen übergeben wird oder auf einer geschlossenen Connection gearbeitet werden soll. ProgrammingError ist eine Unterklasse von DatabaseError.

exception sqlite3.NotSupportedError

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

SQLite- und Python-Typen

SQLite unterstützt von Haus aus die folgenden Typen: NULL, INTEGER, REAL, TEXT, BLOB.

Die folgenden Python-Typen lassen sich daher problemlos an SQLite schicken:

Python-Typ

SQLite-Typ

None

NULL

int

INTEGER

float

REAL

str

TEXT

bytes

BLOB

So werden SQLite-Typen voreingestellt in Python-Typen umgewandelt:

SQLite-Typ

Python-Typ

NULL

None

INTEGER

int

REAL

float

TEXT

hängt von text_factory ab, voreingestellt str

BLOB

bytes

Das Typsystem des Moduls sqlite3 lässt sich auf zwei Wegen erweitern: Über Objektadapter kannst du weitere Python-Typen in einer SQLite-Datenbank speichern, und über Konverter kannst du das Modul sqlite3 SQLite-Typen in Python-Typen umwandeln lassen.

Voreingestellte Adapter und Konverter (veraltet)

Bemerkung

Die voreingestellten Adapter und Konverter sind seit Python 3.12 veraltet. Verwende stattdessen die Rezepte für Adapter und Konverter und passe sie an deine Bedürfnisse an.

Die veralteten voreingestellten Adapter und Konverter bestehen aus:

Bemerkung

Der voreingestellte „timestamp“-Konverter beachtet UTC-Offsets in der Datenbank nicht und gibt immer ein naives datetime.datetime-Objekt zurück. Um UTC-Offsets in Zeitstempeln zu erhalten, lass die Konverter entweder abgeschaltet oder registriere mit register_converter() einen Konverter, der Offsets berücksichtigt.

Veraltet ab Version 3.12.

Befehlszeilenschnittstelle

Das Modul sqlite3 lässt sich über den Schalter -m des Interpreters als Skript aufrufen, um eine einfache SQLite-Shell bereitzustellen. Die Argumentsignatur lautet:

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

Gib .quit oder Strg-D ein, um die Shell zu verlassen.

-h, --help

Gibt die Hilfe zur Befehlszeilenschnittstelle aus.

-v, --version

Gibt die Version der zugrunde liegenden SQLite-Bibliothek aus.

Added in version 3.12.

Anleitungen

Platzhalter verwenden, um Werte in SQL-Abfragen zu binden

SQL-Vorgänge müssen meist Werte aus Python-Variablen verwenden. Hüte dich aber davor, Abfragen mit Pythons Zeichenkettenoperationen zusammenzubauen, denn sie sind anfällig für SQL injection attacks. Ein Angreifer kann zum Beispiel einfach das einfache Anführungszeichen schließen und OR TRUE einschleusen, um alle Zeilen auszuwählen:

>>> # Mach das nie -- unsicher!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
>>> cur.execute(sql)

Verwende stattdessen die Parameterersetzung der DB-API. Um eine Variable in eine Abfragezeichenkette einzufügen, setze einen Platzhalter in die Zeichenkette und ersetze die tatsächlichen Werte in der Abfrage, indem du sie als tuple von Werten dem zweiten Argument der Methode execute() des Cursors übergibst.

Eine SQL-Anweisung darf eine von zwei Arten von Platzhaltern verwenden: Fragezeichen (qmark-Stil) oder benannte Platzhalter (named-Stil). Beim qmark-Stil muss parameters eine Sequenz sein, deren Länge zur Anzahl der Platzhalter passen muss, sonst wird ein ProgrammingError ausgelöst. Beim named-Stil muss parameters eine Instanz eines dict (oder einer Unterklasse) sein, die Schlüssel für alle benannten Parameter enthalten muss. Überzählige Elemente werden übergangen. Hier ein Beispiel für beide Stile:

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

# Das ist der named-Stil, hier mit 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)

# Das ist der qmark-Stil, hier in einer SELECT-Abfrage:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()

Bemerkung

Numerische Platzhalter nach PEP 249 werden nicht unterstützt. Werden sie verwendet, werden sie als benannte Platzhalter ausgelegt.

Eigene Python-Typen an SQLite-Werte anpassen

SQLite unterstützt von Haus aus nur eine begrenzte Menge von Datentypen. Um eigene Python-Typen in SQLite-Datenbanken zu speichern, passe sie an einen der Python-Typen an, die SQLite von Haus aus versteht.

Es gibt zwei Wege, Python-Objekte an SQLite-Typen anzupassen: dein Objekt sich selbst anpassen zu lassen oder ein aufrufbares Adapterobjekt zu verwenden. Letzteres hat Vorrang vor Ersterem. Für eine Bibliothek, die einen eigenen Typ nach außen gibt, kann es sinnvoll sein, diesen Typ sich selbst anpassen zu lassen. Als Anwendungsentwickler ist es vielleicht sinnvoller, die unmittelbare Kontrolle zu behalten und eigene Adapterfunktionen zu registrieren.

Anpassbare Objekte schreiben

Nehmen wir an, wir haben eine Klasse Point, die ein Paar von Koordinaten x und y in einem kartesischen Koordinatensystem darstellt. Das Koordinatenpaar wird als Textzeichenkette in der Datenbank gespeichert, wobei ein Semikolon die Koordinaten trennt. Das lässt sich umsetzen, indem eine Methode __conform__(self, protocol) hinzugefügt wird, die den angepassten Wert zurückgibt. Das an protocol übergebene Objekt ist vom 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()

Aufrufbare Adapterobjekte registrieren

Die andere Möglichkeit ist, eine Funktion zu schreiben, die das Python-Objekt in einen SQLite-verträglichen Typ umwandelt. Diese Funktion lässt sich dann über register_adapter() registrieren.

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

SQLite-Werte in eigene Python-Typen umwandeln

Mit einem Adapter wandelst du von eigenen Python-Typen zu SQLite-Werten um. Um von SQLite-Werten zu eigenen Python-Typen umwandeln zu können, verwenden wir Konverter.

Kommen wir auf die Klasse Point zurück. Wir haben die x- und y-Koordinaten durch Semikolons getrennt als Zeichenketten in SQLite gespeichert.

Zuerst schreiben wir eine Konverterfunktion, die die Zeichenkette als Parameter annimmt und daraus ein Point-Objekt baut.

Bemerkung

Konverterfunktionen wird immer ein bytes-Objekt übergeben, unabhängig vom zugrunde liegenden SQLite-Datentyp.

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

Jetzt müssen wir sqlite3 mitteilen, wann es einen bestimmten SQLite-Wert umwandeln soll. Das geschieht beim Verbinden mit einer Datenbank über den Parameter detect_types von connect(). Es gibt drei Möglichkeiten:

  • Stillschweigend: detect_types auf PARSE_DECLTYPES setzen

  • Ausdrücklich: detect_types auf PARSE_COLNAMES setzen

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

Das folgende Beispiel zeigt den stillschweigenden und den ausdrücklichen Weg:

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)

# Den Adapter und den Konverter registrieren
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Über deklarierte Typen zerlegen
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) Über Spaltennamen zerlegen
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 häufige Adapter und Konverter.

import datetime as dt
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(dt.date, adapt_date_iso)
sqlite3.register_adapter(dt.datetime, adapt_datetime_iso)
sqlite3.register_adapter(dt.datetime, adapt_datetime_epoch)

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

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

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

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

Die Abkürzungsmethoden der Verbindung verwenden

Mit den Methoden execute(), executemany() und executescript() der Klasse Connection lässt sich dein Code knapper schreiben, weil du die (oft überflüssigen) Cursor-Objekte nicht ausdrücklich erzeugen musst. Stattdessen werden die Cursor-Objekte stillschweigend erzeugt, und diese Abkürzungsmethoden geben die Cursor-Objekte zurück. So kannst du eine SELECT-Anweisung ausführen und unmittelbar darüber iterieren, mit nur einem einzigen Aufruf auf dem Connection-Objekt.

# Die Tabelle anlegen und füllen.
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)

# Den Tabelleninhalt ausgeben
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() ist keine Abkürzungsmethode und wird nicht automatisch aufgerufen.
# Das Verbindungsobjekt sollte von Hand geschlossen werden
con.close()

Den Kontextmanager der Verbindung verwenden

Ein Connection-Objekt lässt sich als Kontextmanager verwenden, der offene Transaktionen beim Verlassen des Rumpfs automatisch committet oder zurücksetzt. Endet der Rumpf der with-Anweisung ohne Ausnahmen, wird die Transaktion committet. Schlägt dieser Commit fehl oder löst der Rumpf der with-Anweisung eine nicht abgefangene Ausnahme aus, wird die Transaktion zurückgesetzt. Ist autocommit False, wird nach dem Committen oder Zurücksetzen stillschweigend eine neue Transaktion geöffnet.

Ist beim Verlassen des Rumpfs der with-Anweisung keine Transaktion offen oder ist autocommit True, tut der Kontextmanager nichts.

Bemerkung

Der Kontextmanager öffnet weder stillschweigend eine neue Transaktion noch schließt er die Verbindung. Brauchst du einen Kontextmanager, der schließt, sieh dir contextlib.closing() an.

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

# Erfolgreich, con.commit() wird danach automatisch aufgerufen
with con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() wird aufgerufen, nachdem der with-Block mit einer Ausnahme endet.
# Die Ausnahme wird weiterhin ausgelöst und muss abgefangen werden
try:
    with con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Als Kontextmanager verwendet committet oder verwirft das Verbindungsobjekt nur Transaktionen,
# das Verbindungsobjekt sollte deshalb von Hand geschlossen werden
con.close()

Mit SQLite-URIs arbeiten

Zu den nützlichen URI-Kniffen gehören:

  • Eine Datenbank nur zum Lesen öffnen:

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

  • Keine neue Datenbankdatei stillschweigend anlegen, wenn es sie noch nicht gibt. Löst einen OperationalError aus, wenn sich keine neue Datei anlegen lässt:

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

  • Eine gemeinsam genutzte, benannte Datenbank im Arbeitsspeicher anlegen:

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 Eigenschaft, darunter eine Liste der Parameter, stehen in der SQLite URI documentation.

Row-Factorys erzeugen und verwenden

Voreingestellt stellt sqlite3 jede Zeile als tuple dar. Passt ein tuple nicht zu deinen Bedürfnissen, kannst du die Klasse sqlite3.Row oder eine eigene row_factory verwenden.

row_factory gibt es zwar als Attribut sowohl auf dem Cursor als auch auf der Connection, es wird aber empfohlen, Connection.row_factory zu setzen, damit alle aus der Verbindung erzeugten Cursor dieselbe Row-Factory verwenden.

Row bietet den Zugriff auf Spalten über den Index und über den Namen ohne Rücksicht auf Groß- und Kleinschreibung, bei geringstem Mehraufwand an Speicher und Leistung gegenüber einem tuple. Um Row als Row-Factory zu verwenden, weise 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]         # Zugriff über den Index.
'Earth'
>>> row["name"]    # Zugriff über den Namen.
'Earth'
>>> row["RADIUS"]  # Spaltennamen beachten Groß- und Kleinschreibung nicht.
6378
>>> con.close()

Bemerkung

Die FROM-Klausel darf in der SELECT-Anweisung entfallen, wie im obigen Beispiel. In solchen Fällen gibt SQLite eine einzelne Zeile zurück, deren Spalten durch Ausdrücke festgelegt sind, etwa durch Literale, mit den angegebenen Aliasen expr AS alias.

Du kannst eine eigene row_factory schreiben, die jede Zeile als dict zurückgibt, mit Spaltennamen als Schlüsseln und den Werten als Werten:

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 jetzt ein dict statt 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 Row-Factory 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() lässt sich so verwenden:

>>> 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]  # Zugriff über den Index.
1
>>> row.b   # Zugriff über das Attribut.
2
>>> con.close()

Mit einigen Anpassungen lässt sich das obige Rezept so abwandeln, dass es eine dataclass oder jede andere eigene Klasse statt eines namedtuple verwendet.

Mit Textkodierungen umgehen, die nicht UTF-8 sind

Voreingestellt verwendet sqlite3 str, um SQLite-Werte mit dem Datentyp TEXT anzupassen. Bei UTF-8-kodiertem Text klappt das gut, bei anderen Kodierungen und ungültigem UTF-8 kann es aber fehlschlagen. Für solche Fälle kannst du eine eigene text_factory verwenden.

Wegen der flexible typing-Eigenschaft von SQLite ist es nicht ungewöhnlich, in Tabellenspalten mit dem Datentyp TEXT auf Kodierungen zu stoßen, die nicht UTF-8 sind, oder sogar auf beliebige Daten. Nehmen wir zur Veranschaulichung an, wir haben eine Datenbank mit ISO-8859-2-kodiertem Text (Latin-2), etwa eine Tabelle mit Einträgen eines tschechisch-englischen Wörterbuchs. Angenommen, wir haben nun eine Connection-Instanz con, die mit dieser Datenbank verbunden ist, dann können wir den Latin-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, kannst du die folgende Technik verwenden, die aus Unicode-HOWTO entlehnt ist:

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

Bemerkung

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

Siehe auch

Unicode-HOWTO

Erklärung

Transaktionssteuerung

sqlite3 bietet mehrere Wege zu steuern, ob, wann und wie Datenbanktransaktionen geöffnet und geschlossen werden. Empfohlen wird Transaktionssteuerung über das Attribut autocommit, während Transaktionssteuerung über das Attribut isolation_level das Verhalten von vor Python 3.12 beibehält.

Transaktionssteuerung über das Attribut autocommit

Der empfohlene Weg, das Transaktionsverhalten zu steuern, führt über das Attribut Connection.autocommit, das vorzugsweise über den Parameter autocommit von connect() gesetzt werden sollte.

Es wird nahegelegt, autocommit auf False zu setzen, was eine Transaktionssteuerung nach PEP 249 bedeutet. Das heißt:

  • sqlite3 sorgt dafür, dass immer eine Transaktion offen ist, deshalb öffnen connect(), Connection.commit() und Connection.rollback() stillschweigend eine neue Transaktion (bei den beiden letzteren unmittelbar nach dem Schließen der anstehenden). sqlite3 verwendet beim Öffnen von Transaktionen BEGIN DEFERRED-Anweisungen.

  • Transaktionen sollten ausdrücklich mit commit() committet werden.

  • Transaktionen sollten ausdrücklich mit rollback() zurückgesetzt werden.

  • Ein stillschweigendes Zurücksetzen findet statt, wenn die Datenbank mit anstehenden Änderungen über close() geschlossen wird.

Setze autocommit auf True, um den autocommit mode von SQLite einzuschalten. In diesem Modus haben Connection.commit() und Connection.rollback() keine Wirkung. Beachte, dass sich der autocommit-Modus von SQLite vom Attribut Connection.autocommit nach PEP 249 unterscheidet. Den autocommit-Modus von SQLite auf unterer Ebene fragst du über Connection.in_transaction ab.

Setze autocommit auf LEGACY_TRANSACTION_CONTROL, um das Verhalten der Transaktionssteuerung dem Attribut Connection.isolation_level zu überlassen. Weitere Informationen stehen unter Transaktionssteuerung über das Attribut isolation_level.

Transaktionssteuerung über das Attribut isolation_level

Bemerkung

Der empfohlene Weg, Transaktionen zu steuern, führt über das Attribut autocommit. Siehe Transaktionssteuerung über das Attribut autocommit.

Ist Connection.autocommit auf LEGACY_TRANSACTION_CONTROL gesetzt (die Voreinstellung), wird das Transaktionsverhalten über das Attribut Connection.isolation_level gesteuert. Andernfalls hat isolation_level keine Wirkung.

Ist das Verbindungsattribut isolation_level nicht None, werden stillschweigend neue Transaktionen geöffnet, bevor execute() und executemany() INSERT-, UPDATE-, DELETE- oder REPLACE-Anweisungen ausführen. Bei anderen Anweisungen findet keine stillschweigende Transaktionsbehandlung statt. Verwende die Methoden commit() und rollback(), um anstehende Transaktionen zu committen beziehungsweise zurückzusetzen. Das zugrunde liegende SQLite transaction behaviour – also ob und welche Art von BEGIN-Anweisungen sqlite3 stillschweigend ausführt – wählst du über das Attribut isolation_level.

Ist isolation_level auf None gesetzt, werden überhaupt keine Transaktionen stillschweigend geöffnet. Das lässt die zugrunde liegende SQLite-Bibliothek im autocommit mode, erlaubt dem Nutzer aber auch, die Transaktionsbehandlung über ausdrückliche SQL-Anweisungen selbst zu übernehmen. Der autocommit-Modus der zugrunde liegenden SQLite-Bibliothek lässt sich über das Attribut in_transaction abfragen.

Die Methode executescript() committet vor dem Ausführen des angegebenen SQL-Skripts stillschweigend jede anstehende Transaktion, unabhängig vom Wert von isolation_level.

Geändert in Version 3.6: sqlite3 hat früher vor DDL-Anweisungen stillschweigend eine offene Transaktion committet. Das ist nicht mehr der Fall.

Geändert in Version 3.12: Der empfohlene Weg, Transaktionen zu steuern, führt jetzt über das Attribut autocommit.