Overview

SQLAlchemy SQL Toolkit and Object Relational Mapperは、データベースとPythonを操作するための包括的なツール・セットです。これには、個別にまたは組み合わせて使用できるいくつかの異なる機能領域があります。その主要なコンポーネントを次に示します。コンポーネントの依存関係はレイヤーに編成されています。

_images/sqla_arch_small.png

上の図で、SQLAlchemyの前面にある最も重要な2つの部分は、 Object Relational Mapper(ORM)Core です。

Coreには、SQLAlchemyのSQLとデータベースの統合および記述サービスの幅広さが含まれており、その中で最も顕著な部分は SQL式言語 です。

SQL式言語は、ORMパッケージとは独立した独自のツールキットであり、構成可能なオブジェクトによって表されるSQL式を構築するシステムを提供し、特定のトランザクションのスコープ内でターゲットデータベースに対して”実行”し、結果セットを返すことができます。挿入、更新、削除(すなわち DML)は、これらの文を表すSQL式オブジェクトと、各文で使用されるパラメータを表す辞書を渡すことによって実現されます。

ORMはCore上に構築され、データベーススキーマにマップされたドメインオブジェクトモデルを操作する手段を提供します。ORMを使用する場合、SQL文はCoreを使用する場合とほぼ同じ方法で構築されますが、DMLのタスク(ここではデータベース内のビジネスオブジェクトの永続性を指します)は、 unit of work と呼ばれるパターンを使用して自動化されます。このパターンは、可変オブジェクトに対する状態の変更をINSERT、UPDATE、およびDELETE構文に変換し、これらのオブジェクトに関して呼び出されます。SELECT文は、ORM固有の自動化とオブジェクト中心のクエリ機能によっても強化されます。

CoreとSQL式言語を使用すると、不変性を中心としたプログラミングパラダイムとともに、データベースのスキーマ中心のビューが表示されるのに対して、ORMは、この上に、より明示的にオブジェクト指向であり、可変性に依存するプログラミングパラダイムを使用して、データベースのドメイン中心のビューを構築します。リレーショナル・データベース自体が可変サービスであるため、Core/SQL式言語がコマンド指向であるのに対して、ORMは状態指向である点が異なります。

Documentation Overview

The documentation is separated into four sections:

  • SQLAlchemy Unified Tutorial - SQLAlchemyの1.4/2.0シリーズのためのこの全く新しいチュートリアルでは、Coreの説明から始まり、ORM固有の概念に向けてますます作業を進めながら、ライブラリ全体を総合的に紹介しています。SQLAlchemyの1.xシリーズのユーザーだけでなく、新規ユーザーもここから始める必要があります。

  • SQLAlchemy ORM - このセクションでは、ORMの参考資料を紹介します。

  • SQLAlchemy Core - ここでは、Core内のその他すべての参照ドキュメントを示します。SQLAlchemyエンジン、接続、プーリング・サービスについてもここで説明します。

  • Dialects - DBAPI 仕様を含む、すべての dialect 実装のリファレンスドキュメントを提供します。

Code Examples

SQLAlchemyディストリビューションには、主にORMに関する実用的なコード例が含まれています。含まれているすべてのサンプルアプリケーションの説明は ORM Examples にあります。

wikiには、コアのSQLAlchemy構成体とORMの両方を含むさまざまな例もあります。 Theatrum Chemicum を参照してください。

Installation Guide

Supported Platforms

SQLAlchemyは次のプラットフォームをサポートしています。

Changed in version 2.0:

SQLAlchemyはPython 3.7以降に対応しました。

AsyncIO Support

SQLAlchemyの”asyncio”サポートは、 greenlet プロジェクトに依存しています。 この依存関係は一般的なマシンプラットフォームにデフォルトでインストールされますが、すべてのアーキテクチャでサポートされているわけではなく、あまり一般的でないアーキテクチャにもデフォルトでインストールされない場合があります。asyncioサポートが存在することを確認するための詳細については、 Asyncio Platform Installation Notes (Including Apple M1) を参照してください。

