译者注：译者博客(http://blog.csdn.net/lin_strong)，转载请保留这条。此为pymssql模块version2.1.4官方文档的翻译，仅供学习交流使用，请勿用于商业用途。

模块级符号

pymssql.

version

Unicode常量表示的pymssql版本。如：u"2.1.1", u"2.2.0"pymssql.VERSION元组形式的pymssql版本，这样在程序中更容易处理(转换、比较)。如：(2, 1, 1), (2, 2, 0)

这是版本 2.2.0. 中新加的特性。

pymssql.

full_version

Unicode常量表示的pymssql版本，不同的是，它包括了后缀(PEP 440)。如：u"2.1.0.dev2", u"2.2.0.dev"

以下是DB-API 2.0规范中要求的常量：

pymssql.apilevel‘2.0’ – pymssql 尽可能地遵从 DB-API 2.0.

pymssql.paramstyle‘pyformat’ – pymssql 使用扩展的python格式代码.

pymssql.threadsafety1 – 线程可以共享模块, 但不能共享连接。

函数

pymssql.connect(server=’.’, user=None, password=None, database=’’,

timeout=0, login_timeout=60, charset=‘UTF-8’, as_dict=False, host=’’,

appname=None, port=‘1433’, conn_properties=None, autocommit=False,

tds_version=None)一个构造器(Constructor)，用于创建到数据库的链接。返回一个Connection对象。

注意：大部分情况下你应该会更倾向于使用关键字参数，而不是位置确定的参数。

参数说明：

参数名(类型)说明

server (str)

数据库主机

user (str)

用于连接的数据库用户

password (str)

用户的密码

database (str)

链接初始化的数据库。默认情况下，SQL服务器会选择设置中特定用户所对应的默认数据库。

timeout (int)

用秒表示的查询超时时间，默认为0(无超时)

login_timeout (int)

用秒表示的连接与登陆超时时间，默认为60

charset (str)

连接到数据库所使用的字符集

as_dict (bool)

是否每一行作为字典而不是元组返回。你可以使用基于0的索引或者使用名字来访问列。

host (str)

你想要连接的数据库主机或实体。如：

r’.\SQLEXPRESS’ –本地机器上的SQLEXPRESS实体(仅Windows)

r’(local)\SQLEXPRESS’ – 同上(仅Windows)

‘SQLHOST’ – 默认端口上的默认实体(仅Windows)

‘SQLHOST’ – 在freetds.conf中设置的指定端口上的指定实体 (仅Linux/*nix)

‘SQLHOST,1433’ – 指定主机上的指定TCP端口

’SQLHOST:1433’ – 同上

’SQLHOST,5000’ – 如果你已经设置了一个实体在端口5000进行监听

’SQLHOST:5000’ – 同上

’.’ (本地主机)默认设置，如果没有指定host。

appname (str)

设置链接使用的应用名

port (str)

连接到服务器所使用的TCP端口号

conn_properties

当链接建立时发送给服务器的SQLqueries。可以是一个字符串或者另一类可迭代的字符串组。默认值：见_mssql.connect()

autocommit (bool)

是否使用默认自动提交模式

tds_version (str)

使用的TDS协议版本

警告：目前，设置timeout或login_timeout会有一个过程级的影响，因为用于实现超时的FreeTDS db-lib API函数是全局效果的。

版本2.1.1中新特性: 能连接Azure。

版本2.1.1中新特性: conn_properties参数。

版本2.1.1中新特性: autocommit参数。

版本2.1.2中新特性: tds_version参数。

版本2.2.0的变化: 参数tds_version的默认值变为了None。在版本2.1.2中，其默认值为’7.1’。

警告：参数tds_version的默认值为None。这意味着：

你不能依赖于旧的默认值’7.1’。现在，你得做以下其中一件事：

· 通过传递值给这个参数直接指定它的值，或者

· 使用FreeTDS提供的方法配置它

可能这看起来很麻烦，但同时意味着你可以在Python代码中完整地配置链接的特性，而不用再管freetds.conf了。在版本2.1.1及之前版本，没法控制TDS协议版本；在版本2.1.2中，可以设置它。如果没有指定的话，则使用版本7.1。

警告：FreeTDS在版本0.95中添加了对TDS协议版本7.3的支持。如果你知道由pymssql使用的底层FreeTDS的版本是0.91的话，要小心不要要求TDS7.3，因为这即不会引发任何错误也没有机制阻止你传递这个无效值。

警告：FreeTDS在版本0.95中添加了对TDS协议版本7.3的支持。如果你知道由pymssql使用的底层FreeTDS的版本更旧的话，要小心不要要求TDS7.3，因为这即不会引发任何错误也没有机制阻止你传递这个无效值。pymssql.get_dbversion()封装了DB库的dbversion()函数，这个函数会以字符串形式返回FreeTDS的版本(DB-Lib的实际版本)。如：“freetds v0.95”。

不幸的是：

1 )返回的值没有说明更小的修订号(如：v0.95.50)

2 )它的数据类型使得它难以比较或编程处理

3 )在FreeTDS发行历史中，它并没有被坚持更新

这是pymssql对于DB-API 2.0的扩展

pymssql.set_max_connections(number)设置允许同时连接到数据库的链接的最大数量。默认是25。

这是pymssql对于DB-API 2.0的扩展

pymssql.get_max_connections()获取允许同时连接到数据库的链接的最大数量。

这是pymssql对于DB-API 2.0的扩展pymssql.set_wait_callback(wait_callback_callable)版本2.1.0. 中的新特性

这个特性使得pymssql能用于协作的多任务系统，使其在等待服务器响应时调用一个回调函数。

传递的可调用的回调函数应该接受一个参数：连接到服务器的网络socket的文件描述符/handle，所以其签名应该是这样的

def wait_callback_callable(read_fileno):

#...

pass

1

2

3

1

2

3

它的代码体应该调用你所使用的多任务框架的适当API，以使得当socket中没有输入数据时，当前greenlet主动交出CPU时间。

这是pymssql对于DB-API 2.0的扩展

Connection类

class pymssql.Connection(user, password, host, database, timeout, login_timeout, charset, as_dict)这个类代表了一条MS SQL 数据库链接。你可以通过调用构建器pymssql.connect()来创建这个类的一个实例。

属性

这个类没有有用的属性和数据成员。

方法

Connection.autocommit(status)status是一个boolean值。这个方法返回autocommit模式是否启用

默认的，autocommit模式是关闭的，这意味着如果要在数据库中保存变化的数据，必须明确地提交每个会话。

你可以启用autocommit模式，这样，每个操作一旦成功就会提交自身。

这是pymssql对于DB-API 2.0的扩展

Connection.close()关闭链接。

Connection.cursor()返回一个Cursor对象，这可以用于发送请求并从数据库获取结果。

Connection.commit()提交当前会话。你必须调用这个方法来保存你的数据，如果autocommit为默认的False。

Connection.rollback()回滚当前会话。

Cursor类

class pymssql.Cursor这个类代表一个Cursor(Python DB-API规范的术语)，其用于向数据库发送请求并获取结果。通过调用一个打开的Connection链接对象的cursor()方法来创建Cursor实例。

属性

Cursor.rowcount返回上一次操作中受影响的行数。对于SELECT语句，只有在所有行都被fetched后它才会返回有用的信息。

Cursor.connection这是对于DB-API规范的扩展。返回对创建cursor的Connection对象的引用。

Cursor.lastrowid这是对于DB-API规范的扩展。返回上一个插入的行的标识值。如果之前的操作没涉及向带有标识列的表中插入行，则返回None。

Cursor.rownumber这是对于DB-API规范的扩展。返回在当前结果集中，基于0的当前索引值。

方法

Cursor.close()关闭cursor。之后这个cursor就不可用了。

Cursor.execute(operation)

Cursor.execute(operation, params)operation是一个字符串；而params，如果用到了的话，是一个简单的值、元组、字典或None。

对数据库执行operation，可能会用给的值替换占位符。比起手动连接字符串，这应该是更受欢迎的创建SQL命令的方法，手动连接字符串有受到SQL注入式攻击的风险。这个方法的格式化方式接近于Python内建的方式。但是，由于格式化和类型转换是内部进行的，只支持%s和%d占位符。这两个占位符在功能上与Python内建的是一样的。

如果你给params传递的是字典的话，则支持关键字占位符。

如果你调用了只带一个参数的execute()，%符号就丧失了它的特殊意义，这样你就可以如平常一样在查询字符串中使用它，比如用在LIKE操作符中。

在调用execute()后，你必须调用Connection.commit()，否则数据不会被存到数据库中。如果你想要自动完成这件事的话，你也可以设置connection.autocommit。这个行为是DB-API要求的，如果你不喜欢的话，那就改用_mssql模块吧。

Cursor.executemany(operation, params_seq)operation是一个字符串；而params_seq是一个元组的序列(比如一个列表)。为参数序列中的每一个元素重复执行operation这一数据库操作。

Cursor.fetchone()获取查询结果的下一行，返回一个元组，或者如果as_dict为True的话返回一个字典。如果没有更多可获取的数据了，返回None。如果前一个对execute*()

的调用没有产生任何结果集或者还没有提交调用，则抛出OperationalError (PEP 249#operationalerror)。

Cursor.fetchmany(size=None)获取下一批查询结果，返回一个元组的列表，或者如果as_dict为True的话返回一个字典。如果没有更多可获取的数据了，返回一个空列表。你可以使用size参数调整之后每一批获取的行数，这个值会一直保留使用。如果前一个对execute*()

的调用没有产生任何结果集或者还没有提交调用，则抛出OperationalError (PEP 249#operationalerror)。

Cursor.fetchall()获取查询结果的所有剩余行，返回一个元组的列表，或者如果as_dict为True的话返回一个字典。如果没有更多可获取的数据了，返回一个空列表。如果前一个对execute*()

的调用没有产生任何结果集或者还没有提交调用，则抛出OperationalError (PEP 249#operationalerror)。

Cursor.nextset()这个方法使cursor跳到下一个可得的结果集，抛弃当前集的所有剩下的行。如果有下一个结果集的话，返回True，否则返回None。

Cursor.

iter

()

Cursor.next()这个方法实现了Python迭代器协议。很可能你不会直接，而是间接使用迭代器调用它。

这是pymssql对于DB-API 2.0的扩展

Cursor.setinputsizes()

Cursor.setoutputsize()这两方法啥都不做，这是DB-API规范同意的。

异常

exception pymssql.StandardError异常继承树的根。

exception pymssql.Warning在重要的警告时抛出，如当插入时发生数据截断。StandardError的子类。

exception pymssql.Error其他所有错误异常的基类。你可以用它来通过一个except语句捕获所有错误。StandardError的子类。

exception pymssql.InterfaceError当发生与数据库接口相关而不是数据库本身相关的错误时抛出。Error的子类。

exception pymssql.DatabaseError当发生与数据库相关的错误时抛出。Error的子类。

exception pymssql.DataError当发生与处理数据相关的错误时抛出，如除以0、数值超出范围等。DatabaseError的子类。

exception pymssql.OperationalError当发生与数据库运作相关但不应该是由程序员操作导致的错误时抛出，如意外的连接中断、没有找到数据源名字，无法处理一个会话、处理过程中的内存分配错误等。DatabaseError的子类。

exception pymssql.IntegrityError当数据库的关系完整性受到影响时抛出，如外键检查失败。DatabaseError的子类。

exception pymssql.InternalError当数据库遇到内部错误时抛出，如cursor不再有效、会话不同步。DatabaseError的子类。

exception pymssql.ProgrammingError当发送编程错误时抛出，如没有发现表或表已存在、SQL语法错误、指定了错误数量的参数等。DatabaseError的子类。

exception pymssql.NotSupportedError当使用了数据库不支持的方法或数据库API，如在一个不支持会话或者会话已关闭的链接上要求rollback()。DatabaseError的子类。

exception pymssql.ColumnsWithoutNamesError当打开链接时指定as_dict=True，然后调用 Cursor.execute() 时发现结果中没有列名时抛出。InterfaceError的子类。

注意：ColumnsWithoutNamesError不是PEP-249授权的异常，而是一个pymssql扩展。