~ubuntu-branches/debian/sid/sqlalchemy/sid : revision 22

1

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

2

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

3

4

<html>

5

<head>

6

7

8

<title>

9

Using the Session

10

— SQLAlchemy 0.6.6 Documentation</title>

11

12

13

14

15

16

var DOCUMENTATION_OPTIONS = {

17

URL_ROOT: '../',

18

VERSION: '0.6.6',

19

COLLAPSE_MODINDEX: false,

20

FILE_SUFFIX: '.html'

21

};

22

</script>

23

24

25

26

27

28

29

30

31

32

33

34

35

36

</head>

37

<body>

38

39

40

41

42

43

<h1>SQLAlchemy 0.6.6 Documentation</h1>

44

45

46

Search:

47

48

49

50

51

</form>

52

</div>

53

54

55

Version: 0.6.6 Last Updated: 01/08/2011 17:20:49

56

</div>

57

58

59

60

61

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

62

63

<div class="sourcelink">(<a href="../_sources/orm/session.txt">view source)</div>

64

</div>

65

66

67

<a class="totoc" href="../index.html">Table of Contents</a>

68

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

69

»

70

Using the Session

71

72

73

74

75

<a href="inheritance.html" title="previous chapter">Mapping Class Inheritance Hierarchies</a>

77

<a href="query.html" title="next chapter">Querying</a>

79

</div>

80

81

<h2>

82

83

Using the Session

84

85

</h2>

86

</div>

87

<ul>

88

<li><a class="reference internal" href="#">Using the Session</a><ul>

89

<li><a class="reference internal" href="#what-does-the-session-do">What does the Session do ?</a></li>

90

<li><a class="reference internal" href="#getting-a-session">Getting a Session</a></li>

91

<li><a class="reference internal" href="#id1">Using the Session</a><ul>

92

<li><a class="reference internal" href="#quickie-intro-to-object-states">Quickie Intro to Object States</a></li>

93

<li><a class="reference internal" href="#frequently-asked-questions">Frequently Asked Questions</a></li>

94

<li><a class="reference internal" href="#querying">Querying</a></li>

95

<li><a class="reference internal" href="#adding-new-or-existing-items">Adding New or Existing Items</a></li>

96

<li><a class="reference internal" href="#merging">Merging</a><ul>

97

<li><a class="reference internal" href="#merge-tips">Merge Tips</a></li>

98

</ul>

99

</li>

100

<li><a class="reference internal" href="#deleting">Deleting</a><ul>

101

<li><a class="reference internal" href="#deleting-based-on-filter-criterion">Deleting based on Filter Criterion</a></li>

102

</ul>

103

</li>

104

<li><a class="reference internal" href="#flushing">Flushing</a></li>

105

<li><a class="reference internal" href="#committing">Committing</a></li>

106

<li><a class="reference internal" href="#rolling-back">Rolling Back</a></li>

107

<li><a class="reference internal" href="#expunging">Expunging</a></li>

108

<li><a class="reference internal" href="#closing">Closing</a></li>

109

<li><a class="reference internal" href="#refreshing-expiring">Refreshing / Expiring</a></li>

110

<li><a class="reference internal" href="#session-attributes">Session Attributes</a></li>

111

</ul>

112

</li>

113

<li><a class="reference internal" href="#cascades">Cascades</a></li>

114

<li><a class="reference internal" href="#managing-transactions">Managing Transactions</a><ul>

115

<li><a class="reference internal" href="#using-savepoint">Using SAVEPOINT</a></li>

116

<li><a class="reference internal" href="#using-subtransactions">Using Subtransactions</a></li>

117

<li><a class="reference internal" href="#enabling-two-phase-commit">Enabling Two-Phase Commit</a></li>

118

</ul>

119

</li>

120

<li><a class="reference internal" href="#embedding-sql-insert-update-expressions-into-a-flush">Embedding SQL Insert/Update Expressions into a Flush</a></li>

121

<li><a class="reference internal" href="#using-sql-expressions-with-sessions">Using SQL Expressions with Sessions</a></li>

122

<li><a class="reference internal" href="#joining-a-session-into-an-external-transaction">Joining a Session into an External Transaction</a></li>

123

<li><a class="reference internal" href="#the-session-object-and-sessionmaker-function">The <tt class="docutils literal">Session</tt> object and <tt class="docutils literal">sessionmaker()</tt> function</a></li>

124

<li><a class="reference internal" href="#contextual-thread-local-sessions">Contextual/Thread-local Sessions</a><ul>

125

<li><a class="reference internal" href="#creating-a-thread-local-context">Creating a Thread-local Context</a></li>

126

<li><a class="reference internal" href="#lifespan-of-a-contextual-session">Lifespan of a Contextual Session</a></li>

127

<li><a class="reference internal" href="#contextual-session-api">Contextual Session API</a></li>

128

</ul>

129

</li>

130

<li><a class="reference internal" href="#partitioning-strategies">Partitioning Strategies</a><ul>

131

<li><a class="reference internal" href="#vertical-partitioning">Vertical Partitioning</a></li>

132

<li><a class="reference internal" href="#horizontal-partitioning">Horizontal Partitioning</a></li>

133

</ul>

134

</li>

135

<li><a class="reference internal" href="#session-utilities">Session Utilities</a></li>

136

<li><a class="reference internal" href="#attribute-and-state-management-utilities">Attribute and State Management Utilities</a></li>

137

</ul>

138

</li>

139

</ul>

140

141

142

</div>

143

144

145

146

147

148

<h1>Using the Session<a class="headerlink" href="#module-sqlalchemy.orm.session" title="Permalink to this headline">¶</a></h1>

149

The <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">orm.mapper()</tt></a> function and <a class="reference internal" href="extensions/declarative.html#module-sqlalchemy.ext.declarative"><tt class="xref py py-mod docutils literal">declarative</tt></a> extensions

150

are the primary configurational interface for the ORM. Once mappings are

151

configured, the primary usage interface for persistence operations is the

152

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

153

154

<h2>What does the Session do ?<a class="headerlink" href="#what-does-the-session-do" title="Permalink to this headline">¶</a></h2>

155

In the most general sense, the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> establishes all

156

conversations with the database and represents a “holding zone” for all the

157

objects which you’ve loaded or associated with it during its lifespan. It

158

provides the entrypoint to acquire a <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> object, which sends

159

queries to the database using the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object’s current database

160

connection, populating result rows into objects that are then stored in the

161

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>, inside a structure called the <a class="reference external" href="http://martinfowler.com/eaaCatalog/identityMap.html">Identity Map</a> - a data structure

162

that maintains unique copies of each object, where “unique” means “only one

163

object with a particular primary key”.

164

The <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> begins in an essentially stateless form. Once queries

165

are issued or other objects are persisted with it, it requests a connection

166

resource from an <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> that is associated either with the

167

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> itself or with the mapped <a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects being

168

operated upon. This connection represents an ongoing transaction, which

169

remains in effect until the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> is instructed to commit or roll

170

back its pending state.

171

All changes to objects maintained by a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> are tracked - before

172

the database is queried again or before the current transaction is committed,

173

it flushes all pending changes to the database. This is known as the <a class="reference external" href="http://martinfowler.com/eaaCatalog/unitOfWork.html">Unit

174

of Work</a> pattern.

175

When using a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>, it’s important to note that the objects

176

which are associated with it are proxy objects to the transaction being

177

held by the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> - there are a variety of events that will cause

178

objects to re-access the database in order to keep synchronized. It is

179

possible to “detach” objects from a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>, and to continue using

180

them, though this practice has its caveats. It’s intended that

181

usually, you’d re-associate detached objects another <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> when you

182

want to work with them again, so that they can resume their normal task of

183

representing database state.

184

</div>

185

186

<h2>Getting a Session<a class="headerlink" href="#getting-a-session" title="Permalink to this headline">¶</a></h2>

187

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> is a regular Python class which can

188

be directly instantiated. However, to standardize how sessions are configured

189

and acquired, the <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> function is normally

190

used to create a top level <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>

191

configuration which can then be used throughout an application without the

192

need to repeat the configurational arguments.

193

The usage of <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> is illustrated below:

194

<div class="highlight-python+sql"><div class="highlight"><pre>from sqlalchemy.orm import sessionmaker

195

196

# create a configured "Session" class

197

Session = sessionmaker(bind=some_engine)

198

199

# create a Session

200

session = Session()

201

202

# work with sess

203

myobject = MyObject('foo', 'bar')

204

session.add(myobject)

205

session.commit()</pre></div>

206

</div>

207

Above, the <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> call creates a class for us,

208

which we assign to the name <tt class="docutils literal">Session</tt>. This class is a subclass of the

209

actual <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> class, which when instantiated, will

210

use the arguments we’ve given the function, in this case

211

to use a particular <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> for connection resources.

212

When you write your application, place the call to

213

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> somewhere global, and then make your new

214

<tt class="docutils literal">Session</tt> class available to the rest of your application.

215

A typical setup will associate the <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> with an <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>,

216

so that each <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> generated will use this <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>

217

to acquire connection resources. This association can

218

be set up as in the example above, using the <tt class="docutils literal">bind</tt> argument. You

219

can also associate a <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> with an existing <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a>

220

using the <tt class="xref py py-meth docutils literal">sessionmaker.configure()</tt> method:

221

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.orm import sessionmaker

222

from sqlalchemy import create_engine

223

224

# configure Session class with desired options

225

Session = sessionmaker()

226

227

# later, we create the engine

228

engine = create_engine('postgresql://...')

229

230

# associate it with our custom Session class

231

Session.configure(bind=engine)

232

233

# work with the session

234

session = Session()</pre></div>

235

</div>

236

you can also associate individual <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> objects with an <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>

237

on each invocation:

238

<div class="highlight-python"><div class="highlight"><pre>session = Session(bind=engine)</pre></div>

239

</div>

240

...or directly with a <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>:

241

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

242

session = Session(bind=conn)</pre></div>

243

</div>

244

While the rationale for the above example may not be apparent, the typical

245

usage is in a test fixture that maintains an external transaction - see

246

<a class="reference internal" href="#session-external-transaction">Joining a Session into an External Transaction</a> below for a full example.

247

</div>

248

249

<h2>Using the Session<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>

250

251

<h3>Quickie Intro to Object States<a class="headerlink" href="#quickie-intro-to-object-states" title="Permalink to this headline">¶</a></h3>

252

It’s helpful to know the states which an instance can have within a session:

253

254

<li>Transient - an instance that’s not in a session, and is not saved to the

255

database; i.e. it has no database identity. The only relationship such an

256

object has to the ORM is that its class has a <tt class="docutils literal">mapper()</tt> associated with

257

it.</li>

258

<li>Pending - when you <a class="reference internal" href="#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-func docutils literal">add()</tt></a> a transient

259

instance, it becomes pending. It still wasn’t actually flushed to the

260

database yet, but it will be when the next flush occurs.</li>

261

<li>Persistent - An instance which is present in the session and has a record

262

in the database. You get persistent instances by either flushing so that the

263

pending instances become persistent, or by querying the database for

264

existing instances (or moving persistent instances from other sessions into

265

your local session).</li>

266

<li>Detached - an instance which has a record in the database, but is not in

267

any session. There’s nothing wrong with this, and you can use objects

268

normally when they’re detached, except they will not be able to issue

269

any SQL in order to load collections or attributes which are not yet loaded,

270

or were marked as “expired”.</li>

271

</ul>

272

Knowing these states is important, since the

273

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> tries to be strict about ambiguous

274

operations (such as trying to save the same object to two different sessions

275

at the same time).

276

</div>

277

278

<h3>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h3>

279

<ul>

280

<li>When do I make a <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> ?

281

282

Just one time, somewhere in your application’s global scope. It should be

283

looked upon as part of your application’s configuration. If your

284

application has three .py files in a package, you could, for example,

285

place the <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> line in your <tt class="docutils literal">__init__.py</tt> file; from

286

that point on your other modules say “from mypackage import Session”. That

287

way, everyone else just uses <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session()</tt></a>,

288

and the configuration of that session is controlled by that central point.

289

If your application starts up, does imports, but does not know what

290

database it’s going to be connecting to, you can bind the

291

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> at the “class” level to the

292

engine later on, using <tt class="docutils literal">configure()</tt>.

293

In the examples in this section, we will frequently show the

294

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> being created right above the line where we actually

295

invoke <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session()</tt></a>. But that’s just for

296

example’s sake ! In reality, the <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> would be somewhere

297

at the module level, and your individual

298

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session()</tt></a> calls would be sprinkled all

299

throughout your app, such as in a web application within each controller

300

method.

301

</blockquote>

302

</li>

303

<li>When do I make a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> ?

304

305

You typically invoke <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> when you first need to talk to your

306

database, and want to save some objects or load some existing ones. It

307

then remains in use for the lifespan of a particular database

308

conversation, which includes not just the initial loading of objects but

309

throughout the whole usage of those instances.

310

Objects become detached if their owning session is discarded. They are

311

still functional in the detached state if the user has ensured that their

312

state has not been expired before detachment, but they will not be able to

313

represent the current state of database data. Because of this, it’s best

314

to consider persisted objects as an extension of the state of a particular

315

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>, and to keep that session around until all referenced

316

objects have been discarded.

317

An exception to this is when objects are placed in caches or otherwise

318

shared among threads or processes, in which case their detached state can

319

be stored, transmitted, or shared. However, the state of detached objects

320

should still be transferred back into a new <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> using

321

<a class="reference internal" href="#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal">Session.add()</tt></a> or <a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-meth docutils literal">Session.merge()</tt></a> before working with the

322

object (or in the case of merge, its state) again.

323

It is also very common that a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> as well as its associated

324

objects are only referenced by a single thread. Sharing objects between

325

threads is most safely accomplished by sharing their state among multiple

326

instances of those objects, each associated with a distinct

327

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> per thread, <a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-meth docutils literal">Session.merge()</tt></a> to transfer state

328

between threads. This pattern is not a strict requirement by any means,

329

but it has the least chance of introducing concurrency issues.

330

To help with the recommended <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> -per-thread,

331

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> -per-set-of-objects patterns, the

332

<a class="reference internal" href="#sqlalchemy.orm.scoped_session" title="sqlalchemy.orm.scoped_session"><tt class="xref py py-func docutils literal">scoped_session()</tt></a> function is provided which produces a

333

thread-managed registry of <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> objects. It is commonly used

334

in web applications so that a single global variable can be used to safely

335

represent transactional sessions with sets of objects, localized to a

336

single thread. More on this object is in <a class="reference internal" href="#unitofwork-contextual">Contextual/Thread-local Sessions</a>.

337

</blockquote>

338

</li>

339

<li>Is the Session a cache ?

340

341

Yeee...no. It’s somewhat used as a cache, in that it implements the

342

identity map pattern, and stores objects keyed to their primary key.

343

However, it doesn’t do any kind of query caching. This means, if you say

344

<tt class="docutils literal">session.query(Foo).filter_by(name='bar')</tt>, even if <tt class="docutils literal">Foo(name='bar')</tt>

345

is right there, in the identity map, the session has no idea about that.

346

It has to issue SQL to the database, get the rows back, and then when it

347

sees the primary key in the row, then it can look in the local identity

348

map and see that the object is already there. It’s only when you say

349

<tt class="docutils literal">query.get({some primary key})</tt> that the

350

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> doesn’t have to issue a query.

351

Additionally, the Session stores object instances using a weak reference

352

by default. This also defeats the purpose of using the Session as a cache.

353

The <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> is not designed to be a

354

global object from which everyone consults as a “registry” of objects.

355

That’s more the job of a second level cache. SQLAlchemy provides

356

a pattern for implementing second level caching using <a class="reference external" href="http://beaker.groovie.org/">Beaker</a>,

357

via the <a class="reference internal" href="examples.html#examples-caching">Beaker Caching</a> example.

358

</blockquote>

359

</li>

360

<li>How can I get the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> for a certain object ?

361

362

