~ntt-pf-lab/nova/monkey_patch_notification

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Twisted Documentation: twisted.enterprise.adbapi: Twisted RDBMS support</title>

</head>

<h1 class="title">twisted.enterprise.adbapi: Twisted RDBMS support</h1>

<div class="toc"><ol><li><a href="#auto0">Abstract</a></li><li><a href="#auto1">What you should already know</a></li><li><a href="#auto2">Quick Overview</a></li><li><a href="#auto3">How do I use adbapi?</a></li><li><a href="#auto4">Examples of various database adapters</a></li><li><a href="#auto5">And that's it!</a></li></ol></div>

<h2>Abstract<a name="auto0"/></h2>

Twisted is an asynchronous networking framework, but most

database API implementations unfortunately have blocking

interfaces -- for this reason, <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.enterprise.adbapi.html" title="twisted.enterprise.adbapi">twisted.enterprise.adbapi</a></code> was created. It is

a non-blocking interface to the standardized DB-API 2.0 API,

which allows you to access a number of different RDBMSes.

<h2>What you should already know<a name="auto1"/></h2>

<ul>

<li>Python :-)</li>

<li>How to write a simple Twisted Server (see <a href="servers.html" shape="rect">this tutorial</a> to learn how)</li>

<li>Familiarity with using database interfaces (see <a href="http://www.python.org/dev/peps/pep-0249/" shape="rect">

the documentation for DBAPI 2.0</a> or this <a href="http://www.amk.ca/python/writing/DB-API.html" shape="rect">article</a>

by Andrew Kuchling)</li>

</ul>

<h2>Quick Overview<a name="auto2"/></h2>

Twisted is an asynchronous framework. This means standard

database modules cannot be used directly, as they typically

work something like:

<pre class="python"> 1

# Create connection...

db = dbmodule.connect('mydb', 'andrew', 'password')

# ...which blocks for an unknown amount of time

# Create a cursor

cursor = db.cursor()

# Do a query...

resultset = cursor.query('SELECT * FROM table WHERE ...')

# ...which could take a long time, perhaps even minutes.

</pre>

Those delays are unacceptable when using an asynchronous

framework such as Twisted. For this reason, twisted provides

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.enterprise.adbapi.html" title="twisted.enterprise.adbapi">twisted.enterprise.adbapi</a></code>, an

asynchronous wrapper for any <a href="http://www.python.org/topics/database/DatabaseAPI-2.0.html" shape="rect">

DB-API 2.0</a>-compliant module.

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.enterprise.adbapi.html" title="twisted.enterprise.adbapi">enterprise.adbapi</a></code> will do

blocking

database operations in seperate threads, which trigger

callbacks in the originating thread when they complete. In the

meantime, the original thread can continue doing normal work,

like servicing other requests.

<h2>How do I use adbapi?<a name="auto3"/></h2>

Rather than creating a database connection directly, use the

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.enterprise.adbapi.ConnectionPool.html" title="twisted.enterprise.adbapi.ConnectionPool">adbapi.ConnectionPool</a></code>

class to manage

a connections for you. This allows <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.enterprise.adbapi.html" title="twisted.enterprise.adbapi">enterprise.adbapi</a></code> to use multiple

connections, one per thread. This is easy:

<pre class="python">1

# Using the "dbmodule" from the previous example, create a ConnectionPool

from twisted.enterprise import adbapi

dbpool = adbapi.ConnectionPool("dbmodule", 'mydb', 'andrew', 'password')

</pre>

Things to note about doing this:

<ul>

<li>There is no need to import dbmodule directly. You just

pass the name to <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.enterprise.adbapi.ConnectionPool.html" title="twisted.enterprise.adbapi.ConnectionPool">adbapi.ConnectionPool</a></code>'s constructor.</li>

<li>The parameters you would pass to dbmodule.connect are

passed as extra arguments to <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.enterprise.adbapi.ConnectionPool.html" title="twisted.enterprise.adbapi.ConnectionPool">adbapi.ConnectionPool</a></code>'s constructor.

Keyword parameters work as well.</li>

</ul>

Now we can do a database query:

100

101

<pre class="python"> 1

102

103

104

105

106

107

108

109

110

111

112

# equivalent of cursor.execute(statement), return cursor.fetchall():

113

def getAge(user):

114

return dbpool.runQuery("SELECT age FROM users WHERE name = ?", user)

115

116

def printResult(l):

117

if l:

118

print l[0][0], "years old"

119

else:

120

print "No such user"

121

122

getAge("joe").addCallback(printResult)

123

</pre>

124

125

This is straightforward, except perhaps for the return value

126

of <code>getAge</code>. It returns a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code>, which allows

127

arbitrary callbacks to be called upon completion (or upon

128

failure). More documentation on Deferred is available <a href="defer.html" shape="rect">here</a>.

129

130

In addition to <code>runQuery</code>, there is also <code>runOperation</code>,

131

and <code>runInteraction</code> that gets called with a callable (e.g. a function).

132

The function will be called in the thread with a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.enterprise.adbapi.Transaction.html" title="twisted.enterprise.adbapi.Transaction">twisted.enterprise.adbapi.Transaction</a></code>,

133

which basically mimics a DB-API cursor. In all cases a database transaction will be

134

commited after your database usage is finished, unless an exception is raised in

135

which case it will be rolled back.

136

137

<pre class="python"> 1

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

def _getAge(txn, user):

159

# this will run in a thread, we can use blocking calls

160

txn.execute("SELECT * FROM foo")

161

# ... other cursor commands called on txn ...

162

txn.execute("SELECT age FROM users WHERE name = ?", user)

163

result = txn.fetchall()

164

if result:

165

return result[0][0]

166

else:

167

return None

168

169

def getAge(user):

170

return dbpool.runInteraction(_getAge, user)

171

172

def printResult(age):

173

if age != None:

174

print age, "years old"

175

else:

176

print "No such user"

177

178

getAge("joe").addCallback(printResult)

179

</pre>

180

181

Also worth noting is that these examples assumes that dbmodule

182

uses the <q>qmarks</q> paramstyle (see the DB-API specification). If

183

your dbmodule uses a different paramstyle (e.g. pyformat) then

184

use that. Twisted doesn't attempt to offer any sort of magic

185

paramater munging -- <code class="python">runQuery(query,

186

params, ...)</code> maps directly onto <code class="python">cursor.execute(query, params, ...)</code>.

187

188

<h2>Examples of various database adapters<a name="auto4"/></h2>

189

190

Notice that the first argument is the module name you would

191

usually import and get <code class="python">connect(...)</code>

192

from, and that following arguments are whatever arguments you'd

193

call <code class="python">connect(...)</code> with.

194

195

<pre class="python"> 1

196

197

198

199

200

201

202

203

204

205

from twisted.enterprise import adbapi

206

207

# Gadfly

208

cp = adbapi.ConnectionPool("gadfly", "test", "/tmp/gadflyDB")

209

210

# PostgreSQL PyPgSQL

211

cp = adbapi.ConnectionPool("pyPgSQL.PgSQL", database="test")

212

213

# MySQL

214

cp = adbapi.ConnectionPool("MySQLdb", db="test")

215

</pre>

216

217

218

219

That's all you need to know to use a database from within

220

Twisted. You probably should read the adbapi module's

221

documentation to get an idea of the other functions it has, but

222

hopefully this document presents the core ideas.

223

</div>

224

225

<a href="index.html">Index</a>

226

Version: 10.0.0

227

</body>

228

</html>

b'\\ No newline at end of file'

Older »