Übersicht¶
Das SQLAlchemy SQL Toolkit und Object Relational Mapper ist eine umfassende Sammlung von Werkzeugen für die Arbeit mit Datenbanken und Python. Es verfügt über mehrere unterschiedliche Funktionsbereiche, die einzeln oder kombiniert genutzt werden können. Seine Hauptkomponenten sind unten dargestellt, mit Komponentenabhängigkeiten, die in Schichten organisiert sind.
Oben sind die beiden bedeutendsten front-facing Teile von SQLAlchemy der Object Relational Mapper (ORM) und das Core.
Core enthält die Breite von SQLAs und der Datenbankintegration und Beschreibungsdienste, wobei der prominenteste Teil davon die SQL Expression Language ist.
Die SQL Expression Language ist ein eigenständiges Toolkit, unabhängig vom ORM-Paket, das ein System zum Erstellen von SQL-Ausdrücken bietet, die durch zusammensetzbare Objekte repräsentiert werden, welche dann innerhalb des Geltungsbereichs einer spezifischen Transaktion gegen eine Zieldatenbank "ausgeführt" werden können, was ein Ergebnis-Set zurückgibt. Einfügungen, Aktualisierungen und Löschungen (d. h. DML) werden erreicht, indem SQL-Ausdrucksobjekte, die diese Anweisungen repräsentieren, zusammen mit Dictionaries, die Parameter repräsentieren, die mit jeder Anweisung verwendet werden sollen, übergeben werden.
Der ORM baut auf Core auf, um eine Möglichkeit zu bieten, mit einem Domänenobjektmodell zu arbeiten, das auf ein Datenbankschema abgebildet ist. Bei der Verwendung des ORM werden SQL-Anweisungen größtenteils auf die gleiche Weise erstellt wie bei der Verwendung von Core. Die Aufgabe von DML, die hier die Persistenz von Geschäftsobjekten in einer Datenbank bezeichnet, wird jedoch mithilfe eines Musters namens Unit of Work automatisiert. Dieses Muster übersetzt Zustandsänderungen an veränderlichen Objekten in INSERT-, UPDATE- und DELETE-Konstrukte, die dann im Hinblick auf diese Objekte aufgerufen werden. SELECT-Anweisungen werden ebenfalls durch ORM-spezifische Automatisierungen und objektzentrierte Abfragefunktionen erweitert.
Während die Arbeit mit Core und der SQL Expression Language eine Schema-zentrierte Sicht auf die Datenbank bietet, zusammen mit einem Programmierparadigma, das auf Unveränderlichkeit ausgerichtet ist, baut der ORM darauf auf einer Domänen-zentrierten Sicht auf die Datenbank mit einem Programmierparadigma auf, das explizit objektorientiert ist und auf Veränderlichkeit beruht. Da eine relationale Datenbank selbst ein veränderlicher Dienst ist, besteht der Unterschied darin, dass Core/SQL Expression Language befehlsorientiert ist, während der ORM zustandsorientiert ist.
Dokumentationsübersicht¶
Die Dokumentation ist in vier Abschnitte unterteilt
SQLAlchemy Unified Tutorial - Dieses brandneue Tutorial für die SQLAlchemy-Serie 1.4/2.0 führt die gesamte Bibliothek ganzheitlich ein, beginnend mit einer Beschreibung von Core und sich immer mehr zu ORM-spezifischen Konzepten hin. Neue Benutzer, sowie Benutzer, die aus der 1.x-Serie von SQLAlchemy kommen, sollten hier beginnen.
SQLAlchemy ORM - In diesem Abschnitt wird die Referenzdokumentation für den ORM vorgestellt.
SQLAlchemy Core - Hier wird die Referenzdokumentation für alles andere innerhalb von Core vorgestellt. SQLAlchemy-Engine-, Verbindungs- und Pooling-Dienste werden hier ebenfalls beschrieben.
Dialekte - Bietet Referenzdokumentation für alle Dialekt-Implementierungen, einschließlich DBAPI-Spezifika.
Codebeispiele¶
Funktionierende Codebeispiele, hauptsächlich zum ORM, sind in der SQLAlchemy-Distribution enthalten. Eine Beschreibung aller enthaltenen Beispielanwendungen finden Sie unter ORM Beispiele.
Es gibt auch eine große Vielfalt von Beispielen, die sowohl Core-SQLAlchemy-Konstrukte als auch den ORM auf dem Wiki umfassen. Siehe Theatrum Chemicum.
Installationsanleitung¶
Unterstützte Plattformen¶
SQLAlchemy unterstützt die folgenden Plattformen
cPython 3.7 und höher
Python-3-kompatible Versionen von PyPy
Geändert in Version 2.0: SQLAlchemy richtet sich nun an Python 3.7 und höher.
AsyncIO-Unterstützung¶
Die asyncio-Unterstützung von SQLAlchemy basiert auf dem greenlet-Projekt. Diese Abhängigkeit wird standardmäßig auf gängigen Maschinenplattformen installiert, wird jedoch nicht auf jeder Architektur unterstützt und wird möglicherweise auch auf weniger gängigen Architekturen nicht standardmäßig installiert. Weitere Details zur Sicherstellung der asyncio-Unterstützung finden Sie im Abschnitt Asyncio-Plattforminstallationshinweise (einschließlich Apple M1).
Unterstützte Installationsmethoden¶
Die Installation von SQLAlchemy erfolgt über standardmäßige Python-Methoden, die auf setuptools basieren, entweder durch Verweis auf setup.py direkt oder durch die Verwendung von pip oder anderen setuptools-kompatiblen Ansätzen.
Installation über pip¶
Wenn pip verfügbar ist, kann die Distribution von PyPI heruntergeladen und in einem Schritt installiert werden
pip install SQLAlchemyDieser Befehl lädt die neueste veröffentlichte Version von SQLAlchemy vom Python Cheese Shop herunter und installiert sie auf Ihrem System. Für die meisten gängigen Plattformen wird eine Python Wheel-Datei heruntergeladen, die vorab kompilierte native Cython / C-Erweiterungen enthält.
Um die neueste Vorabversion, wie z. B. 2.0.0b1, zu installieren, erfordert pip die Verwendung des Flags --pre
pip install --pre SQLAlchemyDabei wird, falls die neueste Version eine Vorabversion ist, diese anstelle der neuesten veröffentlichten Version installiert.
Manuelle Installation aus der Quellverteilung¶
Wenn nicht von pip installiert wird, kann die Quellverteilung mit dem setup.py-Skript installiert werden
python setup.py installDie Quellinstallation ist plattformunabhängig und wird auf jeder Plattform installiert, unabhängig davon, ob Cython / C-Build-Tools installiert sind oder nicht. Wie im nächsten Abschnitt Kompilieren der Cython-Erweiterungen beschrieben, versucht setup.py, wenn möglich mit Cython / C zu kompilieren, fällt aber andernfalls auf eine reine Python-Installation zurück.
Kompilieren der Cython-Erweiterungen¶
SQLAlchemy enthält Cython-Erweiterungen, die in verschiedenen Bereichen für zusätzliche Geschwindigkeit sorgen, wobei der Schwerpunkt derzeit auf der Geschwindigkeit von Core-Ergebnis-Sets liegt.
Geändert in Version 2.0: Die SQLAlchemy C-Erweiterungen wurden mit Cython neu geschrieben.
setup.py kompiliert die Erweiterungen automatisch, wenn eine geeignete Plattform erkannt wird und das Cython-Paket installiert ist. Ein vollständiger manueller Build sieht wie folgt aus:
# cd into SQLAlchemy source distribution
cd path/to/sqlalchemy
# install cython
pip install cython
# optionally build Cython extensions ahead of install
python setup.py build_ext
# run the install
python setup.py installQuell-Builds können auch mithilfe von PEP 517-Techniken durchgeführt werden, z. B. mit build
# cd into SQLAlchemy source distribution
cd path/to/sqlalchemy
# install build
pip install build
# build source / wheel dists
python -m buildWenn der Kompilierung der Cython-Erweiterungen aufgrund fehlenden Cythons, eines fehlenden Compilers oder eines anderen Problems fehlschlägt, gibt der Setup-Prozess eine Warnmeldung aus und führt den Build nach Abschluss ohne die Cython-Erweiterungen erneut aus und meldet den Endstatus.
Um den Build/die Installation auszuführen, ohne auch nur zu versuchen, die Cython-Erweiterungen zu kompilieren, kann die Umgebungsvariable DISABLE_SQLALCHEMY_CEXT gesetzt werden. Der Anwendungsfall hierfür sind entweder spezielle Testumgebungen oder in dem seltenen Fall von Kompatibilitäts-/Build-Problemen, die durch den üblichen "Wiederaufbau"-Mechanismus nicht behoben werden können.
export DISABLE_SQLALCHEMY_CEXT=1; python setup.py installInstallation einer Datenbank-API¶
SQLAlchemy ist so konzipiert, dass es mit einer für eine bestimmte Datenbank erstellten DBAPI-Implementierung zusammenarbeitet und unterstützt die gängigsten Datenbanken. Die einzelnen Datenbankabschnitte in Dialekte listen die verfügbaren DBAPIs für jede Datenbank auf, einschließlich externer Links.
Überprüfen der installierten SQLAlchemy-Version¶
Diese Dokumentation behandelt die SQLAlchemy-Version 2.0. Wenn Sie auf einem System arbeiten, auf dem SQLAlchemy bereits installiert ist, überprüfen Sie die Version von Ihrer Python-Eingabeaufforderung aus wie folgt:
>>> import sqlalchemy
>>> sqlalchemy.__version__
2.0.0Nächste Schritte¶
Nach der Installation von SQLAlchemy können neue und alte Benutzer gleichermaßen mit dem SQLAlchemy-Tutorial fortfahren.
Migration von 1.x auf 2.0¶
Hinweise zur neuen in SQLAlchemy 2.0 veröffentlichten API finden Sie hier unter SQLAlchemy 2.0 - Hauptmigrationsleitfaden.
