~ubuntu-branches/debian/jessie/sqlalchemy/jessie : revision 34

10

11

Working with Engines and Connections

12

—

13

SQLAlchemy 0.7 Documentation

13

SQLAlchemy 0.8 Documentation

14

15

</title>

16

20

21

var DOCUMENTATION_OPTIONS = {

22

URL_ROOT: '../',

23

VERSION: '0.7.9',

23

VERSION: '0.8.2',

24

COLLAPSE_MODINDEX: false,

25

FILE_SUFFIX: '.html'

26

};

32

33

34

35

35

36

37

38

55

56

57

58

<h1>SQLAlchemy 0.7 Documentation</h1>

58

<h1>SQLAlchemy 0.8 Documentation</h1>

59

60

61

Search:

67

</div>

68

69

70

Release: 0.7.9 | Release Date: October 1, 2012

70

Release: 0.8.2 | Release Date: July 3, 2013

71

72

73

</div>

93

</div>

94

95

96

<a href="../index.html">SQLAlchemy 0.7 Documentation</a>

96

<a href="../index.html">SQLAlchemy 0.8 Documentation</a>

97

» <a href="index.html" title="SQLAlchemy Core">SQLAlchemy Core</a>

98

»

99

Working with Engines and Connections

122

<li><a class="reference internal" href="#understanding-autocommit">Understanding Autocommit</a></li>

123

<li><a class="reference internal" href="#connectionless-execution-implicit-execution">Connectionless Execution, Implicit Execution</a></li>

124

<li><a class="reference internal" href="#using-the-threadlocal-execution-strategy">Using the Threadlocal Execution Strategy</a></li>

125

<li><a class="reference internal" href="#registering-new-dialects">Registering New Dialects</a><ul>

126

<li><a class="reference internal" href="#registering-dialects-in-process">Registering Dialects In-Process</a></li>

127

</ul>

128

</li>

125

129

<li><a class="reference internal" href="#connection-engine-api">Connection / Engine API</a></li>

126

130

</ul>

127

131

</li>

151

155

152

156

153

157

154

155

<h1>Working with Engines and Connections<a class="headerlink" href="#module-sqlalchemy.engine.base" title="Permalink to this headline">¶</a></h1>

156

This section details direct usage of the <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>,

157

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, and related objects. Its important to note that when

158

159

<h1>Working with Engines and Connections<a class="headerlink" href="#module-sqlalchemy.engine" title="Permalink to this headline">¶</a></h1>

160

This section details direct usage of the <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>,

161

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, and related objects. Its important to note that when

158

162

using the SQLAlchemy ORM, these objects are not generally accessed; instead,

159

163

the <a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object is used as the interface to the database.

160

164

However, for applications that are built around direct usage of textual SQL

161

165

statements and/or SQL expression constructs without involvement by the ORM’s

162

higher level management services, the <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> and

163

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> are king (and queen?) - read on.

166

higher level management services, the <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> and

167

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> are king (and queen?) - read on.

164

168

165

169

<h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h2>

166

Recall from <a class="reference internal" href="engines.html">Engine Configuration</a> that an <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> is created via

170

Recall from <a class="reference internal" href="engines.html">Engine Configuration</a> that an <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> is created via

167

171

the <a class="reference internal" href="engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal">create_engine()</tt></a> call:

168

172

<div class="highlight-python"><div class="highlight"><pre>engine = create_engine('mysql://scott:tiger@localhost/test')</pre></div>

169

173

</div>

170

174

The typical usage of <a class="reference internal" href="engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal">create_engine()</tt></a> is once per particular database

171

175

URL, held globally for the lifetime of a single application process. A single

172

<a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> manages many individual DBAPI connections on behalf of the

176

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> manages many individual DBAPI connections on behalf of the

173

177

process and is intended to be called upon in a concurrent fashion. The

174

<a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> is not synonymous to the DBAPI <tt class="docutils literal">connect</tt> function,

175

which represents just one connection resource - the <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> is most

178

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> is not synonymous to the DBAPI <tt class="docutils literal">connect</tt> function,

179

which represents just one connection resource - the <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> is most

176

180

efficient when created just once at the module level of an application, not

177

181

per-object or per-function call.

178

182

For a multiple-process application that uses the <tt class="docutils literal">os.fork</tt> system call, or

179

183

for example the Python <tt class="docutils literal">multiprocessing</tt> module, it’s usually required that a

180

separate <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> be used for each child process. This is because the

181

<a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> maintains a reference to a connection pool that ultimately

184

separate <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> be used for each child process. This is because the

185

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> maintains a reference to a connection pool that ultimately

182

186

references DBAPI connections - these tend to not be portable across process

183

boundaries. An <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> that is configured not to use pooling (which

187

boundaries. An <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> that is configured not to use pooling (which

184

188

is achieved via the usage of <a class="reference internal" href="pooling.html#sqlalchemy.pool.NullPool" title="sqlalchemy.pool.NullPool"><tt class="xref py py-class docutils literal">NullPool</tt></a>) does not have this

185

189

requirement.

186

190

The engine can be used directly to issue SQL to the database. The most generic

187

way is first procure a connection resource, which you get via the <tt class="xref py py-class docutils literal">connect</tt> method:

191

way is first procure a connection resource, which you get via the

192

<a class="reference internal" href="#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a> method:

188

193

<div class="highlight-python"><div class="highlight"><pre>connection = engine.connect()

189

194

result = connection.execute("select username from users")

190

195

for row in result:

191

196

print "username:", row['username']

192

197

connection.close()</pre></div>

193

198

</div>

194

The connection is an instance of <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>,

199

The connection is an instance of <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>,

195

200

which is a proxy object for an actual DBAPI connection. The DBAPI

196

201

connection is retrieved from the connection pool at the point at which

197

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is created.

198

The returned result is an instance of <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>, which

202

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is created.

203

The returned result is an instance of <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>, which

199

204

references a DBAPI cursor and provides a largely compatible interface

200

205

with that of the DBAPI cursor. The DBAPI cursor will be closed

201

by the <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> when all of its result rows (if any) are

202

exhausted. A <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> that returns no rows, such as that of

206

by the <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> when all of its result rows (if any) are

207

exhausted. A <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> that returns no rows, such as that of

203

208

an UPDATE statement (without any returned rows),

204

209

releases cursor resources immediately upon construction.

205

When the <a class="reference internal" href="#sqlalchemy.engine.base.Connection.close" title="sqlalchemy.engine.base.Connection.close"><tt class="xref py py-meth docutils literal">close()</tt></a> method is called, the referenced DBAPI

210

When the <a class="reference internal" href="#sqlalchemy.engine.Connection.close" title="sqlalchemy.engine.Connection.close"><tt class="xref py py-meth docutils literal">close()</tt></a> method is called, the referenced DBAPI

206

211

connection is <a class="reference internal" href="../glossary.html#term-released">released</a> to the connection pool. From the perspective

207

212

of the database itself, nothing is actually “closed”, assuming pooling is

208

213

in use. The pooling mechanism issues a <tt class="docutils literal">rollback()</tt> call on the DBAPI

209

214

connection so that any transactional state or locks are removed, and

210

215

the connection is ready for its next usage.

211

216

The above procedure can be performed in a shorthand way by using the

212

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.execute" title="sqlalchemy.engine.base.Engine.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method of <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> itself:

217

<a class="reference internal" href="#sqlalchemy.engine.Engine.execute" title="sqlalchemy.engine.Engine.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method of <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> itself:

213

218

<div class="highlight-python"><div class="highlight"><pre>result = engine.execute("select username from users")

214

219

for row in result:

215

220

print "username:", row['username']</pre></div>

216

221

</div>

217

Where above, the <a class="reference internal" href="#sqlalchemy.engine.base.Engine.execute" title="sqlalchemy.engine.base.Engine.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method acquires a new

218

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> on its own, executes the statement with that object,

219

and returns the <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>. In this case, the <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>

222

Where above, the <a class="reference internal" href="#sqlalchemy.engine.Engine.execute" title="sqlalchemy.engine.Engine.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method acquires a new

223

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> on its own, executes the statement with that object,

224

and returns the <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>. In this case, the <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>

220

225

contains a special flag known as <tt class="docutils literal">close_with_result</tt>, which indicates

221

that when its underlying DBAPI cursor is closed, the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

226

that when its underlying DBAPI cursor is closed, the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

222

227

object itself is also closed, which again returns the DBAPI connection

223

228

to the connection pool, releasing transactional resources.

224

If the <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> potentially has rows remaining, it can be

229

If the <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> potentially has rows remaining, it can be

225

230

instructed to close out its resources explicitly:

226

231

<div class="highlight-python"><div class="highlight"><pre>result.close()</pre></div>

227

232

</div>

228

If the <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> has pending rows remaining and is dereferenced by

233

If the <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> has pending rows remaining and is dereferenced by

229

234

the application without being closed, Python garbage collection will

230

235

ultimately close out the cursor as well as trigger a return of the pooled

231

236

DBAPI connection resource to the pool (SQLAlchemy achieves this by the usage

232

237

of weakref callbacks - never the <tt class="docutils literal">__del__</tt> method) - however it’s never a

233

238

good idea to rely upon Python garbage collection to manage resources.

234

239

Our example above illustrated the execution of a textual SQL string.

235

The <a class="reference internal" href="#sqlalchemy.engine.base.Connection.execute" title="sqlalchemy.engine.base.Connection.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method can of course accommodate more than

240

The <a class="reference internal" href="#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method can of course accommodate more than

236

241

that, including the variety of SQL expression constructs described

237

242

in <a class="reference internal" href="tutorial.html">SQL Expression Language Tutorial</a>.

238

243

</div>

241

246

242

247

Note

243

248

This section describes how to use transactions when working directly

244

with <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> and <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> objects. When using the

249

with <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> and <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> objects. When using the

245

250

SQLAlchemy ORM, the public API for transaction control is via the

246

<a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object, which makes usage of the <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

251

<a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object, which makes usage of the <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

247

252

object internally. See <a class="reference internal" href="../orm/session.html#unitofwork-transaction">Managing Transactions</a> for further

248

253

information.

249

254

</div>

250

The <tt class="xref py py-class docutils literal">Connection</tt> object provides a <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a>

251

method which returns a <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object.

255

The <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object provides a <a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a>

256

method which returns a <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object.

252

257

This object is usually used within a try/except clause so that it is

253

guaranteed to invoke <a class="reference internal" href="#sqlalchemy.engine.base.Transaction.rollback" title="sqlalchemy.engine.base.Transaction.rollback"><tt class="xref py py-meth docutils literal">Transaction.rollback()</tt></a> or <a class="reference internal" href="#sqlalchemy.engine.base.Transaction.commit" title="sqlalchemy.engine.base.Transaction.commit"><tt class="xref py py-meth docutils literal">Transaction.commit()</tt></a>:

258

guaranteed to invoke <a class="reference internal" href="#sqlalchemy.engine.Transaction.rollback" title="sqlalchemy.engine.Transaction.rollback"><tt class="xref py py-meth docutils literal">Transaction.rollback()</tt></a> or <a class="reference internal" href="#sqlalchemy.engine.Transaction.commit" title="sqlalchemy.engine.Transaction.commit"><tt class="xref py py-meth docutils literal">Transaction.commit()</tt></a>:

254

259

<div class="highlight-python"><div class="highlight"><pre>connection = engine.connect()

255

260

trans = connection.begin()

256

261

try:

262

267

raise</pre></div>

263

268

</div>

264

269

The above block can be created more succinctly using context

265

managers, either given an <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>:

270

managers, either given an <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>:

266

271

<div class="highlight-python"><div class="highlight"><pre># runs a transaction

267

272

with engine.begin() as connection:

268

273

r1 = connection.execute(table1.select())

269

274

connection.execute(table1.insert(), col1=7, col2='this is some data')</pre></div>

270

275

</div>

271

Or from the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, in which case the <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object

276

Or from the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, in which case the <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object

272

277

is available as well:

273

278

<div class="highlight-python"><div class="highlight"><pre>with connection.begin() as trans:

274

279

r1 = connection.execute(table1.select())

276

281

</div>

277

282

278

283

<h3>Nesting of Transaction Blocks<a class="headerlink" href="#nesting-of-transaction-blocks" title="Permalink to this headline">¶</a></h3>

279

The <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object also handles “nested”

284

The <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object also handles “nested”

280

285

behavior by keeping track of the outermost begin/commit pair. In this example,

281

two functions both issue a transaction on a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, but only the outermost

282

<a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object actually takes effect when it is committed.

286

two functions both issue a transaction on a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, but only the outermost

287

<a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object actually takes effect when it is committed.

283

288

<div class="highlight-python+sql"><div class="highlight"><pre># method_a starts a transaction and calls method_b

284

289

def method_a(connection):

285

290

trans = connection.begin() # open a transaction

319

324

</div>

320

325

321

326

<h2>Understanding Autocommit<a class="headerlink" href="#understanding-autocommit" title="Permalink to this headline">¶</a></h2>

322

The previous transaction example illustrates how to use <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

327

The previous transaction example illustrates how to use <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

323

328

so that several executions can take part in the same transaction. What happens

324

329

when we issue an INSERT, UPDATE or DELETE call without using

325

<a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>? While some DBAPI

330

<a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>? While some DBAPI

326

331

implementations provide various special “non-transactional” modes, the core

327

332

behavior of DBAPI per PEP-0249 is that a transaction is always in progress,

328

333

providing only <tt class="docutils literal">rollback()</tt> and <tt class="docutils literal">commit()</tt> methods but no <tt class="docutils literal">begin()</tt>.

340

345

<div class="highlight-python"><div class="highlight"><pre>conn = engine.connect()

341

346

conn.execute("INSERT INTO users VALUES (1, 'john')") # autocommits</pre></div>

342

347

</div>

343

The “autocommit” feature is only in effect when no <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> has

348

The “autocommit” feature is only in effect when no <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> has

344

349

otherwise been declared. This means the feature is not generally used with

345

350

the ORM, as the <a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object by default always maintains an

346

ongoing <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

351

ongoing <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

347

352

Full control of the “autocommit” behavior is available using the generative

348

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.execution_options" title="sqlalchemy.engine.base.Connection.execution_options"><tt class="xref py py-meth docutils literal">Connection.execution_options()</tt></a> method provided on <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>,

349

<a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>, <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal">Executable</tt></a>, using the “autocommit” flag which will

353

<a class="reference internal" href="#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal">Connection.execution_options()</tt></a> method provided on <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>,

354

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>, <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal">Executable</tt></a>, using the “autocommit” flag which will

350

355

turn on or off the autocommit for the selected scope. For example, a

351

356

<a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal">text()</tt></a> construct representing a stored procedure that commits might use

352

357

it so that a SELECT statement will issue a COMMIT:

356

361

357

362

<h2>Connectionless Execution, Implicit Execution<a class="headerlink" href="#connectionless-execution-implicit-execution" title="Permalink to this headline">¶</a></h2>

358

363

Recall from the first section we mentioned executing with and without explicit

359

usage of <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. “Connectionless” execution

364

usage of <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. “Connectionless” execution

360

365

refers to the usage of the <tt class="docutils literal">execute()</tt> method on an object which is not a

361

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. This was illustrated using the <a class="reference internal" href="#sqlalchemy.engine.base.Engine.execute" title="sqlalchemy.engine.base.Engine.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method

362

of <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>:

366

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. This was illustrated using the <a class="reference internal" href="#sqlalchemy.engine.Engine.execute" title="sqlalchemy.engine.Engine.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method

367

of <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>:

363

368

<div class="highlight-python"><div class="highlight"><pre>result = engine.execute("select username from users")

364

369

for row in result:

365

370

print "username:", row['username']</pre></div>

368

373

to use the <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable.execute" title="sqlalchemy.sql.expression.Executable.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method of

369

374

any <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal">Executable</tt></a> construct, which is a marker for SQL expression objects

370

375

that support execution. The SQL expression object itself references an

371

<a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> or <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> known as the bind, which it uses

376

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> or <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> known as the bind, which it uses

372

377

in order to provide so-called “implicit” execution services.

373

378

Given a table as below:

374

379

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy import MetaData, Table, Column, Integer

380

385

)</pre></div>

