Python DBUtils

Benutzeranleitung für DBUtils +++++++++++++++++++++++++++++ :Version: 1.1 :Released: 08/14/11 :Translations: English_ German .. _English: UsersGuide.html .. contents:: Inhalt Zusammenfassung =============== DBUtils_ ist eine Sammlung von Python-Modulen, mit deren Hilfe man in Python_ geschriebene Multithread-Anwendungen auf sichere und effiziente Weise an Datenbanken anbinden kann. DBUtils wurde mit Blick auf `Webware for Python`_ als Anwendung und PyGreSQL_ als PostgreSQL_-Datenbankadapter entwickelt, kann aber für beliebige Python-Anwendungen und beliebige auf `DB-API 2`_ beruhende Python-Datenbankadapter verwendet werden. Module ====== DBUtils ist als Python-Package realisiert worden, das aus zwei verschiedenen Gruppen von Modulen besteht: Einer Gruppe zur Verwendung mit beliebigen DB-API-2-Datenbankadaptern, und einer Gruppe zur Verwendung mit dem klassischen PyGreSQL-Datenbankadapter-Modul. +-------------------+----------------------------------------------+ | Allgemeine Variante für beliebige DB-API-2-Adapter | +===================+==============================================+ | SteadyDB.py | Gehärtete DB-API-2-Datenbankverbindungen | +-------------------+----------------------------------------------+ | PooledDB.py | Pooling für DB-API-2-Datenbankverbindungen | +-------------------+----------------------------------------------+ | PersistentDB.py | Persistente DB-API-2-Datenbankverbindungen | +-------------------+----------------------------------------------+ | SimplePooledDB.py | Einfaches Pooling für DB-API 2 | +-------------------+----------------------------------------------+ +-------------------+----------------------------------------------+ | Variante speziell für den klassischen PyGreSQL-Adapter | +===================+==============================================+ | SteadyPg.py | Gehärtete klassische PyGreSQL-Verbindungen | +-------------------+----------------------------------------------+ | PooledPg.py | Pooling für klassische PyGreSQL-Verbindungen | +-------------------+----------------------------------------------+ | PersistentPg.py | Persistente klassische PyGreSQL-Verbindungen | +-------------------+----------------------------------------------+ | SimplePooledPg.py | Einfaches Pooling für klassisches PyGreSQL | +-------------------+----------------------------------------------+ Die Abhängigkeiten der Module in der Variante für beliebige DB-API-2-Adapter sind im folgenden Diagramm dargestellt: .. image:: dbdep.gif Die Abhängigkeiten der Module in der Variante für den klassischen PyGreSQL-Adapter sehen ähnlich aus: .. image:: pgdep.gif Download ======== Die aktuelle Version von DBUtils kann von der Homepage von Webware for Python heruntergeladen werden: http://www.webwareforpython.org/downloads/DBUtils/ Außerdem befindet sie sich im Python Package Index (auch bekannt als der "Cheese Shop") und kann von dort heruntergeladen werden: http://www.python.org/pypi/DBUtils/ Installation ============ Installation als eigenständiges Paket ------------------------------------- Wenn Sie DBUtils für andere Anwendungen als Webware for Python verwenden möchten, empfiehlt es sich, das Paket auf die übliche Weise zu installieren:: python setup.py install Installation als Unterpaket (Plug-In) von Webware for Python ------------------------------------------------------------ Wenn Sie DBUtils nur als Ergänzung für das Web-Framework Webware for Python verwenden wollen, sollten Sie DBUtils als Webware-Plug-In installieren:: python setup.py install --install-lib=/pfad/zu/Webware Ersetzen Sie ``/pfad/zu/Webware`` hierbei durch den Pfad zum Wurzelverzeichnis der Installation von Webware for Python. Sie müssen auch das Installationsskript von Webware for Python laufen lassen, wenn dies noch nicht geschehen ist, oder wenn Sie DBUtils in die Webware-Dokumentation integrieren wollen:: cd /pfad/zu/Webware python install.py Anforderungen ============= DBUtils arbeitet mit Python_ 2.3 oder einer neueren Version von Python 2. Die Module in der Variante für klassisches PyGreSQL benötigen PyGreSQL_ Version 3.4 oder höher, während die Module in der allgemeinen Variante für DB-API 2 mit jedem beliebigen Python-Datenbankadapter-Modul zusammenarbeiten, das auf `DB-API 2`_ basiert. Funktionalität ============== Dieser Abschnitt verwendet nur die Bezeichnungen der DB-API-2-Variante, aber Entsprechendes gilt auch für die PyGreSQL-Variante. SimplePooledDB -------------- ``DBUtils.SimplePooledDB`` ist eine sehr elementare Referenz-Implementierung eines Pools von Datenbankverbindungen. Hiermit ist ein Vorratsspeicher an Datenbankverbindungen gemeint, aus dem sich die Python-Anwendung bedienen kann. Diese Implementierung ist weit weniger ausgefeilt als das eigentliche ``PooledDB``-Modul und stellt insbesondere keine Ausfallsicherung zur Verfügung. ``DBUtils.SimplePooledDB`` ist im Wesentlichen identisch mit dem zu Webware for Python gehörenden Modul ``MiscUtils.DBPool``. Es ist eher zur Verdeutlichung des Konzepts gedacht, als zum Einsatz im produktiven Betrieb. SteadyDB -------- ``DBUtils.SteadyDB`` ist ein Modul, das "gehärtete" Datenbankverbindungen bereitstellt, denen gewöhnlichen Verbindungen eines DB-API-2-Datenbankadapters zugrunde liegen. Eine "gehärtete" Verbindung wird bei Zugriff automatisch, ohne dass die Anwendung dies bemerkt, wieder geöffnet, wenn sie geschlossen wurde, die Datenbankverbindung unterbrochen wurde, oder wenn sie öfter als ein optionales Limit genutzt wurde. Ein typisches Beispiel wo dies benötig wird, ist, wenn die Datenbank neu gestartet wurde, während Ihre Anwendung immer noch läuft und Verbindungen zur Datenbank offen hat, oder wenn Ihre Anwendung auf eine entfernte Datenbank über ein Netzwerk zugreift, das durch eine Firewall geschützt ist, und die Firewall neu gestartet wurde und dabei ihren Verbindungsstatus verloren hat. Normalerweise benutzen Sie das ``SteadyDB``-Modul nicht direkt; es wird aber von den beiden nächsten Modulen benötigt, ``PersistentDB`` und ``PooledDB``. PersistentDB ------------ ``DBUtils.PersistentDB`` stellt gehärtete, thread-affine, persistente Datenbankverbindungen zur Verfügung, unter Benutzung eines beliebigen DB-API-2-Datenbankadapters. Mit "thread-affin" und "persistent" ist hierbei gemeint, dass die einzelnen Datenbankverbindungen den jeweiligen Threads fest zugeordnet bleiben und während der Laufzeit des Threads nicht geschlossen werden. Das folgende Diagramm zeigt die beteiligten Verbindungsschichten, wenn Sie ``PersistentDB``-Datenbankverbindungen einsetzen: .. image:: persist.gif Immer wenn ein Thread eine Datenbankverbindung zum ersten Mal öffnet, wird eine neue Datenbankverbindung geöffnet, die von da an immer wieder für genau diesen Thread verwendet wird. Wenn der Thread die Datenbankverbindung schließt, wird sie trotzdem weiter offen gehalten, damit beim nächsten Mal, wenn der gleiche Thread wieder eine Datenbankverbindung anfordert, diese gleiche bereits geöffnete Datenbankverbindung wieder verwendet werden kann. Die Verbindung wird automatisch geschlossen, wenn der Thread beendet wird. Kurz gesagt versucht ``PersistentDB`` Datenbankverbindungen wiederzuverwerten, um die Gesamteffizienz der Datenbankzugriffe Ihrer Multithread-Anwendungen zu steigern, aber es wird dabei sichergestellt, dass verschiedene Threads niemals die gleiche Verbindung benutzen. Daher arbeitet ``PersistentDB`` sogar dann problemlos, wenn der zugrunde liegende DB-API-2-Datenbankadapter nicht thread-sicher auf der Verbindungsebene ist, oder wenn parallele Threads Parameter der Datenbank-Sitzung verändern oder Transaktionen mit mehreren SQL-Befehlen durchführen. PooledDB -------- ``DBUtils.PooledDB`` stellt, unter Benutzung eines beliebigen DB-API-2-Datenbankadapters, einen Pool von gehärteten, thread-sicheren Datenbankverbindungen