SQLAlchemy入门（一）

环境：Ubuntu 15.10 64-bit

SQLAlchemy 是 Python 的 ORM 框架，它的理念是：数据库的量级和性能重要于对象集合，而对象集合的抽象又重要于表和行。

安装

直接经过 pip 安装：

$ pip install sqlalchemy

打开 Python，测试是否安装成功：

>>> import sqlalchemy
>>> sqlalchemy.__version__
'1.0.9'

建立引擎

SQLite

首先以 SQLite 为例，由于它比较简单。

from sqlalchemy import create_engine, MetaData

engine = create_engine('sqlite:///foo.db', echo=True)
metadata = MetaData(engine)

参数 sqlite:///foo.db 解释为：

sqlite://<nohostname>/<path>

其中foo.db是相对路径。也可写成：

sqlite:///./foo.db

SQLAlchemy 缺省使用 Python 内建的 sqlite3 模块来链接或建立 SQLite 数据库。执行完 create_engine 后，能够发现当前目录多了 foo.db 文件，不妨用 sqlite 打开看看。

$ sqlite3 foo.db
SQLite version 3.8.11.1 2015-07-29 20:00:57
Enter ".help" for usage hints.
sqlite> .tables

注意这里用的是 sqlite3 而非 sqlite，由于 foo.db 是经由 Python 内建的 sqlite3 模块建立的。

MySQL

再来看看链接 MySQL 时怎么建立引擎。
本文后续示例所有基于 MySQL，这是与官方文档不一样的地方。
先在MySQL里建立一个测试数据库：sa_test，后续示例都将基于这个数据库。

mysql> CREATE DATABASE sa_test DEFAULT CHARACTER SET UTF8;

from sqlalchemy import create_engine, MetaData

engine = create_engine('mysql+mysqldb://root:******@localhost/sa_test', echo=True)
metadata = MetaData(engine)

这里的参数看上去就比较复杂了，完整的格式为：

dialect+driver://username:password@host:port/database

这里 driver 用了 mysqldb，详见：MySQLdb：Python 操做 MySQL 数据库

引擎配置的详细信息可参考官方文档：Engine Configuration

MetaData

前面在建立 MetaData 时绑定了引擎：

metadata = MetaData(engine)

固然也能够不绑定。绑定的好处是，后续不少调用 （好比 MetaData.create_all()，Table.create()，等等）就不用指定引擎了。

建立表

建立两张表，user 和 address，address 表里有一个 user id 的外键。
注意：表名没有像官方文档及不少人推荐的那样使用复数形式，我的偏好而已，详细讨论请见 StackOverflow 的这个问题：Table Naming Dilemma: Singular vs. Plural Names （中文版）

from sqlalchemy import create_engine, MetaData,\
        Table, Column, Integer, String, ForeignKey

engine = create_engine('mysql+mysqldb://root:******@localhost/sa_test', echo=True)
metadata = MetaData(engine)

user_table = Table('user', metadata,
        Column('id', Integer, primary_key=True),
        Column('name', String(50)),
        Column('fullname', String(100))
        )

address_table = Table('address', metadata,
        Column('id', Integer, primary_key=True),
        Column('user_id', None, ForeignKey('user.id')),
        Column('email', String(128), nullable=False)
        )

metadata.create_all()

执行完 metadata.create_all() 这一句，两张表就建立好了，能够在 MySQL 里当即查看。

MetaData.create_all() 能够屡次调用，不会报错，它在内部会检查表是否已经建立。
由于 MetaData 建立时已经绑定了引擎，因此此处 create_all() 就没必要再指定了，不然得写成：

metadata.create_all(engine)

建立引擎时，echo 参数为 True，程序运行时便有不少调试信息打印出来。在这些调试信息中，能够看到以下两条 MySQL的CREATE TABLE 语句：

CREATE TABLE user (
    id INTEGER NOT NULL AUTO_INCREMENT,
    name VARCHAR(50),
    fullname VARCHAR(100),
    PRIMARY KEY (id)
)

CREATE TABLE address (
    id INTEGER NOT NULL AUTO_INCREMENT,
    user_id INTEGER,
    email VARCHAR(128) NOT NULL,
    PRIMARY KEY (id),
    FOREIGN KEY(user_id) REFERENCES user (id)
)

除了 metadata.create_all()，Table 本身也有 create 方法：

create(bind=None, checkfirst=False)

参数 bind 通常就是指引擎。
参数 checkfirst 表示是否检查表已经存在。为 True 时，若表已经存在，不报错，只是什么也不作；为
False 时，若表已经存在，则将引起异常。
使用这个方法来建立这两张表：

user_table.create(checkfirst=True)
address_table.create(checkfirst=True)

这里忽略了 bind 参数，由于建立 MetaData 对象时已经绑定了引擎，而建立表对象时又传入了 metadata，因此顺藤摸瓜，表本身是知道引擎的。
若是调整一下表的建立顺序，就会报错，由于 address 表里有一个 user 表的外键，而这时候 user 表还没建立呢。因此，仍是建议使用 MetaData.create_all() 吧，毕竟它也会检查表是否已经存在。

表的反射（Table Reflection）