Use the <a class="reference internal" href="#sqlalchemy.orm.session.Session.object_session" title="sqlalchemy.orm.session.Session.object_session"><tt class="xref py py-func docutils literal">object_session()</tt></a> classmethod

363

available on <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>:

364

<div class="highlight-python"><div class="highlight"><pre>session = Session.object_session(someobject)</pre></div>

365

</div>

366

</blockquote>

367

</li>

368

</ul>

369

370

<li>Is the session thread-safe?

371

372

Nope. It has no thread synchronization of any kind built in, and

373

particularly when you do a flush operation, it definitely is not open to

374

concurrent threads accessing it, because it holds onto a single database

375

connection at that point. If you use a session which is non-transactional

376

(meaning, <tt class="docutils literal">autocommit</tt> is set to <tt class="xref docutils literal">True</tt>, not the default setting)

377

for read operations only, it’s still not thread-“safe”, but you also wont

378

get any catastrophic failures either, since it checks out and returns

379

connections to the connection pool on an as-needed basis; it’s just that

380

different threads might load the same objects independently of each other,

381

but only one will wind up in the identity map (however, the other one

382

might still live in a collection somewhere).

383

But the bigger point here is, you should not want to use the session

384

with multiple concurrent threads. That would be like having everyone at a

385

restaurant all eat from the same plate. The session is a local “workspace”

386

that you use for a specific set of tasks; you don’t want to, or need to,

387

share that session with other threads who are doing some other task. If,

388

on the other hand, there are other threads participating in the same task

389

you are, such as in a desktop graphical application, then you would be

390

sharing the session with those threads, but you also will have implemented

391

a proper locking scheme (or your graphical framework does) so that those

392

threads do not collide.

393

A multithreaded application is usually going to want to make usage of

394

<a class="reference internal" href="#sqlalchemy.orm.scoped_session" title="sqlalchemy.orm.scoped_session"><tt class="xref py py-func docutils literal">scoped_session()</tt></a> to transparently manage sessions per thread.

395

More on this at <a class="reference internal" href="#unitofwork-contextual">Contextual/Thread-local Sessions</a>.

396

</blockquote>

397

</li>

398

</ul>

399

</div>

400

401

<h3>Querying<a class="headerlink" href="#querying" title="Permalink to this headline">¶</a></h3>

402

The <a class="reference internal" href="#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><tt class="xref py py-func docutils literal">query()</tt></a> function takes one or more

403

entities and returns a new <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> object which

404

will issue mapper queries within the context of this Session. An entity is

405

defined as a mapped class, a <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> object, an

406

orm-enabled descriptor, or an <tt class="docutils literal">AliasedClass</tt> object:

407

<div class="highlight-python"><div class="highlight"><pre># query from a class

408

session.query(User).filter_by(name='ed').all()

409

410

# query with multiple classes, returns tuples

411

session.query(User, Address).join('addresses').filter_by(name='ed').all()

412

413

# query using orm-enabled descriptors

414

session.query(User.name, User.fullname).all()

415

416

# query from a mapper

417

user_mapper = class_mapper(User)

418

session.query(user_mapper)</pre></div>

419

</div>

420

When <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> returns results, each object

421

instantiated is stored within the identity map. When a row matches an object

422

which is already present, the same object is returned. In the latter case,

423

whether or not the row is populated onto an existing object depends upon

424

whether the attributes of the instance have been expired or not. A

425

default-configured <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> automatically

426

expires all instances along transaction boundaries, so that with a normally

427

isolated transaction, there shouldn’t be any issue of instances representing

428

data which is stale with regards to the current transaction.

429

The <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> object is introduced in great detail in

430

<a class="reference internal" href="tutorial.html">Object Relational Tutorial</a>, and further documented in

431

<a class="reference internal" href="query.html">Querying</a>.

432

</div>

433

434

<h3>Adding New or Existing Items<a class="headerlink" href="#adding-new-or-existing-items" title="Permalink to this headline">¶</a></h3>

435

<a class="reference internal" href="#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-func docutils literal">add()</tt></a> is used to place instances in the

436

session. For transient (i.e. brand new) instances, this will have the effect

437

of an INSERT taking place for those instances upon the next flush. For

438

instances which are persistent (i.e. were loaded by this session), they are

439

already present and do not need to be added. Instances which are detached

440

(i.e. have been removed from a session) may be re-associated with a session

441

using this method:

442

<div class="highlight-python"><div class="highlight"><pre>user1 = User(name='user1')

443

user2 = User(name='user2')

444

session.add(user1)

445

session.add(user2)

446

447

session.commit() # write changes to the database</pre></div>

448

</div>

449

To add a list of items to the session at once, use

450

<a class="reference internal" href="#sqlalchemy.orm.session.Session.add_all" title="sqlalchemy.orm.session.Session.add_all"><tt class="xref py py-func docutils literal">add_all()</tt></a>:

451

<div class="highlight-python"><div class="highlight"><pre>session.add_all([item1, item2, item3])</pre></div>

452

</div>

453

The <a class="reference internal" href="#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-func docutils literal">add()</tt></a> operation cascades along

454

the <tt class="docutils literal">save-update</tt> cascade. For more details see the section

455

<a class="reference internal" href="#unitofwork-cascades">Cascades</a>.

456

</div>

457

458

<h3>Merging<a class="headerlink" href="#merging" title="Permalink to this headline">¶</a></h3>

459

<a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-func docutils literal">merge()</tt></a> reconciles the current state of

460

an instance and its associated children with existing data in the database,

461

and returns a copy of the instance associated with the session. Usage is as

462

follows:

463

<div class="highlight-python"><div class="highlight"><pre>merged_object = session.merge(existing_object)</pre></div>

464

</div>

465

When given an instance, it follows these steps:

466

467

<li>It examines the primary key of the instance. If it’s present, it attempts

468

to load an instance with that primary key (or pulls from the local

469

identity map).</li>

470

<li>If there’s no primary key on the given instance, or the given primary key

471

does not exist in the database, a new instance is created.</li>

472

<li>The state of the given instance is then copied onto the located/newly

473

created instance.</li>

474

<li>The operation is cascaded to associated child items along the <tt class="docutils literal">merge</tt>

475

cascade. Note that all changes present on the given instance, including

476

changes to collections, are merged.</li>

477

<li>The new instance is returned.</li>

478

</ul>

479

With <a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-func docutils literal">merge()</tt></a>, the given instance is not

480

placed within the session, and can be associated with a different session or

481

detached. <a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-func docutils literal">merge()</tt></a> is very useful for

482

taking the state of any kind of object structure without regard for its

483

origins or current session associations and placing that state within a

484

session. Here’s two examples:

485

486

<li>An application which reads an object structure from a file and wishes to

487

save it to the database might parse the file, build up the

488

structure, and then use

489

<a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-func docutils literal">merge()</tt></a> to save it

490

to the database, ensuring that the data within the file is

491

used to formulate the primary key of each element of the

492

structure. Later, when the file has changed, the same

493

process can be re-run, producing a slightly different

494

object structure, which can then be <tt class="docutils literal">merged</tt> in again,

495

and the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> will

496

automatically update the database to reflect those

497

changes.</li>

498

<li>A web application stores mapped entities within an HTTP session object.

499

When each request starts up, the serialized data can be

500

merged into the session, so that the original entity may

501

be safely shared among requests and threads.</li>

502

</ul>

503

<a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-func docutils literal">merge()</tt></a> is frequently used by

504

applications which implement their own second level caches. This refers to an

505

application which uses an in memory dictionary, or an tool like Memcached to

506

store objects over long running spans of time. When such an object needs to

507

exist within a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>,

508

<a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-func docutils literal">merge()</tt></a> is a good choice since it leaves

509

the original cached object untouched. For this use case, merge provides a

510

keyword option called <tt class="docutils literal">load=False</tt>. When this boolean flag is set to

511

<tt class="xref docutils literal">False</tt>, <a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-func docutils literal">merge()</tt></a> will not issue any

512

SQL to reconcile the given object against the current state of the database,

513

thereby reducing query overhead. The limitation is that the given object and

514

all of its children may not contain any pending changes, and it’s also of

515

course possible that newer information in the database will not be present on

516

the merged object, since no load is issued.

517

518

<h4>Merge Tips<a class="headerlink" href="#merge-tips" title="Permalink to this headline">¶</a></h4>

519

<a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-meth docutils literal">merge()</tt></a> is an extremely useful method for many purposes. However,

520

it deals with the intricate border between objects that are transient/detached and

521

those that are persistent, as well as the automated transferrence of state.

522

The wide variety of scenarios that can present themselves here often require a

523

more careful approach to the state of objects. Common problems with merge usually involve

524

some unexpected state regarding the object being passed to <a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-meth docutils literal">merge()</tt></a>.

525

Lets use the canonical example of the User and Address objects:

526

<div class="highlight-python"><div class="highlight"><pre>class User(Base):

527

__tablename__ = 'user'

528

529

id = Column(Integer, primary_key=True)

530

name = Column(String(50), nullable=False)

531

addresses = relationship("Address", backref="user")

532

533

class Address(Base):

534

__tablename__ = 'address'

535

536

id = Column(Integer, primary_key=True)

537

email_address = Column(String(50), nullable=False)

538

user_id = Column(Integer, ForeignKey('user.id'), nullable=False)</pre></div>

539

</div>

540

Assume a <tt class="docutils literal">User</tt> object with one <tt class="docutils literal">Address</tt>, already persistent:

541

<div class="highlight-python"><div class="highlight"><pre>>>> u1 = User(name='ed', addresses=[Address(email_address='ed@ed.com')])

542

>>> session.add(u1)

543

>>> session.commit()</pre></div>

544

</div>

545

We now create <tt class="docutils literal">a1</tt>, an object outside the session, which we’d like

546

to merge on top of the existing <tt class="docutils literal">Address</tt>:

547

<div class="highlight-python"><div class="highlight"><pre>>>> existing_a1 = u1.addresses[0]

548

>>> a1 = Address(id=existing_a1.id)</pre></div>

549

</div>

550

A surprise would occur if we said this:

551

<div class="highlight-python"><div class="highlight"><pre>>>> a1.user = u1

552

>>> a1 = session.merge(a1)

553

>>> session.commit()

554

sqlalchemy.orm.exc.FlushError: New instance <Address at 0x1298f50>

555

with identity key (<class '__main__.Address'>, (1,)) conflicts with

556

persistent instance <Address at 0x12a25d0></pre></div>

557

</div>

558

Why is that ? We weren’t careful with our cascades. The assignment

559

of <tt class="docutils literal">a1.user</tt> to a persistent object cascaded to the backref of <tt class="docutils literal">User.addresses</tt>

560

and made our <tt class="docutils literal">a1</tt> object pending, as though we had added it. Now we have

561

two <tt class="docutils literal">Address</tt> objects in the session:

562

<div class="highlight-python"><div class="highlight"><pre>>>> a1 = Address()

563

>>> a1.user = u1

564

>>> a1 in session

565

True

566

>>> existing_a1 in session

567

True

568

>>> a1 is existing_a1

569

False</pre></div>

570

</div>

571

Above, our <tt class="docutils literal">a1</tt> is already pending in the session. The

572

subsequent <a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-meth docutils literal">merge()</tt></a> operation essentially

573

does nothing. Cascade can be configured via the <tt class="docutils literal">cascade</tt>

574

option on <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a>, although in this case it

575

would mean removing the <tt class="docutils literal">save-update</tt> cascade from the

576

<tt class="docutils literal">User.addresses</tt> relationship - and usually, that behavior

577

is extremely convenient. The solution here would usually be to not assign

578

<tt class="docutils literal">a1.user</tt> to an object already persistent in the target

579

session.

580

Note that a new <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a> option introduced in 0.6.5,

581

<tt class="docutils literal">cascade_backrefs=False</tt>, will also prevent the <tt class="docutils literal">Address</tt> from

582

being added to the session via the <tt class="docutils literal">a1.user = u1</tt> assignment.

583

Further detail on cascade operation is at <a class="reference internal" href="#unitofwork-cascades">Cascades</a>.

584

Another example of unexpected state:

585

<div class="highlight-python"><div class="highlight"><pre>>>> a1 = Address(id=existing_a1.id, user_id=u1.id)

586

>>> assert a1.user is None

587

>>> True

588

>>> a1 = session.merge(a1)

589

>>> session.commit()

590

sqlalchemy.exc.IntegrityError: (IntegrityError) address.user_id

591

may not be NULL</pre></div>

592

</div>

593

Here, we accessed a1.user, which returned its default value

594

of <tt class="xref docutils literal">None</tt>, which as a result of this access, has been placed in the <tt class="docutils literal">__dict__</tt> of

595

our object <tt class="docutils literal">a1</tt>. Normally, this operation creates no change event,

596

so the <tt class="docutils literal">user_id</tt> attribute takes precedence during a

597

flush. But when we merge the <tt class="docutils literal">Address</tt> object into the session, the operation

598

is equivalent to:

599

<div class="highlight-python"><div class="highlight"><pre>>>> existing_a1.id = existing_a1.id

600

>>> existing_a1.user_id = u1.id

601

>>> existing_a1.user = None</pre></div>

602

</div>

603

Where above, both <tt class="docutils literal">user_id</tt> and <tt class="docutils literal">user</tt> are assigned to, and change events

604

are emitted for both. The <tt class="docutils literal">user</tt> association

605

takes precedence, and None is applied to <tt class="docutils literal">user_id</tt>, causing a failure.

606

Most <a class="reference internal" href="#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><tt class="xref py py-meth docutils literal">merge()</tt></a> issues can be examined by first checking -

607

is the object prematurely in the session ?

608

<div class="highlight-python+sql"><div class="highlight"><pre>>>> a1 = Address(id=existing_a1, user_id=user.id)

609

>>> assert a1 not in session

610

>>> a1 = session.merge(a1)</pre></div>

611

</div>

612

Or is there state on the object that we don’t want ? Examining <tt class="docutils literal">__dict__</tt>

613

is a quick way to check:

614

<div class="highlight-python"><div class="highlight"><pre>>>> a1 = Address(id=existing_a1, user_id=user.id)

615

>>> a1.user

616

>>> a1.__dict__

617

{'_sa_instance_state': <sqlalchemy.orm.state.InstanceState object at 0x1298d10>,

618

'user_id': 1,

619

'id': 1,

620

'user': None}

621

>>> # we don't want user=None merged, remove it

622

>>> del a1.user

623

>>> a1 = session.merge(a1)

624

>>> # success

625

>>> session.commit()</pre></div>

626

</div>

627

</div>

628

</div>

629

630

<h3>Deleting<a class="headerlink" href="#deleting" title="Permalink to this headline">¶</a></h3>

631

The <a class="reference internal" href="#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-func docutils literal">delete()</tt></a> method places an instance

632

into the Session’s list of objects to be marked as deleted:

633

<div class="highlight-python"><div class="highlight"><pre># mark two objects to be deleted

634

session.delete(obj1)

635

session.delete(obj2)

636

637

# commit (or flush)

638

session.commit()</pre></div>

639

</div>

640

The big gotcha with <a class="reference internal" href="#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-func docutils literal">delete()</tt></a> is that

641

nothing is removed from collections. Such as, if a <tt class="docutils literal">User</tt> has a

642

collection of three <tt class="docutils literal">Addresses</tt>, deleting an <tt class="docutils literal">Address</tt> will not remove it

643

from <tt class="docutils literal">user.addresses</tt>:

644

<div class="highlight-python"><div class="highlight"><pre>>>> address = user.addresses[1]

645

>>> session.delete(address)

646

>>> session.flush()

647

>>> address in user.addresses

648

True</pre></div>

649

</div>

650

The solution is to use proper cascading:

651

<div class="highlight-python"><div class="highlight"><pre>mapper(User, users_table, properties={

652

'addresses':relationship(Address, cascade="all, delete, delete-orphan")

653

})

654

del user.addresses[1]

655

session.flush()</pre></div>

656

</div>

657

658