Supported Installation Methods

SQLAlchemyのインストールは、 setuptools に基づく標準的なPythonの方法で行われます。これは、 setup.py を直接参照するか、 pip やその他のsetuptools互換の方法を使用します。

Install via pip

pip が利用可能な場合は、ディストリビューションをPyPIからダウンロードして、1ステップでインストールできます。

pip install SQLAlchemy

このコマンドは、Python Cheese Shop から最新の リリースされた バージョンのSQLAlchemyをダウンロードし、システムにインストールします。ほとんどの一般的なプラットフォームでは、ネイティブの Cython / C 拡張機能が事前に構築されたPython Wheelファイルがダウンロードされます。

2.0.0b1 のような最新の プレリリース バージョンをインストールするには、pipは --pre フラグを使用する必要があります。

pip install --pre SQLAlchemy

上記の場合、最新バージョンがプレリリースであれば、最新リリースバージョンではなくプレリリースバージョンがインストールされます。

Installing manually from the source distribution

pipからインストールしない場合、ソースディストリビューションは setup.py スクリプトを使ってインストールできます。

python setup.py install

ソースインストールはプラットフォームに依存せず、Cython / C ビルドツールがインストールされているかどうかにかかわらず、どのプラットフォームにもインストールされます。次のセクション Building the Cython Extensions で詳しく説明しますが、 setup.py は可能であれば Cython / C を使ってビルドしようとしますが、そうでなければ純粋なPythonインストールに戻ります。

Building the Cython Extensions

SQLAlchemyには Cython extensionsが含まれており、さまざまな領域で速度をさらに向上させることができます。現在はコア結果セットの速度に重点が置かれています。

Changed in version 2.0: SQLAlchemy C拡張はCythonを使用して書き直されました。

setup.py は、Cythonパッケージがインストールされていれば、適切なプラットフォームが検出されれば自動的に拡張機能をビルドします。完全な手動ビルドは次のようになります。

# 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 install

ソースの構築は、build のような PEP 517 のテクニックを使って行うこともできます。

# cd into SQLAlchemy source distribution
cd path/to/sqlalchemy

# install build
pip install build

# build source / wheel dists
python -m build

Cythonがインストールされていない、コンパイラが見つからない、またはその他の問題が原因でCython拡張機能のビルドが失敗した場合、セットアッププロセスは警告メッセージを出力し、完了時にCython拡張機能なしでビルドを再実行し、最終ステータスを報告します。

Cython拡張モジュールをコンパイルすることもせずにビルド/インストールを実行するには、 DISABLE_SQLALCHEMY_CEXT 環境変数を指定します。このユースケースは、特別なテスト状況の場合、または通常の”再構築”メカニズムでは克服できない互換性/ビルドの問題のまれなケースのいずれかです。

export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install

Installing a Database API

SQLAlchemyは、特定のデータベース用に構築された DBAPI 実装で動作するように設計されており、最も一般的なデータベースをサポートしています。 Dialects の個々のデータベースセクションには、外部リンクを含め、各データベースで利用可能なDB APIが列挙されています。

Checking the Installed SQLAlchemy Version

このドキュメントでは、SQLAlchemyバージョン2.0について説明します。すでにSQLAlchemyがインストールされているシステムで作業している場合は、次のようにPythonプロンプトからバージョンを確認してください:

>>> import sqlalchemy
>>> sqlalchemy.__version__  
2.0.0

Next Steps

SQLAlchemyがインストールされていれば、今までと同じように Proceed to the SQLAlchemy Tutorial で学習できます。

1.x to 2.0 Migration

SQLAlchemy 2.0でリリースされた新しいAPIに関する注記は、 SQLAlchemy 2.0 - Major Migration Guide を参照してください。