Einleitung

Diese API wurde definiert, um Ähnlichkeiten zwischen den Python-Modulen, die zum Zugriff auf Datenbanken verwendet werden, zu fördern. Auf diese Weise hoffen wir, eine Konsistenz zu erreichen, die zu leichter verständlichen Modulen, Code, der generell portabler über Datenbanken hinweg ist, und einer breiteren Reichweite von Datenbankverbindungen aus Python führt.

Diese Schnittstellenspezifikation besteht aus mehreren Punkten

• Modulschnittstelle
• Connection-Objekte
• Cursor-Objekte
• DBI Hilfsobjekte

Kommentare und Fragen zu dieser Spezifikation können an die SIG zu Tabellarischen Datenbanken in Python (https://pythonlang.de/sigs/db-sig) gerichtet werden.

Dieses Spezifikationsdokument wurde zuletzt aktualisiert am: 9. April 1996. Es wird als Version 1.0 dieser Spezifikation bekannt sein.

Modulschnittstelle

Die Datenbank-Schnittstellenmodule sollten typischerweise mit etwas benannt werden, das auf db endet. Bestehende Beispiele sind: oracledb, informixdb und pg95db. Diese Module sollten mehrere Namen exportieren

modulname(verbindungszeichenkette)

Konstruktor zum Erstellen einer Verbindung zur Datenbank. Gibt ein Connection-Objekt zurück.

error

Ausnahme, die bei Fehlern aus dem Datenbankmodul ausgelöst wird.

Connection-Objekte

Connection-Objekte sollten auf die folgenden Methoden reagieren

close()

Schließt die Verbindung sofort (anstatt wann immer __del__ aufgerufen wird). Die Verbindung ist ab diesem Zeitpunkt unbrauchbar; eine Ausnahme wird ausgelöst, wenn versucht wird, eine Operation mit der Verbindung durchzuführen.

commit()

Bestätigt jede ausstehende Transaktion in der Datenbank.

rollback()

Macht die Datenbank bis zum Beginn jeder ausstehenden Transaktion rückgängig.

cursor()

Gibt ein neues Cursor-Objekt zurück. Eine Ausnahme kann ausgelöst werden, wenn die Datenbank kein Cursor-Konzept unterstützt.

callproc([parameter])

(Hinweis: Diese Methode ist noch nicht gut definiert.) Ruft eine gespeicherte Datenbankprozedur mit den gegebenen (optionalen) Parametern auf. Gibt das Ergebnis der gespeicherten Prozedur zurück.

(alle Attribute und Methoden von Cursor-Objekten)

Für Datenbanken, die keine Cursor haben, und für einfache Anwendungen, die nicht die Komplexität eines Cursors benötigen, sollte ein Connection-Objekt auf jedes der Attribute und Methoden eines Cursor-Objekts reagieren. Datenbanken, die Cursor haben, können dies durch die Verwendung eines impliziten, internen Cursors implementieren.

Cursor-Objekte

Diese Objekte repräsentieren einen Datenbank-Cursor, der zur Verwaltung des Kontexts einer Abfrageoperation verwendet wird.

Cursor-Objekte sollten auf die folgenden Methoden und Attribute reagieren

arraysize

Dieses Lese-/Schreibattribut gibt die Anzahl der Zeilen an, die mit fetchmany() auf einmal abgerufen werden sollen. Dieser Wert wird auch beim Einfügen mehrerer Zeilen gleichzeitig verwendet (Übergabe eines Tupels/einer Liste von Tupeln/Listen als Parameterwert an execute()). Dieses Attribut wird standardmäßig auf eine einzelne Zeile gesetzt.

Beachten Sie, dass arraysize optional ist und lediglich für leistungsstärkere Datenbankinteraktionen bereitgestellt wird. Implementierungen sollten dies in Bezug auf die Methode fetchmany() beachten, sind aber frei, mit der Datenbank zeilenweise zu interagieren.

description

Dieses schreibgeschützte Attribut ist ein Tupel von 7-Tupeln. Jedes 7-Tupel enthält Informationen, die jede Ergebnisspalte beschreiben: (Name, Typ_Code, display_size, internal_size, precision, scale, null_ok). Dieses Attribut ist None für Operationen, die keine Zeilen zurückgeben, oder wenn noch keine Operation über die Methode execute() aufgerufen wurde.

Der ‘type_code’ ist einer der im folgenden Abschnitt angegebenen ‘dbi’-Werte.

Hinweis: Dies ist etwas im Fluss. Im Allgemeinen sind die ersten beiden Elemente des 7-Tupels immer vorhanden; die anderen können datenbankspezifisch sein.

close()

Schließt den Cursor sofort (anstatt wann immer __del__ aufgerufen wird). Der Cursor ist ab diesem Zeitpunkt unbrauchbar; eine Ausnahme wird ausgelöst, wenn versucht wird, eine Operation mit dem Cursor durchzuführen.

execute(operation [,parameter])

Führt eine Datenbankoperation (Abfrage oder Befehl) aus (bereitet sie vor). Parameter können bereitgestellt werden (als Sequenz (z. B. Tupel/Liste)) und werden an Variablen in der Operation gebunden. Variablen werden in einer datenbankspezifischen Notation angegeben, die auf dem Index im Parameter-Tupel basiert (positionsbasiert anstatt namensbasiert).

Die Parameter können auch als Sequenz von Sequenzen (z. B. eine Liste von Tupeln) angegeben werden, um mehrere Zeilen in einer einzigen Operation einzufügen.

Eine Referenz auf die Operation wird vom Cursor beibehalten. Wenn dasselbe Operations-Objekt erneut übergeben wird, kann der Cursor sein Verhalten optimieren. Dies ist am effektivsten für Algorithmen, bei denen dieselbe Operation verwendet wird, aber unterschiedliche Parameter daran gebunden werden (viele Male).

Für maximale Effizienz bei der Wiederverwendung einer Operation ist es am besten, die Methode setinputsizes() zu verwenden, um die Parametertypen und -größen im Voraus anzugeben. Es ist zulässig, dass ein Parameter nicht mit den vordefinierten Informationen übereinstimmt; die Implementierung sollte dies kompensieren, möglicherweise mit einem Effizienzverlust.

Unter Verwendung von SQL-Terminologie sind dies die möglichen Ergebniswerte der Methode execute()

• Wenn die Anweisung DDL ist (z. B. CREATE TABLE), wird 1 zurückgegeben.
• Wenn die Anweisung DML ist (z. B. UPDATE oder INSERT), wird die Anzahl der betroffenen Zeilen zurückgegeben (0 oder eine positive Ganzzahl).
• Wenn die Anweisung DQL ist (z. B. SELECT), wird None zurückgegeben, was anzeigt, dass die Anweisung erst vollständig ist, wenn Sie eine der 'fetch'-Methoden verwenden.

fetchone()

Ruft die nächste Zeile eines Abfrageergebnisses ab und gibt ein einzelnes Tupel zurück.

fetchmany([größe])

Ruft den nächsten Satz von Zeilen eines Abfrageergebnisses ab und gibt eine Liste von Tupeln zurück. Eine leere Liste wird zurückgegeben, wenn keine Zeilen mehr verfügbar sind. Die Anzahl der abzurufenden Zeilen wird durch den Parameter angegeben. Wenn er None ist, bestimmt die arraysize des Cursors die Anzahl der abzurufenden Zeilen.

Beachten Sie, dass es Leistungsüberlegungen bezüglich des größenparameters gibt. Für optimale Leistung ist es in der Regel am besten, das arraysize-Attribut zu verwenden. Wenn der größenparameter verwendet wird, ist es am besten, ihn von einem fetchmany()-Aufruf zum nächsten beizubehalten.

fetchall()

Ruft alle Zeilen eines Abfrageergebnisses ab und gibt eine Liste von Tupeln zurück. Beachten Sie, dass das arraysize-Attribut des Cursors die Leistung dieser Operation beeinflussen kann.

setinputsizes(größen)

(Hinweis: Diese Methode ist noch nicht gut definiert.) Dies kann vor einem Aufruf von execute() verwendet werden, um Speicherbereiche für die Parameter der Operation vordefinieren. größen wird als Tupel angegeben – ein Element für jeden Eingabeparameter. Das Element sollte ein Typobjekt sein, das dem verwendeten Input entspricht, oder eine Ganzzahl, die die maximale Länge eines Zeichenkettenparameters angibt. Wenn das Element None ist, wird kein vordefinierter Speicherbereich für diese Spalte reserviert (dies ist nützlich, um vordefinierte Bereiche für große Inputs zu vermeiden).

Diese Methode würde vor dem Aufruf der Methode execute() verwendet werden.

Beachten Sie, dass diese Methode optional ist und lediglich für leistungsstärkere Datenbankinteraktionen bereitgestellt wird. Implementierungen dürfen nichts tun und Benutzer dürfen sie nicht verwenden.

setoutputsize(größe [,spalte])

(Hinweis: Diese Methode ist noch nicht gut definiert.)

Legt eine Spaltenpuffergröße für Abrufe von großen Spalten fest (z. B. LONG). Die Spalte wird als Index in das Ergebnis-Tupel angegeben. Die Verwendung einer Spalte von None setzt die Standardgröße für alle großen Spalten im Cursor.

Diese Methode würde vor dem Aufruf der Methode execute() verwendet werden.

Beachten Sie, dass diese Methode optional ist und lediglich für leistungsstärkere Datenbankinteraktionen bereitgestellt wird. Implementierungen dürfen nichts tun und Benutzer dürfen sie nicht verwenden.

DBI Hilfsobjekte

Viele Datenbanken benötigen die Eingabe in einem bestimmten Format für die Bindung an die Eingabeparameter einer Operation. Wenn eine Eingabe beispielsweise für eine DATE-Spalte bestimmt ist, muss sie in einem bestimmten Zeichenkettenformat an die Datenbank gebunden werden. Ähnliche Probleme bestehen für „Row ID“-Spalten oder große Binärdaten (z. B. Blobs oder RAW-Spalten). Dies stellt Probleme für Python dar, da die Parameter der Methode execute() untypisiert sind. Wenn das Datenbankmodul ein Python-Zeichenkettenobjekt sieht, weiß es nicht, ob es als einfache CHAR-Spalte, als rohes Binärelement oder als DATE gebunden werden soll.

Um dieses Problem zu lösen, wurde das 'dbi'-Modul erstellt. Dieses Modul definiert einige grundlegende Datenbank-Schnittstellen-Typen für die Arbeit mit Datenbanken. Es gibt zwei Klassen: 'dbiDate' und 'dbiRaw'. Dies sind einfache Containerklassen, die einen Wert umschließen. Wenn sie an die Datenbankmodule übergeben werden, kann das Modul erkennen, dass der Eingabeparameter als DATE oder RAW gedacht ist. Zur Symmetrie geben die Datenbankmodule DATE- und RAW-Spalten als Instanzen dieser Klassen zurück.

Das Attribut ‘description’ eines Cursor-Objekts gibt Informationen über jede der Ergebnisspalten einer Abfrage zurück. Der ‘type_code’ ist definiert als einer von fünf Typen, die von diesem Modul exportiert werden: STRING, RAW, NUMBER, DATE oder ROWID.

Das Modul exportiert die folgenden Namen

dbiDate(wert)

Diese Funktion konstruiert eine 'dbiDate'-Instanz, die einen Datumswert enthält. Der Wert sollte als Ganzzahl von Sekunden seit der "Epoche" angegeben werden (z. B. time.time()).

dbiRaw(wert)

Diese Funktion konstruiert eine 'dbiRaw'-Instanz, die einen Roh- (Binär-) Wert enthält. Der Wert sollte als Python-Zeichenkette angegeben werden.

STRING

Dieses Objekt wird verwendet, um datenbankbasierte Spalten zu beschreiben (z. B. CHAR).

RAW

Dieses Objekt wird verwendet, um (große) Binärspalten in einer Datenbank zu beschreiben (z. B. LONG RAW, Blobs).

NUMBER

Dieses Objekt wird verwendet, um numerische Spalten in einer Datenbank zu beschreiben.

DATE

Dieses Objekt wird verwendet, um Datumsspalten in einer Datenbank zu beschreiben.

ROWID

Dieses Objekt wird verwendet, um die "Row ID"-Spalte in einer Datenbank zu beschreiben.

Danksagungen

Vielen Dank an Andrew Kuchling, der die Python Database API Specification 1.0 im Jahr 2001 aus dem ursprünglichen HTML-Format in das PEP-Format konvertiert hat.

Greg Stein ist der ursprüngliche Autor der Python Database API Specification 1.0. Marc-André hat später die Wartung der API als Herausgeber fortgesetzt.

Urheberrecht

Dieses Dokument wurde gemeinfrei erklärt.