<h4>Deleting based on Filter Criterion<a class="headerlink" href="#deleting-based-on-filter-criterion" title="Permalink to this headline">¶</a></h4>

659

The caveat with <tt class="docutils literal">Session.delete()</tt> is that you need to have an object handy

660

already in order to delete. The Query includes a

661

<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.delete" title="sqlalchemy.orm.query.Query.delete"><tt class="xref py py-func docutils literal">delete()</tt></a> method which deletes based on

662

filtering criteria:

663

<div class="highlight-python"><div class="highlight"><pre>session.query(User).filter(User.id==7).delete()</pre></div>

664

</div>

665

The <tt class="docutils literal">Query.delete()</tt> method includes functionality to “expire” objects

666

already in the session which match the criteria. However it does have some

667

caveats, including that “delete” and “delete-orphan” cascades won’t be fully

668

expressed for collections which are already loaded. See the API docs for

669

<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.delete" title="sqlalchemy.orm.query.Query.delete"><tt class="xref py py-meth docutils literal">delete()</tt></a> for more details.

670

</div>

671

</div>

672

673

<h3>Flushing<a class="headerlink" href="#flushing" title="Permalink to this headline">¶</a></h3>

674

When the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> is used with its default

675

configuration, the flush step is nearly always done transparently.

676

Specifically, the flush occurs before any individual

677

<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> is issued, as well as within the

678

<a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-func docutils literal">commit()</tt></a> call before the transaction is

679

committed. It also occurs before a SAVEPOINT is issued when

680

<a class="reference internal" href="#sqlalchemy.orm.session.Session.begin_nested" title="sqlalchemy.orm.session.Session.begin_nested"><tt class="xref py py-func docutils literal">begin_nested()</tt></a> is used.

681

Regardless of the autoflush setting, a flush can always be forced by issuing

682

<a class="reference internal" href="#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><tt class="xref py py-func docutils literal">flush()</tt></a>:

683

<div class="highlight-python"><div class="highlight"><pre>session.flush()</pre></div>

684

</div>

685

The “flush-on-Query” aspect of the behavior can be disabled by constructing

686

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> with the flag <tt class="docutils literal">autoflush=False</tt>:

687

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker(autoflush=False)</pre></div>

688

</div>

689

Additionally, autoflush can be temporarily disabled by setting the

690

<tt class="docutils literal">autoflush</tt> flag at any time:

691

<div class="highlight-python"><div class="highlight"><pre>mysession = Session()

692

mysession.autoflush = False</pre></div>

693

</div>

694

Some autoflush-disable recipes are available at <a class="reference external" href="http://www.sqlalchemy.org/trac/wiki/UsageRecipes/DisableAutoflush">DisableAutoFlush</a>.

695

The flush process always occurs within a transaction, even if the

696

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> has been configured with

697

<tt class="docutils literal">autocommit=True</tt>, a setting that disables the session’s persistent

698

transactional state. If no transaction is present,

699

<a class="reference internal" href="#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><tt class="xref py py-func docutils literal">flush()</tt></a> creates its own transaction and

700

commits it. Any failures during flush will always result in a rollback of

701

whatever transaction is present. If the Session is not in <tt class="docutils literal">autocommit=True</tt>

702

mode, an explicit call to <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-func docutils literal">rollback()</tt></a> is

703

required after a flush fails, even though the underlying transaction will have

704

been rolled back already - this is so that the overall nesting pattern of

705

so-called “subtransactions” is consistently maintained.

706

</div>

707

708

<h3>Committing<a class="headerlink" href="#committing" title="Permalink to this headline">¶</a></h3>

709

<a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-func docutils literal">commit()</tt></a> is used to commit the current

710

transaction. It always issues <a class="reference internal" href="#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><tt class="xref py py-func docutils literal">flush()</tt></a>

711

beforehand to flush any remaining state to the database; this is independent

712

of the “autoflush” setting. If no transaction is present, it raises an error.

713

Note that the default behavior of the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>

714

is that a transaction is always present; this behavior can be disabled by

715

setting <tt class="docutils literal">autocommit=True</tt>. In autocommit mode, a transaction can be

716

initiated by calling the <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-func docutils literal">begin()</tt></a> method.

717

Another behavior of <a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-func docutils literal">commit()</tt></a> is that by

718

default it expires the state of all instances present after the commit is

719

complete. This is so that when the instances are next accessed, either through

720

attribute access or by them being present in a

721

<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> result set, they receive the most recent

722

state. To disable this behavior, configure

723

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> with <tt class="docutils literal">expire_on_commit=False</tt>.

724

Normally, instances loaded into the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>

725

are never changed by subsequent queries; the assumption is that the current

726

transaction is isolated so the state most recently loaded is correct as long

727

as the transaction continues. Setting <tt class="docutils literal">autocommit=True</tt> works against this

728

model to some degree since the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>

729

behaves in exactly the same way with regard to attribute state, except no

730

transaction is present.

731

</div>

732

733

<h3>Rolling Back<a class="headerlink" href="#rolling-back" title="Permalink to this headline">¶</a></h3>

734

<a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-func docutils literal">rollback()</tt></a> rolls back the current

735

transaction. With a default configured session, the post-rollback state of the

736

session is as follows:

737

738

739

<li>All transactions are rolled back and all connections returned to the

740

connection pool, unless the Session was bound directly to a Connection, in

741

which case the connection is still maintained (but still rolled back).</li>

742

<li>Objects which were initially in the pending state when they were added

743

to the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> within the lifespan of the

744

transaction are expunged, corresponding to their INSERT statement being

745

rolled back. The state of their attributes remains unchanged.</li>

746

<li>Objects which were marked as deleted within the lifespan of the

747

transaction are promoted back to the persistent state, corresponding to

748

their DELETE statement being rolled back. Note that if those objects were

749

first pending within the transaction, that operation takes precedence

750

instead.</li>

751

<li>All objects not expunged are fully expired.</li>

752

</ul>

753

</blockquote>

754

With that state understood, the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> may

755

safely continue usage after a rollback occurs.

756

When a <a class="reference internal" href="#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><tt class="xref py py-func docutils literal">flush()</tt></a> fails, typically for

757

reasons like primary key, foreign key, or “not nullable” constraint

758

violations, a <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-func docutils literal">rollback()</tt></a> is issued

759

automatically (it’s currently not possible for a flush to continue after a

760

partial failure). However, the flush process always uses its own transactional

761

demarcator called a subtransaction, which is described more fully in the

762

docstrings for <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>. What it means here is

763

that even though the database transaction has been rolled back, the end user

764

must still issue <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-func docutils literal">rollback()</tt></a> to fully

765

reset the state of the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>.

766

</div>

767

768

<h3>Expunging<a class="headerlink" href="#expunging" title="Permalink to this headline">¶</a></h3>

769

Expunge removes an object from the Session, sending persistent instances to

770

the detached state, and pending instances to the transient state:

771

<div class="highlight-python+sql"><div class="highlight"><pre>session.expunge(obj1)</pre></div>

772

</div>

773

To remove all items, call <a class="reference internal" href="#sqlalchemy.orm.session.Session.expunge_all" title="sqlalchemy.orm.session.Session.expunge_all"><tt class="xref py py-func docutils literal">expunge_all()</tt></a>

774

(this method was formerly known as <tt class="docutils literal">clear()</tt>).

775

</div>

776

777

<h3>Closing<a class="headerlink" href="#closing" title="Permalink to this headline">¶</a></h3>

778

The <a class="reference internal" href="#sqlalchemy.orm.session.Session.close" title="sqlalchemy.orm.session.Session.close"><tt class="xref py py-func docutils literal">close()</tt></a> method issues a

779

<a class="reference internal" href="#sqlalchemy.orm.session.Session.expunge_all" title="sqlalchemy.orm.session.Session.expunge_all"><tt class="xref py py-func docutils literal">expunge_all()</tt></a>, and releases any

780

transactional/connection resources. When connections are returned to the

781

connection pool, transactional state is rolled back as well.

782

</div>

783

784

<h3>Refreshing / Expiring<a class="headerlink" href="#refreshing-expiring" title="Permalink to this headline">¶</a></h3>

785

The Session normally works in the context of an ongoing transaction (with the

786

default setting of autoflush=False). Most databases offer “isolated”

787

transactions - this refers to a series of behaviors that allow the work within

788

a transaction to remain consistent as time passes, regardless of the

789

activities outside of that transaction. A key feature of a high degree of

790

transaction isolation is that emitting the same SELECT statement twice will

791

return the same results as when it was called the first time, even if the data

792

has been modified in another transaction.

793

For this reason, the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> gains very efficient behavior by

794

loading the attributes of each instance only once. Subsequent reads of the

795

same row in the same transaction are assumed to have the same value. The

796

user application also gains directly from this assumption, that the transaction

797

is regarded as a temporary shield against concurrent changes - a good application

798

will ensure that isolation levels are set appropriately such that this assumption

799

can be made, given the kind of data being worked with.

800

To clear out the currently loaded state on an instance, the instance or its individual

801

attributes can be marked as “expired”, which results in a reload to

802

occur upon next access of any of the instance’s attrbutes. The instance

803

can also be immediately reloaded from the database. The <a class="reference internal" href="#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><tt class="xref py py-meth docutils literal">expire()</tt></a>

804

and <a class="reference internal" href="#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><tt class="xref py py-meth docutils literal">refresh()</tt></a> methods achieve this:

805

<div class="highlight-python"><div class="highlight"><pre># immediately re-load attributes on obj1, obj2

806

session.refresh(obj1)

807

session.refresh(obj2)

808

809

# expire objects obj1, obj2, attributes will be reloaded

810

# on the next access:

811

session.expire(obj1)

812

session.expire(obj2)</pre></div>

813

</div>

814

When an expired object reloads, all non-deferred column-based attributes are

815

loaded in one query. Current behavior for expired relationship-based

816

attributes is that they load individually upon access - this behavior may be

817

enhanced in a future release. When a refresh is invoked on an object, the

818

ultimate operation is equivalent to a <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.get" title="sqlalchemy.orm.query.Query.get"><tt class="xref py py-meth docutils literal">Query.get()</tt></a>, so any relationships

819

configured with eager loading should also load within the scope of the refresh

820

operation.

821

<a class="reference internal" href="#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><tt class="xref py py-meth docutils literal">refresh()</tt></a> and

822

<a class="reference internal" href="#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><tt class="xref py py-meth docutils literal">expire()</tt></a> also support being passed a

823

list of individual attribute names in which to be refreshed. These names can

824

refer to any attribute, column-based or relationship based:

825

<div class="highlight-python"><div class="highlight"><pre># immediately re-load the attributes 'hello', 'world' on obj1, obj2

826

session.refresh(obj1, ['hello', 'world'])

827

session.refresh(obj2, ['hello', 'world'])

828

829

# expire the attributes 'hello', 'world' objects obj1, obj2, attributes will be reloaded

830

# on the next access:

831

session.expire(obj1, ['hello', 'world'])

832

session.expire(obj2, ['hello', 'world'])</pre></div>

833

</div>

834

The full contents of the session may be expired at once using

835

<a class="reference internal" href="#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><tt class="xref py py-meth docutils literal">expire_all()</tt></a>:

836

<div class="highlight-python"><div class="highlight"><pre>session.expire_all()</pre></div>

837

</div>

838

Note that <a class="reference internal" href="#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><tt class="xref py py-meth docutils literal">expire_all()</tt></a> is called automatically whenever

839

<a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-meth docutils literal">commit()</tt></a> or <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-meth docutils literal">rollback()</tt></a> are called. If using the

840

session in its default mode of autocommit=False and with a well-isolated

841

transactional environment (which is provided by most backends with the notable

842

exception of MySQL MyISAM), there is virtually no reason to ever call

843

<a class="reference internal" href="#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><tt class="xref py py-meth docutils literal">expire_all()</tt></a> directly - plenty of state will remain on the

844

current transaction until it is rolled back or committed or otherwise removed.

845

<a class="reference internal" href="#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><tt class="xref py py-meth docutils literal">refresh()</tt></a> and <a class="reference internal" href="#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><tt class="xref py py-meth docutils literal">expire()</tt></a> similarly are usually

846

only necessary when an UPDATE or DELETE has been issued manually within the

847

transaction using <a class="reference internal" href="#sqlalchemy.orm.session.Session.execute" title="sqlalchemy.orm.session.Session.execute"><tt class="xref py py-meth docutils literal">Session.execute()</tt></a>.

848

</div>

849

850

<h3>Session Attributes<a class="headerlink" href="#session-attributes" title="Permalink to this headline">¶</a></h3>

851

The <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> itself acts somewhat like a

852

set-like collection. All items present may be accessed using the iterator

853

interface:

854

<div class="highlight-python"><div class="highlight"><pre>for obj in session:

855

print obj</pre></div>

856

</div>

857

And presence may be tested for using regular “contains” semantics:

858

<div class="highlight-python"><div class="highlight"><pre>if obj in session:

859

print "Object is present"</pre></div>

860

</div>

861

The session is also keeping track of all newly created (i.e. pending) objects,

862

all objects which have had changes since they were last loaded or saved (i.e.

863

“dirty”), and everything that’s been marked as deleted:

864

<div class="highlight-python"><div class="highlight"><pre># pending objects recently added to the Session

865

session.new

866

867

# persistent objects which currently have changes detected

868

# (this collection is now created on the fly each time the property is called)

869

session.dirty

870

871

# persistent objects that have been marked as deleted via session.delete(obj)

872

session.deleted</pre></div>

873

</div>

874

Note that objects within the session are by default weakly referenced. This

875

means that when they are dereferenced in the outside application, they fall

876

out of scope from within the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> as well

877

and are subject to garbage collection by the Python interpreter. The

878

exceptions to this include objects which are pending, objects which are marked

879

as deleted, or persistent objects which have pending changes on them. After a

880

full flush, these collections are all empty, and all objects are again weakly

881

referenced. To disable the weak referencing behavior and force all objects

882

within the session to remain until explicitly expunged, configure

883

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> with the <tt class="docutils literal">weak_identity_map=False</tt>

884

setting.

885

</div>

886

</div>

887

888

<h2>Cascades<a class="headerlink" href="#cascades" title="Permalink to this headline">¶</a></h2>

889

Mappers support the concept of configurable cascade behavior on

890

<a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a> constructs. This behavior controls how

891

the Session should treat the instances that have a parent-child relationship

892

with another instance that is operated upon by the Session. Cascade is

893

indicated as a comma-separated list of string keywords, with the possible

894

values <tt class="docutils literal">all</tt>, <tt class="docutils literal">delete</tt>, <tt class="docutils literal">save-update</tt>, <tt class="docutils literal">refresh-expire</tt>, <tt class="docutils literal">merge</tt>,

895

<tt class="docutils literal">expunge</tt>, and <tt class="docutils literal">delete-orphan</tt>.

896

Cascading is configured by setting the <tt class="docutils literal">cascade</tt> keyword argument on a

897

<a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a>:

898

<div class="highlight-python"><div class="highlight"><pre>mapper(Order, order_table, properties={

899

'items' : relationship(Item, items_table, cascade="all, delete-orphan"),

900

'customer' : relationship(User, users_table, user_orders_table, cascade="save-update"),

901

})</pre></div>

902

</div>

903

The above mapper specifies two relationships, <tt class="docutils literal">items</tt> and <tt class="docutils literal">customer</tt>. The

904

<tt class="docutils literal">items</tt> relationship specifies “all, delete-orphan” as its <tt class="docutils literal">cascade</tt>

905

value, indicating that all <tt class="docutils literal">add</tt>, <tt class="docutils literal">merge</tt>, <tt class="docutils literal">expunge</tt>, <tt class="docutils literal">refresh</tt>

906

<tt class="docutils literal">delete</tt> and <tt class="docutils literal">expire</tt> operations performed on a parent <tt class="docutils literal">Order</tt> instance

907

should also be performed on the child <tt class="docutils literal">Item</tt> instances attached to it. The

908

<tt class="docutils literal">delete-orphan</tt> cascade value additionally indicates that if an <tt class="docutils literal">Item</tt>