381

386

</div>

382

387

Explicit execution delivers the SQL text or constructed SQL expression to the

383

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.execute" title="sqlalchemy.engine.base.Connection.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method of <tt class="xref py py-class docutils literal">Connection</tt>:

388

<a class="reference internal" href="#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method of <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>:

384

389

<div class="highlight-python+sql"><div class="highlight"><pre>engine = create_engine('sqlite:///file.db')

385

390

connection = engine.connect()

386

391

result = connection.execute(users_table.select())

389

394

connection.close()</pre></div>

390

395

</div>

391

396

Explicit, connectionless execution delivers the expression to the

392

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.execute" title="sqlalchemy.engine.base.Engine.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method of <tt class="xref py py-class docutils literal">Engine</tt>:

397

<a class="reference internal" href="#sqlalchemy.engine.Engine.execute" title="sqlalchemy.engine.Engine.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a> method of <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>:

393

398

<div class="highlight-python+sql"><div class="highlight"><pre>engine = create_engine('sqlite:///file.db')

394

399

result = engine.execute(users_table.select())

395

400

for row in result:

401

406

<a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal">Executable</tt></a> class, which refers to a SQL statement that is sufficient

402

407

for being invoked against the database. The method makes usage of

403

408

the assumption that either an

404

<tt class="xref py py-class docutils literal">Engine</tt> or

405

<tt class="xref py py-class docutils literal">Connection</tt> has been bound to the expression

409

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> or

410

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> has been bound to the expression

406

411

object. By “bound” we mean that the special attribute <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.bind" title="sqlalchemy.schema.MetaData.bind"><tt class="xref py py-attr docutils literal">MetaData.bind</tt></a>

407

412

has been used to associate a series of

408

413

<a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects and all SQL constructs derived from them with a specific

414

419

# ....

415

420

result.close()</pre>

416

421

</div>

417

Above, we associate an <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> with a <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal">MetaData</tt></a> object using

422

Above, we associate an <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> with a <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal">MetaData</tt></a> object using

418

423

the special attribute <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.bind" title="sqlalchemy.schema.MetaData.bind"><tt class="xref py py-attr docutils literal">MetaData.bind</tt></a>. The <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> construct produced

419

424

from the <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> object has a method <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable.execute" title="sqlalchemy.sql.expression.Executable.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a>, which will

420

search for an <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> that’s “bound” to the <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>.

425

search for an <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> that’s “bound” to the <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>.

421

426

Overall, the usage of “bound metadata” has three general effects:

422

427

423

428

<li>SQL statement objects gain an <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable.execute" title="sqlalchemy.sql.expression.Executable.execute"><tt class="xref py py-meth docutils literal">Executable.execute()</tt></a> method which automatically

424

429

locates a “bind” with which to execute themselves.</li>

425

430

<li>The ORM <a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object supports using “bound metadata” in order

426

to establish which <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> should be used to invoke SQL statements

431

to establish which <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> should be used to invoke SQL statements

427

432

on behalf of a particular mapped class, though the <a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>

428

also features its own explicit system of establishing complex <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>/

433

also features its own explicit system of establishing complex <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>/

429

434

mapped class configurations.</li>

430

<li>The <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.create_all" title="sqlalchemy.schema.MetaData.create_all"><tt class="xref py py-meth docutils literal">MetaData.create_all()</tt></a>, <tt class="xref py py-meth docutils literal">Metadata.drop_all()</tt>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Table.create" title="sqlalchemy.schema.Table.create"><tt class="xref py py-meth docutils literal">Table.create()</tt></a>,

435

<li>The <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.create_all" title="sqlalchemy.schema.MetaData.create_all"><tt class="xref py py-meth docutils literal">MetaData.create_all()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.drop_all" title="sqlalchemy.schema.MetaData.drop_all"><tt class="xref py py-meth docutils literal">MetaData.drop_all()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Table.create" title="sqlalchemy.schema.Table.create"><tt class="xref py py-meth docutils literal">Table.create()</tt></a>,

431

436

<a class="reference internal" href="schema.html#sqlalchemy.schema.Table.drop" title="sqlalchemy.schema.Table.drop"><tt class="xref py py-meth docutils literal">Table.drop()</tt></a>, and “autoload” features all make usage of the bound

432

<a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> automatically without the need to pass it explicitly.</li>

437

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> automatically without the need to pass it explicitly.</li>

433

438

</ul>

434

439

435

440

Note

436

441

The concepts of “bound metadata” and “implicit execution” are not emphasized in modern SQLAlchemy.

437

442

While they offer some convenience, they are no longer required by any API and

438

443

are never necessary.

439

In applications where multiple <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> objects are present, each one logically associated

444

In applications where multiple <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> objects are present, each one logically associated

440

445

with a certain set of tables (i.e. vertical sharding), the “bound metadata” technique can be used

441

so that individual <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> can refer to the appropriate <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> automatically;

446

so that individual <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> can refer to the appropriate <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> automatically;

442

447

in particular this is supported within the ORM via the <a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object

443

as a means to associate <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects with an appropriate <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>,

448

as a means to associate <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects with an appropriate <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>,

444

449

as an alternative to using the bind arguments accepted directly by the <a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>.

445

450

However, the “implicit execution” technique is not at all appropriate for use with the

446

451

ORM, as it bypasses the transactional context maintained by the <a class="reference internal" href="../orm/session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>.

458

463

usually not the desired effect.

459

464

</div>

460

465

In both “connectionless” examples, the

461

<tt class="xref py py-class docutils literal">Connection</tt> is created behind the scenes; the

462

<tt class="xref py py-class docutils literal">ResultProxy</tt> returned by the <tt class="docutils literal">execute()</tt>

463

call references the <tt class="xref py py-class docutils literal">Connection</tt> used to issue

464

the SQL statement. When the <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> is closed, the underlying

465

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is closed for us, resulting in the

466

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is created behind the scenes; the

467

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> returned by the <tt class="docutils literal">execute()</tt>

468

call references the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> used to issue

469

the SQL statement. When the <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> is closed, the underlying

470

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is closed for us, resulting in the

466

471

DBAPI connection being returned to the pool with transactional resources removed.

467

472

</div>

468

473

471

476

can be used by non-ORM applications to associate transactions

472

477

with the current thread, such that all parts of the

473

478

application can participate in that transaction implicitly without the need to

474

explicitly reference a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

479

explicitly reference a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

475

480

476

481

Note

477

482

The “threadlocal” feature is generally discouraged. It’s

487

492

Enabling <tt class="docutils literal">threadlocal</tt> is achieved as follows:

488

493

<div class="highlight-python"><div class="highlight"><pre>db = create_engine('mysql://localhost/test', strategy='threadlocal')</pre></div>

489

494

</div>

490

The above <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> will now acquire a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> using

495

The above <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> will now acquire a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> using

491

496

connection resources derived from a thread-local variable whenever

492

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.execute" title="sqlalchemy.engine.base.Engine.execute"><tt class="xref py py-meth docutils literal">Engine.execute()</tt></a> or <a class="reference internal" href="#sqlalchemy.engine.base.Engine.contextual_connect" title="sqlalchemy.engine.base.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a> is called. This

497

<a class="reference internal" href="#sqlalchemy.engine.Engine.execute" title="sqlalchemy.engine.Engine.execute"><tt class="xref py py-meth docutils literal">Engine.execute()</tt></a> or <a class="reference internal" href="#sqlalchemy.engine.Engine.contextual_connect" title="sqlalchemy.engine.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a> is called. This

493

498

connection resource is maintained as long as it is referenced, which allows

494

499

multiple points of an application to share a transaction while using

495

500

connectionless execution:

508

513

db.rollback()</pre></div>

509

514

</div>

510

515

Explicit execution can be mixed with connectionless execution by

511

using the <tt class="xref py py-class docutils literal">Engine.connect</tt> method to acquire a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

516

using the <a class="reference internal" href="#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a> method to acquire a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

512

517

that is not part of the threadlocal scope:

513

518

<div class="highlight-python"><div class="highlight"><pre>db.begin()

514

519

conn = db.connect()

524

529

finally:

525

530

conn.close()</pre></div>

526

531

</div>

527

To access the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> that is bound to the threadlocal scope,

528

call <a class="reference internal" href="#sqlalchemy.engine.base.Engine.contextual_connect" title="sqlalchemy.engine.base.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a>:

532

To access the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> that is bound to the threadlocal scope,

533

call <a class="reference internal" href="#sqlalchemy.engine.Engine.contextual_connect" title="sqlalchemy.engine.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a>:

529

534

<div class="highlight-python"><div class="highlight"><pre>conn = db.contextual_connect()

530

535

call_operation3(conn)

531

536

conn.close()</pre></div>

532

537

</div>

533

Calling <a class="reference internal" href="#sqlalchemy.engine.base.Connection.close" title="sqlalchemy.engine.base.Connection.close"><tt class="xref py py-meth docutils literal">close()</tt></a> on the “contextual” connection does not <a class="reference internal" href="../glossary.html#term-release">release</a>

538

Calling <a class="reference internal" href="#sqlalchemy.engine.Connection.close" title="sqlalchemy.engine.Connection.close"><tt class="xref py py-meth docutils literal">close()</tt></a> on the “contextual” connection does not <a class="reference internal" href="../glossary.html#term-release">release</a>

534

539

its resources until all other usages of that resource are closed as well, including

535

540

that any ongoing transactions are rolled back or committed.

536

541

</div>

542

543

<h2>Registering New Dialects<a class="headerlink" href="#registering-new-dialects" title="Permalink to this headline">¶</a></h2>

544

The <a class="reference internal" href="engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal">create_engine()</tt></a> function call locates the given dialect

545

using setuptools entrypoints. These entry points can be established

546

for third party dialects within the setup.py script. For example,

547

to create a new dialect “foodialect://”, the steps are as follows:

548

549

<li>Create a package called <tt class="docutils literal">foodialect</tt>.

550

</li>

551

<li>The package should have a module containing the dialect class,

552

which is typically a subclass of <a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect" title="sqlalchemy.engine.default.DefaultDialect"><tt class="xref py py-class docutils literal">sqlalchemy.engine.default.DefaultDialect</tt></a>.

553

In this example let’s say it’s called <tt class="docutils literal">FooDialect</tt> and its module is accessed

554

via <tt class="docutils literal">foodialect.dialect</tt>.

555

</li>

556

<li>The entry point can be established in setup.py as follows:

557

<div class="highlight-python"><div class="highlight"><pre>entry_points="""

558

[sqlalchemy.dialects]

559

foodialect = foodialect.dialect:FooDialect

560

"""</pre></div>

561

</div>

562

</li>

563

</ol>

564

If the dialect is providing support for a particular DBAPI on top of

565

an existing SQLAlchemy-supported database, the name can be given

566

including a database-qualification. For example, if <tt class="docutils literal">FooDialect</tt>

567

were in fact a MySQL dialect, the entry point could be established like this:

568

<div class="highlight-python"><div class="highlight"><pre>entry_points="""

569

[sqlalchemy.dialects]

570

mysql.foodialect = foodialect.dialect:FooDialect

571

"""</pre></div>

572

</div>

573

The above entrypoint would then be accessed as <tt class="docutils literal">create_engine("mysql+foodialect://")</tt>.

574

575

<h3>Registering Dialects In-Process<a class="headerlink" href="#registering-dialects-in-process" title="Permalink to this headline">¶</a></h3>

576

SQLAlchemy also allows a dialect to be registered within the current process, bypassing

577

the need for separate installation. Use the <tt class="docutils literal">register()</tt> function as follows:

578

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.dialects import registry

579

registry.register("mysql.foodialect", "myapp.dialect", "MyMySQLDialect")</pre></div>

580

</div>

581

The above will respond to <tt class="docutils literal">create_engine("mysql+foodialect://")</tt> and load the

582

<tt class="docutils literal">MyMySQLDialect</tt> class from the <tt class="docutils literal">myapp.dialect</tt> module.

583

584

New in version 0.8.

585

</div>

586

</div>

537

587

538

588

<h2>Connection / Engine API<a class="headerlink" href="#connection-engine-api" title="Permalink to this headline">¶</a></h2>

539

589

540

541

