Python SQLAlchemy ORM - 1

本文為 Python SQLAlchemy ORM 一系列教學文:

SQLAlchemy 大概是目前 Python 最完整的資料庫操作的套件了,不過最令人垢病的是它的文件真的很難閱讀,如果不搭配個實例進行學習真的很難理解。

此外,SQLAlchemy 依照架構將文件說明分為 SQLAlchemy ORMSQLAlchemy 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 、新增資料表格

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# -*- coding: utf-8 -*-
import hashlib
from sqlalchemy import create_engine
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import ForeignKey
from 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__)

執行成功的話,應該會看到類似以下的執行訊息:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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.Engine
CREATE 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 COMMIT
Mapper: 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 與資料庫互動

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
# -*- coding: utf-8 -*-
import hashlib
from sqlalchemy import create_engine
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import ForeignKey
from sqlalchemy.orm import relationship, backref
from 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()

如果執行成功的話,會出現類似以下的結果:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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.Engine
CREATE 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 COMMIT
2013-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_password
FROM user
WHERE user.name = ?
LIMIT ? OFFSET ?
2013-08-21 17:57:32,554 INFO sqlalchemy.engine.base.Engine ('user1', 1, 0)
Found user1
2013-08-21 17:57:32,555 INFO sqlalchemy.engine.base.Engine ROLLBACK
2013-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_password
FROM user
WHERE user.name = ?
LIMIT ? OFFSET ?
2013-08-21 17:57:32,556 INFO sqlalchemy.engine.base.Engine ('user1', 1, 0)
Can not find user1 after rollback
2013-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 綁定。

1
2
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 篇察看。

參考資料:

http://www.sqlalchemy.org/