DBUtils 用户指南

  • 格式:pdf
  • 大小:199.44 KB
  • 文档页数:8

DBUtils 用户指南

http://www.webwareforpython.org/DBUtils/Docs/UsersGuide.zh.html[2011/7/15 14:42:07]DBUtils 用户指南版本:0.9.4发行版:07/07/07翻译:English German Chinese目录摘要模块下载安装安装为顶层模块安装为Webware的子模块(插件)要求功能SimplePooledDBSteadyDBPersistentDBPooledDB该选择哪一个?使用方法PersistentDBPooledDB在Webware中使用注意未来功能错误报告与回馈链接作者列表版权与许可摘要DBUtils 是一套允许线程化 Python 程序可以安全和有效的访问数据库的模块。DBUtils已经作为 Webware for Python 一部分用来结合 PyGreSQL 访问 PostgreSQL 数据库,当然他也可以用在其他Python应用程序中来访问 DB-API 2 兼容的数据库接口。模块DBUtils实际上是一个包含两个子模块的Python包,一个用于连接DB-API 2模块,另一个用于连接典型的PyGreSQL模块。全局的DB-API 2变量SteadyDB.py用于稳定数据库连接PooledDB.py连接池PersistentDB.py维持持续的数据库连接DBUtils 用户指南

http://www.webwareforpython.org/DBUtils/Docs/UsersGuide.zh.html[2011/7/15 14:42:07]SimplePooledDB.py简单连接池典型的 PyGreSQL 变量SteadyPg.py稳定PyGreSQL连接PooledPg.pyPyGreSQL连接池PersistentPg.py维持持续的PyGreSQL连接SimplePooledPg.py简单的PyGreSQL连接池对标准DB-API 2模块的依赖如下图所示:对典型的PyGreSQL模块依赖如下图所示:下载你可以从 Webware 的网站下载最新版本:http://www.webwareforpython.org/downloads/DBUtils/也可以从Python Package Index来下载:http://www.python.org/pypi/DBUtils/安装安装为顶层模块如果你打算在除了Webware之外的程序中使用,推荐安装为顶层模块:python setup.py install安装为Webware的子模块(插件)如果你只是打算在Webware中使用,则可以按照如下安装:python setup.py install --install-lib=/path/to/Webware替换 /path/to/Webware 为Webware安装的根路径。你还需要运行Webware的安装程序来同时包含DBUtils的文档:DBUtils 用户指南

http://www.webwareforpython.org/DBUtils/Docs/UsersGuide.zh.html[2011/7/15 14:42:07]cd path/to/Webwarepython install.py要求DBUtils需要Python2.2或更高的版本。而典型的PyGreSQL则需要PyGreSQL3.4版本或更高。而DB-API 相关的则需要 DB-API 2 版本或更高的数据库接口模块。功能这一节的主要例子面向DB-API 2,但是也适用于典型的PyGreSQL模块。SimplePooledDBDBUtils.SimplePooledDB 是一个非常简单的数据库连接池实现。他比完善的 PooledDB 模块缺少很多功能。 DBUtils.SimplePooledDB 本质上类似于 MiscUtils.DBPool 这个Webware的组成部分。你可以把它看作一种演示程序。SteadyDBDBUtils.SteadyDB 是一个模块实现了"强硬"的数据库连接,基于DB-API 2建立的原始连接。一个"强硬"的连接意味着在连接关闭之后,或者使用次数操作限制时会重新连接。一个典型的例子是数据库重启时,而你的程序仍然在运行并需要访问数据库,或者当你的程序连接了一个防火墙后面的远程数据库,而防火墙重启时丢失了状态时。一般来说你不需要直接使用 SteadyDB 它只是给接下来的两个模块提供基本服务, PersistentDB 和 PooledDB 。PersistentDBDBUtils.PersistentDB 实现了强硬的、线程安全的、顽固的数据库连接,使用DB-API 2模块。如下图展示了使用 PersistentDB 时的连接层步骤:DBUtils 用户指南http://www.webwareforpython.org/DBUtils/Docs/UsersGuide.zh.html[2011/7/15 14:42:07]当一个线程首次打开一个数据库连接时,一个连接会打开并仅供这个线程使用。当线程关闭连接时,连接仍然持续打开供这个线程下次请求时使用这个已经打开的连接。连接在线程死亡时自动关闭。简单的来说 PersistentDB 尝试重用数据库连接来提高线程化程序的数据库访问性能,并且他确保连接不会被线程之间共享。因此, PersistentDB 可以在底层DB-API模块并非线程安全的时候同样工作的很好,并且他会在其他线程改变数据库会话或者使用多语句事务时同样避免问题的发生。PooledDBDBUtils.PooledDB 实现了一个强硬的、线程安全的、有缓存的、可复用的数据库连接,使用任何DB-API 2模块。如下图展示了使用 PooledDB 时的工作流程:DBUtils 用户指南http://www.webwareforpython.org/DBUtils/Docs/UsersGuide.zh.html[2011/7/15 14:42:07]如图所示 PooledDB 可以在不同线程之间共享打开的数据库连接。这在你连接并指定 maxshared 参数,并且底层的DB-API2接口是线程安全才可以,但是你仍然可以使用专用数据库连接而不在线程之间共享连接。除了共享连接以外,还可以设立一个至少 mincached 的连接池,并且最多允许使用 maxcached 个连接,这可以同时用于专用和共享连接池。当一个线程关闭了一个非共享连接,则会返还到空闲连接池中等待下次使用。如果底层DB-API模块是非线程安全的,线程锁会确保使用 PooledDB 是线程安全的。所以你并不需要为此担心,但是你在使用专用连接来改变数据库会话或执行多命令事务时必须小心。该选择哪一个?PersistentDB 和 PooledDB 都是为了重用数据库连接来提高性能,并保持数据库的稳定性。所以选择何种模块,可以参考上面的解释。 PersistentDB 将会保持一定数量的连接供频繁使用。在这种情况下你总是保持固定数量的连接。如果你的程序频繁的启动和关闭线程,最好使用 PooledDB 。后面将会提到更好的调整,尤其在使用线程安全的DB-API 2模块时。当然,这两个模块的接口是很相似的,你可以方便的在他们之间转换,并查看哪个更好一些。使用方法所有模块的使用方法都很相似,但是在初始化 "Pooled" 和 "Persistent" 时还有有些不同,尤其是DB-API和PyGreSQL之间。这里只讲解 PersistentDB 和更复杂的 PooledDB 模块。其他模块的细节请参与其文档。使用Python解释器控制台,你可以显示 PooledDB 的文档,如下:help(PooledDB)DBUtils 用户指南