909

instance is no longer associated with an <tt class="docutils literal">Order</tt>, it should also be deleted.

910

The “all, delete-orphan” cascade argument allows a so-called lifecycle

911

relationship between an <tt class="docutils literal">Order</tt> and an <tt class="docutils literal">Item</tt> object.

912

The <tt class="docutils literal">customer</tt> relationship specifies only the “save-update” cascade value,

913

indicating most operations will not be cascaded from a parent <tt class="docutils literal">Order</tt>

914

instance to a child <tt class="docutils literal">User</tt> instance except for the

915

<a class="reference internal" href="#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-func docutils literal">add()</tt></a> operation. <tt class="docutils literal">save-update</tt> cascade

916

indicates that an <a class="reference internal" href="#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-func docutils literal">add()</tt></a> on the parent

917

will cascade to all child items, and also that items added to a parent which

918

is already present in a session will also be added to that same session.

919

“save-update” cascade also cascades the pending history of a

920

relationship()-based attribute, meaning that objects which were removed from a

921

scalar or collection attribute whose changes have not yet been flushed are

922

also placed into the new session - this so that foreign key clear operations

923

and deletions will take place (new in 0.6).

924

Note that the <tt class="docutils literal">delete-orphan</tt> cascade only functions for relationships where

925

the target object can have a single parent at a time, meaning it is only

926

appropriate for one-to-one or one-to-many relationships. For a

927

<a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a> which establishes one-to-one via a local

928

foreign key, i.e. a many-to-one that stores only a single parent, or

929

one-to-one/one-to-many via a “secondary” (association) table, a warning will

930

be issued if <tt class="docutils literal">delete-orphan</tt> is configured. To disable this warning, also

931

specify the <tt class="docutils literal">single_parent=True</tt> flag on the relationship, which constrains

932

objects to allow attachment to only one parent at a time.

933

The default value for <tt class="docutils literal">cascade</tt> on <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a> is

934

<tt class="docutils literal">save-update, merge</tt>.

935

<tt class="docutils literal">save-update</tt> cascade also takes place on backrefs by default. This means

936

that, given a mapping such as this:

937

<div class="highlight-python"><div class="highlight"><pre>mapper(Order, order_table, properties={

938

'items' : relationship(Item, items_table, backref='order')

939

})</pre></div>

940

</div>

941

If an <tt class="docutils literal">Order</tt> is already in the session, and is assigned to the <tt class="docutils literal">order</tt>

942

attribute of an <tt class="docutils literal">Item</tt>, the backref appends the <tt class="docutils literal">Item</tt> to the <tt class="docutils literal">orders</tt>

943

collection of that <tt class="docutils literal">Order</tt>, resulting in the <tt class="docutils literal">save-update</tt> cascade taking

944

place:

945

<div class="highlight-python"><div class="highlight"><pre>>>> o1 = Order()

946

>>> session.add(o1)

947

>>> o1 in session

948

True

949

950

>>> i1 = Item()

951

>>> i1.order = o1

952

>>> i1 in o1.orders

953

True

954

>>> i1 in session

955

True</pre></div>

956

</div>

957

This behavior can be disabled as of 0.6.5 using the <tt class="docutils literal">cascade_backrefs</tt> flag:

958

<div class="highlight-python"><div class="highlight"><pre>mapper(Order, order_table, properties={

959

'items' : relationship(Item, items_table, backref='order',

960

cascade_backrefs=False)

961

})</pre></div>

962

</div>

963

So above, the assignment of <tt class="docutils literal">i1.order = o1</tt> will append <tt class="docutils literal">i1</tt> to the <tt class="docutils literal">orders</tt>

964

collection of <tt class="docutils literal">o1</tt>, but will not add <tt class="docutils literal">i1</tt> to the session. You can of

965

course <a class="reference internal" href="#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-func docutils literal">add()</tt></a> <tt class="docutils literal">i1</tt> to the session at a later point. This option

966

may be helpful for situations where an object needs to be kept out of a

967

session until it’s construction is completed, but still needs to be given

968

associations to objects which are already persistent in the target session.

969

</div>

970

971

<h2>Managing Transactions<a class="headerlink" href="#managing-transactions" title="Permalink to this headline">¶</a></h2>

972

The <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> manages transactions across all

973

engines associated with it. As the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>

974

receives requests to execute SQL statements using a particular

975

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

976

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, it adds each individual

977

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> encountered to its transactional state

978

and maintains an open connection for each one (note that a simple application

979

normally has just one <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a>). At commit

980

time, all unflushed data is flushed, and each individual transaction is

981

committed. If the underlying databases support two-phase semantics, this may

982

be used by the Session as well if two-phase transactions are enabled.

983

Normal operation ends the transactional state using the

984

<a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-func docutils literal">rollback()</tt></a> or

985

<a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-func docutils literal">commit()</tt></a> methods. After either is

986

called, the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> starts a new

987

transaction:

988

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker()

989

session = Session()

990

try:

991

item1 = session.query(Item).get(1)

992

item2 = session.query(Item).get(2)

993

item1.foo = 'bar'

994

item2.bar = 'foo'

995

996

# commit- will immediately go into

997

# a new transaction on next use.

998

session.commit()

999

except:

1000

# rollback - will immediately go into

1001

# a new transaction on next use.

1002

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

1003

</div>

1004

A session which is configured with <tt class="docutils literal">autocommit=True</tt> may be placed into a

1005

transaction using <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-func docutils literal">begin()</tt></a>. With an

1006

<tt class="docutils literal">autocommit=True</tt> session that’s been placed into a transaction using

1007

<a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-func docutils literal">begin()</tt></a>, the session releases all

1008

connection resources after a <a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-func docutils literal">commit()</tt></a> or

1009

<a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-func docutils literal">rollback()</tt></a> and remains transaction-less

1010

(with the exception of flushes) until the next

1011

<a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-func docutils literal">begin()</tt></a> call:

1012

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker(autocommit=True)

1013

session = Session()

1014

session.begin()

1015

try:

1016

item1 = session.query(Item).get(1)

1017

item2 = session.query(Item).get(2)

1018

item1.foo = 'bar'

1019

item2.bar = 'foo'

1020

session.commit()

1021

except:

1022

session.rollback()

1023

raise</pre></div>

1024

</div>

1025

The <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-func docutils literal">begin()</tt></a> method also returns a

1026

transactional token which is compatible with the Python 2.6 <tt class="docutils literal">with</tt>

1027

statement:

1028

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker(autocommit=True)

1029

session = Session()

1030

with session.begin():

1031

item1 = session.query(Item).get(1)

1032

item2 = session.query(Item).get(2)

1033

item1.foo = 'bar'

1034

item2.bar = 'foo'</pre></div>

1035

</div>

1036

1037

<h3>Using SAVEPOINT<a class="headerlink" href="#using-savepoint" title="Permalink to this headline">¶</a></h3>

1038

SAVEPOINT transactions, if supported by the underlying engine, may be

1039

delineated using the <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin_nested" title="sqlalchemy.orm.session.Session.begin_nested"><tt class="xref py py-func docutils literal">begin_nested()</tt></a>

1040

method:

1041

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker()

1042

session = Session()

1043

session.add(u1)

1044

session.add(u2)

1045

1046

session.begin_nested() # establish a savepoint

1047

session.add(u3)

1048

session.rollback() # rolls back u3, keeps u1 and u2

1049

1050

session.commit() # commits u1 and u2</pre></div>

1051

</div>

1052

<a class="reference internal" href="#sqlalchemy.orm.session.Session.begin_nested" title="sqlalchemy.orm.session.Session.begin_nested"><tt class="xref py py-func docutils literal">begin_nested()</tt></a> may be called any number

1053

of times, which will issue a new SAVEPOINT with a unique identifier for each

1054

call. For each <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin_nested" title="sqlalchemy.orm.session.Session.begin_nested"><tt class="xref py py-func docutils literal">begin_nested()</tt></a> call, a

1055

corresponding <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-func docutils literal">rollback()</tt></a> or

1056

<a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-func docutils literal">commit()</tt></a> must be issued.

1057

When <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin_nested" title="sqlalchemy.orm.session.Session.begin_nested"><tt class="xref py py-func docutils literal">begin_nested()</tt></a> is called, a

1058

<a class="reference internal" href="#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><tt class="xref py py-func docutils literal">flush()</tt></a> is unconditionally issued

1059

(regardless of the <tt class="docutils literal">autoflush</tt> setting). This is so that when a

1060

<a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-func docutils literal">rollback()</tt></a> occurs, the full state of the

1061

session is expired, thus causing all subsequent attribute/instance access to

1062

reference the full state of the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> right

1063

before <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin_nested" title="sqlalchemy.orm.session.Session.begin_nested"><tt class="xref py py-func docutils literal">begin_nested()</tt></a> was called.

1064

</div>

1065

1066

<h3>Using Subtransactions<a class="headerlink" href="#using-subtransactions" title="Permalink to this headline">¶</a></h3>

1067

A subtransaction, as offered by the <tt class="docutils literal">subtransactions=True</tt> flag of <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-meth docutils literal">Session.begin()</tt></a>,

1068

is a non-transactional, delimiting construct that

1069

allows nesting of calls to <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a> and <a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-meth docutils literal">commit()</tt></a>.

1070

It’s purpose is to allow the construction of code that can function within a transaction

1071

both independently of any external code that starts a transaction,

1072

as well as within a block that has already demarcated a transaction. By “non-transactional”, we

1073

mean that no actual transactional dialogue with the database is generated by this flag beyond that of

1074

a single call to <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a>, regardless of how many times the method

1075

is called within a transaction.

1076

The subtransaction feature is in fact intrinsic to any call to <a class="reference internal" href="#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><tt class="xref py py-meth docutils literal">flush()</tt></a>, which uses

1077

it internally to ensure that the series of flush steps are enclosed within a transaction,

1078

regardless of the setting of <tt class="docutils literal">autocommit</tt> or the presence of an existing transactional context.

1079

However, explicit usage of the <tt class="docutils literal">subtransactions=True</tt> flag is generally only useful with an

1080

application that uses the

1081

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> in “autocommit=True” mode, and calls <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a> explicitly

1082

in order to demarcate transactions. For this reason the subtransaction feature is not

1083

commonly used in an explicit way, except for apps that integrate SQLAlchemy-level transaction control with

1084

the transaction control of another library or subsystem. For true, general purpose “nested”

1085

transactions, where a rollback affects only a portion of the work which has proceeded,

1086

savepoints should be used, documented in <a class="reference internal" href="#session-begin-nested">Using SAVEPOINT</a>.

1087

The feature is the ORM equivalent to the pattern described at <a class="reference internal" href="../core/connections.html#connections-nested-transactions">Nesting of Transaction Blocks</a>,

1088

where any number of functions can call <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection.begin" title="sqlalchemy.engine.base.Connection.begin"><tt class="xref py py-meth docutils literal">Connection.begin()</tt></a> and <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Transaction.commit" title="sqlalchemy.engine.base.Transaction.commit"><tt class="xref py py-meth docutils literal">Transaction.commit()</tt></a>

1089

as though they are the initiator of the transaction, but in fact may be participating

1090

in an already ongoing transaction.

1091

As is the case with the non-ORM <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> object,

1092

calling <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-meth docutils literal">Session.rollback()</tt></a> rolls back the entire

1093

transaction, which was initiated by the first call to

1094

<a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-meth docutils literal">Session.begin()</tt></a> (whether this call was explicit by the

1095

end user, or implicit in an <tt class="docutils literal">autocommit=False</tt> scenario).

1096

However, the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> still considers itself to be in a

1097

“partially rolled back” state until <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-meth docutils literal">Session.rollback()</tt></a> is

1098

called explicitly for each call that was made to

1099

<a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-meth docutils literal">Session.begin()</tt></a>, where “partially rolled back” means that

1100

no further SQL operations can proceed until each level

1101

of the transaction has been acounted for, unless the <a class="reference internal" href="#sqlalchemy.orm.session.Session.close" title="sqlalchemy.orm.session.Session.close"><tt class="xref py py-meth docutils literal">close()</tt></a> method

1102

is called which cancels all transactional markers. For a full exposition on

1103

the rationale for this,

1104

please see “<a class="reference external" href="http://www.sqlalchemy.org/trac/wiki/FAQ#ButwhyisnttheoneautomaticcalltoROLLBACKenoughWhymustIROLLBACKagain">But why isn’t the one automatic call to ROLLBACK

1105

enough ? Why must I ROLLBACK again?</a>“.

1106

The general theme is that if subtransactions are used as intended, that is, as a means to nest multiple

1107

begin/commit pairs, the appropriate rollback calls naturally occur in any case, and allow the session’s

1108

nesting of transactional pairs to function in a simple and predictable way

1109

without the need to guess as to what level is active.

1110

An example of <tt class="docutils literal">subtransactions=True</tt> is nearly identical to

1111

that of the non-ORM technique. The nesting of transactions, as

1112

well as the natural presence of “rollback” for all transactions

1113

should an exception occur, is illustrated:

1114

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

1115

def method_a(session):

1116

session.begin(subtransactions=True) # open a transaction. If there was

1117

# no previous call to begin(), this will

1118

# begin a real transaction (meaning, a

1119

# DBAPI connection is procured, which as

1120

# per the DBAPI specification is in a transactional

1121

# state ready to be committed or rolled back)

1122

try:

1123

method_b(session)

1124

session.commit() # transaction is committed here

1125

except:

1126

session.rollback() # rolls back the transaction

1127

raise

1128

1129

# method_b also starts a transaction

1130

def method_b(connection):

1131

session.begin(subtransactions=True) # open a transaction - this

1132

# runs in the context of method_a()'s

1133

# transaction

1134

try:

1135

session.add(SomeObject('bat', 'lala'))

1136

session.commit() # transaction is not committed yet

1137

except:

1138

session.rollback() # rolls back the transaction, in this case

1139

# the one that was initiated in method_a().

1140

raise

1141

1142

# create a Session and call method_a

1143

session = Session(autocommit=True)

1144

method_a(session)

1145

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

1146

</div>

1147

Since the <a class="reference internal" href="#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><tt class="xref py py-meth docutils literal">Session.flush()</tt></a> method uses a subtransaction, a failed flush

1148

will always issue a rollback which then affects the state of the outermost transaction (unless a SAVEPOINT

1149

is in use). This forces the need to issue <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-meth docutils literal">rollback()</tt></a> for the full operation

1150

before subsequent SQL operations can proceed.

1151

</div>

1152

1153

<h3>Enabling Two-Phase Commit<a class="headerlink" href="#enabling-two-phase-commit" title="Permalink to this headline">¶</a></h3>

1154

Finally, for MySQL, PostgreSQL, and soon Oracle as well, the session can be

1155

instructed to use two-phase commit semantics. This will coordinate the

1156

committing of transactions across databases so that the transaction is either

1157

committed or rolled back in all databases. You can also

1158

<a class="reference internal" href="#sqlalchemy.orm.session.Session.prepare" title="sqlalchemy.orm.session.Session.prepare"><tt class="xref py py-func docutils literal">prepare()</tt></a> the session for interacting

1159

with transactions not managed by SQLAlchemy. To use two phase transactions set

1160

the flag <tt class="docutils literal">twophase=True</tt> on the session:

1161

<div class="highlight-python"><div class="highlight"><pre>engine1 = create_engine('postgresql://db1')

1162

engine2 = create_engine('postgresql://db2')

1163

1164

Session = sessionmaker(twophase=True)

1165

1166

# bind User operations to engine 1, Account operations to engine 2

1167

Session.configure(binds={User:engine1, Account:engine2})

1168

1169

session = Session()

1170

1171

# .... work with accounts and users

1172

1173

# commit. session will issue a flush to all DBs, and a prepare step to all DBs,

1174

# before committing both transactions

1175

session.commit()</pre></div>

1176

</div>

1177

</div>

1178

</div>

1179

1180

