本文為 Python SQLAlchemy ORM 一系列教學文：
SQLAlchemy 大概是目前 Python 最完整的資料庫操作的套件了，不過最令人垢病的是它的文件真的很難閱讀，如果不搭配個實例進行學習真的很難理解。
此外，SQLAlchemy 依照架構將文件說明分為 SQLAlchemy ORM 與 SQLAlchemy Core ，如果不去細究到底有何不同，很容易讓人誤解。
基本上，如果只是基本的資料庫的表格建立、查詢、更新、刪除等，比較不需要使用表格間的關聯以及表格與 Python 表格物件關聯的話，其實用 SQLAlchemy Core 就足以應付需求了；但是想追求優雅的解決方案，同時又需要兼顧多表格之間的關聯的話，建議使用 SQLAlchemy ORM 。
事實上，從 SQLAlchemy 的架構圖來看， SQLAlchemy ORM 相較於 SQLAlchemy Core 而言是高層次的功能，因此學會 SQLAlchemy ORM 的話，絕對是猶如神器在手，所向披靡。
接下來就用幾個範例實際來說明 SQLAlchemy ORM 的使用吧。
安裝
- 本文以 Linux 環境為主
- 需安裝 Python 3 以上
- 需安裝 Python setuptools (連結)
- 以 SQLAlchemy 1.0.15 為主
安裝 SQLAlchemy 很簡單，只要用 pip 指令安裝即可(不過要先用 easy_install 安裝 pip)。
$ easy_install pip
$ pip install SQLAlchemy
操作 SQLite 資料庫
SQLite 是一個極輕量級的 RDBMS(Relational DataBase Management System)，非常適合較小型的非網頁架構應用程式使用，因為它不具備網路的 client/server 架構，所以無法透過網路遠端存取 SQLite 資料庫。
此外，SQLite 對於龐大的查詢、更新等負載能力也不如其他資料庫(MySQL, PostgreSQL 等)出色。即使如此，它仍具備一些十分有用的特性，例如可完全在記憶體中執行的資料庫、很多手持裝置開發環境(iOS, Android)都有支援等等，依然是一個撰寫輕量級應用程式的好選擇！
接下來，可以用範例 1 試著在記憶體中建立 SQLite 資料庫，並且新增一個 user 的表格。
範例1，連接資料庫 Engine 、新增資料表格
1234567891011121314151617181920212223242526272829303132333435363738394041 |
# -*- coding: utf-8 -*-import hashlibfrom sqlalchemy import create_enginefrom sqlalchemy import Column, Integer, Stringfrom sqlalchemy.ext.declarative import declarative_basefrom sqlalchemy import ForeignKeyfrom sqlalchemy.orm import relationship, backref
Base = declarative_base()
class User(Base): __tablename__ = ‘users‘
id = Column(Integer, primary_key=True) name = Column(String) username = Column(String) password = Column(String)
def __init__(self, name, username, password): self.name = name self.username = username self.password = hashlib.sha1(password).hexdigest()
def __repr__(self): return "User(‘{}‘,‘{}‘, ‘{}‘)".format( self.name, self.username, self.password )
if __name__ == ‘__main__‘: ‘‘‘ 此時只有建立 SQLAlchemy Engine 實例，還沒在記憶體內建立資料， 只有第一個 SQL 指令被下達時，才會真正連接到資料庫內執行 ‘‘‘ engine = create_engine(‘sqlite:///:memory:‘, echo=True)
‘‘‘ 真正建立表格是使用 Base.metadata.create_all(engine) ‘‘‘ Base.metadata.create_all(engine)
auser = User(‘user1‘, ‘username‘, ‘userpassword‘.encode(‘utf-8‘)) print(‘Mapper:‘, auser.__mapper__)
|
執行成功的話，應該會看到類似以下的執行訊息：
123456789101112131415 |
2013-08-21 13:51:39,073 INFO sqlalchemy.engine.base.Engine PRAGMA table_info("user")2013-08-21 13:51:39,073 INFO sqlalchemy.engine.base.Engine ()2013-08-21 13:51:39,074 INFO sqlalchemy.engine.base.EngineCREATE TABLE user ( id INTEGER NOT NULL, name VARCHAR, username VARCHAR, password VARCHAR, PRIMARY KEY (id))
2013-08-21 13:51:39,074 INFO sqlalchemy.engine.base.Engine ()2013-08-21 13:51:39,074 INFO sqlalchemy.engine.base.Engine COMMITMapper: Mapper|User|user
|
範例 1 說明
先從 35 行的 create_engine(‘sqlite:///:memory:‘, echo=True) 談起。
在 SQLAlchemy 的實做過程中，使用了Python 標準的 logging 模組進行開發，因此想要察看 SQLAlchemy 的執行過程的訊息就可以加上參數 echo=True，就可以看到 SQL 的指令與相關訊息。而 engine 是 SQLAlchemy 的 Engine 實例(instance)， Engine 則是可以視為用來介接主要的資料庫(MySQL, SQLite, …)的介面。
值得注意的是，建立 Engine 實例時，實際是還沒真正連接到資料庫的，只有在第一個工作或 SQL 指令被下達，它才會真正連接到資料庫執行。
接著第 38 行，則是使用 Base.metadata.create_all(engine) 在資料庫內建立起相對應的 users 表格。這個用來建立相對應表格以及建立與 Python 類別間的動作，是由 metadata 負責的。
第 40, 41 行則是建立一個 User 類別的實例，並且列印出其所對應的 Python 類別與資料庫表格名稱，其結果為 Mapper|User|user 代表 User 類別映對到 user 資料表。此外，需要注意的是截至目前為止這筆資料仍尚未寫進資料庫內，我們會在後續的範例中學會如何將實例內的資料寫進資料庫中。
再來談談第 9 行的 declarative_base()，SQLAlchemy 使用了稱為 Declarative system 的類別，用來映對 Python 類別與資料庫表格之間的關聯，所以才會看到第 11 行 User 類別繼承了 Base ，而且又需要在 User 類別中定義 __tablename__ 屬性的值，代表它映對到資料庫中的 users 資料表。如果把 Declarative system 想像成 Python 類別介接資料庫的接線生就會相對較好理解，也因此 User 類別需要繼承 Base 才能夠讓 Declarative system 了解表格的欄位名稱、型態、長度以及相對應的 Python 類別。
通常一個應用程式也只會用到一個 declarative_base() 類別(也就是範例 1 的 Base )。
當然，SQLAlchemy 沒有這麼聰明，可以自動幫我們分別表格欄位的型態、長度、主鍵等，這些都還需要我們自行設計，這些動作也就是第 14 行到第 17 行的內容。第 14 行到第 17 行定義表格的內容，被稱為 Table metadata，而 User 類別則稱為 Mapped class ，若想知道一個實例映對的資料表名稱與 Python 類別名稱，則可以試著存取 __mapper__ 屬性，例如第 41 行。
p.s. 第 14 行到第 17 行的資料表格欄位沒有指定長度，這在 SQLite, PostgreSQL 中是合法的，被稱為 minimal table descriptiopn ，而有指定長度的情況就是 full table description
第 19 行的 __init__ 與第 24 行的 __repr__ 兩個 Python 預設類別方法。在 SQLAlchemy 這兩個方法是可以省略不寫的。如果沒有覆寫(override) __init__ 的話，SQLAlchemy 自行預設的 __init__ 就會把所有欄位列為 __init__ 的參數，因此若不改寫 __init__ 的話，預設的參數就是 id, name, username, password 4 個，而不是第 19 行所定義的 3 個(name, username, password)。
而且在建立一個資料類別的實例時，我們有時會希望對某些表格欄位的值進行檢查或是改寫，例如第 22 行的密碼加密，此時就是需要覆寫 __init__ 的情況。最後，覆寫 __repr__ 只是為了方便偵錯(debug)，讓我們能夠較直觀地觀察User實例到底存放甚麼數值。
談到此處，就能夠稍微理解使用 ORM 過程就是定義資料庫表格、撰寫資料庫表格對應的 Python 類別、設定資料庫表格與其他資料庫表格間的關聯等動作。
截至目前為止，範例 1 仍未真正與資料庫進行互動，僅止於建立資料庫 Engine 、定義資料基模(scheme)。
事實上，如果要真正與資料庫進行互動(新增、刪除、修改)就得建立 Session 進行。
範例 2 將說明如何建立 Session 與資料庫進行互動。
範例 2 ，建立 Session 與資料庫互動
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960 |
# -*- coding: utf-8 -*-import hashlibfrom sqlalchemy import create_enginefrom sqlalchemy import Column, Integer, Stringfrom sqlalchemy.ext.declarative import declarative_basefrom sqlalchemy import ForeignKeyfrom sqlalchemy.orm import relationship, backreffrom sqlalchemy.orm import sessionmaker
Base = declarative_base()
class User(Base): __tablename__ = ‘users‘
id = Column(Integer, primary_key=True) name = Column(String) username = Column(String) password = Column(String)
def __init__(self, name, username, password): self.name = name self.username = username self.password = hashlib.sha1(password).hexdigest()
def __repr__(self): return "User(‘{}‘,‘{}‘, ‘{}‘)".format( self.name, self.username, self.password )
if __name__ == ‘__main__‘: engine = create_engine(‘sqlite:///:memory:‘, echo=True) Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine) session = Session()
user_1 = User(‘user1‘, ‘username1‘, ‘password_1‘.encode(‘utf-8‘)) session.add(user_1) row = session.query(User).filter_by(name=‘user1‘).first() if row: print(‘Found user1‘) print(row) else: print(‘Can not find user1‘)
session.rollback() # 資料庫回到新增 user1 之前的狀態
row = session.query(User).filter_by(name=‘user1‘).first() if row: print(‘Found user1 after rollback‘) print(row) else: print(‘Can not find user1 after rollback‘)
user_2 = User(‘user2‘, ‘username2‘, ‘password_2‘.encode(‘utf-8‘)) session.add(user_2) session.commit()
|
如果執行成功的話，會出現類似以下的結果：
12345678910111213141516171819202122232425262728293031323334 |
2013-08-21 17:57:32,546 INFO sqlalchemy.engine.base.Engine PRAGMA table_info("user")2013-08-21 17:57:32,547 INFO sqlalchemy.engine.base.Engine ()2013-08-21 17:57:32,548 INFO sqlalchemy.engine.base.EngineCREATE TABLE user ( id INTEGER NOT NULL, name VARCHAR, username VARCHAR, password VARCHAR, PRIMARY KEY (id))
2013-08-21 17:57:32,548 INFO sqlalchemy.engine.base.Engine ()2013-08-21 17:57:32,548 INFO sqlalchemy.engine.base.Engine COMMIT2013-08-21 17:57:32,551 INFO sqlalchemy.engine.base.Engine BEGIN (implicit)2013-08-21 17:57:32,552 INFO sqlalchemy.engine.base.Engine INSERT INTO user (name, username, password) VALUES (?, ?, ?)2013-08-21 17:57:32,552 INFO sqlalchemy.engine.base.Engine (‘user1‘, ‘username1‘, ‘3833b3a1c69cf71a31d86cb5bb4d3866789b4d1e‘)2013-08-21 17:57:32,554 INFO sqlalchemy.engine.base.Engine SELECT user.id AS user_id, user.name AS user_name, user.username AS user_username, user.password AS user_passwordFROM userWHERE user.name = ? LIMIT ? OFFSET ?2013-08-21 17:57:32,554 INFO sqlalchemy.engine.base.Engine (‘user1‘, 1, 0)Found user12013-08-21 17:57:32,555 INFO sqlalchemy.engine.base.Engine ROLLBACK2013-08-21 17:57:32,555 INFO sqlalchemy.engine.base.Engine BEGIN (implicit)2013-08-21 17:57:32,556 INFO sqlalchemy.engine.base.Engine SELECT user.id AS user_id, user.name AS user_name, user.username AS user_username, user.password AS user_passwordFROM userWHERE user.name = ? LIMIT ? OFFSET ?2013-08-21 17:57:32,556 INFO sqlalchemy.engine.base.Engine (‘user1‘, 1, 0)Can not find user1 after rollback2013-08-21 17:57:32,557 INFO sqlalchemy.engine.base.Engine INSERT INTO user (name, username, password) VALUES (?, ?, ?)2013-08-21 17:57:32,557 INFO sqlalchemy.engine.base.Engine (‘user2‘, ‘username2‘, ‘148dfdc3c539d35004cb808ca84e17ff962af744‘)2013-08-21 17:57:32,558 INFO sqlalchemy.engine.base.Engine COMMIT
|
範例 2 說明
定義類別的部份在範例 1 中已經做了不少說明，在範例 2 中就不多做說明了。
直接從第 37 行的部份開始說明，第 37 行 sessionmaker(bind=engine) 將 engine綁定(bind)到 Session 類別中，接著我們就能在第 38 行中將這個已經與 engine 綁定的 Session 類別實例化，以開始進行與資料庫的互動。
此外， Session 類別用以下的方法進行綁定。等於是先建立一個未綁定的 Session ，稍後再將 Engine 綁定。
12 |
Session = sessionmaker()Session.configure(bind=engine) # once engine is available |
有了 session 實例之後，我們將 1 筆 user_1 資料交給 session 準備 加入到資料庫之中，也就是第 41 行的部份。
為甚麼是 準備 呢？因為此時的資料庫還未沒有 user_1 的資料，此時的狀態被稱為 pending (事實上，共有 4 種狀態 Transient, Pending, Persistent, Detached)。
那甚麼時候這些資料才會被新增到資料庫內呢？只有進行 QUERY, COMMIT, FLUSH 時才會被寫入資料庫內。
因此當第 42 行進行 user1 的查詢時，SQLAlchemy 會先將 user_1 的資料寫入資料庫中，再進行查詢。所以其執行結果先出現了 INSERT，接著才出現 SELECT 。
接著，第 43 行至第 47 行的部份則是用來判斷是否能夠查詢到 user_1 的資料， filter_by(name="user_1") 是對欄位名稱為 name 所下的查詢條件，first() 則是回傳查詢結果的第1筆。
事實上，使用 query() 方法時，若有查詢到結果會回傳 Query Object，若無則是回傳 None 。
然後第 49 行的部份，我們利用 session 的 rollback() 方法，將資料庫狀態回到尚未加入 user_1 時的狀態。
第 51 行到第 56 行則是再查詢一次 user_1 的資料，想當然，這筆資料將無法查詢得到，因為資料庫狀態已經回到尚未加入 user_1 時的狀態了。
最後，第 59 行則是再將 user_2 的資料加到 session 內。然後直接在第 60 行使用 session 的 commit() 方法，告訴 session 要直接將這筆資料寫入資料庫內，所以就不需等到要查詢時才會寫入到資料庫內。
到此，大家應已能夠掌握 Session 的基本操作了。
如果有需要了解更多關於 Session 的操作可以至 SQLAlchemy 中的 Session 篇察看。
參考資料：