python pymssql - _mssql模块官方文档的翻译

一时失言乱红尘 2022-05-08 22:30 539阅读 0赞

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

# 模块级符号 #

\_mssql. **version**

见 pymssql. **version**.

\_mssql.VERSION

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

\_mssql. **full\_version**

见 pymssql. **full\_version**.

你可以修改其值以改变全局行为的变量：

\_mssql.login\_timeout

用秒表示的连接和登录超时时间，默认60秒。

\_mssql.min\_error\_severity

抛出异常的最小错误等级。默认值6在大部分情况下应该是合适的。

# 函数 #

\_mssql.set\_max\_connections(number)

设置同一时刻处于开启状态的链接的最大数量。默认25。

\_mssql.get\_max\_connections()

获取同一时刻处于开启状态的链接的最大数量。

# MSSQLConnection 类 #

class \_mssql.MSSQLConnection

这个类代表一个MS SQL数据库链接。你可以通过数据库链接发出queries并获取结果。

你可以通过调用\_mssql.connect()来创建这个类的一个实例。它接收以下参数。注意，除了位置定位的参数外，你还可以使用关键字参数。

<table> 
 <thead> 
  <tr> 
   <th align="center">参数名(类型)</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">server (str)</td> 
   <td align="left">你想要连接的数据库服务器和实体。如：<br> r’.\SQLEXPRESS’ –本地机器上的SQLEXPRESS实体(仅Windows)<br>r’(local)\SQLEXPRESS’ – 同上(仅Windows)<br>‘SQLHOST’ – 默认端口上的默认实体(仅Windows) <br>‘SQLHOST’ – 在freetds.conf中设置的指定端口上的指定实体 (仅Linux/*nix)<br>‘SQLHOST,1433’ – 指定主机上的指定TCP端口<br>’SQLHOST:1433’ – 同上<br>’SQLHOST,5000’ – 如果你已经设置了一个实体在端口5000进行监听<br>’SQLHOST:5000’ – 同上</td> 
  </tr> 
  <tr> 
   <td align="center">user (str)</td> 
   <td align="left">用于连接的数据库用户</td> 
  </tr> 
  <tr> 
   <td align="center">password (str)</td> 
   <td align="left">用户的密码</td> 
  </tr> 
  <tr> 
   <td align="center">charset (str)</td> 
   <td align="left">连接到数据库所使用的字符集名字</td> 
  </tr> 
  <tr> 
   <td align="center">database (str)</td> 
   <td align="left">链接初始化的数据库。默认情况下，SQL服务器会选择设置中特定用户所对应的默认数据库。</td> 
  </tr> 
  <tr> 
   <td align="center">appname (str)</td> 
   <td align="left">设置链接使用的应用名</td> 
  </tr> 
  <tr> 
   <td align="center">port (str)</td> 
   <td align="left">连接到服务器所使用的TCP端口号</td> 
  </tr> 
  <tr> 
   <td align="center">tds_version (str)</td> 
   <td align="left">使用的TDS协议版本，默认为None</td> 
  </tr> 
  <tr> 
   <td align="center">conn_properties</td> 
   <td align="left">当链接建立时发送给服务器的SQL queries。可以是一个字符串或者另一类可迭代的字符串组。默认值：见下面</td> 
  </tr> 
 </tbody> 
</table>

SET ARITHABORT ON;
    SET CONCAT_NULL_YIELDS_NULL ON;
    SET ANSI_NULLS ON;
    SET ANSI_NULL_DFLT_ON ON;
    SET ANSI_PADDING ON;
    SET ANSI_WARNINGS ON;
    SET ANSI_NULL_DFLT_ON ON;
    SET CURSOR_CLOSE_ON_COMMIT ON;
    SET QUOTED_IDENTIFIER ON;
    SET TEXTSIZE 2147483647; -- http://msdn.microsoft.com/en-us/library/aa259190%28v=sql.80%29.aspx

版本2.1.1中新特性：conn\_properties参数。  
版本2.1.1的变化：在2.1.1之前，现在由conn\_properties指定的初始化请求不是可定制的，其值硬编码为以上文本。  
版本2.1.1中新特性: 能连接Azure。  
版本2.2.0的变化: 参数tds\_version的默认值变为了None。在版本2.0.0与版本2.1.2之间，其默认值为’7.1’。

警告：

参数tds\_version的默认值为None。这意味着：  
1 .你不能依赖于旧的默认值’7.1’。  
2 .你得做以下其中一件事：  
· 通过传递值给这个参数直接指定它的值，或者  
· 使用FreeTDS提供的方法配置它  
可能这看起来很麻烦，但同时意味着你可以使用pymssql/\_mssql完整地配置链接的特性，而不用再管freetds.conf了。从版本2.0.0到版本2.1.2，已经可以设置连接到服务器时请求的TDS协议版本了，但如果没有指定的话，则使用版本7.1。

警告：

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

警告：

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

## 属性 ##

MSSQLConnection.connected

如果connection对象拥有一个已经打开的数据库链接则为True，否则为False。

MSSQLConnection.charset

传递给\_mssql.connect()的字符集名。

MSSQLConnection.identity

返回上一个插入的行的标识值。如果之前的操作没涉及向带有标识列的表中插入行，则返回None。用例 - 假设persons表包含一个标识列加上一个name列：

conn.execute_non_query("INSERT INTO persons (name) VALUES('John Doe')")
    print "Last inserted row has id = " + conn.identity

MSSQLConnection.query\_timeout

用秒表示的query超时时间，默认为0，0的意思是无限等待。由于DB库的工作方式，设置这个属性会影响所有从当前Python脚本打开的链接(或从技术上说，所有从这个dbinit()实例创建的链接) 。

MSSQLConnection.rows\_affected

上一个query所影响的行数。对于SELECT语句，只有在读了所有行后这个值才有意义。

MSSQLConnection.debug\_queries

如果设为true，所有query都会在格式化并完成参数引用后打印到stderr，然后才发送给SQL服务器。如果你怀疑格式化或参数引用上出了问题的话，这应该会有帮助。

MSSQLConnection.tds\_version

这个链接使用的TDS版本。可能为4.2、5.0、7.0、 7.1、7.2、7.3，或者如果没有探测到任何TDS版本的话为None。  
版本2.1.4的变化：为了正确性和一致性，在pymssql2.1.4中，用于指示TDS 7.1的值从8.0改为了7.1。  
版本2.1.3的变化：加入了7.3这个选项。

MSSQLConnection.tds\_version\_tuple

这是版本 2.2.0. 中新加的特性。  
元组形式的这条链接使用的TDS 版本，这样在程序中更容易处理(转换、比较)。可能为(4, 2)、 (5, 0)、 (7, 0)、 (7, 1)、 (7, 2)、 (7, 3) 或者如果没有探测到任何TDS版本的话为None。  
版本2.1.3的变化：加入了7.3这个选项。

## 方法 ##

MSSQLConnection.cancel()

取消所有从上个SQL操作以来挂起的结果。可以在同一行上多次调用。这种情况下不会抛出异常。

MSSQLConnection.close()

关闭链接并释放所有内存。可以在同一行上多次调用。这种情况下不会抛出异常。

MSSQLConnection.execute\_query(query\_string)  
MSSQLConnection.execute\_query(query\_string, params)

这个方法发送一条query给这个对象实例所连接的MS SQL数据库。当失败时会抛出一条异常。如果在执行这个命令之前有挂起的结果或者行，它们会被默默地丢掉。  
在调用这个方法之后，你可以迭代这个链接对象来获取query返回的行。  
你可以使用Python格式化，所有值都会被合理地引用。  
这个方法应该用于会返回结果的query，即SELECT。

MSSQLConnection.execute\_non\_query(query\_string)  
MSSQLConnection.execute\_non\_query(query\_string, params)

这个方法发送一条query给这个对象实例所连接的MS SQL数据库。它的结果(如果有)会被抛弃。当失败时会抛出一条异常。如果在执行这个命令之前有挂起的结果或者行，它们会被默默地丢掉。  
你可以使用Python格式化，所有值都会被合理地引用。  
这个方法很适合INSERT、 UPDATE、 DELETE和数据定义语言(Data Definition Language)，即当你想改变你的数据库的schema时。

MSSQLConnection.execute\_scalar(query\_string)  
MSSQLConnection.execute\_scalar(query\_string, params)

这个方法发送一条query给这个对象实例所连接的MS SQL数据库，然后返回结果的首行首列。当失败时会抛出一条异常。如果在执行这个命令之前有挂起的结果或者行，它们会被默默地丢掉。  
你可以使用Python格式化，所有值都会被合理地引用。  
如果你的query只返回一个值的话，这个方法就很有用了，如下例所示。这个方法的工作方式相当于iter(conn).next()\[0\]。如果还有剩下的行的话，你还是可以在调用这条命令后进行迭代。

count = conn.execute_scalar("SELECT COUNT(*) FROM employees")

MSSQLConnection.execute\_row(query\_string)  
MSSQLConnection.execute\_row(query\_string, params)

这个方法发送一条query给这个对象实例所连接的MS SQL数据库，然后返回结果的首行。当失败时会抛出一条异常。如果在执行这个命令之前有挂起的结果或者行，它们会被默默地丢掉。  
你可以使用Python格式化，所有值都会被合理地引用。  
如果你的query只返回一行并且不想或不需要迭代链接对象的话，这个方法就很有用了。这个方法的工作方式相当于iter(conn).next()。如果还有剩下的行的话，你还是可以在调用这条命令后进行迭代。

empinfo = conn.execute_row("SELECT * FROM employees WHERE empid=10")

MSSQLConnection.get\_header()

这个方法是一个基础函数，不需要由你的代码调用。它获取遵从Python DB-API的头信息。返回一个描述当前结果头的一个有7个元素的元组。只填充了名字和遵从的DB-API类型，剩下的都是None，这是规范许可的。

MSSQLConnection.init\_procedure(name)

创建一个MSSQLStoredProcedure对象，用于调用名字由name指定的存储过程。

MSSQLConnection.nextresult()

移到下一个结果集，跳过所有挂起的结果。这个方法获取并抛弃当前操作剩下的所有行，然后移到下一个结果(如果有的话)。如果有下一个结果集，则返回True，否则返回None。当失败时会抛出一条异常。

MSSQLConnection.select\_db(dbname)

这个函数把指定数据库变为当前数据库。当失败时会抛出一条异常。

MSSQLConnection. **iter**()  
MSSQLConnection.next()

这是版本 2.1.0. 中新加的特性。  
这两方法实现了Python迭代器协议。很可能你不会直接，而是间接使用迭代器调用它。

MSSQLConnection.set\_msghandler(handler)

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

这个方法为链接设置一个消息handler函数，这样客户端就可以访问从服务器返回的信息了。  
传递给这个方法的消息handler函数的签名应该是这样的：

def my_msg_handler(msgstate, severity, srvname, procname, line, msgtext):
        # The body of the message handler.

msgstate、severity和line是整型值；srvname、procname和msgtext是字符串.

# MSSQLStoredProcedure 类 #

class \_mssql.MSSQLStoredProcedure

这个类代表一个存储过程。你可以通过调用MSSQLConnection对象上的init\_procedure()方法来创建这个类的一个实例。

## 属性 ##

MSSQLStoredProcedure.connection

底层的MSSQLConnection对象。

[MSSQLStoredProcedure.name][]

这个对象代表的存储过程的名字。

MSSQLStoredProcedure.parameters

绑定到这个存储过程的参数们。

## 方法 ##

MSSQLStoredProcedure.bind(value, dbtype, name=None, output=False, null=False, max\_length=-1)

这个方法绑定一个参数到存储过程。value和dbtype是强制的，剩下的都是可选的。

<table> 
 <thead> 
  <tr> 
   <th align="center">参数名</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">value</td> 
   <td align="left">存储在参数中的值</td> 
  </tr> 
  <tr> 
   <td align="center">dbtype</td> 
   <td align="left">以下之一: SQLBINARY、SQLBIT、SQLBITN、SQLCHAR、SQLDATETIME、SQLDATETIM4、SQLDATETIMN、SQLDECIMAL、SQLFLT4、SQLFLT8、SQLFLTN、SQLIMAGE、SQLINT1、SQLINT2、SQLINT4、SQLINT8、SQLINTN、SQLMONEY、SQLMONEY4、SQLMONEYN、SQLNUMERIC、SQLREAL、SQLTEXT、SQLVARBINARY、SQLVARCHAR、SQLUUID</td> 
  </tr> 
  <tr> 
   <td align="center">name</td> 
   <td align="left">参数的名字。需要为"@name"这样的形式。</td> 
  </tr> 
  <tr> 
   <td align="center">output</td> 
   <td align="left">参数的方向。True表示是一个输出参数，即在存储过程执行后它返回一个值(在SQL DDL中是通过一个"output"后缀来声明它们的，如"@aname varchar(10) output")</td> 
  </tr> 
  <tr> 
   <td align="center">null</td> 
   <td align="left">Boolean类型。表明这个输入参数的值是NULL</td> 
  </tr> 
  <tr> 
   <td align="center">max_length</td> 
   <td align="left">从存储过程返回的这个参数的最大数据长度</td> 
  </tr> 
 </tbody> 
</table>

MSSQLStoredProcedure.execute()

执行这个存储过程。

# 模块级异常 #

异常继承树：

MSSQLException
    |
    +-- MSSQLDriverException
    |
    +-- MSSQLDatabaseException

exception \_mssql.MSSQLDriverException

只要\_mssql内部发生了问题，就会抛出MSSQLDriverException – 如数据结构的内存不足等。

exception \_mssql.MSSQLDatabaseException

只要数据库发生了问题，就会抛出MSSQLDatabaseException – 如query语法错误、无效对象名等。这种情况下，你可以使用以下属性来获得错误细节：  
number：错误码，是由SQL服务器返回的。  
severity：严重级别，是由SQL服务器返回的。如果这个属性的值低于\_mssql.min\_error\_severity的值，这个错误会被忽略，不会抛出异常。  
state：第三个错误码，是由SQL服务器返回的。  
message：错误信息，是由SQL服务器返回的。

[http_blog.csdn.net_lin_strong]: http://blog.csdn.net/lin_strong
[MSSQLStoredProcedure.name]: http://MSSQLStoredProcedure.name