<h2>Embedding SQL Insert/Update Expressions into a Flush<a class="headerlink" href="#embedding-sql-insert-update-expressions-into-a-flush" title="Permalink to this headline">¶</a></h2>

1181

This feature allows the value of a database column to be set to a SQL

1182

expression instead of a literal value. It’s especially useful for atomic

1183

updates, calling stored procedures, etc. All you do is assign an expression to

1184

an attribute:

1185

<div class="highlight-python"><div class="highlight"><pre>class SomeClass(object):

1186

pass

1187

mapper(SomeClass, some_table)

1188

1189

someobject = session.query(SomeClass).get(5)

1190

1191

# set 'value' attribute to a SQL expression adding one

1192

someobject.value = some_table.c.value + 1

1193

1194

# issues "UPDATE some_table SET value=value+1"

1195

session.commit()</pre></div>

1196

</div>

1197

This technique works both for INSERT and UPDATE statements. After the

1198

flush/commit operation, the <tt class="docutils literal">value</tt> attribute on <tt class="docutils literal">someobject</tt> above is

1199

expired, so that when next accessed the newly generated value will be loaded

1200

from the database.

1201

</div>

1202

1203

<h2>Using SQL Expressions with Sessions<a class="headerlink" href="#using-sql-expressions-with-sessions" title="Permalink to this headline">¶</a></h2>

1204

SQL expressions and strings can be executed via the

1205

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> within its transactional context.

1206

This is most easily accomplished using the

1207

<a class="reference internal" href="#sqlalchemy.orm.session.Session.execute" title="sqlalchemy.orm.session.Session.execute"><tt class="xref py py-func docutils literal">execute()</tt></a> method, which returns a

1208

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> in the same manner as an

1209

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

1210

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

1211

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker(bind=engine)

1212

session = Session()

1213

1214

# execute a string statement

1215

result = session.execute("select * from table where id=:id", {'id':7})

1216

1217

# execute a SQL expression construct

1218

result = session.execute(select([mytable]).where(mytable.c.id==7))</pre></div>

1219

</div>

1220

The current <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> held by the

1221

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> is accessible using the

1222

<a class="reference internal" href="#sqlalchemy.orm.session.Session.connection" title="sqlalchemy.orm.session.Session.connection"><tt class="xref py py-func docutils literal">connection()</tt></a> method:

1223

<div class="highlight-python"><div class="highlight"><pre>connection = session.connection()</pre></div>

1224

</div>

1225

The examples above deal with a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> that’s

1226

bound to a single <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal">Engine</tt></a> or

1227

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. To execute statements using a

1228

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> which is bound either to multiple

1229

engines, or none at all (i.e. relies upon bound metadata), both

1230

<a class="reference internal" href="#sqlalchemy.orm.session.Session.execute" title="sqlalchemy.orm.session.Session.execute"><tt class="xref py py-func docutils literal">execute()</tt></a> and

1231

<a class="reference internal" href="#sqlalchemy.orm.session.Session.connection" title="sqlalchemy.orm.session.Session.connection"><tt class="xref py py-func docutils literal">connection()</tt></a> accept a <tt class="docutils literal">mapper</tt> keyword

1232

argument, which is passed a mapped class or

1233

<a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> instance, which is used to locate the

1234

proper context for the desired engine:

1235

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker()

1236

session = Session()

1237

1238

# need to specify mapper or class when executing

1239

result = session.execute("select * from table where id=:id", {'id':7}, mapper=MyMappedClass)

1240

1241

result = session.execute(select([mytable], mytable.c.id==7), mapper=MyMappedClass)

1242

1243

connection = session.connection(MyMappedClass)</pre></div>

1244

</div>

1245

</div>

1246

1247

<h2>Joining a Session into an External Transaction<a class="headerlink" href="#joining-a-session-into-an-external-transaction" title="Permalink to this headline">¶</a></h2>

1248

If a <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> is being used which is already in a transactional

1249