http://www.webwareforpython.org/DBUtils/Docs/UsersGuide.zh.html[2011/7/15 14:42:07]PersistentDB为了使用 PersistentDB 你首先需要通过创建 PersistentDB 的实例来设置一个特定数据库连接的生成器,床底如下参数:creator: 可以使用任意返回 DB-API 2 连接对象的函数活 DB-API 2 兼容的数据库模块。maxusage: 一个连接最大允许复用次数(缺省为 0 或 False 意味着无限制的重用),当达到限制时,将会重新连接数据库setsession: 一个可选的SQL命令列表可以用于准备会话,如 ["set datestyle to german", ...]creator 函数或生成 DB-API 2 连接的函数,可以接受这里的附加参数,比如主机名、数据库、用户名、密码等等。你也可以选择传递给 creator 的其他参数,并允许提供失败重连和负载均衡。举个例子,如果你正在使用 pgdb 作为数据库模块并想要连接本机数据库 mydb ,允许重用1000次:import pgdb # import used DB-API 2 modulefrom DBUtils.PersistentDB import PersistentDBpersist = PersistentDB(pgdb, 1000, database='mydb')按照如上设置完成了连接生成器之后,你可以按照如下来请求一个连接:db = persist.connection()你可以使用这些连接就像使用原始的DB-API 2连接一样。实际上你得到的是一个通过``SteadyDB``得到的强硬的连接,基于DB-API 2。关闭一个强硬的连接使用 db.close() ,这在内部实际上被忽略掉了,并且供下次使用。在线程关闭时,也会自动关闭数据库连接。你可以改变这个行为通过 persist._closeable 为 True 。PooledDB为了使用 PooledDB 模块,你首先需要通过创建 PooledDB 来设置数据库连接池,传递如下参数:creator: 可以生成 DB-API 2 连接的任何函数或 DB-API 2 兼容的数据库连接模块。mincached : 启动时开启的空连接数量(缺省值 0 意味着开始时不创建连接)maxcached: 连接池使用的最多连接数量(缺省值 0 代表不限制连接池大小)maxshared: 最大允许的共享连接数量(缺省值 0 代表所有连接都是专用的)如果达到了最大数量,被请求为共享的连接将会被共享使用。maxconnections: 最大允许连接数量(缺省值 0 代表不限制)blocking: 设置在达到最大数量时的行为(缺省值 0 或 False 代表返回一个错误;其他代表阻塞直到连接数减少)maxusage: 单个连接的最大允许复用次数(缺省值 0 或 False 代表不限制的复用)。当达到最大数值时,连接会自动重新连接(关闭和重新打开)setsession: 一个可选的SQL命令列表用于准备每个会话,如 ["set datestyle to german", ...]creator 函数或可以生成连接的函数可以接受这里传入的其他参数,例如主机名、数据库、用户名、密码等。你还可以选择传入creator函数的其他参数,允许失败重连和负载均衡。举个例子,如果你正在使用 pgdb 作为DB-API模块,并希望连接池中至少有5个连接到数据库 mydbimport pgdb # import used DB-API 2 modulefrom DBUtils.PooledDB import PooledDBpool = PooledDB(pgdb, 5, database='mydb')一旦设置好了连接池,你就可以按照如下请求一个连接:db = pool.connection()你可以使用这些连接有如原始的DB-API 2一样。而实际使用的是``SteadyDB``版本的强硬连接。请注意连接可以与其他线程共享,只要你设置 maxshared 参数为非零,并且DB-API 2模块也允许。如果你想要使用专用连接则使用:db = pool.connection(0)