表建立好了，通常也就不动了。因此实际应用时，每每表都已经存在，并不须要建立，只需把它们”导入”进来便可，这时就得使用 autoload 参数。

from sqlalchemy import create_engine, MetaData, Table

engine = create_engine('mysql+mysqldb://root:******@localhost/sa_test', echo=False)
metadata = MetaData(engine)

user_table = Table('user', metadata, autoload=True)

print 'user' in metadata.tables
print [c.name for c in user_table.columns]

address_table = Table('address', metadata, autoload=True)
print 'address' in metadata.tables

输出：

True
['id', 'name', 'fullname']
True

若是 MetaData 没有绑定引擎，则另需指定 autoload_with 参数：

user_table = Table('user', metadata, autoload=True, autoload_with=engine)

若是被反射的表外键引用了另外一个表，那么被引用的表也会一并被反射。好比只反射 address 表，user 表也一并被反射了。

from sqlalchemy import create_engine, MetaData, Table

engine = create_engine('mysql+mysqldb://root:******@localhost/sa_test', echo=False)
metadata = MetaData(engine)

address_table = Table('address', metadata, autoload=True)

print 'user' in metadata.tables
print 'address' in metadata.tables

输出：

True
True

插入数据

插入数据以前，必需要有表对象，不论是新建立的，仍是经过反射导入的。

Insert 对象

要往表里插数据，先建立一个 Insert 对象：

ins = user_table.insert()
print ins

打印这个 Insert 对象，能够看到它所对应的 SQL 语句：

INSERT INTO user (id, name, fullname) VALUES (%s, %s, %s)

若是链接的数据库不是 MySQL 而是 SQLite，那输出可能就是下面这样：

INSERT INTO user (id, name, fullname) VALUES (?, ?, ?)

可见 SQLAlchemy 帮咱们封装了不一样数据库之间语法的差别。
若是 MetaData 建立时没有绑定引擎，那么输出会略有不一样：

INSERT INTO "user" (id, name, fullname) VALUES (:id, :name, :fullname)

这时 SQLAlchemy 还不知道具体的数据库语法，表名加了引号（"user"），列名也改用为:id之类通常性的格式。
此外，这条INSERT语句列出了 user 表里的每一列，而id在插入时通常是不须要指定的，能够经过
Insert.values() 方法加以限制：

ins = ins.values(name='adam', fullname='Adam Gu')
print ins

限制后，id 列已经没有了：

INSERT INTO user (name, fullname) VALUES (%s, %s)

可见 values() 方法限制了 INSERT 语句所包含的列。可是咱们指定的 name 和 fullname 的值并无打印出来，这两个值保存在 Insert 对象里，只有等到执行时才会用到。

执行

咱们一直在说的引擎，能够理解成一个数据库链接对象的仓库，经过链接对象能够往数据库发送具体的 SQL 语句。调用引擎的 connect() 方法能够获取一个链接：

conn = engine.connect()

如今把前面的 Insert 对象丢给它来执行：

result = conn.execute(ins)

由调试信息可见具体的 INSERT 语句：

INSERT INTO user (name, fullname) VALUES (%s, %s)
('adam', 'Adam Gu')
COMMIT

返回值 result 是一个 ResultProxy 对象，ResultProxy 是对 DB-API 中 cursor 的封装。插入语句的结果并不经常使用，可是查询语句确定是要用到它的。
不妨在 MySQL 里看一下刚插入的数据。

mysql> select * from user;
+----+------+----------+
| id | name | fullname |
+----+------+----------+
|  1 | adam | Adam Gu  |
+----+------+----------+
1 row in set (0.00 sec)

执行多条语句

还记得前面的 Insert 对象使用 values() 方法来限制列吗？

ins = ins.values(name='adam', fullname='Adam Gu')

这种方式其实不利于 Insert 对象的复用，更好的作法是把参数经过 execute() 方法传进去：

ins = user_table.insert()
conn.execute(ins, name='adam', fullname='Adam Gu')

Insert 对象自己仍是会包含全部列，最终 INSERT 语句里的列由 execute() 的参数决定。由调试信息可见具体的 INSERT 语句：

INSERT INTO user (name, fullname) VALUES (%s, %s)
('adam', 'Adam Gu')
COMMIT

一次插入多条记录也很简单，只要传一个字典列表（每一个字典的键必须一致）给 execute() 便可。

conn.execute(address_table.insert(), [
    { 'user_id': 1, 'email': 'sprinfall@gmail.com' },
    { 'user_id': 1, 'email': 'sprinfall@hotmail.com' },
    ])

调试信息里具体的 INSERT 语句：

INSERT INTO address (user_id, email) VALUES (%s, %s)
((1, 'sprinfall@gmail.com'), (1, 'sprinfall@hotmail.com'))
COMMIT

在 MySQL 里看一下插入的地址：

mysql> select * from address;
+----+---------+-----------------------+
| id | user_id | email                 |
+----+---------+-----------------------+
|  1 |       1 | sprinfall@gmail.com   |
|  2 |       1 | sprinfall@hotmail.com |
+----+---------+-----------------------+
2 rows in set (0.00 sec)

第一部分到此结束。