state (i.e. has a <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Transaction" title="sqlalchemy.engine.base.Transaction"><tt class="xref py py-class docutils literal">Transaction</tt></a> established), a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> can

1250

be made to participate within that transaction by just binding the

1251

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> to that <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>. The usual rationale for this

1252

is a test suite that allows ORM code to work freely with a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>,

1253

including the ability to call <a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-meth docutils literal">Session.commit()</tt></a>, where afterwards the

1254

entire database interaction is rolled back:

1255

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.orm import sessionmaker

1256

from sqlalchemy import create_engine

1257

from unittest import TestCase

1258

1259

# global application scope. create Session class, engine

1260

Session = sessionmaker()

1261

1262

engine = create_engine('postgresql://...')

1263

1264

class SomeTest(TestCase):

1265

def setUp(self):

1266

# connect to the database

1267

self.connection = engine.connect()

1268

1269

# begin a non-ORM transaction

1270

self.trans = connection.begin()

1271

1272

# bind an individual Session to the connection

1273

self.session = Session(bind=self.connection)

1274

1275

def test_something(self):

1276

# use the session in tests.

1277

1278

self.session.add(Foo())

1279

self.session.commit()

1280

1281

def tearDown(self):

1282

# rollback - everything that happened with the

1283

# Session above (including calls to commit())

1284

# is rolled back.

1285

self.trans.rollback()

1286

self.session.close()</pre></div>

1287

</div>

1288

Above, we issue <a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-meth docutils literal">Session.commit()</tt></a> as well as

1289

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Transaction.rollback" title="sqlalchemy.engine.base.Transaction.rollback"><tt class="xref py py-meth docutils literal">Transaction.rollback()</tt></a>. This is an example of where we take advantage

1290

of the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object’s ability to maintain subtransactions, or

1291

nested begin/commit-or-rollback pairs where only the outermost begin/commit

1292

pair actually commits the transaction, or if the outermost block rolls back,

1293

everything is rolled back.

1294

</div>

1295

1296

<h2>The <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object and <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> function<a class="headerlink" href="#the-session-object-and-sessionmaker-function" title="Permalink to this headline">¶</a></h2>

1297

1298

1299

<tt class="descclassname">sqlalchemy.orm.session.</tt><tt class="descname">sessionmaker</tt><big>(</big>bind=None, class_=None, autoflush=True, autocommit=False, expire_on_commit=True, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.sessionmaker" title="Permalink to this definition">¶</a></dt>

1300

<dd>Generate a custom-configured <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> class.

1301

The returned object is a subclass of <tt class="docutils literal">Session</tt>, which, when instantiated

1302

with no arguments, uses the keyword arguments configured here as its

1303

constructor arguments.

1304

It is intended that the <cite>sessionmaker()</cite> function be called within the

1305

global scope of an application, and the returned class be made available

1306

to the rest of the application as the single class used to instantiate

1307

sessions.

1308

e.g.:

1309

<div class="highlight-python"><div class="highlight"><pre># global scope

1310

Session = sessionmaker(autoflush=False)

1311

1312

# later, in a local scope, create and use a session:

1313

sess = Session()</pre></div>

1314

</div>

1315

Any keyword arguments sent to the constructor itself will override the

1316

“configured” keywords:

1317

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker()

1318

1319

# bind an individual session to a connection

1320

sess = Session(bind=connection)</pre></div>

1321

</div>

1322

The class also includes a special classmethod <tt class="docutils literal">configure()</tt>, which

1323

allows additional configurational options to take place after the custom

1324

<tt class="docutils literal">Session</tt> class has been generated. This is useful particularly for

1325

defining the specific <tt class="docutils literal">Engine</tt> (or engines) to which new instances of

1326

<tt class="docutils literal">Session</tt> should be bound:

1327

<div class="highlight-python"><div class="highlight"><pre>Session = sessionmaker()

1328

Session.configure(bind=create_engine('sqlite:///foo.db'))

1329

1330

sess = Session()</pre></div>

1331

</div>

1332

Options:

1333

1334

1335

1336

1337

<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1338

<li>autocommit – Defaults to <tt class="xref docutils literal">False</tt>. When <tt class="xref docutils literal">True</tt>, the <tt class="docutils literal">Session</tt>

1339

does not keep a persistent transaction running, and will acquire

1340

connections from the engine on an as-needed basis, returning them

1341

immediately after their use. Flushes will begin and commit (or possibly

1342

rollback) their own transaction if no transaction is present. When using

1343

this mode, the <cite>session.begin()</cite> method may be used to begin a

1344

transaction explicitly.

1345

Leaving it on its default value of <tt class="xref docutils literal">False</tt> means that the <tt class="docutils literal">Session</tt>

1346

will acquire a connection and begin a transaction the first time it is

1347

used, which it will maintain persistently until <tt class="docutils literal">rollback()</tt>,

1348

<tt class="docutils literal">commit()</tt>, or <tt class="docutils literal">close()</tt> is called. When the transaction is released

1349

by any of these methods, the <tt class="docutils literal">Session</tt> is ready for the next usage,

1350

which will again acquire and maintain a new connection/transaction.

1351

</li>

1352

<li>autoflush – When <tt class="xref docutils literal">True</tt>, all query operations will issue a

1353

<tt class="docutils literal">flush()</tt> call to this <tt class="docutils literal">Session</tt> before proceeding. This is a

1354

convenience feature so that <tt class="docutils literal">flush()</tt> need not be called repeatedly

1355

in order for database queries to retrieve results. It’s typical that

1356

<tt class="docutils literal">autoflush</tt> is used in conjunction with <tt class="docutils literal">autocommit=False</tt>. In this

1357

scenario, explicit calls to <tt class="docutils literal">flush()</tt> are rarely needed; you usually

1358

only need to call <tt class="docutils literal">commit()</tt> (which flushes) to finalize changes.</li>

1359

<li>bind – An optional <tt class="docutils literal">Engine</tt> or <tt class="docutils literal">Connection</tt> to which this

1360

<tt class="docutils literal">Session</tt> should be bound. When specified, all SQL operations

1361

performed by this session will execute via this connectable.</li>

1362

<li>binds – <dl class="docutils">

1363

<dt>An optional dictionary which contains more granular “bind”</dt>

1364

<dd>information than the <tt class="docutils literal">bind</tt> parameter provides. This dictionary can

1365

map individual <tt class="docutils literal">Table</tt> instances as well as <tt class="docutils literal">Mapper</tt> instances to

1366

individual <tt class="docutils literal">Engine</tt> or <tt class="docutils literal">Connection</tt> objects. Operations which

1367

proceed relative to a particular <tt class="docutils literal">Mapper</tt> will consult this

1368

dictionary for the direct <tt class="docutils literal">Mapper</tt> instance as well as the mapper’s

1369

<tt class="docutils literal">mapped_table</tt> attribute in order to locate an connectable to use.

1370

The full resolution is described in the <tt class="docutils literal">get_bind()</tt> method of

1371

<tt class="docutils literal">Session</tt>. Usage looks like:<div class="last highlight-python"><div class="highlight"><pre>Session = sessionmaker(binds={

1372

SomeMappedClass: create_engine('postgresql://engine1'),

1373

somemapper: create_engine('postgresql://engine2'),

1374

some_table: create_engine('postgresql://engine3'),

1375

})</pre></div>

1376

</div>

1377

</dd>

1378

</dl>

1379

Also see the <a class="reference internal" href="#sqlalchemy.orm.session.Session.bind_mapper" title="sqlalchemy.orm.session.Session.bind_mapper"><tt class="xref py py-meth docutils literal">Session.bind_mapper()</tt></a> and <a class="reference internal" href="#sqlalchemy.orm.session.Session.bind_table" title="sqlalchemy.orm.session.Session.bind_table"><tt class="xref py py-meth docutils literal">Session.bind_table()</tt></a> methods.

1380

</li>

1381

<li>class_ – Specify an alternate class other than

1382

<tt class="docutils literal">sqlalchemy.orm.session.Session</tt> which should be used by the returned

1383

class. This is the only argument that is local to the

1384

<tt class="docutils literal">sessionmaker()</tt> function, and is not sent directly to the

1385

constructor for <tt class="docutils literal">Session</tt>.</li>

1386

<li>_enable_transaction_accounting – Defaults to <tt class="xref docutils literal">True</tt>. A

1387

legacy-only flag which when <tt class="xref docutils literal">False</tt> disables all 0.5-style object

1388

accounting on transaction boundaries, including auto-expiry of

1389

instances on rollback and commit, maintenance of the “new” and

1390

“deleted” lists upon rollback, and autoflush of pending changes upon

1391

begin(), all of which are interdependent.</li>

1392

<li>expire_on_commit – Defaults to <tt class="xref docutils literal">True</tt>. When <tt class="xref docutils literal">True</tt>, all

1393

instances will be fully expired after each <tt class="docutils literal">commit()</tt>, so that all

1394

attribute/object access subsequent to a completed transaction will load

1395

from the most recent database state.</li>

1396

<li>extension – An optional

1397

<tt class="xref py py-class docutils literal">SessionExtension</tt> instance, or a list

1398

of such instances, which will receive pre- and post- commit and flush

1399

events, as well as a post-rollback event. User- defined code may be

1400

placed within these hooks using a user-defined subclass of

1401

<tt class="docutils literal">SessionExtension</tt>.</li>

1402

<li>query_cls – Class which should be used to create new Query objects,

1403

as returned by the <tt class="docutils literal">query()</tt> method. Defaults to

1404

<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a>.</li>

1405

<li>twophase – When <tt class="xref docutils literal">True</tt>, all transactions will be started as

1406

a “two phase” transaction, i.e. using the “two phase” semantics

1407

of the database in use along with an XID. During a <tt class="docutils literal">commit()</tt>,

1408

after <tt class="docutils literal">flush()</tt> has been issued for all attached databases, the

1409

<tt class="docutils literal">prepare()</tt> method on each database’s <tt class="docutils literal">TwoPhaseTransaction</tt> will

1410

be called. This allows each database to roll back the entire

1411

transaction, before each transaction is committed.</li>

1412

<li>weak_identity_map – When set to the default value of <tt class="xref docutils literal">True</tt>, a

1413

weak-referencing map is used; instances which are not externally

1414

referenced will be garbage collected immediately. For dereferenced

1415

instances which have pending changes present, the attribute management

1416

system will create a temporary strong-reference to the object which

1417

lasts until the changes are flushed to the database, at which point

1418

it’s again dereferenced. Alternatively, when using the value <tt class="xref docutils literal">False</tt>,

1419

the identity map uses a regular Python dictionary to store instances.

1420

The session will maintain all instances present until they are removed

1421

using expunge(), clear(), or purge().</li>

1422

</ul>

1423

</td>

1424

</tr>

1425

</tbody>

1426

</table>

1427

</dd></dl>

1428

1429

1430

1431

class <tt class="descclassname">sqlalchemy.orm.session.</tt><tt class="descname">Session</tt><big>(</big>bind=None, autoflush=True, expire_on_commit=True, _enable_transaction_accounting=True, autocommit=False, twophase=False, weak_identity_map=True, binds=None, extension=None, query_cls=<class 'sqlalchemy.orm.query.Query'><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session" title="Permalink to this definition">¶</a></dt>

1432

<dd>Manages persistence operations for ORM-mapped objects.

1433

The Session’s usage paradigm is described at <a class="reference internal" href="#">Using the Session</a>.

1434

1435

1436

<tt class="descname">__init__</tt><big>(</big>bind=None, autoflush=True, expire_on_commit=True, _enable_transaction_accounting=True, autocommit=False, twophase=False, weak_identity_map=True, binds=None, extension=None, query_cls=<class 'sqlalchemy.orm.query.Query'><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.__init__" title="Permalink to this definition">¶</a></dt>

1437

<dd>Construct a new Session.

1438

Arguments to <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> are described using the

1439

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> function, which is the

1440

typical point of entry.

1441

</dd></dl>

1442

1443

1444

1445

<tt class="descname">add</tt><big>(</big>instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.add" title="Permalink to this definition">¶</a></dt>

1446

<dd>Place an object in the <tt class="docutils literal">Session</tt>.

1447

Its state will be persisted to the database on the next flush

1448

operation.

1449

Repeated calls to <tt class="docutils literal">add()</tt> will be ignored. The opposite of <tt class="docutils literal">add()</tt>

1450

is <tt class="docutils literal">expunge()</tt>.

1451

</dd></dl>

1452

1453

1454

1455

<tt class="descname">add_all</tt><big>(</big>instances<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.add_all" title="Permalink to this definition">¶</a></dt>

1456

<dd>Add the given collection of instances to this <tt class="docutils literal">Session</tt>.

1457

</dd></dl>

1458

1459

1460

1461

<tt class="descname">begin</tt><big>(</big>subtransactions=False, nested=False<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.begin" title="Permalink to this definition">¶</a></dt>

1462

<dd>Begin a transaction on this Session.

1463

If this Session is already within a transaction, either a plain

1464

transaction or nested transaction, an error is raised, unless

1465

<tt class="docutils literal">subtransactions=True</tt> or <tt class="docutils literal">nested=True</tt> is specified.

1466

The <tt class="docutils literal">subtransactions=True</tt> flag indicates that this <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin" title="sqlalchemy.orm.session.Session.begin"><tt class="xref py py-meth docutils literal">begin()</tt></a>

1467

can create a subtransaction if a transaction is already in progress.

1468

For documentation on subtransactions, please see <a class="reference internal" href="#session-subtransactions">Using Subtransactions</a>.

1469

The <tt class="docutils literal">nested</tt> flag begins a SAVEPOINT transaction and is equivalent

1470

to calling <a class="reference internal" href="#sqlalchemy.orm.session.Session.begin_nested" title="sqlalchemy.orm.session.Session.begin_nested"><tt class="xref py py-meth docutils literal">begin_nested()</tt></a>. For documentation on SAVEPOINT

1471

transactions, please see <a class="reference internal" href="#session-begin-nested">Using SAVEPOINT</a>.

1472

</dd></dl>

1473

1474

1475

1476

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

1477

<dd>Begin a <cite>nested</cite> transaction on this Session.

1478

The target database(s) must support SQL SAVEPOINTs or a

1479

SQLAlchemy-supported vendor implementation of the idea.

1480

For documentation on SAVEPOINT

1481

transactions, please see <a class="reference internal" href="#session-begin-nested">Using SAVEPOINT</a>.

1482

</dd></dl>

1483

1484

1485

1486

<tt class="descname">bind_mapper</tt><big>(</big>mapper, bind<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.bind_mapper" title="Permalink to this definition">¶</a></dt>

1487

<dd>Bind operations for a mapper to a Connectable.

1488

1489

<dt>mapper</dt>

1490

<dd>A mapper instance or mapped class</dd>

1491

1492

<dd>Any Connectable: a <tt class="docutils literal">Engine</tt> or <tt class="docutils literal">Connection</tt>.</dd>

1493

</dl>

1494

All subsequent operations involving this mapper will use the given

1495

<cite>bind</cite>.

1496

</dd></dl>

1497

1498

1499

1500

<tt class="descname">bind_table</tt><big>(</big>table, bind<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.bind_table" title="Permalink to this definition">¶</a></dt>

1501

<dd>Bind operations on a Table to a Connectable.

1502

1503

<dt>table</dt>

1504

<dd>A <tt class="docutils literal">Table</tt> instance</dd>

1505

1506

<dd>Any Connectable: a <tt class="docutils literal">Engine</tt> or <tt class="docutils literal">Connection</tt>.</dd>

1507

</dl>

1508

All subsequent operations involving this <tt class="docutils literal">Table</tt> will use the

1509

given <cite>bind</cite>.

1510

</dd></dl>

1511

1512

1513

1514

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

1515

<dd>Close this Session.

1516

This clears all items and ends any transaction in progress.

1517

If this session were created with <tt class="docutils literal">autocommit=False</tt>, a new

1518

transaction is immediately begun. Note that this new transaction does

1519

not use any connection resources until they are first needed.

1520

</dd></dl>

1521

1522

1523

1524

classmethod <tt class="descname">close_all</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.close_all" title="Permalink to this definition">¶</a></dt>

1525

<dd>Close all sessions in memory.

1526

</dd></dl>

1527

1528

1529

1530

<tt class="descname">commit</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.commit" title="Permalink to this definition">¶</a></dt>

1531

<dd>Flush pending changes and commit the current transaction.

1532

If no transaction is in progress, this method raises an

1533

InvalidRequestError.

1534

By default, the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> also expires all database

1535

loaded state on all ORM-managed attributes after transaction commit.

1536

This so that subsequent operations load the most recent

1537

data from the database. This behavior can be disabled using

1538

the <tt class="docutils literal">expire_on_commit=False</tt> option to <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> or

1539

the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> constructor.

1540

If a subtransaction is in effect (which occurs when begin() is called

1541

multiple times), the subtransaction will be closed, and the next call

1542

to <tt class="docutils literal">commit()</tt> will operate on the enclosing transaction.

1543

For a session configured with autocommit=False, a new transaction will

1544

be begun immediately after the commit, but note that the newly begun

1545

transaction does not use any connection resources until the first

1546

SQL is actually emitted.

1547

</dd></dl>

1548

1549

1550

1551

<tt class="descname">connection</tt><big>(</big>mapper=None, clause=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.connection" title="Permalink to this definition">¶</a></dt>

1552

<dd>Return the active Connection.

1553

Retrieves the <tt class="docutils literal">Connection</tt> managing the current transaction. Any

1554

operations executed on the Connection will take place in the same

1555

transactional context as <tt class="docutils literal">Session</tt> operations.

1556

For <tt class="docutils literal">autocommit</tt> Sessions with no active manual transaction,

1557

<tt class="docutils literal">connection()</tt> is a passthrough to <tt class="docutils literal">contextual_connect()</tt> on the

1558

underlying engine.

1559

Ambiguity in multi-bind or unbound Sessions can be resolved through

1560

any of the optional keyword arguments. See <tt class="docutils literal">get_bind()</tt> for more

1561

information.

1562

1563

<dt>mapper</dt>

1564

<dd>Optional, a <tt class="docutils literal">mapper</tt> or mapped class</dd>

1565

<dt>clause</dt>

1566

<dd>Optional, any <tt class="docutils literal">ClauseElement</tt></dd>

1567

</dl>

1568

</dd></dl>

1569

1570

1571

1572

<tt class="descname">delete</tt><big>(</big>instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.delete" title="Permalink to this definition">¶</a></dt>

1573

<dd>Mark an instance as deleted.

1574

The database delete operation occurs upon <tt class="docutils literal">flush()</tt>.

1575

</dd></dl>

1576

1577

1578

1579

<tt class="descname">deleted</tt><a class="headerlink" href="#sqlalchemy.orm.session.Session.deleted" title="Permalink to this definition">¶</a></dt>

1580

<dd>The set of all instances marked as ‘deleted’ within this <tt class="docutils literal">Session</tt>

1581

</dd></dl>

1582

1583

1584

1585

<tt class="descname">dirty</tt><a class="headerlink" href="#sqlalchemy.orm.session.Session.dirty" title="Permalink to this definition">¶</a></dt>

1586

<dd>The set of all persistent instances considered dirty.

1587

Instances are considered dirty when they were modified but not

1588

deleted.

1589

Note that this ‘dirty’ calculation is ‘optimistic’; most

1590

attribute-setting or collection modification operations will

1591

mark an instance as ‘dirty’ and place it in this set, even if

1592

there is no net change to the attribute’s value. At flush

1593

time, the value of each attribute is compared to its

1594

previously saved value, and if there’s no net change, no SQL

1595

operation will occur (this is a more expensive operation so

1596

it’s only done at flush time).

1597

To check if an instance has actionable net changes to its

1598

attributes, use the is_modified() method.

1599

</dd></dl>

1600

1601

1602

1603

<tt class="descname">execute</tt><big>(</big>clause, params=None, mapper=None, **kw<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.execute" title="Permalink to this definition">¶</a></dt>

1604

<dd>Execute a clause within the current transaction.

1605

Returns a <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> representing

1606

results of the statement execution, in the same manner as that of an

1607

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

1608

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

1609

<a class="reference internal" href="#sqlalchemy.orm.session.Session.execute" title="sqlalchemy.orm.session.Session.execute"><tt class="xref py py-meth docutils literal">Session.execute()</tt></a> accepts any executable clause construct, such

1610

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

1611

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

1612

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

1613

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

1614

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

1615

plain strings that represent SQL statements. If a plain string is

1616

passed, it is first converted to a

1617

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

1618

that bind parameters should be specified using the format <tt class="docutils literal">:param</tt>.

1619

The statement is executed within the current transactional context of

1620

this <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>. If this <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> is set for

1621

“autocommit”, and no transaction is in progress, an ad-hoc transaction

1622

will be created for the life of the result (i.e., a connection is

1623

checked out from the connection pool, which is returned when the

1624

result object is closed).

1625

If the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> is not bound to an

1626

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

1627

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>, the given clause will be

1628

inspected for binds (i.e., looking for “bound metadata”). If the

1629

session is bound to multiple connectables, the <tt class="docutils literal">mapper</tt> keyword

1630

argument is typically passed in to specify which bind should be used

1631

(since the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> keys multiple bind sources to a series of

1632

<tt class="xref py py-func docutils literal">mapper()</tt> objects). See <a class="reference internal" href="#sqlalchemy.orm.session.Session.get_bind" title="sqlalchemy.orm.session.Session.get_bind"><tt class="xref py py-meth docutils literal">get_bind()</tt></a> for further details on

1633

bind resolution.

1634

1635

1636

1637

1638

<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1639

<li>clause – A ClauseElement (i.e. select(), text(), etc.) or

1640

string SQL statement to be executed</li>

1641

<li>params – Optional, a dictionary of bind parameters.</li>

1642

<li>mapper – Optional, a <tt class="docutils literal">mapper</tt> or mapped class</li>

1643

<li>**kw – Additional keyword arguments are sent to <a class="reference internal" href="#sqlalchemy.orm.session.Session.get_bind" title="sqlalchemy.orm.session.Session.get_bind"><tt class="xref py py-meth docutils literal">get_bind()</tt></a>

1644

which locates a connectable to use for the execution.</li>

1645

</ul>

1646

</td>

1647

</tr>

1648

</tbody>

1649

</table>

1650

</dd></dl>

1651

1652

1653

1654

<tt class="descname">expire</tt><big>(</big>instance, attribute_names=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.expire" title="Permalink to this definition">¶</a></dt>

1655

<dd>Expire the attributes on an instance.

1656

Marks the attributes of an instance as out of date. When an expired

1657

attribute is next accessed, a query will be issued to the

1658

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object’s current transactional context in order to

1659

load all expired attributes for the given instance. Note that

1660

a highly isolated transaction will return the same values as were

1661

previously read in that same transaction, regardless of changes

1662

in database state outside of that transaction.

1663

To expire all objects in the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> simultaneously,

1664

use <a class="reference internal" href="#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><tt class="xref py py-meth docutils literal">Session.expire_all()</tt></a>.

1665

The <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object’s default behavior is to

1666

expire all state whenever the <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-meth docutils literal">Session.rollback()</tt></a>

1667

or <a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-meth docutils literal">Session.commit()</tt></a> methods are called, so that new

1668

state can be loaded for the new transaction. For this reason,

1669

calling <a class="reference internal" href="#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><tt class="xref py py-meth docutils literal">Session.expire()</tt></a> only makes sense for the specific

1670

case that a non-ORM SQL statement was emitted in the current

1671

transaction.

1672

1673

1674

1675

1676

<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1677

<li>instance – The instance to be refreshed.</li>

1678

<li>attribute_names – optional list of string attribute names

1679

indicating a subset of attributes to be expired.</li>

1680

</ul>

1681

</td>

1682

</tr>

1683

</tbody>

1684

</table>

1685

</dd></dl>

1686

1687

1688

1689

<tt class="descname">expire_all</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.expire_all" title="Permalink to this definition">¶</a></dt>

1690

<dd>Expires all persistent instances within this Session.

1691

When any attributes on a persitent instance is next accessed,

1692

a query will be issued using the

1693

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object’s current transactional context in order to

1694

load all expired attributes for the given instance. Note that

1695

a highly isolated transaction will return the same values as were

1696

previously read in that same transaction, regardless of changes

1697

in database state outside of that transaction.

1698

To expire individual objects and individual attributes

1699

on those objects, use <a class="reference internal" href="#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><tt class="xref py py-meth docutils literal">Session.expire()</tt></a>.

1700

The <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object’s default behavior is to

1701

expire all state whenever the <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-meth docutils literal">Session.rollback()</tt></a>

1702

or <a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-meth docutils literal">Session.commit()</tt></a> methods are called, so that new

1703

state can be loaded for the new transaction. For this reason,

1704

calling <a class="reference internal" href="#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><tt class="xref py py-meth docutils literal">Session.expire_all()</tt></a> should not be needed when

1705

autocommit is <tt class="xref docutils literal">False</tt>, assuming the transaction is isolated.

1706

</dd></dl>

1707

1708

1709

1710

<tt class="descname">expunge</tt><big>(</big>instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.expunge" title="Permalink to this definition">¶</a></dt>

1711

<dd>Remove the <cite>instance</cite> from this <tt class="docutils literal">Session</tt>.

1712

This will free all internal references to the instance. Cascading

1713

will be applied according to the expunge cascade rule.

1714

</dd></dl>

1715

1716

1717

1718

<tt class="descname">expunge_all</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.expunge_all" title="Permalink to this definition">¶</a></dt>

1719

<dd>Remove all object instances from this <tt class="docutils literal">Session</tt>.

1720

This is equivalent to calling <tt class="docutils literal">expunge(obj)</tt> on all objects in this

1721

<tt class="docutils literal">Session</tt>.

1722

</dd></dl>

1723

1724

1725

1726

<tt class="descname">flush</tt><big>(</big>objects=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.flush" title="Permalink to this definition">¶</a></dt>

1727

<dd>Flush all the object changes to the database.

1728

Writes out all pending object creations, deletions and modifications

1729

to the database as INSERTs, DELETEs, UPDATEs, etc. Operations are

1730

automatically ordered by the Session’s unit of work dependency

1731

solver..

1732

Database operations will be issued in the current transactional

1733

context and do not affect the state of the transaction. You may

1734

flush() as often as you like within a transaction to move changes from

1735

Python to the database’s transaction buffer.

1736

For <tt class="docutils literal">autocommit</tt> Sessions with no active manual transaction, flush()

1737

will create a transaction on the fly that surrounds the entire set of

1738

operations int the flush.

1739

1740

<dt>objects</dt>

1741

<dd>Optional; a list or tuple collection. Restricts the flush operation

1742

to only these objects, rather than all pending changes.

1743

Deprecated - this flag prevents the session from properly maintaining

1744

accounting among inter-object relations and can cause invalid results.</dd>

1745

</dl>

1746

</dd></dl>

1747

1748

1749

1750

<tt class="descname">get_bind</tt><big>(</big>mapper, clause=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.get_bind" title="Permalink to this definition">¶</a></dt>

1751

<dd>Return an engine corresponding to the given arguments.

1752

All arguments are optional.

1753

1754

<dt>mapper</dt>

1755

<dd>Optional, a <tt class="docutils literal">Mapper</tt> or mapped class</dd>

1756

<dt>clause</dt>

1757

<dd>Optional, A ClauseElement (i.e. select(), text(), etc.)</dd>

1758

</dl>

1759

</dd></dl>

1760

1761

1762

1763

<tt class="descname">is_active</tt><a class="headerlink" href="#sqlalchemy.orm.session.Session.is_active" title="Permalink to this definition">¶</a></dt>

1764

<dd>True if this Session has an active transaction.

1765

</dd></dl>

1766

1767

1768

1769

<tt class="descname">is_modified</tt><big>(</big>instance, include_collections=True, passive=False<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.is_modified" title="Permalink to this definition">¶</a></dt>

1770

<dd>Return <tt class="xref docutils literal">True</tt> if instance has modified attributes.

1771

This method retrieves a history instance for each instrumented

1772

attribute on the instance and performs a comparison of the current

1773

value to its previously committed value.

1774

<tt class="docutils literal">include_collections</tt> indicates if multivalued collections should be

1775

included in the operation. Setting this to False is a way to detect

1776

only local-column based properties (i.e. scalar columns or many-to-one

1777

foreign keys) that would result in an UPDATE for this instance upon

1778

flush.

1779

The <tt class="docutils literal">passive</tt> flag indicates if unloaded attributes and collections

1780

should not be loaded in the course of performing this test.

1781

A few caveats to this method apply:

1782

<ul>

1783

<li>Instances present in the ‘dirty’ collection may result in a value

1784

of <tt class="xref docutils literal">False</tt> when tested with this method. This because while

1785

the object may have received attribute set events, there may be

1786

no net changes on its state.

1787

</li>

1788

<li>Scalar attributes may not have recorded the “previously” set

1789

value when a new value was applied, if the attribute was not loaded,

1790

or was expired, at the time the new value was received - in these

1791

cases, the attribute is assumed to have a change, even if there is

1792

ultimately no net change against its database value. SQLAlchemy in

1793

most cases does not need the “old” value when a set event occurs, so

1794

it skips the expense of a SQL call if the old value isn’t present,

1795

based on the assumption that an UPDATE of the scalar value is

1796

usually needed, and in those few cases where it isn’t, is less

1797

expensive on average than issuing a defensive SELECT.

1798

The “old” value is fetched unconditionally only if the attribute

1799

container has the “active_history” flag set to <tt class="xref docutils literal">True</tt>. This flag

1800

is set typically for primary key attributes and scalar references

1801

that are not a simple many-to-one.

1802

</li>

1803

</ul>

1804

</dd></dl>

1805

1806

1807

1808

<tt class="descname">merge</tt><big>(</big>instance, load=True, **kw<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.merge" title="Permalink to this definition">¶</a></dt>

1809

<dd>Copy the state an instance onto the persistent instance with the same identifier.

1810

If there is no persistent instance currently associated with the

1811

session, it will be loaded. Return the persistent instance. If the

1812

given instance is unsaved, save a copy of and return it as a newly

1813

persistent instance. The given instance does not become associated

1814

with the session.

1815

This operation cascades to associated instances if the association is

1816

mapped with <tt class="docutils literal">cascade="merge"</tt>.

1817

See <a class="reference internal" href="#unitofwork-merging">Merging</a> for a detailed discussion of merging.

1818

</dd></dl>

1819

1820

1821

1822

1823

<dd>The set of all instances marked as ‘new’ within this <tt class="docutils literal">Session</tt>.

1824

</dd></dl>

1825

1826

1827

1828

classmethod <tt class="descname">object_session</tt><big>(</big>instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.object_session" title="Permalink to this definition">¶</a></dt>

1829

<dd>Return the <tt class="docutils literal">Session</tt> to which an object belongs.

1830

</dd></dl>

1831

1832

1833

1834

<tt class="descname">prepare</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.prepare" title="Permalink to this definition">¶</a></dt>

1835

<dd>Prepare the current transaction in progress for two phase commit.

1836

If no transaction is in progress, this method raises an

1837

InvalidRequestError.

1838

Only root transactions of two phase sessions can be prepared. If the

1839

current transaction is not such, an InvalidRequestError is raised.

1840

</dd></dl>

1841

1842

1843

1844

<tt class="descname">prune</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.prune" title="Permalink to this definition">¶</a></dt>

1845

<dd>Remove unreferenced instances cached in the identity map.

1846

Note that this method is only meaningful if “weak_identity_map” is set

1847

to False. The default weak identity map is self-pruning.

1848

Removes any object in this Session’s identity map that is not

1849

referenced in user code, modified, new or scheduled for deletion.

1850

Returns the number of objects pruned.

1851

</dd></dl>

1852

1853

1854

1855

<tt class="descname">query</tt><big>(</big>*entities, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.query" title="Permalink to this definition">¶</a></dt>

1856

<dd>Return a new <tt class="docutils literal">Query</tt> object corresponding to this <tt class="docutils literal">Session</tt>.

1857

</dd></dl>

1858

1859

1860

1861

<tt class="descname">refresh</tt><big>(</big>instance, attribute_names=None, lockmode=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.refresh" title="Permalink to this definition">¶</a></dt>

1862

<dd>Expire and refresh the attributes on the given instance.

1863

A query will be issued to the database and all attributes will be

1864

refreshed with their current database value.

1865

Lazy-loaded relational attributes will remain lazily loaded, so that

1866

the instance-wide refresh operation will be followed immediately by

1867

the lazy load of that attribute.

1868

Eagerly-loaded relational attributes will eagerly load within the

1869

single refresh operation.

1870

Note that a highly isolated transaction will return the same values as

1871

were previously read in that same transaction, regardless of changes

1872

in database state outside of that transaction - usage of

1873

<a class="reference internal" href="#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><tt class="xref py py-meth docutils literal">refresh()</tt></a> usually only makes sense if non-ORM SQL

1874

statement were emitted in the ongoing transaction, or if autocommit

1875

mode is turned on.

1876

1877

1878

1879

1880

<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1881

<li>attribute_names – optional. An iterable collection of

1882

string attribute names indicating a subset of attributes to

1883

be refreshed.</li>

1884

<li>lockmode – Passed to the <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a>

1885

as used by <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.with_lockmode" title="sqlalchemy.orm.query.Query.with_lockmode"><tt class="xref py py-meth docutils literal">with_lockmode()</tt></a>.</li>

1886

</ul>

1887

</td>

1888

</tr>

1889

</tbody>

1890

</table>

1891

</dd></dl>

1892

1893

1894

1895

<tt class="descname">rollback</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.rollback" title="Permalink to this definition">¶</a></dt>

1896

<dd>Rollback the current transaction in progress.

1897

If no transaction is in progress, this method is a pass-through.

1898

This method rolls back the current transaction or nested transaction

1899

regardless of subtransactions being in effect. All subtransactions up

1900

to the first real transaction are closed. Subtransactions occur when

1901

begin() is called multiple times.

1902

</dd></dl>

1903

1904

1905

1906

<tt class="descname">scalar</tt><big>(</big>clause, params=None, mapper=None, **kw<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.Session.scalar" title="Permalink to this definition">¶</a></dt>

1907

<dd>Like execute() but return a scalar result.

1908

</dd></dl>

1909

1910

</dd></dl>

1911

1912

</div>

1913

1914

<h2>Contextual/Thread-local Sessions<a class="headerlink" href="#contextual-thread-local-sessions" title="Permalink to this headline">¶</a></h2>

1915

A common need in applications, particularly those built around web frameworks,

1916

is the ability to “share” a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object

1917

among disparate parts of an application, without needing to pass the object

1918

explicitly to all method and function calls. What you’re really looking for is

1919

some kind of “global” session object, or at least “global” to all the parts of

1920

an application which are tasked with servicing the current request. For this

1921

pattern, SQLAlchemy provides the ability to enhance the

1922

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> class generated by

1923

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> to provide auto-contextualizing support.

1924

This means that whenever you create a <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>

1925

instance with its constructor, you get an existing

1926

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object which is bound to some

1927

“context”. By default, this context is the current thread. This feature is

1928

what previously was accomplished using the <tt class="docutils literal">sessioncontext</tt> SQLAlchemy

1929

extension.

1930

1931

<h3>Creating a Thread-local Context<a class="headerlink" href="#creating-a-thread-local-context" title="Permalink to this headline">¶</a></h3>

1932

The <a class="reference internal" href="#sqlalchemy.orm.scoped_session" title="sqlalchemy.orm.scoped_session"><tt class="xref py py-func docutils literal">scoped_session()</tt></a> function wraps around the

1933

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a> function, and produces an object which

1934

behaves the same as the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> subclass

1935

returned by <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a>:

1936

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.orm import scoped_session, sessionmaker

1937

Session = scoped_session(sessionmaker())</pre></div>

1938

</div>

1939

However, when you instantiate this <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a>

1940

“class”, in reality the object is pulled from a threadlocal variable, or if it

1941

doesn’t exist yet, it’s created using the underlying class generated by

1942

<a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a>:

1943

<div class="highlight-python"><div class="highlight"><pre>>>> # call Session() the first time. the new Session instance is created.

1944

>>> session = Session()

1945

1946

>>> # later, in the same application thread, someone else calls Session()

1947

>>> session2 = Session()

1948

1949

>>> # the two Session objects are *the same* object

1950

>>> session is session2

1951

True</pre></div>

1952

</div>

1953

Since the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session()</tt></a> constructor now returns

1954

the same <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> object every time within the

1955

current thread, the object returned by <a class="reference internal" href="#sqlalchemy.orm.scoped_session" title="sqlalchemy.orm.scoped_session"><tt class="xref py py-func docutils literal">scoped_session()</tt></a>

1956

also implements most of the <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> methods

1957

and properties at the “class” level, such that you don’t even need to

1958

instantiate <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session()</tt></a>:

1959

<div class="highlight-python"><div class="highlight"><pre># create some objects

1960

u1 = User()

1961

u2 = User()

1962

1963

# save to the contextual session, without instantiating

1964

Session.add(u1)

1965

Session.add(u2)

1966

1967

# view the "new" attribute

1968

assert u1 in Session.new

1969

1970

# commit changes

1971

Session.commit()</pre></div>

1972

</div>

1973

The contextual session may be disposed of by calling <tt class="docutils literal">Session.remove()</tt>:

1974

<div class="highlight-python"><div class="highlight"><pre># remove current contextual session

1975

Session.remove()</pre></div>

1976

</div>

1977

After <tt class="docutils literal">remove()</tt> is called, the next operation with the contextual session

1978

will start a new <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> for the current

1979

thread.

1980

</div>

1981

1982

<h3>Lifespan of a Contextual Session<a class="headerlink" href="#lifespan-of-a-contextual-session" title="Permalink to this headline">¶</a></h3>

1983

A (really, really) common question is when does the contextual session get

1984

created, when does it get disposed ? We’ll consider a typical lifespan as used

1985

in a web application:

1986

<div class="highlight-python"><pre>Web Server Web Framework User-defined Controller Call

1987

-------------- -------------- ------------------------------

1988

web request ->

1989

call controller -> # call Session(). this establishes a new,

1990

# contextual Session.

1991

session = Session()

1992

1993

# load some objects, save some changes

1994

objects = session.query(MyClass).all()

1995

1996

# some other code calls Session, it's the

1997

# same contextual session as "sess"

1998

session2 = Session()

1999

session2.add(foo)

2000

session2.commit()

2001

2002

# generate content to be returned

2003

return generate_content()

2004

Session.remove() <-

2005

web response <-</pre>

2006

</div>

2007

The above example illustrates an explicit call to <a class="reference internal" href="#sqlalchemy.orm.scoping.ScopedSession.remove" title="sqlalchemy.orm.scoping.ScopedSession.remove"><tt class="xref py py-meth docutils literal">ScopedSession.remove()</tt></a>. This

2008

has the effect such that each web request starts fresh with a brand new

2009

session, and is the most definitive approach to closing out a request.

2010

It’s not strictly necessary to remove the session at the end of the request -

2011

other options include calling <a class="reference internal" href="#sqlalchemy.orm.session.Session.close" title="sqlalchemy.orm.session.Session.close"><tt class="xref py py-meth docutils literal">Session.close()</tt></a>, <a class="reference internal" href="#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><tt class="xref py py-meth docutils literal">Session.rollback()</tt></a>,

2012

<a class="reference internal" href="#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><tt class="xref py py-meth docutils literal">Session.commit()</tt></a> at the end so that the existing session returns

2013

its connections to the pool and removes any existing transactional context.

2014

Doing nothing is an option too, if individual controller methods take responsibility

2015

for ensuring that no transactions remain open after a request ends.

2016

</div>

2017

2018

<h3>Contextual Session API<a class="headerlink" href="#contextual-session-api" title="Permalink to this headline">¶</a></h3>

2019

2020

2021

<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">scoped_session</tt><big>(</big>session_factory, scopefunc=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.scoped_session" title="Permalink to this definition">¶</a></dt>

2022

<dd>Provides thread-local or scoped management of <a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> objects.

2023

This is a front-end function to

2024

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

2025

2026

2027

2028

2029

<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">

2030

<li>session_factory – a callable function that produces

2031

<a class="reference internal" href="#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> instances, such as <a class="reference internal" href="#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a>.</li>

2032

<li>scopefunc – Optional “scope” function which would be

2033

passed to the <a class="reference internal" href="#sqlalchemy.util.ScopedRegistry" title="sqlalchemy.util.ScopedRegistry"><tt class="xref py py-class docutils literal">ScopedRegistry</tt></a>. If None, the

2034

<a class="reference internal" href="#sqlalchemy.util.ThreadLocalRegistry" title="sqlalchemy.util.ThreadLocalRegistry"><tt class="xref py py-class docutils literal">ThreadLocalRegistry</tt></a> is used by default.</li>

2035

</ul>

2036

</td>

2037

</tr>

2038

<tr class="field"><th class="field-name">Returns:</th><td class="field-body">an <a class="reference internal" href="#sqlalchemy.orm.scoping.ScopedSession" title="sqlalchemy.orm.scoping.ScopedSession"><tt class="xref py py-class docutils literal">ScopedSession</tt></a> instance

2039

</td>

2040

</tr>

2041

</tbody>

2042

</table>

2043

Usage:

2044

<div class="highlight-python"><div class="highlight"><pre>Session = scoped_session(sessionmaker(autoflush=True))</pre></div>

2045

</div>

2046

To instantiate a Session object which is part of the scoped context,

2047

instantiate normally:

2048

<div class="highlight-python"><div class="highlight"><pre>session = Session()</pre></div>

2049

</div>

2050

Most session methods are available as classmethods from the scoped

2051

session:

2052

<div class="highlight-python"><div class="highlight"><pre>Session.commit()

2053

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

2054

</div>

2055

</dd></dl>

2056

2057

2058

2059

class <tt class="descclassname">sqlalchemy.orm.scoping.</tt><tt class="descname">ScopedSession</tt><big>(</big>session_factory, scopefunc=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.scoping.ScopedSession" title="Permalink to this definition">¶</a></dt>

2060

<dd>Provides thread-local management of Sessions.

2061

Usage:

2062

<div class="highlight-python"><div class="highlight"><pre>Session = scoped_session(sessionmaker())</pre></div>

2063

</div>

2064

... use Session normally.

2065

The internal registry is accessible as well,

2066

and by default is an instance of <a class="reference internal" href="#sqlalchemy.util.ThreadLocalRegistry" title="sqlalchemy.util.ThreadLocalRegistry"><tt class="xref py py-class docutils literal">ThreadLocalRegistry</tt></a>.

2067

2068

2069

<tt class="descname">__init__</tt><big>(</big>session_factory, scopefunc=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.scoping.ScopedSession.__init__" title="Permalink to this definition">¶</a></dt>

2070

2071

2072

2073

2074

<tt class="descname">configure</tt><big>(</big>**kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.orm.scoping.ScopedSession.configure" title="Permalink to this definition">¶</a></dt>

2075

<dd>reconfigure the sessionmaker used by this ScopedSession.

2076

</dd></dl>

2077

2078

2079

2080

<tt class="descname">mapper</tt><big>(</big>*args, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.orm.scoping.ScopedSession.mapper" title="Permalink to this definition">¶</a></dt>

2081

<dd>return a <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a> function which associates this ScopedSession with the Mapper.

2082

2083

Deprecated since version 0.5: <a class="reference internal" href="#sqlalchemy.orm.scoping.ScopedSession.mapper" title="sqlalchemy.orm.scoping.ScopedSession.mapper"><tt class="xref py py-meth docutils literal">ScopedSession.mapper()</tt></a> is deprecated. Please see <a class="reference external" href="http://www.sqlalchemy.org/trac/wiki/UsageRecipes/SessionAwareMapper">http://www.sqlalchemy.org/trac/wiki/UsageRecipes/SessionAwareMapper</a> for information on how to replicate its behavior.

2084

</dd></dl>

2085

2086

2087

2088

<tt class="descname">query_property</tt><big>(</big>query_cls=None<big>)</big><a class="headerlink" href="#sqlalchemy.orm.scoping.ScopedSession.query_property" title="Permalink to this definition">¶</a></dt>

2089

<dd>return a class property which produces a <cite>Query</cite> object against the

2090

class when called.

2091

e.g.:

2092

<div class="highlight-python"><div class="highlight"><pre>Session = scoped_session(sessionmaker())

2093

2094

class MyClass(object):

2095

query = Session.query_property()

2096

2097

# after mappers are defined

2098

result = MyClass.query.filter(MyClass.name=='foo').all()</pre></div>

2099

</div>

2100

Produces instances of the session’s configured query class by

2101

default. To override and use a custom implementation, provide

2102

a <tt class="docutils literal">query_cls</tt> callable. The callable will be invoked with

2103

the class’s mapper as a positional argument and a session

2104

keyword argument.

2105

There is no limit to the number of query properties placed on

2106

a class.

2107

</dd></dl>

2108

2109

2110

2111

<tt class="descname">remove</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.scoping.ScopedSession.remove" title="Permalink to this definition">¶</a></dt>

2112

<dd>Dispose of the current contextual session.

2113

</dd></dl>

2114

2115

</dd></dl>

2116

2117

2118

2119

class <tt class="descclassname">sqlalchemy.util.</tt><tt class="descname">ScopedRegistry</tt><big>(</big>createfunc, scopefunc<big>)</big><a class="headerlink" href="#sqlalchemy.util.ScopedRegistry" title="Permalink to this definition">¶</a></dt>

2120

<dd>A Registry that can store one or multiple instances of a single

2121

class on the basis of a “scope” function.

2122

The object implements <tt class="docutils literal">__call__</tt> as the “getter”, so by

2123

calling <tt class="docutils literal">myregistry()</tt> the contained object is returned

2124

for the current scope.

2125

2126

2127

2128

2129

<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

2130

<li>createfunc – a callable that returns a new object to be placed in the registry</li>

2131

<li>scopefunc – a callable that will return a key to store/retrieve an object.</li>

2132

</ul>

2133

</td>

2134

</tr>

2135

</tbody>

2136

</table>

2137

2138

2139

<tt class="descname">__init__</tt><big>(</big>createfunc, scopefunc<big>)</big><a class="headerlink" href="#sqlalchemy.util.ScopedRegistry.__init__" title="Permalink to this definition">¶</a></dt>

2140

<dd>Construct a new <a class="reference internal" href="#sqlalchemy.util.ScopedRegistry" title="sqlalchemy.util.ScopedRegistry"><tt class="xref py py-class docutils literal">ScopedRegistry</tt></a>.

2141

2142

2143

2144

2145

<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

2146

<li>createfunc – A creation function that will generate

2147

a new value for the current scope, if none is present.</li>

2148

<li>scopefunc – A function that returns a hashable

2149

token representing the current scope (such as, current

2150

thread identifier).</li>

2151

</ul>

2152

</td>

2153

</tr>

2154

</tbody>

2155

</table>

2156

</dd></dl>

2157

2158

2159

2160

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

2161

<dd>Clear the current scope, if any.

2162

</dd></dl>

2163

2164

2165

2166

2167

<dd>Return True if an object is present in the current scope.

2168

</dd></dl>

2169

2170

2171

2172

2173

<dd>Set the value forthe current scope.

2174

</dd></dl>

2175

2176

</dd></dl>

2177

2178

2179

2180

class <tt class="descclassname">sqlalchemy.util.</tt><tt class="descname">ThreadLocalRegistry</tt><big>(</big>createfunc<big>)</big><a class="headerlink" href="#sqlalchemy.util.ThreadLocalRegistry" title="Permalink to this definition">¶</a></dt>

2181

<dd>A <a class="reference internal" href="#sqlalchemy.util.ScopedRegistry" title="sqlalchemy.util.ScopedRegistry"><tt class="xref py py-class docutils literal">ScopedRegistry</tt></a> that uses a <tt class="docutils literal">threading.local()</tt>

2182

variable for storage.

2183

</dd></dl>

2184

2185

</div>

2186

</div>

2187

2188

<h2>Partitioning Strategies<a class="headerlink" href="#partitioning-strategies" title="Permalink to this headline">¶</a></h2>

2189

2190

<h3>Vertical Partitioning<a class="headerlink" href="#vertical-partitioning" title="Permalink to this headline">¶</a></h3>

2191

Vertical partitioning places different kinds of objects, or different tables,

2192

across multiple databases:

2193

<div class="highlight-python"><div class="highlight"><pre>engine1 = create_engine('postgresql://db1')

2194

engine2 = create_engine('postgresql://db2')

2195

2196

Session = sessionmaker(twophase=True)

2197

2198

# bind User operations to engine 1, Account operations to engine 2

2199

Session.configure(binds={User:engine1, Account:engine2})

2200

2201

session = Session()</pre></div>

2202

</div>

2203

</div>

2204

2205

<h3>Horizontal Partitioning<a class="headerlink" href="#horizontal-partitioning" title="Permalink to this headline">¶</a></h3>

2206

Horizontal partitioning partitions the rows of a single table (or a set of

2207

tables) across multiple databases.

2208

See the “sharding” example: <a class="reference internal" href="examples.html#examples-sharding">Horizontal Sharding</a>.

2209

</div>

2210

</div>

2211

2212

<h2>Session Utilities<a class="headerlink" href="#session-utilities" title="Permalink to this headline">¶</a></h2>

2213

2214

2215

<tt class="descclassname">sqlalchemy.orm.session.</tt><tt class="descname">make_transient</tt><big>(</big>instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.make_transient" title="Permalink to this definition">¶</a></dt>

2216

<dd>Make the given instance ‘transient’.

2217

This will remove its association with any

2218

session and additionally will remove its “identity key”,

2219

such that it’s as though the object were newly constructed,

2220

except retaining its values. It also resets the

2221

“deleted” flag on the state if this object

2222

had been explicitly deleted by its session.

2223

Attributes which were “expired” or deferred at the

2224

instance level are reverted to undefined, and

2225

will not trigger any loads.

2226

</dd></dl>

2227

2228

2229

2230

<tt class="descclassname">sqlalchemy.orm.session.</tt><tt class="descname">object_session</tt><big>(</big>instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.session.object_session" title="Permalink to this definition">¶</a></dt>

2231

<dd>Return the <tt class="docutils literal">Session</tt> to which instance belongs.

2232

If the instance is not a mapped instance, an error is raised.

2233

</dd></dl>

2234

2235

</div>

2236

2237

<h2>Attribute and State Management Utilities<a class="headerlink" href="#attribute-and-state-management-utilities" title="Permalink to this headline">¶</a></h2>

2238

These functions are provided by the SQLAlchemy attribute

2239

instrumentation API to provide a detailed interface for dealing

2240

with instances, attribute values, and history. Some of them

2241

are useful when constructing event listener functions, such as

2242

those described in <a class="reference internal" href="interfaces.html">ORM Event Interfaces</a>.

2243

2244

2245

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">del_attribute</tt><big>(</big>instance, key<big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.del_attribute" title="Permalink to this definition">¶</a></dt>

2246

<dd>Delete the value of an attribute, firing history events.

2247

This function may be used regardless of instrumentation

2248

applied directly to the class, i.e. no descriptors are required.

2249

Custom attribute management schemes will need to make usage

2250

of this method to establish attribute state as understood

2251

by SQLAlchemy.

2252

</dd></dl>

2253

2254

2255

2256

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">get_attribute</tt><big>(</big>instance, key<big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.get_attribute" title="Permalink to this definition">¶</a></dt>

2257

<dd>Get the value of an attribute, firing any callables required.

2258

This function may be used regardless of instrumentation

2259

applied directly to the class, i.e. no descriptors are required.

2260

Custom attribute management schemes will need to make usage

2261

of this method to make usage of attribute state as understood

2262

by SQLAlchemy.

2263

</dd></dl>

2264

2265

2266

2267

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">get_history</tt><big>(</big>obj, key, **kwargs<big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.get_history" title="Permalink to this definition">¶</a></dt>

2268

<dd>Return a <a class="reference internal" href="#sqlalchemy.orm.attributes.History" title="sqlalchemy.orm.attributes.History"><tt class="xref py py-class docutils literal">History</tt></a> record for the given object

2269

and attribute key.

2270

2271

2272

2273

2274

<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

2275

<li>obj – an object whose class is instrumented by the

2276

attributes package.</li>

2277

<li>key – string attribute name.</li>

2278

<li>kwargs – Optional keyword arguments currently

2279

include the <tt class="docutils literal">passive</tt> flag, which indicates if the attribute should be

2280

loaded from the database if not already present (<tt class="xref py py-attr docutils literal">PASSIVE_NO_FETCH</tt>), and

2281

if the attribute should be not initialized to a blank value otherwise

2282

(<tt class="xref py py-attr docutils literal">PASSIVE_NO_INITIALIZE</tt>). Default is <tt class="xref py py-attr docutils literal">PASSIVE_OFF</tt>.</li>

2283

</ul>

2284

</td>

2285

</tr>

2286

</tbody>

2287

</table>

2288

</dd></dl>

2289

2290

2291

2292

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">init_collection</tt><big>(</big>obj, key<big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.init_collection" title="Permalink to this definition">¶</a></dt>

2293

<dd>Initialize a collection attribute and return the collection adapter.

2294

This function is used to provide direct access to collection internals

2295

for a previously unloaded attribute. e.g.:

2296

<div class="highlight-python"><div class="highlight"><pre>collection_adapter = init_collection(someobject, 'elements')

2297

for elem in values:

2298

collection_adapter.append_without_event(elem)</pre></div>

2299

</div>

2300

2301

<dt>For an easier way to do the above, see</dt>

2302

<dd><a class="reference internal" href="#sqlalchemy.orm.attributes.set_committed_value" title="sqlalchemy.orm.attributes.set_committed_value"><tt class="xref py py-func docutils literal">set_committed_value()</tt></a>.</dd>

2303

</dl>

2304

obj is an instrumented object instance. An InstanceState

2305

is accepted directly for backwards compatibility but

2306

this usage is deprecated.

2307

</dd></dl>

2308

2309

2310

2311

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">instance_state</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.instance_state" title="Permalink to this definition">¶</a></dt>

2312

<dd>Return the <tt class="xref py py-class docutils literal">InstanceState</tt> for a given object.

2313

</dd></dl>

2314

2315

2316

2317

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">is_instrumented</tt><big>(</big>instance, key<big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.is_instrumented" title="Permalink to this definition">¶</a></dt>

2318

<dd>Return True if the given attribute on the given instance is

2319

instrumented by the attributes package.

2320

This function may be used regardless of instrumentation

2321

applied directly to the class, i.e. no descriptors are required.

2322

</dd></dl>

2323

2324

2325

2326

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">manager_of_class</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.manager_of_class" title="Permalink to this definition">¶</a></dt>

2327

<dd>Return the <tt class="xref py py-class docutils literal">ClassManager</tt> for a given class.

2328

</dd></dl>

2329

2330

2331

2332

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">set_attribute</tt><big>(</big>instance, key, value<big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.set_attribute" title="Permalink to this definition">¶</a></dt>

2333

<dd>Set the value of an attribute, firing history events.

2334

This function may be used regardless of instrumentation

2335

applied directly to the class, i.e. no descriptors are required.

2336

Custom attribute management schemes will need to make usage

2337

of this method to establish attribute state as understood

2338

by SQLAlchemy.

2339

</dd></dl>

2340

2341

2342

2343

<tt class="descclassname">sqlalchemy.orm.attributes.</tt><tt class="descname">set_committed_value</tt><big>(</big>instance, key, value<big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.set_committed_value" title="Permalink to this definition">¶</a></dt>

2344

<dd>Set the value of an attribute with no history events.

2345

Cancels any previous history present. The value should be

2346

a scalar value for scalar-holding attributes, or

2347

an iterable for any collection-holding attribute.

2348

This is the same underlying method used when a lazy loader

2349

fires off and loads additional data from the database.

2350

In particular, this method can be used by application code

2351

which has loaded additional attributes or collections through

2352

separate queries, which can then be attached to an instance

2353

as though it were part of its original loaded state.

2354

</dd></dl>

2355

2356

2357

2358

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

2359

<dd>A 3-tuple of added, unchanged and deleted values,

2360

representing the changes which have occured on an instrumented

2361

attribute.

2362

Each tuple member is an iterable sequence.

2363

2364

2365

<tt class="descname">added</tt><a class="headerlink" href="#sqlalchemy.orm.attributes.History.added" title="Permalink to this definition">¶</a></dt>

2366

<dd>Return the collection of items added to the attribute (the first tuple

2367

element).

2368

</dd></dl>

2369

2370

2371

2372

<tt class="descname">deleted</tt><a class="headerlink" href="#sqlalchemy.orm.attributes.History.deleted" title="Permalink to this definition">¶</a></dt>

2373

<dd>Return the collection of items that have been removed from the

2374

attribute (the third tuple element).

2375

</dd></dl>

2376

2377

2378

2379

<tt class="descname">empty</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.History.empty" title="Permalink to this definition">¶</a></dt>

2380

<dd>Return True if this <a class="reference internal" href="#sqlalchemy.orm.attributes.History" title="sqlalchemy.orm.attributes.History"><tt class="xref py py-class docutils literal">History</tt></a> has no changes

2381

and no existing, unchanged state.

2382

</dd></dl>

2383

2384

2385

2386

<tt class="descname">has_changes</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.History.has_changes" title="Permalink to this definition">¶</a></dt>

2387

<dd>Return True if this <a class="reference internal" href="#sqlalchemy.orm.attributes.History" title="sqlalchemy.orm.attributes.History"><tt class="xref py py-class docutils literal">History</tt></a> has changes.

2388

</dd></dl>

2389

2390

2391

2392

<tt class="descname">non_added</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.History.non_added" title="Permalink to this definition">¶</a></dt>

2393

<dd>Return a collection of unchanged + deleted.

2394

</dd></dl>

2395

2396

2397

2398

<tt class="descname">non_deleted</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.attributes.History.non_deleted" title="Permalink to this definition">¶</a></dt>

2399

<dd>Return a collection of added + unchanged.

2400

</dd></dl>

2401

2402

2403

2404

2405

<dd>Return a collection of added + unchanged + deleted.

2406

</dd></dl>

2407

2408

2409

2410

<tt class="descname">unchanged</tt><a class="headerlink" href="#sqlalchemy.orm.attributes.History.unchanged" title="Permalink to this definition">¶</a></dt>

2411

<dd>Return the collection of items that have not changed on the attribute

2412

(the second tuple element).

2413

</dd></dl>

2414

2415

</dd></dl>

2416

2417

2418

2419

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

2420

<dd>Symbol indicating that loader callables should

2421

not be fired off, and a non-initialized attribute

2422

should remain that way.

2423

</dd></dl>

2424

2425

2426

2427

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

2428

<dd>Symbol indicating that loader callables should not boe fired off.

2429

Non-initialized attributes should be initialized to an empty value.

2430

</dd></dl>

2431

2432

2433

2434

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

2435

<dd>Symbol indicating that loader callables should be executed.

2436

</dd></dl>

2437

2438

</div>

2439

</div>

2440

2441

</div>

2442

</div>

2443

2444

2445

2446

2447

2448

2449

<a href="inheritance.html" title="previous chapter">Mapping Class Inheritance Hierarchies</a>

2451

<a href="query.html" title="next chapter">Querying</a>

2453

</div>

2454

2455

2456

2457

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.

2458

</div>

2459

</div>

2460

2461

2462

2463

2464

2465

2466

2467

</body>

2468

</html>

2469

2470

2471