class <tt class="descclassname">sqlalchemy.engine.base.</tt><tt class="descname">Connection</tt><big>(</big>engine, connection=None, close_with_result=False, _branch=False, _execution_options=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection" title="Permalink to this definition">¶</a></dt>

542

<dd>Bases: <a class="reference internal" href="#sqlalchemy.engine.base.Connectable" title="sqlalchemy.engine.base.Connectable"><tt class="xref py py-class docutils literal">sqlalchemy.engine.base.Connectable</tt></a>

590

591

class <tt class="descclassname">sqlalchemy.engine.</tt><tt class="descname">Connection</tt><big>(</big>engine, connection=None, close_with_result=False, _branch=False, _execution_options=None, _dispatch=None, _has_events=False<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection" title="Permalink to this definition">¶</a></dt>

592

<dd>Bases: <tt class="xref py py-class docutils literal">sqlalchemy.engine.interfaces.Connectable</tt>

543

593

Provides high-level functionality for a wrapped DB-API connection.

544

594

Provides execution support for string-based SQL statements as well as

545

<a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal">ClauseElement</tt></a>, <a class="reference internal" href="internals.html#sqlalchemy.engine.base.Compiled" title="sqlalchemy.engine.base.Compiled"><tt class="xref py py-class docutils literal">Compiled</tt></a> and <a class="reference internal" href="schema.html#sqlalchemy.schema.DefaultGenerator" title="sqlalchemy.schema.DefaultGenerator"><tt class="xref py py-class docutils literal">DefaultGenerator</tt></a>

546

objects. Provides a <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a> method to return <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

595

<a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal">ClauseElement</tt></a>, <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal">Compiled</tt></a> and <a class="reference internal" href="schema.html#sqlalchemy.schema.DefaultGenerator" title="sqlalchemy.schema.DefaultGenerator"><tt class="xref py py-class docutils literal">DefaultGenerator</tt></a>

596

objects. Provides a <a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a> method to return <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

547

597

objects.

548

598

The Connection object is not thread-safe. While a Connection can be

549

599

shared among threads using properly synchronized access, it is still

556

606

returned to the connection pool (i.e. <tt class="docutils literal">connection.close()</tt>) whenever the

557

607

connection is not in use.

558

608

559

560

<tt class="descname">__init__</tt><big>(</big>engine, connection=None, close_with_result=False, _branch=False, _execution_options=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.__init__" title="Permalink to this definition">¶</a></dt>

609

610

<tt class="descname">__init__</tt><big>(</big>engine, connection=None, close_with_result=False, _branch=False, _execution_options=None, _dispatch=None, _has_events=False<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.__init__" title="Permalink to this definition">¶</a></dt>

561

611

<dd>Construct a new Connection.

562

612

The constructor here is not public and is only called only by an

563

<a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>. See <a class="reference internal" href="#sqlalchemy.engine.base.Engine.connect" title="sqlalchemy.engine.base.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a> and

564

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.contextual_connect" title="sqlalchemy.engine.base.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a> methods.

613

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>. See <a class="reference internal" href="#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a> and

614

<a class="reference internal" href="#sqlalchemy.engine.Engine.contextual_connect" title="sqlalchemy.engine.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a> methods.

565

615

</dd></dl>

566

616

567

617

568

569

<tt class="descname">begin</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.begin" title="Permalink to this definition">¶</a></dt>

618

619

<tt class="descname">begin</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.begin" title="Permalink to this definition">¶</a></dt>

570

620

<dd>Begin a transaction and return a transaction handle.

571

The returned object is an instance of <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

621

The returned object is an instance of <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

572

622

This object represents the “scope” of the transaction,

573

which completes when either the <a class="reference internal" href="#sqlalchemy.engine.base.Transaction.rollback" title="sqlalchemy.engine.base.Transaction.rollback"><tt class="xref py py-meth docutils literal">Transaction.rollback()</tt></a>

574

or <a class="reference internal" href="#sqlalchemy.engine.base.Transaction.commit" title="sqlalchemy.engine.base.Transaction.commit"><tt class="xref py py-meth docutils literal">Transaction.commit()</tt></a> method is called.

575

Nested calls to <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a> on the same <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

576

will return new <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> objects that represent

623

which completes when either the <a class="reference internal" href="#sqlalchemy.engine.Transaction.rollback" title="sqlalchemy.engine.Transaction.rollback"><tt class="xref py py-meth docutils literal">Transaction.rollback()</tt></a>

624

or <a class="reference internal" href="#sqlalchemy.engine.Transaction.commit" title="sqlalchemy.engine.Transaction.commit"><tt class="xref py py-meth docutils literal">Transaction.commit()</tt></a> method is called.

625

Nested calls to <a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a> on the same <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

626

will return new <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> objects that represent

577

627

an emulated transaction within the scope of the enclosing

578

628

transaction, that is:

579

629

<div class="highlight-python"><div class="highlight"><pre>trans = conn.begin() # outermost transaction

581

631

trans2.commit() # does nothing

582

632

trans.commit() # actually commits</pre></div>

583

633

</div>

584

Calls to <a class="reference internal" href="#sqlalchemy.engine.base.Transaction.commit" title="sqlalchemy.engine.base.Transaction.commit"><tt class="xref py py-meth docutils literal">Transaction.commit()</tt></a> only have an effect

585

when invoked via the outermost <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object, though the

586

<a class="reference internal" href="#sqlalchemy.engine.base.Transaction.rollback" title="sqlalchemy.engine.base.Transaction.rollback"><tt class="xref py py-meth docutils literal">Transaction.rollback()</tt></a> method of any of the

587

<a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> objects will roll back the

634

Calls to <a class="reference internal" href="#sqlalchemy.engine.Transaction.commit" title="sqlalchemy.engine.Transaction.commit"><tt class="xref py py-meth docutils literal">Transaction.commit()</tt></a> only have an effect

635

when invoked via the outermost <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object, though the

636

<a class="reference internal" href="#sqlalchemy.engine.Transaction.rollback" title="sqlalchemy.engine.Transaction.rollback"><tt class="xref py py-meth docutils literal">Transaction.rollback()</tt></a> method of any of the

637

<a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> objects will roll back the

588

638

transaction.

589

639

See also:

590

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin_nested" title="sqlalchemy.engine.base.Connection.begin_nested"><tt class="xref py py-meth docutils literal">Connection.begin_nested()</tt></a> - use a SAVEPOINT

591

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin_twophase" title="sqlalchemy.engine.base.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a> - use a two phase /XID transaction

592

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.begin" title="sqlalchemy.engine.base.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a> - context manager available from <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

640

<a class="reference internal" href="#sqlalchemy.engine.Connection.begin_nested" title="sqlalchemy.engine.Connection.begin_nested"><tt class="xref py py-meth docutils literal">Connection.begin_nested()</tt></a> - use a SAVEPOINT

641

<a class="reference internal" href="#sqlalchemy.engine.Connection.begin_twophase" title="sqlalchemy.engine.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a> - use a two phase /XID transaction

642

<a class="reference internal" href="#sqlalchemy.engine.Engine.begin" title="sqlalchemy.engine.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a> - context manager available from

643

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

593

644

</dd></dl>

594

645

595

646

596

597

<tt class="descname">begin_nested</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.begin_nested" title="Permalink to this definition">¶</a></dt>

647

648

<tt class="descname">begin_nested</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.begin_nested" title="Permalink to this definition">¶</a></dt>

598

649

<dd>Begin a nested transaction and return a transaction handle.

599

The returned object is an instance of <a class="reference internal" href="#sqlalchemy.engine.base.NestedTransaction" title="sqlalchemy.engine.base.NestedTransaction"><tt class="xref py py-class docutils literal">NestedTransaction</tt></a>.

650

The returned object is an instance of <a class="reference internal" href="#sqlalchemy.engine.NestedTransaction" title="sqlalchemy.engine.NestedTransaction"><tt class="xref py py-class docutils literal">NestedTransaction</tt></a>.

600

651

Nested transactions require SAVEPOINT support in the

601

652

underlying database. Any transaction in the hierarchy may

602

653

<tt class="docutils literal">commit</tt> and <tt class="docutils literal">rollback</tt>, however the outermost transaction

603

654

still controls the overall <tt class="docutils literal">commit</tt> or <tt class="docutils literal">rollback</tt> of the

604

655

transaction of a whole.

605

See also <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a>,

606

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin_twophase" title="sqlalchemy.engine.base.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a>.

656

See also <a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a>,

657

<a class="reference internal" href="#sqlalchemy.engine.Connection.begin_twophase" title="sqlalchemy.engine.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a>.

607

658

</dd></dl>

608

659

609

660

610

611

<tt class="descname">begin_twophase</tt><big>(</big>xid=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.begin_twophase" title="Permalink to this definition">¶</a></dt>

661

662

<tt class="descname">begin_twophase</tt><big>(</big>xid=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.begin_twophase" title="Permalink to this definition">¶</a></dt>

612

663

<dd>Begin a two-phase or XA transaction and return a transaction

613

664

handle.

614

The returned object is an instance of <a class="reference internal" href="#sqlalchemy.engine.base.TwoPhaseTransaction" title="sqlalchemy.engine.base.TwoPhaseTransaction"><tt class="xref py py-class docutils literal">TwoPhaseTransaction</tt></a>,

665

The returned object is an instance of <a class="reference internal" href="#sqlalchemy.engine.TwoPhaseTransaction" title="sqlalchemy.engine.TwoPhaseTransaction"><tt class="xref py py-class docutils literal">TwoPhaseTransaction</tt></a>,

615

666

which in addition to the methods provided by

616

<a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>, also provides a <a class="reference internal" href="#sqlalchemy.engine.base.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.base.TwoPhaseTransaction.prepare"><tt class="xref py py-meth docutils literal">prepare()</tt></a>

617

method.

667

<a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>, also provides a

668

<a class="reference internal" href="#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.TwoPhaseTransaction.prepare"><tt class="xref py py-meth docutils literal">prepare()</tt></a> method.

618

669

619

670

620

671

624

675

</tr>

625

676

</tbody>

626

677

</table>

627

See also <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a>,

628

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin_twophase" title="sqlalchemy.engine.base.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a>.

678

See also <a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a>,

679

<a class="reference internal" href="#sqlalchemy.engine.Connection.begin_twophase" title="sqlalchemy.engine.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a>.

629

680

</dd></dl>

630

681

631

682

632

633

<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.close" title="Permalink to this definition">¶</a></dt>

634

<dd>Close this <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

683

684

<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.close" title="Permalink to this definition">¶</a></dt>

685

<dd>Close this <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

635

686

This results in a release of the underlying database

636

687

resources, that is, the DBAPI connection referenced

637

688

internally. The DBAPI connection is typically restored

638

689

back to the connection-holding <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal">Pool</tt></a> referenced

639

by the <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> that produced this

640

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. Any transactional state present on

690

by the <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> that produced this

691

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. Any transactional state present on

641

692

the DBAPI connection is also unconditionally released via

642

693

the DBAPI connection’s <tt class="docutils literal">rollback()</tt> method, regardless

643

of any <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object that may be

644

outstanding with regards to this <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

645

After <a class="reference internal" href="#sqlalchemy.engine.base.Connection.close" title="sqlalchemy.engine.base.Connection.close"><tt class="xref py py-meth docutils literal">close()</tt></a> is called, the

646

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is permanently in a closed state,

694

of any <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object that may be

695

outstanding with regards to this <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

696

After <a class="reference internal" href="#sqlalchemy.engine.Connection.close" title="sqlalchemy.engine.Connection.close"><tt class="xref py py-meth docutils literal">close()</tt></a> is called, the

697

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is permanently in a closed state,

647

698

and will allow no further operations.

648

699

</dd></dl>

649

700

650

701

651

652

<tt class="descname">closed</tt><a class="headerlink" href="#sqlalchemy.engine.base.Connection.closed" title="Permalink to this definition">¶</a></dt>

702

703

<tt class="descname">closed</tt><a class="headerlink" href="#sqlalchemy.engine.Connection.closed" title="Permalink to this definition">¶</a></dt>

653

704

<dd>Return True if this connection is closed.

654

705

</dd></dl>

655

706

656

707

657

658

<tt class="descname">connect</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.connect" title="Permalink to this definition">¶</a></dt>

659

<dd>Returns self.

660

This <tt class="docutils literal">Connectable</tt> interface method returns self, allowing

661

Connections to be used interchangeably with Engines in most

662

situations that require a bind.

708

709

<tt class="descname">connect</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.connect" title="Permalink to this definition">¶</a></dt>

710

<dd>Returns a branched version of this <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

711

The <a class="reference internal" href="#sqlalchemy.engine.Connection.close" title="sqlalchemy.engine.Connection.close"><tt class="xref py py-meth docutils literal">Connection.close()</tt></a> method on the returned

712

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> can be called and this

713

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> will remain open.

714

This method provides usage symmetry with

715

<a class="reference internal" href="#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a>, including for usage

716

with context managers.

663

717

</dd></dl>

664

718

665

719

666

667

<tt class="descname">connection</tt><a class="headerlink" href="#sqlalchemy.engine.base.Connection.connection" title="Permalink to this definition">¶</a></dt>

720

721

<tt class="descname">connection</tt><a class="headerlink" href="#sqlalchemy.engine.Connection.connection" title="Permalink to this definition">¶</a></dt>

668

722

<dd>The underlying DB-API connection managed by this Connection.

669

723

</dd></dl>

670

724

671

725

672

673

<tt class="descname">contextual_connect</tt><big>(</big>**kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.contextual_connect" title="Permalink to this definition">¶</a></dt>

674

<dd>Returns self.

675

This <tt class="docutils literal">Connectable</tt> interface method returns self, allowing

676

Connections to be used interchangeably with Engines in most

677

situations that require a bind.

678

</dd></dl>

679

680

681

682

<tt class="descname">create</tt><big>(</big>entity, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.create" title="Permalink to this definition">¶</a></dt>

683

<dd>Emit CREATE statements for the given schema entity.

684

685

Deprecated since version 0.7: Use the create() method on the given schema object directly, i.e. <a class="reference internal" href="schema.html#sqlalchemy.schema.Table.create" title="sqlalchemy.schema.Table.create"><tt class="xref py py-meth docutils literal">Table.create()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Index.create" title="sqlalchemy.schema.Index.create"><tt class="xref py py-meth docutils literal">Index.create()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.create_all" title="sqlalchemy.schema.MetaData.create_all"><tt class="xref py py-meth docutils literal">MetaData.create_all()</tt></a>

686

</dd></dl>

687

688

689

690

<tt class="descname">detach</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.detach" title="Permalink to this definition">¶</a></dt>

726

727

<tt class="descname">contextual_connect</tt><big>(</big>**kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.contextual_connect" title="Permalink to this definition">¶</a></dt>

728

<dd>Returns a branched version of this <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

729

The <a class="reference internal" href="#sqlalchemy.engine.Connection.close" title="sqlalchemy.engine.Connection.close"><tt class="xref py py-meth docutils literal">Connection.close()</tt></a> method on the returned

730

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> can be called and this

731

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> will remain open.

732

This method provides usage symmetry with

733

<a class="reference internal" href="#sqlalchemy.engine.Engine.contextual_connect" title="sqlalchemy.engine.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a>, including for usage

734

with context managers.

735

</dd></dl>

736

737

738

739

<tt class="descname">detach</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.detach" title="Permalink to this definition">¶</a></dt>

691

740

<dd>Detach the underlying DB-API connection from its connection pool.

692

741

This Connection instance will remain usable. When closed,

693

742

the DB-API connection will be literally closed and not

702

751

</dd></dl>

703

752

704

753

705

706

<tt class="descname">drop</tt><big>(</big>entity, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.drop" title="Permalink to this definition">¶</a></dt>

707

<dd>Emit DROP statements for the given schema entity.

708

709

Deprecated since version 0.7: Use the drop() method on the given schema object directly, i.e. <a class="reference internal" href="schema.html#sqlalchemy.schema.Table.drop" title="sqlalchemy.schema.Table.drop"><tt class="xref py py-meth docutils literal">Table.drop()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Index.drop" title="sqlalchemy.schema.Index.drop"><tt class="xref py py-meth docutils literal">Index.drop()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.drop_all" title="sqlalchemy.schema.MetaData.drop_all"><tt class="xref py py-meth docutils literal">MetaData.drop_all()</tt></a>

710

</dd></dl>

711

712

713

714

<tt class="descname">execute</tt><big>(</big>object, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.execute" title="Permalink to this definition">¶</a></dt>

715

<dd>Executes the a SQL statement construct and returns a <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>.

754

755

<tt class="descname">execute</tt><big>(</big>object, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.execute" title="Permalink to this definition">¶</a></dt>

756

<dd>Executes the a SQL statement construct and returns a

757

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>.

716

758

717

759

718

760

726

768

a subclass of <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal">Executable</tt></a>, such as a

727

769

<a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal">select()</tt></a> construct</li>

728

770

<li>a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.FunctionElement" title="sqlalchemy.sql.expression.FunctionElement"><tt class="xref py py-class docutils literal">FunctionElement</tt></a>, such as that generated

729

by <a class="reference internal" href="#sqlalchemy.engine.base.Engine.func" title="sqlalchemy.engine.base.Engine.func"><tt class="xref py py-attr docutils literal">func</tt></a>, will be automatically wrapped in

771

by <tt class="xref py py-attr docutils literal">func</tt>, will be automatically wrapped in

730

772

a SELECT statement, which is then executed.</li>

731

773

<li>a <a class="reference internal" href="schema.html#sqlalchemy.schema.DDLElement" title="sqlalchemy.schema.DDLElement"><tt class="xref py py-class docutils literal">DDLElement</tt></a> object</li>

732

774

<li>a <a class="reference internal" href="schema.html#sqlalchemy.schema.DefaultGenerator" title="sqlalchemy.schema.DefaultGenerator"><tt class="xref py py-class docutils literal">DefaultGenerator</tt></a> object</li>

733

<li>a <a class="reference internal" href="internals.html#sqlalchemy.engine.base.Compiled" title="sqlalchemy.engine.base.Compiled"><tt class="xref py py-class docutils literal">Compiled</tt></a> object</li>

775

<li>a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal">Compiled</tt></a> object</li>

734

776

</ul>

735

777

</li>

736

778

<li>*multiparams/**params – represent bound parameter

777

819

</dd></dl>

778

820

779

821

780

781

<tt class="descname">execution_options</tt><big>(</big>**opt<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.execution_options" title="Permalink to this definition">¶</a></dt>

822

823

<tt class="descname">execution_options</tt><big>(</big>**opt<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.execution_options" title="Permalink to this definition">¶</a></dt>

782

824

<dd>Set non-SQL options for the connection which take effect

783

825

during execution.

784

The method returns a copy of this <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> which references

826

The method returns a copy of this <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> which references

785

827

the same underlying DBAPI connection, but also defines the given

786

828

execution options which will take effect for a call to

787

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.execute" title="sqlalchemy.engine.base.Connection.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a>. As the new <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> references the same

788

underlying resource, it is probably best to ensure that the copies

829

<a class="reference internal" href="#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal">execute()</tt></a>. As the new <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> references the same

830

underlying resource, it’s usually a good idea to ensure that the copies

789

831

would be discarded immediately, which is implicit if used as in:

790

832

<div class="highlight-python"><div class="highlight"><pre>result = connection.execution_options(stream_results=True).\

791

833

execute(stmt)</pre></div>

792

834

</div>

793

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.execution_options" title="sqlalchemy.engine.base.Connection.execution_options"><tt class="xref py py-meth docutils literal">Connection.execution_options()</tt></a> accepts all options as those

794

accepted by <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><tt class="xref py py-meth docutils literal">Executable.execution_options()</tt></a>. Additionally,

795

it includes options that are applicable only to

796

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

835

Note that any key/value can be passed to

836

<a class="reference internal" href="#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal">Connection.execution_options()</tt></a>, and it will be stored in the

837

<tt class="docutils literal">_execution_options</tt> dictionary of the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. It

838

is suitable for usage by end-user schemes to communicate with

839

event listeners, for example.

840

The keywords that are currently recognized by SQLAlchemy itself

841

include all those listed under <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><tt class="xref py py-meth docutils literal">Executable.execution_options()</tt></a>,

842

as well as others that are specific to <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

797

843

798

844

799

845

813

859

calling stored procedures and such), and an explicit

814

860

transaction is not in progress.</li>

815

861

<li>compiled_cache – Available on: Connection.

816

A dictionary where <a class="reference internal" href="internals.html#sqlalchemy.engine.base.Compiled" title="sqlalchemy.engine.base.Compiled"><tt class="xref py py-class docutils literal">Compiled</tt></a> objects

817

will be cached when the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> compiles a clause

818

expression into a <a class="reference internal" href="internals.html#sqlalchemy.engine.base.Compiled" title="sqlalchemy.engine.base.Compiled"><tt class="xref py py-class docutils literal">Compiled</tt></a> object.

862

A dictionary where <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal">Compiled</tt></a> objects

863

will be cached when the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> compiles a clause

864

expression into a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal">Compiled</tt></a> object.

819

865

It is the user’s responsibility to

820

866

manage the size of this dictionary, which will have keys

821

867

corresponding to the dialect, clause element, the column

838

884

for further info.

839

885

Note that this option necessarily affects the underlying

840

886

DBAPI connection for the lifespan of the originating

841

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, and is not per-execution. This

887

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, and is not per-execution. This

842

888

setting is not removed until the underlying DBAPI connection

843

889

is returned to the connection pool, i.e.

844

the <a class="reference internal" href="#sqlalchemy.engine.base.Connection.close" title="sqlalchemy.engine.base.Connection.close"><tt class="xref py py-meth docutils literal">Connection.close()</tt></a> method is called.

890

the <a class="reference internal" href="#sqlalchemy.engine.Connection.close" title="sqlalchemy.engine.Connection.close"><tt class="xref py py-meth docutils literal">Connection.close()</tt></a> method is called.

845

891

</li>

846

892

<li>no_parameters – When <tt class="docutils literal">True</tt>, if the final parameter

847

893

list or dictionary is totally empty, will invoke the

870

916

</dd></dl>

871

917

872

918

873

874

<tt class="descname">in_transaction</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.in_transaction" title="Permalink to this definition">¶</a></dt>

919

920

<tt class="descname">in_transaction</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.in_transaction" title="Permalink to this definition">¶</a></dt>

875

921

<dd>Return True if a transaction is in progress.

876

922

</dd></dl>

877

923

878

924

879

880

881

<dd>A collection of per-DB-API connection instance properties.

925

926

927

<dd>Info dictionary associated with the underlying DBAPI connection

928

referred to by this <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, allowing user-defined

929

data to be associated with the connection.

930

The data here will follow along with the DBAPI connection including

931

after it is returned to the connection pool and used again

932

in subsequent instances of <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

882

933

</dd></dl>

883

934

884

935

885

886

<tt class="descname">invalidate</tt><big>(</big>exception=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.invalidate" title="Permalink to this definition">¶</a></dt>

936

937

<tt class="descname">invalidate</tt><big>(</big>exception=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.invalidate" title="Permalink to this definition">¶</a></dt>

887

938

<dd>Invalidate the underlying DBAPI connection associated with

888

939

this Connection.

889

940

The underlying DB-API connection is literally closed (if

899

950

</dd></dl>

900

951

901

952

902

903

<tt class="descname">invalidated</tt><a class="headerlink" href="#sqlalchemy.engine.base.Connection.invalidated" title="Permalink to this definition">¶</a></dt>

953

954

<tt class="descname">invalidated</tt><a class="headerlink" href="#sqlalchemy.engine.Connection.invalidated" title="Permalink to this definition">¶</a></dt>

904

955

<dd>Return True if this connection was invalidated.

905

956

</dd></dl>

906

957

907

958

908

909

<tt class="descname">reflecttable</tt><big>(</big>table, include_columns=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.reflecttable" title="Permalink to this definition">¶</a></dt>

910

<dd>Load table description from the database.

911

912

Deprecated since version 0.7: Use autoload=True with <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, or use the <a class="reference internal" href="schema.html#sqlalchemy.engine.reflection.Inspector" title="sqlalchemy.engine.reflection.Inspector"><tt class="xref py py-class docutils literal">Inspector</tt></a> object.

913

Given a <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> object, reflect its columns and

914

properties from the database, populating the given <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>

915

object with attributes.. If include_columns (a list or

916

set) is specified, limit the autoload to the given column

917

names.

918

The default implementation uses the

919

<a class="reference internal" href="schema.html#sqlalchemy.engine.reflection.Inspector" title="sqlalchemy.engine.reflection.Inspector"><tt class="xref py py-class docutils literal">Inspector</tt></a> interface to

920

provide the output, building upon the granular table/column/

921

constraint etc. methods of <a class="reference internal" href="internals.html#sqlalchemy.engine.base.Dialect" title="sqlalchemy.engine.base.Dialect"><tt class="xref py py-class docutils literal">Dialect</tt></a>.

922

</dd></dl>

923

924

925

926

<tt class="descname">run_callable</tt><big>(</big>callable_, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.run_callable" title="Permalink to this definition">¶</a></dt>

959

960

<tt class="descname">run_callable</tt><big>(</big>callable_, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.run_callable" title="Permalink to this definition">¶</a></dt>

927

961

<dd>Given a callable object or function, execute it, passing

928

a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> as the first argument.

962

a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> as the first argument.

929

963

The given *args and **kwargs are passed subsequent

930

to the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> argument.

931

This function, along with <a class="reference internal" href="#sqlalchemy.engine.base.Engine.run_callable" title="sqlalchemy.engine.base.Engine.run_callable"><tt class="xref py py-meth docutils literal">Engine.run_callable()</tt></a>,

932

allows a function to be run with a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

933

or <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> object without the need to know

964

to the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> argument.

965

This function, along with <a class="reference internal" href="#sqlalchemy.engine.Engine.run_callable" title="sqlalchemy.engine.Engine.run_callable"><tt class="xref py py-meth docutils literal">Engine.run_callable()</tt></a>,

966

allows a function to be run with a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

967

or <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> object without the need to know

934

968

which one is being dealt with.

935

969

</dd></dl>

936

970

937

971

938

939

<tt class="descname">scalar</tt><big>(</big>object, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.scalar" title="Permalink to this definition">¶</a></dt>

972

973

<tt class="descname">scalar</tt><big>(</big>object, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.scalar" title="Permalink to this definition">¶</a></dt>

940

974

<dd>Executes and returns the first column of the first row.

941

975

The underlying result/cursor is closed after execution.

942

976

</dd></dl>

943

977

944

978

945

946

<tt class="descname">transaction</tt><big>(</big>callable_, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connection.transaction" title="Permalink to this definition">¶</a></dt>

979

980

<tt class="descname">transaction</tt><big>(</big>callable_, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connection.transaction" title="Permalink to this definition">¶</a></dt>

947

981

<dd>Execute the given function within a transaction boundary.

948

The function is passed this <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

982

The function is passed this <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

949

983

as the first argument, followed by the given *args and **kwargs,

950

984

e.g.:

951

985

<div class="highlight-python"><div class="highlight"><pre>def do_something(conn, x, y):

954

988

conn.transaction(do_something, 5, 10)</pre></div>

955

989

</div>

956

990

The operations inside the function are all invoked within the

957

context of a single <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

991

context of a single <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

958

992

Upon success, the transaction is committed. If an

959

993

exception is raised, the transaction is rolled back

960

994

before propagating the exception.

961

995

962

996

Note

963

The <a class="reference internal" href="#sqlalchemy.engine.base.Connection.transaction" title="sqlalchemy.engine.base.Connection.transaction"><tt class="xref py py-meth docutils literal">transaction()</tt></a> method is superseded by

997

The <a class="reference internal" href="#sqlalchemy.engine.Connection.transaction" title="sqlalchemy.engine.Connection.transaction"><tt class="xref py py-meth docutils literal">transaction()</tt></a> method is superseded by

964

998

the usage of the Python <tt class="docutils literal">with:</tt> statement, which can

965

be used with <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a>:

999

be used with <a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a>:

966

1000

<div class="highlight-python"><div class="highlight"><pre>with conn.begin():

967

1001

conn.execute("some statement", {'x':5, 'y':10})</pre></div>

968

1002

</div>

969

As well as with <a class="reference internal" href="#sqlalchemy.engine.base.Engine.begin" title="sqlalchemy.engine.base.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a>:

1003

As well as with <a class="reference internal" href="#sqlalchemy.engine.Engine.begin" title="sqlalchemy.engine.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a>:

970

1004

<div class="last highlight-python"><div class="highlight"><pre>with engine.begin() as conn:

971

1005

conn.execute("some statement", {'x':5, 'y':10})</pre></div>

972

1006

</div>

973

1007

</div>

974

1008

See also:

975

1009

976

<div><a class="reference internal" href="#sqlalchemy.engine.base.Engine.begin" title="sqlalchemy.engine.base.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a> - engine-level transactional

1010

<div><a class="reference internal" href="#sqlalchemy.engine.Engine.begin" title="sqlalchemy.engine.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a> - engine-level transactional

977

1011

context

978

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.transaction" title="sqlalchemy.engine.base.Engine.transaction"><tt class="xref py py-meth docutils literal">Engine.transaction()</tt></a> - engine-level version of

979

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.transaction" title="sqlalchemy.engine.base.Connection.transaction"><tt class="xref py py-meth docutils literal">Connection.transaction()</tt></a>

1012

<a class="reference internal" href="#sqlalchemy.engine.Engine.transaction" title="sqlalchemy.engine.Engine.transaction"><tt class="xref py py-meth docutils literal">Engine.transaction()</tt></a> - engine-level version of

1013

<a class="reference internal" href="#sqlalchemy.engine.Connection.transaction" title="sqlalchemy.engine.Connection.transaction"><tt class="xref py py-meth docutils literal">Connection.transaction()</tt></a>

980

1014

</div></blockquote>

981

1015

</dd></dl>

982

1016

983

1017

</dd></dl>

984

1018

985

1019

986

987

class <tt class="descclassname">sqlalchemy.engine.base.</tt><tt class="descname">Connectable</tt><a class="headerlink" href="#sqlalchemy.engine.base.Connectable" title="Permalink to this definition">¶</a></dt>

1020

1021

class <tt class="descclassname">sqlalchemy.engine.</tt><tt class="descname">Connectable</tt><a class="headerlink" href="#sqlalchemy.engine.Connectable" title="Permalink to this definition">¶</a></dt>

988

1022

<dd>Bases: <tt class="xref py py-class docutils literal">object</tt>

989

1023

Interface for an object which supports execution of SQL constructs.

990

The two implementations of <a class="reference internal" href="#sqlalchemy.engine.base.Connectable" title="sqlalchemy.engine.base.Connectable"><tt class="xref py py-class docutils literal">Connectable</tt></a> are <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> and

991

<a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1024

The two implementations of <a class="reference internal" href="#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><tt class="xref py py-class docutils literal">Connectable</tt></a> are

1025

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> and <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

992

1026

Connectable must also implement the ‘dialect’ member which references a

993

<a class="reference internal" href="internals.html#sqlalchemy.engine.base.Dialect" title="sqlalchemy.engine.base.Dialect"><tt class="xref py py-class docutils literal">Dialect</tt></a> instance.

1027

<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal">Dialect</tt></a> instance.

994

1028

995

996

<tt class="descname">connect</tt><big>(</big>**kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connectable.connect" title="Permalink to this definition">¶</a></dt>

997

<dd>Return a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object.

1029

1030

<tt class="descname">connect</tt><big>(</big>**kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connectable.connect" title="Permalink to this definition">¶</a></dt>

1031

<dd>Return a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object.

998

1032

Depending on context, this may be <tt class="docutils literal">self</tt> if this object

999

is already an instance of <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, or a newly

1000

procured <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> if this object is an instance

1001

of <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1033

is already an instance of <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, or a newly

1034

procured <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> if this object is an instance

1035

of <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1002

1036

</dd></dl>

1003

1037

1004

1038

1005

1006

<tt class="descname">contextual_connect</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connectable.contextual_connect" title="Permalink to this definition">¶</a></dt>

1007

<dd>Return a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object which may be part of an ongoing

1039

1040

<tt class="descname">contextual_connect</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connectable.contextual_connect" title="Permalink to this definition">¶</a></dt>

1041

<dd>Return a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object which may be part of an ongoing

1008

1042

context.

1009

1043

Depending on context, this may be <tt class="docutils literal">self</tt> if this object

1010

is already an instance of <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, or a newly

1011

procured <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> if this object is an instance

1012

of <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1044

is already an instance of <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, or a newly

1045

procured <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> if this object is an instance

1046

of <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1013

1047

</dd></dl>

1014

1048

1015

1049

1016

1017

<tt class="descname">create</tt><big>(</big>entity, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connectable.create" title="Permalink to this definition">¶</a></dt>

1050

1051

<tt class="descname">create</tt><big>(</big>entity, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connectable.create" title="Permalink to this definition">¶</a></dt>

1018

1052

<dd>Emit CREATE statements for the given schema entity.

1019

1053

1020

1054

Deprecated since version 0.7: Use the create() method on the given schema object directly, i.e. <a class="reference internal" href="schema.html#sqlalchemy.schema.Table.create" title="sqlalchemy.schema.Table.create"><tt class="xref py py-meth docutils literal">Table.create()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Index.create" title="sqlalchemy.schema.Index.create"><tt class="xref py py-meth docutils literal">Index.create()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.create_all" title="sqlalchemy.schema.MetaData.create_all"><tt class="xref py py-meth docutils literal">MetaData.create_all()</tt></a>

1021

1055

</dd></dl>

1022

1056

1023

1057

1024

1025

<tt class="descname">drop</tt><big>(</big>entity, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connectable.drop" title="Permalink to this definition">¶</a></dt>

1058

1059

<tt class="descname">drop</tt><big>(</big>entity, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connectable.drop" title="Permalink to this definition">¶</a></dt>

1026

1060

<dd>Emit DROP statements for the given schema entity.

1027

1061

1028

1062

Deprecated since version 0.7: Use the drop() method on the given schema object directly, i.e. <a class="reference internal" href="schema.html#sqlalchemy.schema.Table.drop" title="sqlalchemy.schema.Table.drop"><tt class="xref py py-meth docutils literal">Table.drop()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Index.drop" title="sqlalchemy.schema.Index.drop"><tt class="xref py py-meth docutils literal">Index.drop()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.drop_all" title="sqlalchemy.schema.MetaData.drop_all"><tt class="xref py py-meth docutils literal">MetaData.drop_all()</tt></a>

1029

1063

</dd></dl>

1030

1064

1031

1065

1032

1033

<tt class="descname">execute</tt><big>(</big>object, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connectable.execute" title="Permalink to this definition">¶</a></dt>

1034

<dd>Executes the given construct and returns a <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>.

1066

1067

<tt class="descname">execute</tt><big>(</big>object, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connectable.execute" title="Permalink to this definition">¶</a></dt>

1068

<dd>Executes the given construct and returns a <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>.

1035

1069

</dd></dl>

1036

1070

1037

1071

1038

1039

<tt class="descname">scalar</tt><big>(</big>object, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Connectable.scalar" title="Permalink to this definition">¶</a></dt>

1072

1073

<tt class="descname">scalar</tt><big>(</big>object, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Connectable.scalar" title="Permalink to this definition">¶</a></dt>

1040

1074

<dd>Executes and returns the first column of the first row.

1041

1075

The underlying cursor is closed after execution.

1042

1076

</dd></dl>

1044

1078

</dd></dl>

1045

1079

1046

1080

1047

1048

class <tt class="descclassname">sqlalchemy.engine.base.</tt><tt class="descname">Engine</tt><big>(</big>pool, dialect, url, logging_name=None, echo=None, proxy=None, execution_options=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine" title="Permalink to this definition">¶</a></dt>

1049

<dd>Bases: <a class="reference internal" href="#sqlalchemy.engine.base.Connectable" title="sqlalchemy.engine.base.Connectable"><tt class="xref py py-class docutils literal">sqlalchemy.engine.base.Connectable</tt></a>, <tt class="xref py py-class docutils literal">sqlalchemy.log.Identified</tt>

1081

1082

class <tt class="descclassname">sqlalchemy.engine.</tt><tt class="descname">Engine</tt><big>(</big>pool, dialect, url, logging_name=None, echo=None, proxy=None, execution_options=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine" title="Permalink to this definition">¶</a></dt>

1083

<dd>Bases: <tt class="xref py py-class docutils literal">sqlalchemy.engine.interfaces.Connectable</tt>, <tt class="xref py py-class docutils literal">sqlalchemy.log.Identified</tt>

1050

1084

Connects a <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal">Pool</tt></a> and

1051

<a class="reference internal" href="internals.html#sqlalchemy.engine.base.Dialect" title="sqlalchemy.engine.base.Dialect"><tt class="xref py py-class docutils literal">Dialect</tt></a> together to provide a source

1052

of database connectivity and behavior.

1053

An <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> object is instantiated publicly using the

1085

<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal">Dialect</tt></a> together to provide a

1086

source of database connectivity and behavior.

1087

An <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> object is instantiated publicly using the

1054

1088

<a class="reference internal" href="engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal">create_engine()</tt></a> function.

1055

1089

See also:

1056

1090

<a class="reference internal" href="engines.html">Engine Configuration</a>

1057

1091

<a class="reference internal" href="#">Working with Engines and Connections</a>

1058

1092

1059

1060

<tt class="descname">begin</tt><big>(</big>close_with_result=False<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.begin" title="Permalink to this definition">¶</a></dt>

1061

<dd>Return a context manager delivering a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

1062

with a <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> established.

1093

1094

<tt class="descname">begin</tt><big>(</big>close_with_result=False<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.begin" title="Permalink to this definition">¶</a></dt>

1095

<dd>Return a context manager delivering a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

1096

with a <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> established.

1063

1097

E.g.:

1064

1098

<div class="highlight-python"><div class="highlight"><pre>with engine.begin() as conn:

1065

1099

conn.execute("insert into table (x, y, z) values (1, 2, 3)")

1066

1100

conn.execute("my_special_procedure(5)")</pre></div>

1067

1101

</div>

1068

Upon successful operation, the <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

1069

is committed. If an error is raised, the <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

1102

Upon successful operation, the <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

1103

is committed. If an error is raised, the <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

1070

1104

is rolled back.

1071

1105

The <tt class="docutils literal">close_with_result</tt> flag is normally <tt class="docutils literal">False</tt>, and indicates

1072

that the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> will be closed when the operation

1073

is complete. When set to <tt class="docutils literal">True</tt>, it indicates the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

1074

is in “single use” mode, where the <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>

1075

returned by the first call to <a class="reference internal" href="#sqlalchemy.engine.base.Connection.execute" title="sqlalchemy.engine.base.Connection.execute"><tt class="xref py py-meth docutils literal">Connection.execute()</tt></a> will

1076

close the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> when that <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>

1077

has exhausted all result rows.

1106

that the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> will be closed when the operation

1107

is complete. When set to <tt class="docutils literal">True</tt>, it indicates the

1108

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is in “single use” mode, where the

1109

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> returned by the first call to

1110

<a class="reference internal" href="#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal">Connection.execute()</tt></a> will close the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> when

1111

that <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> has exhausted all result rows.

1078

1112

1079

1113

New in version 0.7.6.

1080

1114

See also:

1081

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.connect" title="sqlalchemy.engine.base.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a> - procure a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> from

1082

an <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1083

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a> - start a <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

1084

for a particular <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

1085

</dd></dl>

1086

1087

1088

1089

<tt class="descname">connect</tt><big>(</big>**kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.connect" title="Permalink to this definition">¶</a></dt>

1090

<dd>Return a new <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object.

1091

The <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object is a facade that uses a DBAPI connection internally

1092

in order to communicate with the database. This connection is procured

1093

from the connection-holding <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal">Pool</tt></a> referenced by this <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1094

When the <a class="reference internal" href="#sqlalchemy.engine.base.Connection.close" title="sqlalchemy.engine.base.Connection.close"><tt class="xref py py-meth docutils literal">close()</tt></a> method of the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object is called,

1095

the underlying DBAPI connection is then returned to the connection pool,

1096

where it may be used again in a subsequent call to <a class="reference internal" href="#sqlalchemy.engine.base.Engine.connect" title="sqlalchemy.engine.base.Engine.connect"><tt class="xref py py-meth docutils literal">connect()</tt></a>.

1097

</dd></dl>

1098

1099

1100

1101

<tt class="descname">contextual_connect</tt><big>(</big>close_with_result=False, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.contextual_connect" title="Permalink to this definition">¶</a></dt>

1102

<dd>Return a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object which may be part of some ongoing context.

1103

By default, this method does the same thing as <a class="reference internal" href="#sqlalchemy.engine.base.Engine.connect" title="sqlalchemy.engine.base.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a>.

1104

Subclasses of <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> may override this method

1115

<a class="reference internal" href="#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a> - procure a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> from

1116

an <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1117

<a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a> - start a <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

1118

for a particular <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>.

1119

</dd></dl>

1120

1121

1122

1123

<tt class="descname">connect</tt><big>(</big>**kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.connect" title="Permalink to this definition">¶</a></dt>

1124

<dd>Return a new <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object.

1125

The <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object is a facade that uses a DBAPI

1126

connection internally in order to communicate with the database. This

1127

connection is procured from the connection-holding <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal">Pool</tt></a>

1128

referenced by this <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>. When the

1129

<a class="reference internal" href="#sqlalchemy.engine.Connection.close" title="sqlalchemy.engine.Connection.close"><tt class="xref py py-meth docutils literal">close()</tt></a> method of the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object

1130

is called, the underlying DBAPI connection is then returned to the

1131

connection pool, where it may be used again in a subsequent call to

1132

<a class="reference internal" href="#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><tt class="xref py py-meth docutils literal">connect()</tt></a>.

1133

</dd></dl>

1134

1135

1136

1137

<tt class="descname">contextual_connect</tt><big>(</big>close_with_result=False, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.contextual_connect" title="Permalink to this definition">¶</a></dt>

1138

<dd>Return a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object which may be part of some

1139

ongoing context.

1140

By default, this method does the same thing as <a class="reference internal" href="#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a>.

1141

Subclasses of <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> may override this method

1105

1142

to provide contextual behavior.

1106

1143

1107

1144

1108

1145

1109

1146

1110

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body">close_with_result – When True, the first <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> created

1111

by the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> will call the <a class="reference internal" href="#sqlalchemy.engine.base.Connection.close" title="sqlalchemy.engine.base.Connection.close"><tt class="xref py py-meth docutils literal">Connection.close()</tt></a> method

1112

of that connection as soon as any pending result rows are exhausted.

1113

This is used to supply the “connectionless execution” behavior provided

1114

by the <a class="reference internal" href="#sqlalchemy.engine.base.Engine.execute" title="sqlalchemy.engine.base.Engine.execute"><tt class="xref py py-meth docutils literal">Engine.execute()</tt></a> method.</td>

1147

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body">close_with_result – When True, the first <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>

1148

created by the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> will call the

1149

<a class="reference internal" href="#sqlalchemy.engine.Connection.close" title="sqlalchemy.engine.Connection.close"><tt class="xref py py-meth docutils literal">Connection.close()</tt></a> method of that connection as soon as any

1150

pending result rows are exhausted. This is used to supply the

1151

“connectionless execution” behavior provided by the

1152

<a class="reference internal" href="#sqlalchemy.engine.Engine.execute" title="sqlalchemy.engine.Engine.execute"><tt class="xref py py-meth docutils literal">Engine.execute()</tt></a> method.</td>

1115

1153

</tr>

1116

1154

</tbody>

1117

1155

</table>

1118

1156

</dd></dl>

1119

1157

1120

1158

1121

1122

<tt class="descname">create</tt><big>(</big>entity, connection=None, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.create" title="Permalink to this definition">¶</a></dt>

1123

<dd>Emit CREATE statements for the given schema entity.

1124

1125

Deprecated since version 0.7: Use the create() method on the given schema object directly, i.e. <a class="reference internal" href="schema.html#sqlalchemy.schema.Table.create" title="sqlalchemy.schema.Table.create"><tt class="xref py py-meth docutils literal">Table.create()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Index.create" title="sqlalchemy.schema.Index.create"><tt class="xref py py-meth docutils literal">Index.create()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.create_all" title="sqlalchemy.schema.MetaData.create_all"><tt class="xref py py-meth docutils literal">MetaData.create_all()</tt></a>

1126

</dd></dl>

1127

1128

1129

1130

<tt class="descname">dispose</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.dispose" title="Permalink to this definition">¶</a></dt>

1131

<dd>Dispose of the connection pool used by this <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1159

1160

<tt class="descname">dispose</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.dispose" title="Permalink to this definition">¶</a></dt>

1161

<dd>Dispose of the connection pool used by this <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1132

1162

A new connection pool is created immediately after the old one has

1133

1163

been disposed. This new pool, like all SQLAlchemy connection pools,

1134

1164

does not make any actual connections to the database until one is

1139

1169

<li>When a dropped connection is detected, it is assumed that all

1140

1170

connections held by the pool are potentially dropped, and

1141

1171

the entire pool is replaced.</li>

1142

<li>An application may want to use <a class="reference internal" href="#sqlalchemy.engine.base.Engine.dispose" title="sqlalchemy.engine.base.Engine.dispose"><tt class="xref py py-meth docutils literal">dispose()</tt></a> within a test

1172

<li>An application may want to use <a class="reference internal" href="#sqlalchemy.engine.Engine.dispose" title="sqlalchemy.engine.Engine.dispose"><tt class="xref py py-meth docutils literal">dispose()</tt></a> within a test

1143

1173

suite that is creating multiple engines.</li>

1144

1174

</ul>

1145

1175

</div></blockquote>

1146

It is critical to note that <a class="reference internal" href="#sqlalchemy.engine.base.Engine.dispose" title="sqlalchemy.engine.base.Engine.dispose"><tt class="xref py py-meth docutils literal">dispose()</tt></a> does not guarantee

1176

It is critical to note that <a class="reference internal" href="#sqlalchemy.engine.Engine.dispose" title="sqlalchemy.engine.Engine.dispose"><tt class="xref py py-meth docutils literal">dispose()</tt></a> does not guarantee

1147

1177

that the application will release all open database connections - only

1148

1178

those connections that are checked into the pool are closed.

1149

1179

Connections which remain checked out or have been detached from

1151

1181

</dd></dl>

1152

1182

1153

1183

1154

1155

<tt class="descname">driver</tt><a class="headerlink" href="#sqlalchemy.engine.base.Engine.driver" title="Permalink to this definition">¶</a></dt>

1156

<dd>Driver name of the <tt class="xref py py-class docutils literal">Dialect</tt> in use by

1157

this <tt class="docutils literal">Engine</tt>.

1158

</dd></dl>

1159

1160

1161

1162

<tt class="descname">drop</tt><big>(</big>entity, connection=None, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.drop" title="Permalink to this definition">¶</a></dt>

1163

<dd>Emit DROP statements for the given schema entity.

1164

1165

Deprecated since version 0.7: Use the drop() method on the given schema object directly, i.e. <a class="reference internal" href="schema.html#sqlalchemy.schema.Table.drop" title="sqlalchemy.schema.Table.drop"><tt class="xref py py-meth docutils literal">Table.drop()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.Index.drop" title="sqlalchemy.schema.Index.drop"><tt class="xref py py-meth docutils literal">Index.drop()</tt></a>, <a class="reference internal" href="schema.html#sqlalchemy.schema.MetaData.drop_all" title="sqlalchemy.schema.MetaData.drop_all"><tt class="xref py py-meth docutils literal">MetaData.drop_all()</tt></a>

1166

</dd></dl>

1167

1168

1169

1170

<tt class="descname">execute</tt><big>(</big>statement, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.execute" title="Permalink to this definition">¶</a></dt>

1171

<dd>Executes the given construct and returns a <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>.

1184

1185

<tt class="descname">driver</tt><a class="headerlink" href="#sqlalchemy.engine.Engine.driver" title="Permalink to this definition">¶</a></dt>

1186

<dd>Driver name of the <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal">Dialect</tt></a>

1187

in use by this <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1188

</dd></dl>

1189

1190

1191

1192

<tt class="descname">execute</tt><big>(</big>statement, *multiparams, **params<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.execute" title="Permalink to this definition">¶</a></dt>

1193

<dd>Executes the given construct and returns a <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a>.

1172

1194

The arguments are the same as those used by

1173

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.execute" title="sqlalchemy.engine.base.Connection.execute"><tt class="xref py py-meth docutils literal">Connection.execute()</tt></a>.

1174

Here, a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is acquired using the

1175

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.contextual_connect" title="sqlalchemy.engine.base.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">contextual_connect()</tt></a> method, and the statement executed

1176

with that connection. The returned <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> is flagged

1177

such that when the <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> is exhausted and its

1178

underlying cursor is closed, the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> created here

1195

<a class="reference internal" href="#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal">Connection.execute()</tt></a>.

1196

Here, a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is acquired using the

1197

<a class="reference internal" href="#sqlalchemy.engine.Engine.contextual_connect" title="sqlalchemy.engine.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">contextual_connect()</tt></a> method, and the statement executed

1198

with that connection. The returned <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> is flagged

1199

such that when the <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> is exhausted and its

1200

underlying cursor is closed, the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> created here

1179

1201

will also be closed, which allows its associated DBAPI connection

1180

1202

resource to be returned to the connection pool.

1181

1203

</dd></dl>

1182

1204

1183

1184

1185

1186

<dd>

1187

Deprecated since version 0.7: Use <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-attr docutils literal">func</tt></a> to create function constructs.

1188

</dd></dl>

1189

1190

1191

1192

1193

<dd>String name of the <tt class="xref py py-class docutils literal">Dialect</tt> in use by

1194

this <tt class="docutils literal">Engine</tt>.

1195

</dd></dl>

1196

1197

1198

1199

<tt class="descname">raw_connection</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.raw_connection" title="Permalink to this definition">¶</a></dt>

1205

1206

1207

<tt class="descname">execution_options</tt><big>(</big>**opt<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.execution_options" title="Permalink to this definition">¶</a></dt>

1208

<dd>Return a new <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> that will provide

1209

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> objects with the given execution options.

1210

The returned <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> remains related to the original

1211

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> in that it shares the same connection pool and

1212

other state:

1213

1214

<li>The <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal">Pool</tt></a> used by the new <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> is the

1215

same instance. The <a class="reference internal" href="#sqlalchemy.engine.Engine.dispose" title="sqlalchemy.engine.Engine.dispose"><tt class="xref py py-meth docutils literal">Engine.dispose()</tt></a> method will replace

1216

the connection pool instance for the parent engine as well

1217

as this one.</li>

1218

<li>Event listeners are “cascaded” - meaning, the new <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>

1219

inherits the events of the parent, and new events can be associated

1220

with the new <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> individually.</li>

1221

<li>The logging configuration and logging_name is copied from the parent

1222

<a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.</li>

1223

</ul>

1224

The intent of the <a class="reference internal" href="#sqlalchemy.engine.Engine.execution_options" title="sqlalchemy.engine.Engine.execution_options"><tt class="xref py py-meth docutils literal">Engine.execution_options()</tt></a> method is

1225

to implement “sharding” schemes where multiple <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>

1226

objects refer to the same connection pool, but are differentiated

1227

by options that would be consumed by a custom event:

1228

<div class="highlight-python"><div class="highlight"><pre>primary_engine = create_engine("mysql://")

1229

shard1 = primary_engine.execution_options(shard_id="shard1")

1230

shard2 = primary_engine.execution_options(shard_id="shard2")</pre></div>

1231

</div>

1232

Above, the <tt class="docutils literal">shard1</tt> engine serves as a factory for

1233

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> objects that will contain the execution option

1234

<tt class="docutils literal">shard_id=shard1</tt>, and <tt class="docutils literal">shard2</tt> will produce <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

1235

objects that contain the execution option <tt class="docutils literal">shard_id=shard2</tt>.

1236

An event handler can consume the above execution option to perform

1237

a schema switch or other operation, given a connection. Below

1238

we emit a MySQL <tt class="docutils literal">use</tt> statement to switch databases, at the same

1239

time keeping track of which database we’ve established using the

1240

<a class="reference internal" href="#sqlalchemy.engine.Connection.info" title="sqlalchemy.engine.Connection.info"><tt class="xref py py-attr docutils literal">Connection.info</tt></a> dictionary, which gives us a persistent

1241

storage space that follows the DBAPI connection:

1242

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy import event

1243

from sqlalchemy.engine import Engine

1244

1245

shards = {"default": "base", shard_1: "db1", "shard_2": "db2"}

1246

1247

@event.listens_for(Engine, "before_cursor_execute")

1248

def _switch_shard(conn, cursor, stmt, params, context, executemany):

1249

shard_id = conn._execution_options.get('shard_id', "default")

1250

current_shard = conn.info.get("current_shard", None)

1251

1252

if current_shard != shard_id:

1253

cursor.execute("use %s" % shards[shard_id])

1254

conn.info["current_shard"] = shard_id</pre></div>

1255

</div>

1256

1257

New in version 0.8.

1258

1259

See also

1260

<a class="reference internal" href="#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal">Connection.execution_options()</tt></a> - update execution options

1261

on a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object.

1262

<a class="reference internal" href="#sqlalchemy.engine.Engine.update_execution_options" title="sqlalchemy.engine.Engine.update_execution_options"><tt class="xref py py-meth docutils literal">Engine.update_execution_options()</tt></a> - update the execution

1263

options for a given <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> in place.

1264

</div>

1265

</dd></dl>

1266

1267

1268

1269

1270

<dd>String name of the <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Dialect" title="sqlalchemy.engine.interfaces.Dialect"><tt class="xref py py-class docutils literal">Dialect</tt></a>

1271

in use by this <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1272

</dd></dl>

1273

1274

1275

1276

<tt class="descname">raw_connection</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.raw_connection" title="Permalink to this definition">¶</a></dt>

1200

1277

<dd>Return a “raw” DBAPI connection from the connection pool.

1201

1278

The returned object is a proxied version of the DBAPI

1202

1279

connection object used by the underlying driver in use.

1205

1282

connection being returned to the pool, rather than being closed

1206

1283

for real.

1207

1284

This method provides direct DBAPI connection access for

1208

special situations. In most situations, the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

1285

special situations. In most situations, the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

1209

1286

object should be used, which is procured using the

1210

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.connect" title="sqlalchemy.engine.base.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a> method.

1211

</dd></dl>

1212

1213

1214

1215

<tt class="descname">reflecttable</tt><big>(</big>table, connection=None, include_columns=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.reflecttable" title="Permalink to this definition">¶</a></dt>

1216

<dd>Load table description from the database.

1217

1218

Deprecated since version 0.7: Use autoload=True with <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a>, or use the <a class="reference internal" href="schema.html#sqlalchemy.engine.reflection.Inspector" title="sqlalchemy.engine.reflection.Inspector"><tt class="xref py py-class docutils literal">Inspector</tt></a> object.

1219

Uses the given <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, or if None produces

1220

its own <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, and passes the <tt class="docutils literal">table</tt>

1221

and <tt class="docutils literal">include_columns</tt> arguments onto that

1222

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object’s <a class="reference internal" href="#sqlalchemy.engine.base.Connection.reflecttable" title="sqlalchemy.engine.base.Connection.reflecttable"><tt class="xref py py-meth docutils literal">Connection.reflecttable()</tt></a>

1223

method. The <a class="reference internal" href="schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> object is then populated

1224

with new attributes.

1225

</dd></dl>

1226

1227

1228

1229

<tt class="descname">run_callable</tt><big>(</big>callable_, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.run_callable" title="Permalink to this definition">¶</a></dt>

1287

<a class="reference internal" href="#sqlalchemy.engine.Engine.connect" title="sqlalchemy.engine.Engine.connect"><tt class="xref py py-meth docutils literal">Engine.connect()</tt></a> method.

1288

</dd></dl>

1289

1290

1291

1292

<tt class="descname">run_callable</tt><big>(</big>callable_, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.run_callable" title="Permalink to this definition">¶</a></dt>

1230

1293

<dd>Given a callable object or function, execute it, passing

1231

a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> as the first argument.

1294

a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> as the first argument.

1232

1295

The given *args and **kwargs are passed subsequent

1233

to the <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> argument.

1234

This function, along with <a class="reference internal" href="#sqlalchemy.engine.base.Connection.run_callable" title="sqlalchemy.engine.base.Connection.run_callable"><tt class="xref py py-meth docutils literal">Connection.run_callable()</tt></a>,

1235

allows a function to be run with a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

1236

or <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> object without the need to know

1296

to the <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> argument.

1297

This function, along with <a class="reference internal" href="#sqlalchemy.engine.Connection.run_callable" title="sqlalchemy.engine.Connection.run_callable"><tt class="xref py py-meth docutils literal">Connection.run_callable()</tt></a>,

1298

allows a function to be run with a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

1299

or <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> object without the need to know

1237

1300

which one is being dealt with.

1238

1301

</dd></dl>

1239

1302

1240

1303

1241

1242

<tt class="descname">table_names</tt><big>(</big>schema=None, connection=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.table_names" title="Permalink to this definition">¶</a></dt>

1304

1305

<tt class="descname">table_names</tt><big>(</big>schema=None, connection=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.table_names" title="Permalink to this definition">¶</a></dt>

1243

1306

<dd>Return a list of all table names available in the database.

1244

1307

1245

1308

1257

1320

</dd></dl>

1258

1321

1259

1322

1260

1261

<tt class="descname">text</tt><big>(</big>text, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.text" title="Permalink to this definition">¶</a></dt>

1262

<dd>Return a <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal">text()</tt></a> construct,

1263

1264

Deprecated since version 0.7: Use <a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal">expression.text()</tt></a> to create text constructs.

1265

bound to this engine.

1266

This is equivalent to:

1267

<div class="highlight-python"><div class="highlight"><pre>text("SELECT * FROM table", bind=engine)</pre></div>

1268

</div>

1269

</dd></dl>

1270

1271

1272

1273

<tt class="descname">transaction</tt><big>(</big>callable_, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.transaction" title="Permalink to this definition">¶</a></dt>

1323

1324

<tt class="descname">transaction</tt><big>(</big>callable_, *args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.transaction" title="Permalink to this definition">¶</a></dt>

1274

1325

<dd>Execute the given function within a transaction boundary.

1275

The function is passed a <a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> newly procured

1276

from <a class="reference internal" href="#sqlalchemy.engine.base.Engine.contextual_connect" title="sqlalchemy.engine.base.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a> as the first argument,

1326

The function is passed a <a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> newly procured

1327

from <a class="reference internal" href="#sqlalchemy.engine.Engine.contextual_connect" title="sqlalchemy.engine.Engine.contextual_connect"><tt class="xref py py-meth docutils literal">Engine.contextual_connect()</tt></a> as the first argument,

1277

1328

followed by the given *args and **kwargs.

1278

1329

e.g.:

1279

1330

<div class="highlight-python"><div class="highlight"><pre>def do_something(conn, x, y):

1282

1333

engine.transaction(do_something, 5, 10)</pre></div>

1283

1334

</div>

1284

1335

The operations inside the function are all invoked within the

1285

context of a single <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1336

context of a single <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1286

1337

Upon success, the transaction is committed. If an

1287

1338

exception is raised, the transaction is rolled back

1288

1339

before propagating the exception.

1289

1340

1290

1341

Note

1291

The <a class="reference internal" href="#sqlalchemy.engine.base.Engine.transaction" title="sqlalchemy.engine.base.Engine.transaction"><tt class="xref py py-meth docutils literal">transaction()</tt></a> method is superseded by

1342

The <a class="reference internal" href="#sqlalchemy.engine.Engine.transaction" title="sqlalchemy.engine.Engine.transaction"><tt class="xref py py-meth docutils literal">transaction()</tt></a> method is superseded by

1292

1343

the usage of the Python <tt class="docutils literal">with:</tt> statement, which can

1293

be used with <a class="reference internal" href="#sqlalchemy.engine.base.Engine.begin" title="sqlalchemy.engine.base.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a>:

1344

be used with <a class="reference internal" href="#sqlalchemy.engine.Engine.begin" title="sqlalchemy.engine.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a>:

1294

1345

<div class="last highlight-python"><div class="highlight"><pre>with engine.begin() as conn:

1295

1346

conn.execute("some statement", {'x':5, 'y':10})</pre></div>

1296

1347

</div>

1297

1348

</div>

1298

1349

See also:

1299

1350

1300

<div><a class="reference internal" href="#sqlalchemy.engine.base.Engine.begin" title="sqlalchemy.engine.base.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a> - engine-level transactional

1351

<div><a class="reference internal" href="#sqlalchemy.engine.Engine.begin" title="sqlalchemy.engine.Engine.begin"><tt class="xref py py-meth docutils literal">Engine.begin()</tt></a> - engine-level transactional

1301

1352

context

1302

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.transaction" title="sqlalchemy.engine.base.Connection.transaction"><tt class="xref py py-meth docutils literal">Connection.transaction()</tt></a> - connection-level version of

1303

<a class="reference internal" href="#sqlalchemy.engine.base.Engine.transaction" title="sqlalchemy.engine.base.Engine.transaction"><tt class="xref py py-meth docutils literal">Engine.transaction()</tt></a>

1353

<a class="reference internal" href="#sqlalchemy.engine.Connection.transaction" title="sqlalchemy.engine.Connection.transaction"><tt class="xref py py-meth docutils literal">Connection.transaction()</tt></a> - connection-level version of

1354

<a class="reference internal" href="#sqlalchemy.engine.Engine.transaction" title="sqlalchemy.engine.Engine.transaction"><tt class="xref py py-meth docutils literal">Engine.transaction()</tt></a>

1304

1355

</div></blockquote>

1305

1356

</dd></dl>

1306

1357

1307

1358

1308

1309

<tt class="descname">update_execution_options</tt><big>(</big>**opt<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Engine.update_execution_options" title="Permalink to this definition">¶</a></dt>

1359

1360

<tt class="descname">update_execution_options</tt><big>(</big>**opt<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Engine.update_execution_options" title="Permalink to this definition">¶</a></dt>

1310

1361

<dd>Update the default execution_options dictionary

1311

of this <a class="reference internal" href="#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1362

of this <a class="reference internal" href="#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>.

1312

1363

The given keys/values in **opt are added to the

1313

1364

default execution options that will be used for

1314

1365

all connections. The initial contents of this dictionary

1315

1366

can be sent via the <tt class="docutils literal">execution_options</tt> parameter

1316

1367

to <a class="reference internal" href="engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><tt class="xref py py-func docutils literal">create_engine()</tt></a>.

1317

See <a class="reference internal" href="#sqlalchemy.engine.base.Connection.execution_options" title="sqlalchemy.engine.base.Connection.execution_options"><tt class="xref py py-meth docutils literal">Connection.execution_options()</tt></a> for more

1318

details on execution options.

1368

1369

See also

1370

<a class="reference internal" href="#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal">Connection.execution_options()</tt></a>

1371

<a class="reference internal" href="#sqlalchemy.engine.Engine.execution_options" title="sqlalchemy.engine.Engine.execution_options"><tt class="xref py py-meth docutils literal">Engine.execution_options()</tt></a>

1372

</div>

1319

1373

</dd></dl>

1320

1374

1321

1375

</dd></dl>

1322

1376

1323

1377

1324

1325

class <tt class="descclassname">sqlalchemy.engine.base.</tt><tt class="descname">NestedTransaction</tt><big>(</big>connection, parent<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.NestedTransaction" title="Permalink to this definition">¶</a></dt>

1326

<dd>Bases: <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">sqlalchemy.engine.base.Transaction</tt></a>

1378

1379

class <tt class="descclassname">sqlalchemy.engine.</tt><tt class="descname">NestedTransaction</tt><big>(</big>connection, parent<big>)</big><a class="headerlink" href="#sqlalchemy.engine.NestedTransaction" title="Permalink to this definition">¶</a></dt>

1380

<dd>Bases: <tt class="xref py py-class docutils literal">sqlalchemy.engine.base.Transaction</tt>

1327

1381

Represent a ‘nested’, or SAVEPOINT transaction.

1328

A new <a class="reference internal" href="#sqlalchemy.engine.base.NestedTransaction" title="sqlalchemy.engine.base.NestedTransaction"><tt class="xref py py-class docutils literal">NestedTransaction</tt></a> object may be procured

1329

using the <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin_nested" title="sqlalchemy.engine.base.Connection.begin_nested"><tt class="xref py py-meth docutils literal">Connection.begin_nested()</tt></a> method.

1330

The interface is the same as that of <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1382

A new <a class="reference internal" href="#sqlalchemy.engine.NestedTransaction" title="sqlalchemy.engine.NestedTransaction"><tt class="xref py py-class docutils literal">NestedTransaction</tt></a> object may be procured

1383

using the <a class="reference internal" href="#sqlalchemy.engine.Connection.begin_nested" title="sqlalchemy.engine.Connection.begin_nested"><tt class="xref py py-meth docutils literal">Connection.begin_nested()</tt></a> method.

1384

The interface is the same as that of <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1331

1385

</dd></dl>

1332

1386

1333

1387

1334

1335

class <tt class="descclassname">sqlalchemy.engine.base.</tt><tt class="descname">ResultProxy</tt><big>(</big>context<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy" title="Permalink to this definition">¶</a></dt>

1388

1389

class <tt class="descclassname">sqlalchemy.engine.</tt><tt class="descname">ResultProxy</tt><big>(</big>context<big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy" title="Permalink to this definition">¶</a></dt>

1336

1390

<dd>Wraps a DB-API cursor object to provide easier access to row columns.

1337

1391

Individual columns may be accessed by their integer position,

1338

1392

case-insensitive column name, or by <tt class="docutils literal">schema.Column</tt>

1349

1403

data using <tt class="docutils literal">TypeEngine</tt> objects, which are referenced from

1350

1404

the originating SQL statement that produced this result set.

1351

1405

1352

1353

<tt class="descname">close</tt><big>(</big>_autoclose_connection=True<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.close" title="Permalink to this definition">¶</a></dt>

1406

1407

<tt class="descname">close</tt><big>(</big>_autoclose_connection=True<big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.close" title="Permalink to this definition">¶</a></dt>

1354

1408

<dd>Close this ResultProxy.

1355

1409

Closes the underlying DBAPI cursor corresponding to the execution.

1356

1410

Note that any data cached within this ResultProxy is still available.

1366

1420

</dd></dl>

1367

1421

1368

1422

1369

1370

<tt class="descname">fetchall</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.fetchall" title="Permalink to this definition">¶</a></dt>

1423

1424

<tt class="descname">fetchall</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.fetchall" title="Permalink to this definition">¶</a></dt>

1371

1425

<dd>Fetch all rows, just like DB-API <tt class="docutils literal">cursor.fetchall()</tt>.

1372

1426

</dd></dl>

1373

1427

1374

1428

1375

1376

<tt class="descname">fetchmany</tt><big>(</big>size=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.fetchmany" title="Permalink to this definition">¶</a></dt>

1429

1430

<tt class="descname">fetchmany</tt><big>(</big>size=None<big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.fetchmany" title="Permalink to this definition">¶</a></dt>

1377

1431

<dd>Fetch many rows, just like DB-API

1378

1432

<tt class="docutils literal">cursor.fetchmany(size=cursor.arraysize)</tt>.

1379

1433

If rows are present, the cursor remains open after this is called.

1381

1435

</dd></dl>

1382

1436

1383

1437

1384

1385

<tt class="descname">fetchone</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.fetchone" title="Permalink to this definition">¶</a></dt>

1438

1439

<tt class="descname">fetchone</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.fetchone" title="Permalink to this definition">¶</a></dt>

1386

1440

<dd>Fetch one row, just like DB-API <tt class="docutils literal">cursor.fetchone()</tt>.

1387

1441

If a row is present, the cursor remains open after this is called.

1388

1442

Else the cursor is automatically closed and None is returned.

1389

1443

</dd></dl>

1390

1444

1391

1445

1392

1393

<tt class="descname">first</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.first" title="Permalink to this definition">¶</a></dt>

1446

1447

<tt class="descname">first</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.first" title="Permalink to this definition">¶</a></dt>

1394

1448

<dd>Fetch the first row and then close the result set unconditionally.

1395

1449

Returns None if no row is present.

1396

1450

</dd></dl>

1397

1451

1398

1452

1399

1400

<tt class="descname">inserted_primary_key</tt><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.inserted_primary_key" title="Permalink to this definition">¶</a></dt>

1453

1454

<tt class="descname">inserted_primary_key</tt><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.inserted_primary_key" title="Permalink to this definition">¶</a></dt>

1401

1455

<dd>Return the primary key for the row just inserted.

1402

1456

The return value is a list of scalar values

1403

1457

corresponding to the list of primary key columns

1413

1467

appear in this list as <tt class="docutils literal">None</tt> unless the backend

1414

1468

supports “returning” and the insert statement executed

1415

1469

with the “implicit returning” enabled.

1470

Raises <a class="reference internal" href="exceptions.html#sqlalchemy.exc.InvalidRequestError" title="sqlalchemy.exc.InvalidRequestError"><tt class="xref py py-class docutils literal">InvalidRequestError</tt></a> if the executed

1471

statement is not a compiled expression construct

1472

or is not an insert() construct.

1416

1473

</dd></dl>

1417

1474

1418

1475

1419

1420

<tt class="descname">is_insert</tt><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.is_insert" title="Permalink to this definition">¶</a></dt>

1421

<dd>True if this <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> is the result

1476

1477

<tt class="descname">is_insert</tt><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.is_insert" title="Permalink to this definition">¶</a></dt>

1478

<dd>True if this <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> is the result

1422

1479

of a executing an expression language compiled

1423

1480

<a class="reference internal" href="expression_api.html#sqlalchemy.sql.expression.insert" title="sqlalchemy.sql.expression.insert"><tt class="xref py py-func docutils literal">expression.insert()</tt></a> construct.

1424

1481

When True, this implies that the

1425

<a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.inserted_primary_key" title="sqlalchemy.engine.base.ResultProxy.inserted_primary_key"><tt class="xref py py-attr docutils literal">inserted_primary_key</tt></a> attribute is accessible,

1482

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy.inserted_primary_key" title="sqlalchemy.engine.ResultProxy.inserted_primary_key"><tt class="xref py py-attr docutils literal">inserted_primary_key</tt></a> attribute is accessible,

1426

1483

assuming the statement did not include

1427

1484

a user defined “returning” construct.

1428

1485

</dd></dl>

1429

1486

1430

1487

1431

1432

1488

1489

1433

1490

<dd>Return the current set of string keys for rows.

1434

1491

</dd></dl>

1435

1492

1436

1493

1437

1438

<tt class="descname">last_inserted_ids</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.last_inserted_ids" title="Permalink to this definition">¶</a></dt>

1439

<dd>Return the primary key for the row just inserted.

1440

1441

Deprecated since version 0.6: Use <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.inserted_primary_key" title="sqlalchemy.engine.base.ResultProxy.inserted_primary_key"><tt class="xref py py-attr docutils literal">ResultProxy.inserted_primary_key</tt></a>

1442

</dd></dl>

1443

1444

1445

1446

<tt class="descname">last_inserted_params</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.last_inserted_params" title="Permalink to this definition">¶</a></dt>

1494

1495

<tt class="descname">last_inserted_params</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.last_inserted_params" title="Permalink to this definition">¶</a></dt>

1447

1496

<dd>Return the collection of inserted parameters from this

1448

1497

execution.

1498

Raises <a class="reference internal" href="exceptions.html#sqlalchemy.exc.InvalidRequestError" title="sqlalchemy.exc.InvalidRequestError"><tt class="xref py py-class docutils literal">InvalidRequestError</tt></a> if the executed

1499

statement is not a compiled expression construct

1500

or is not an insert() construct.

1449

1501

</dd></dl>

1450

1502

1451

1503

1452

1453

<tt class="descname">last_updated_params</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.last_updated_params" title="Permalink to this definition">¶</a></dt>

1504

1505

<tt class="descname">last_updated_params</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.last_updated_params" title="Permalink to this definition">¶</a></dt>

1454

1506

<dd>Return the collection of updated parameters from this

1455

1507

execution.

1508

Raises <a class="reference internal" href="exceptions.html#sqlalchemy.exc.InvalidRequestError" title="sqlalchemy.exc.InvalidRequestError"><tt class="xref py py-class docutils literal">InvalidRequestError</tt></a> if the executed

1509

statement is not a compiled expression construct

1510

or is not an update() construct.

1456

1511

</dd></dl>

1457

1512

1458

1513

1459

1460

<tt class="descname">lastrow_has_defaults</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.lastrow_has_defaults" title="Permalink to this definition">¶</a></dt>

1514

1515

<tt class="descname">lastrow_has_defaults</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.lastrow_has_defaults" title="Permalink to this definition">¶</a></dt>

1461

1516

<dd>Return <tt class="docutils literal">lastrow_has_defaults()</tt> from the underlying

1462

ExecutionContext.

1463

See ExecutionContext for details.

1517

<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal">ExecutionContext</tt></a>.

1518

See <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal">ExecutionContext</tt></a> for details.

1464

1519

</dd></dl>

1465

1520

1466

1521

1467

1468

<tt class="descname">lastrowid</tt><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.lastrowid" title="Permalink to this definition">¶</a></dt>

1522

1523

<tt class="descname">lastrowid</tt><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.lastrowid" title="Permalink to this definition">¶</a></dt>

1469

1524

<dd>return the ‘lastrowid’ accessor on the DBAPI cursor.

1470

1525

This is a DBAPI specific method and is only functional

1471

1526

for those backends which support it, for statements

1472

1527

where it is appropriate. It’s behavior is not

1473

1528

consistent across backends.

1474

Usage of this method is normally unnecessary; the

1475

<a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.inserted_primary_key" title="sqlalchemy.engine.base.ResultProxy.inserted_primary_key"><tt class="xref py py-attr docutils literal">inserted_primary_key</tt></a> attribute provides a

1529

Usage of this method is normally unnecessary when

1530

using insert() expression constructs; the

1531

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy.inserted_primary_key" title="sqlalchemy.engine.ResultProxy.inserted_primary_key"><tt class="xref py py-attr docutils literal">inserted_primary_key</tt></a> attribute provides a

1476

1532

tuple of primary key values for a newly inserted row,

1477

1533

regardless of database backend.

1478

1534

</dd></dl>

1479

1535

1480

1536

1481

1482

<tt class="descname">postfetch_cols</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.postfetch_cols" title="Permalink to this definition">¶</a></dt>

1483

<dd>Return <tt class="docutils literal">postfetch_cols()</tt> from the underlying ExecutionContext.

1484

See ExecutionContext for details.

1537

1538

<tt class="descname">postfetch_cols</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.postfetch_cols" title="Permalink to this definition">¶</a></dt>

1539

<dd>Return <tt class="docutils literal">postfetch_cols()</tt> from the underlying

1540

<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal">ExecutionContext</tt></a>.

1541

See <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal">ExecutionContext</tt></a> for details.

1542

Raises <a class="reference internal" href="exceptions.html#sqlalchemy.exc.InvalidRequestError" title="sqlalchemy.exc.InvalidRequestError"><tt class="xref py py-class docutils literal">InvalidRequestError</tt></a> if the executed

1543

statement is not a compiled expression construct

1544

or is not an insert() or update() construct.

1545

</dd></dl>

1546

1547

1548

1549

<tt class="descname">prefetch_cols</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.prefetch_cols" title="Permalink to this definition">¶</a></dt>

1550

<dd>Return <tt class="docutils literal">prefetch_cols()</tt> from the underlying

1551

<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal">ExecutionContext</tt></a>.

1552

See <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal">ExecutionContext</tt></a> for details.

1553

Raises <a class="reference internal" href="exceptions.html#sqlalchemy.exc.InvalidRequestError" title="sqlalchemy.exc.InvalidRequestError"><tt class="xref py py-class docutils literal">InvalidRequestError</tt></a> if the executed

1554

statement is not a compiled expression construct

1555

or is not an insert() or update() construct.

1485

1556

</dd></dl>

1486

1557

1487

1558

1488

1489

<tt class="descname">returns_rows</tt><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.returns_rows" title="Permalink to this definition">¶</a></dt>

1490

<dd>True if this <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> returns rows.

1559

1560

<tt class="descname">returns_rows</tt><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.returns_rows" title="Permalink to this definition">¶</a></dt>

1561

<dd>True if this <a class="reference internal" href="#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> returns rows.

1491

1562

I.e. if it is legal to call the methods

1492

<a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.fetchone" title="sqlalchemy.engine.base.ResultProxy.fetchone"><tt class="xref py py-meth docutils literal">fetchone()</tt></a>,

1493

<a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.fetchmany" title="sqlalchemy.engine.base.ResultProxy.fetchmany"><tt class="xref py py-meth docutils literal">fetchmany()</tt></a>

1494

<a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.fetchall" title="sqlalchemy.engine.base.ResultProxy.fetchall"><tt class="xref py py-meth docutils literal">fetchall()</tt></a>.

1563

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy.fetchone" title="sqlalchemy.engine.ResultProxy.fetchone"><tt class="xref py py-meth docutils literal">fetchone()</tt></a>,

1564

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy.fetchmany" title="sqlalchemy.engine.ResultProxy.fetchmany"><tt class="xref py py-meth docutils literal">fetchmany()</tt></a>

1565

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy.fetchall" title="sqlalchemy.engine.ResultProxy.fetchall"><tt class="xref py py-meth docutils literal">fetchall()</tt></a>.

1495

1566

</dd></dl>

1496

1567

1497

1568

1498

1499

<tt class="descname">rowcount</tt><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.rowcount" title="Permalink to this definition">¶</a></dt>

1569

1570

<tt class="descname">rowcount</tt><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.rowcount" title="Permalink to this definition">¶</a></dt>

1500

1571

<dd>Return the ‘rowcount’ for this result.

1501

1572

The ‘rowcount’ reports the number of rows matched

1502

1573

by the WHERE criterion of an UPDATE or DELETE statement.

1503

1574

1504

1575

Note

1505

Notes regarding <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.rowcount" title="sqlalchemy.engine.base.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a>:

1576

Notes regarding <a class="reference internal" href="#sqlalchemy.engine.ResultProxy.rowcount" title="sqlalchemy.engine.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a>:

1506

1577

1507

1578

<li>This attribute returns the number of rows matched,

1508

1579

which is not necessarily the same as the number of rows

1513

1584

On backends that feature both styles, such as MySQL,

1514

1585

rowcount is configured by default to return the match

1515

1586

count in all cases.</li>

1516

<li><a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.rowcount" title="sqlalchemy.engine.base.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a> is only useful in conjunction

1587

<li><a class="reference internal" href="#sqlalchemy.engine.ResultProxy.rowcount" title="sqlalchemy.engine.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a> is only useful in conjunction

1517

1588

with an UPDATE or DELETE statement. Contrary to what the Python

1518

1589

DBAPI says, it does not return the

1519

1590

number of rows available from the results of a SELECT statement

1520

1591

as DBAPIs cannot support this functionality when rows are

1521

1592

unbuffered.</li>

1522

<li><a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.rowcount" title="sqlalchemy.engine.base.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a> may not be fully implemented by

1593

<li><a class="reference internal" href="#sqlalchemy.engine.ResultProxy.rowcount" title="sqlalchemy.engine.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a> may not be fully implemented by

1523

1594

all dialects. In particular, most DBAPIs do not support an

1524

1595

aggregate rowcount result from an executemany call.

1525

The <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.supports_sane_rowcount" title="sqlalchemy.engine.base.ResultProxy.supports_sane_rowcount"><tt class="xref py py-meth docutils literal">ResultProxy.supports_sane_rowcount()</tt></a> and

1526

<a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.supports_sane_multi_rowcount" title="sqlalchemy.engine.base.ResultProxy.supports_sane_multi_rowcount"><tt class="xref py py-meth docutils literal">ResultProxy.supports_sane_multi_rowcount()</tt></a> methods

1596

The <a class="reference internal" href="#sqlalchemy.engine.ResultProxy.supports_sane_rowcount" title="sqlalchemy.engine.ResultProxy.supports_sane_rowcount"><tt class="xref py py-meth docutils literal">ResultProxy.supports_sane_rowcount()</tt></a> and

1597

<a class="reference internal" href="#sqlalchemy.engine.ResultProxy.supports_sane_multi_rowcount" title="sqlalchemy.engine.ResultProxy.supports_sane_multi_rowcount"><tt class="xref py py-meth docutils literal">ResultProxy.supports_sane_multi_rowcount()</tt></a> methods

1527

1598

will report from the dialect if each usage is known to be

1528

1599

supported.</li>

1529

1600

<li>Statements that use RETURNING may not return a correct

1533

1604

</dd></dl>

1534

1605

1535

1606

1536

1537

<tt class="descname">scalar</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.scalar" title="Permalink to this definition">¶</a></dt>

1607

1608

<tt class="descname">scalar</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.scalar" title="Permalink to this definition">¶</a></dt>

1538

1609

<dd>Fetch the first column of the first row, and close the result set.

1539

1610

Returns None if no row is present.

1540

1611

</dd></dl>

1541

1612

1542

1613

1543

1544

<tt class="descname">supports_sane_multi_rowcount</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.supports_sane_multi_rowcount" title="Permalink to this definition">¶</a></dt>

1614

1615

<tt class="descname">supports_sane_multi_rowcount</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.supports_sane_multi_rowcount" title="Permalink to this definition">¶</a></dt>

1545

1616

<dd>Return <tt class="docutils literal">supports_sane_multi_rowcount</tt> from the dialect.

1546

See <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.rowcount" title="sqlalchemy.engine.base.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a> for background.

1617

See <a class="reference internal" href="#sqlalchemy.engine.ResultProxy.rowcount" title="sqlalchemy.engine.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a> for background.

1547

1618

</dd></dl>

1548

1619

1549

1620

1550

1551

<tt class="descname">supports_sane_rowcount</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.ResultProxy.supports_sane_rowcount" title="Permalink to this definition">¶</a></dt>

1621

1622

<tt class="descname">supports_sane_rowcount</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.ResultProxy.supports_sane_rowcount" title="Permalink to this definition">¶</a></dt>

1552

1623

<dd>Return <tt class="docutils literal">supports_sane_rowcount</tt> from the dialect.

1553

See <a class="reference internal" href="#sqlalchemy.engine.base.ResultProxy.rowcount" title="sqlalchemy.engine.base.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a> for background.

1624

See <a class="reference internal" href="#sqlalchemy.engine.ResultProxy.rowcount" title="sqlalchemy.engine.ResultProxy.rowcount"><tt class="xref py py-attr docutils literal">ResultProxy.rowcount</tt></a> for background.

1554

1625

</dd></dl>

1555

1626

1556

1627

</dd></dl>

1557

1628

1558

1629

1559

1560

class <tt class="descclassname">sqlalchemy.engine.base.</tt><tt class="descname">RowProxy</tt><big>(</big>parent, row, processors, keymap<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.RowProxy" title="Permalink to this definition">¶</a></dt>

1630

1631

class <tt class="descclassname">sqlalchemy.engine.</tt><tt class="descname">RowProxy</tt><big>(</big>parent, row, processors, keymap<big>)</big><a class="headerlink" href="#sqlalchemy.engine.RowProxy" title="Permalink to this definition">¶</a></dt>

1561

1632

<dd>Proxy values from a single cursor row.

1562

1633

Mostly follows “ordered dictionary” behavior, mapping result

1563

1634

values to the string-based column name, the integer position of

1565

1636

mapped to the original Columns that produced this result set (for

1566

1637

results that correspond to constructed SQL expressions).

1567

1638

1568

1569

1639

1640

1570

1641

<dd>Return True if this RowProxy contains the given key.

1571

1642

</dd></dl>

1572

1643

1573

1644

1574

1575

<tt class="descname">items</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.RowProxy.items" title="Permalink to this definition">¶</a></dt>

1645

1646

<tt class="descname">items</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.RowProxy.items" title="Permalink to this definition">¶</a></dt>

1576

1647

<dd>Return a list of tuples, each tuple containing a key/value pair.

1577

1648

</dd></dl>

1578

1649

1579

1650

1580

1581

1651

1652

1582

1653

<dd>Return the list of keys as strings represented by this RowProxy.

1583

1654

</dd></dl>

1584

1655

1585

1656

</dd></dl>

1586

1657

1587

1658

1588

1589

class <tt class="descclassname">sqlalchemy.engine.base.</tt><tt class="descname">Transaction</tt><big>(</big>connection, parent<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Transaction" title="Permalink to this definition">¶</a></dt>

1659

1660

class <tt class="descclassname">sqlalchemy.engine.</tt><tt class="descname">Transaction</tt><big>(</big>connection, parent<big>)</big><a class="headerlink" href="#sqlalchemy.engine.Transaction" title="Permalink to this definition">¶</a></dt>

1590

1661

<dd>Bases: <tt class="xref py py-class docutils literal">object</tt>

1591

1662

Represent a database transaction in progress.

1592

The <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object is procured by

1593

calling the <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a> method of

1594

<a class="reference internal" href="#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>:

1663

The <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object is procured by

1664

calling the <a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a> method of

1665

<a class="reference internal" href="#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>:

1595

1666

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy import create_engine

1596

1667

engine = create_engine("postgresql://scott:tiger@localhost/test")

1597

1668

connection = engine.connect()

1599

1670

connection.execute("insert into x (a, b) values (1, 2)")

1600

1671

trans.commit()</pre></div>

1601

1672

</div>

1602

The object provides <a class="reference internal" href="#sqlalchemy.engine.base.Transaction.rollback" title="sqlalchemy.engine.base.Transaction.rollback"><tt class="xref py py-meth docutils literal">rollback()</tt></a> and <a class="reference internal" href="#sqlalchemy.engine.base.Transaction.commit" title="sqlalchemy.engine.base.Transaction.commit"><tt class="xref py py-meth docutils literal">commit()</tt></a>

1673

The object provides <a class="reference internal" href="#sqlalchemy.engine.Transaction.rollback" title="sqlalchemy.engine.Transaction.rollback"><tt class="xref py py-meth docutils literal">rollback()</tt></a> and <a class="reference internal" href="#sqlalchemy.engine.Transaction.commit" title="sqlalchemy.engine.Transaction.commit"><tt class="xref py py-meth docutils literal">commit()</tt></a>

1603

1674

methods in order to control transaction boundaries. It

1604

1675

also implements a context manager interface so that

1605

1676

the Python <tt class="docutils literal">with</tt> statement can be used with the

1606

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a> method:

1677

<a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a> method:

1607

1678

<div class="highlight-python"><div class="highlight"><pre>with connection.begin():

1608

1679

connection.execute("insert into x (a, b) values (1, 2)")</pre></div>

1609

1680

</div>

1610

1681

The Transaction object is not threadsafe.

1611

See also: <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a>, <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin_twophase" title="sqlalchemy.engine.base.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a>,

1612

<a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin_nested" title="sqlalchemy.engine.base.Connection.begin_nested"><tt class="xref py py-meth docutils literal">Connection.begin_nested()</tt></a>.

1682

See also: <a class="reference internal" href="#sqlalchemy.engine.Connection.begin" title="sqlalchemy.engine.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a>, <a class="reference internal" href="#sqlalchemy.engine.Connection.begin_twophase" title="sqlalchemy.engine.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a>,

1683

<a class="reference internal" href="#sqlalchemy.engine.Connection.begin_nested" title="sqlalchemy.engine.Connection.begin_nested"><tt class="xref py py-meth docutils literal">Connection.begin_nested()</tt></a>.

1613

1684

1614

1615

<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Transaction.close" title="Permalink to this definition">¶</a></dt>

1616

<dd>Close this <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1685

1686

<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Transaction.close" title="Permalink to this definition">¶</a></dt>

1687

<dd>Close this <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1617

1688

If this transaction is the base transaction in a begin/commit

1618

1689

nesting, the transaction will rollback(). Otherwise, the

1619

1690

method returns.

1622

1693

</dd></dl>

1623

1694

1624

1695

1625

1626

<tt class="descname">commit</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Transaction.commit" title="Permalink to this definition">¶</a></dt>

1627

<dd>Commit this <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1696

1697

<tt class="descname">commit</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Transaction.commit" title="Permalink to this definition">¶</a></dt>

1698

<dd>Commit this <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1628

1699

</dd></dl>

1629

1700

1630

1701

1631

1632

<tt class="descname">rollback</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.Transaction.rollback" title="Permalink to this definition">¶</a></dt>

1633

<dd>Roll back this <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1702

1703

<tt class="descname">rollback</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.Transaction.rollback" title="Permalink to this definition">¶</a></dt>

1704

<dd>Roll back this <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>.

1634

1705

</dd></dl>

1635

1706

1636

1707

</dd></dl>

1637

1708

1638

1709

1639

1640

class <tt class="descclassname">sqlalchemy.engine.base.</tt><tt class="descname">TwoPhaseTransaction</tt><big>(</big>connection, xid<big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.TwoPhaseTransaction" title="Permalink to this definition">¶</a></dt>

1641

<dd>Bases: <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">sqlalchemy.engine.base.Transaction</tt></a>

1710

1711

class <tt class="descclassname">sqlalchemy.engine.</tt><tt class="descname">TwoPhaseTransaction</tt><big>(</big>connection, xid<big>)</big><a class="headerlink" href="#sqlalchemy.engine.TwoPhaseTransaction" title="Permalink to this definition">¶</a></dt>

1712

<dd>Bases: <tt class="xref py py-class docutils literal">sqlalchemy.engine.base.Transaction</tt>

1642

1713

Represent a two-phase transaction.

1643

A new <a class="reference internal" href="#sqlalchemy.engine.base.TwoPhaseTransaction" title="sqlalchemy.engine.base.TwoPhaseTransaction"><tt class="xref py py-class docutils literal">TwoPhaseTransaction</tt></a> object may be procured

1644

using the <a class="reference internal" href="#sqlalchemy.engine.base.Connection.begin_twophase" title="sqlalchemy.engine.base.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a> method.

1645

The interface is the same as that of <a class="reference internal" href="#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

1646

with the addition of the <a class="reference internal" href="#sqlalchemy.engine.base.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.base.TwoPhaseTransaction.prepare"><tt class="xref py py-meth docutils literal">prepare()</tt></a> method.

1714

A new <a class="reference internal" href="#sqlalchemy.engine.TwoPhaseTransaction" title="sqlalchemy.engine.TwoPhaseTransaction"><tt class="xref py py-class docutils literal">TwoPhaseTransaction</tt></a> object may be procured

1715

using the <a class="reference internal" href="#sqlalchemy.engine.Connection.begin_twophase" title="sqlalchemy.engine.Connection.begin_twophase"><tt class="xref py py-meth docutils literal">Connection.begin_twophase()</tt></a> method.

1716

The interface is the same as that of <a class="reference internal" href="#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a>

1717

with the addition of the <a class="reference internal" href="#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.TwoPhaseTransaction.prepare"><tt class="xref py py-meth docutils literal">prepare()</tt></a> method.

1647

1718

1648

1649

<tt class="descname">prepare</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.base.TwoPhaseTransaction.prepare" title="Permalink to this definition">¶</a></dt>

1650

<dd>Prepare this <a class="reference internal" href="#sqlalchemy.engine.base.TwoPhaseTransaction" title="sqlalchemy.engine.base.TwoPhaseTransaction"><tt class="xref py py-class docutils literal">TwoPhaseTransaction</tt></a>.

1719

1720

<tt class="descname">prepare</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="Permalink to this definition">¶</a></dt>

1721

<dd>Prepare this <a class="reference internal" href="#sqlalchemy.engine.TwoPhaseTransaction" title="sqlalchemy.engine.TwoPhaseTransaction"><tt class="xref py py-class docutils literal">TwoPhaseTransaction</tt></a>.

1651

1722

After a PREPARE, the transaction can be committed.

1652

1723

</dd></dl>

1653

1724

1667

1738

<a href="pooling.html" title="next chapter">Connection Pooling</a>

1668

1739

1669

1740

1670

1741

1671

1742

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.

1672

1743

</div>

1673

1744

</div>