SQLAlchemy DocumentationRelease 1.0.12

Mike Bayer

April 27, 2016

Contents

1 Overview 31.1 Documentation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2 Code Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3.1 Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.2 Supported Installation Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.3 Install via pip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3.4 Installing using setup.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3.5 Installing the C Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3.6 Installing on Python 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3.7 Installing a Database API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3.8 Checking the Installed SQLAlchemy Version . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4 0.9 to 1.0 Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 SQLAlchemy ORM 72.1 Object Relational Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.1.1 Version Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.2 Connecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1.3 Declare a Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1.4 Create a Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.1.5 Create an Instance of the Mapped Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.1.6 Creating a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.7 Adding and Updating Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.1.8 Rolling Back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.1.9 Querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Common Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Returning Lists and Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Using Textual SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.1.10 Building a Relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.1.11 Working with Related Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.1.12 Querying with Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Using Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Using Subqueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Selecting Entities from Subqueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Using EXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Common Relationship Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2.1.13 Eager Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

i

Subquery Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Joined Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Explicit Join + Eagerload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

2.1.14 Deleting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Configuring delete/delete-orphan Cascade . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

2.1.15 Building a Many To Many Relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342.1.16 Further Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

2.2 Mapper Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372.2.1 Types of Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Declarative Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Classical Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Runtime Introspection of Mappings, Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 39

2.2.2 Mapping Columns and Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Mapping Table Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40SQL Expressions as Mapped Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Changing Attribute Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Composite Column Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

2.2.3 Mapping Class Inheritance Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Joined Table Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Single Table Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Concrete Table Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Using Relationships with Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Using Inheritance with Declarative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

2.2.4 Non-Traditional Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Mapping a Class against Multiple Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Mapping a Class against Arbitrary Selects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Multiple Mappers for One Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

2.2.5 Configuring a Version Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Simple Version Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Custom Version Counters / Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Server Side Version Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Programmatic or Conditional Version Counters . . . . . . . . . . . . . . . . . . . . . . . . . 77

2.2.6 Class Mapping API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782.3 Relationship Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

2.3.1 Basic Relationship Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92One To Many . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Many To One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93One To One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Many To Many . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Association Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

2.3.2 Adjacency List Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Composite Adjacency Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Self-Referential Query Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Configuring Self-Referential Eager Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

2.3.3 Linking Relationships with Backref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Backref Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105One Way Backrefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

2.3.4 Configuring how Relationship Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Handling Multiple Join Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Specifying Alternate Join Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Creating Custom Foreign Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Using custom operators in join conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Overlapping Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Non-relational Comparisons / Materialized Path . . . . . . . . . . . . . . . . . . . . . . . . . 113

ii

Self-Referential Many-to-Many Relationship . . . . . . . . . . . . . . . . . . . . . . . . . . 114Composite Secondary Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Relationship to Non Primary Mapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Building Query-Enabled Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

2.3.5 Collection Configuration and Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Working with Large Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Customizing Collection Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Custom Collection Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Collection Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

2.3.6 Special Relationship Persistence Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Rows that point to themselves / Mutually Dependent Rows . . . . . . . . . . . . . . . . . . . 131Mutable Primary Keys / Update Cascades . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

2.3.7 Relationships API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352.4 Loading Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

2.4.1 Loading Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Deferred Column Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Column Bundles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

2.4.2 Relationship Loading Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Using Loader Strategies: Lazy Loading, Eager Loading . . . . . . . . . . . . . . . . . . . . . 149The Importance of Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Loading Along Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Default Loading Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Per-Entity Default Loading Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152The Zen of Eager Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152What Kind of Loading to Use ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Routing Explicit Joins/Statements into Eagerly Loaded Collections . . . . . . . . . . . . . . 155Creating Custom Load Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Relationship Loader API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

2.4.3 Constructors and Object Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622.4.4 Query API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

The Query Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163ORM-Specific Query Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

2.5 Using the Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932.5.1 Session Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

What does the Session do ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Getting a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Session Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Basics of Using a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

2.5.2 State Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Quickie Intro to Object States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Session Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Merging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Expunging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Refreshing / Expiring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

2.5.3 Cascades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211save-update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213delete-orphan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216refresh-expire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216expunge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Controlling Cascade on Backrefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

2.5.4 Transactions and Connection Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Managing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

iii

Joining a Session into an External Transaction (such as for test suites) . . . . . . . . . . . . . 2232.5.5 Additional Persistence Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Embedding SQL Insert/Update Expressions into a Flush . . . . . . . . . . . . . . . . . . . . 224Using SQL Expressions with Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Partitioning Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Bulk Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

2.5.6 Contextual/Thread-local Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Implicit Method Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Thread-Local Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Using Thread-Local Scope with Web Applications . . . . . . . . . . . . . . . . . . . . . . . 230Using Custom Created Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Contextual Session API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

2.5.7 Tracking Object and Session Changes with Events . . . . . . . . . . . . . . . . . . . . . . 233Persistence Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Object Lifecycle Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Transaction Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Attribute Change Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

2.5.8 Session API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Session and sessionmaker() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Session Utilites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Attribute and State Management Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

2.6 Events and Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2572.6.1 ORM Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Attribute Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Mapper Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Instance Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Query Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Instrumentation Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

2.6.2 ORM Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2842.6.3 ORM Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3232.6.4 Deprecated ORM Event Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Mapper Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Attribute Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

2.7 ORM Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3292.7.1 Association Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Simplifying Scalar Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329Creation of New Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Simplifying Association Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Proxying to Dictionary Based Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Composite Association Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Querying with Association Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

2.7.2 Automap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Basic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Generating Mappings from an Existing MetaData . . . . . . . . . . . . . . . . . . . . . . . . 341Specifying Classes Explicitly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Overriding Naming Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Relationship Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344Using Automap with Explicit Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . 347API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

2.7.3 Baked Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

iv

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Lazy Loading Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

2.7.4 Declarative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358Basic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358Configuring Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360Table Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362Inheritance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364Mixin and Custom Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368Declarative API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

2.7.5 Mutation Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Establishing Mutability on Scalar Column Values . . . . . . . . . . . . . . . . . . . . . . . . 384Establishing Mutability on Composites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

2.7.6 Ordering List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

2.7.7 Horizontal Sharding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

2.7.8 Hybrid Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397Defining Expression Behavior Distinct from Attribute Behavior . . . . . . . . . . . . . . . . 398Defining Setters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399Working with Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400Building Custom Comparators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Hybrid Value Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403Building Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

2.7.9 Alternate Class Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

2.8 ORM Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4102.8.1 Mapping Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

Adjacency List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Directed Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Dynamic Relations as Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Generic Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Large Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Materialized Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412Nested Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412Relationship Join Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416XML Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416Versioning Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417Vertical Attribute Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

2.8.2 Inheritance Mapping Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419Basic Inheritance Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

2.8.3 Special APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419Attribute Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419Horizontal Sharding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

2.8.4 Extending the ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Dogpile Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420PostGIS Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

3 SQLAlchemy Core 423

v

3.1 SQL Expression Language Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4233.1.1 Version Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4233.1.2 Connecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4243.1.3 Define and Create Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4243.1.4 Insert Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4263.1.5 Executing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4263.1.6 Executing Multiple Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4273.1.7 Selecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4283.1.8 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

Operator Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4323.1.9 Conjunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4323.1.10 Using Textual SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

Using More Specific Text with table(), literal_column(), and column() . . . . . 435Ordering or Grouping by a Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

3.1.11 Using Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4373.1.12 Using Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4383.1.13 Everything Else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Bind Parameter Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Window Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442Unions and Other Set Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442Scalar Selects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444Correlated Subqueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444Ordering, Grouping, Limiting, Offset...ing... . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

3.1.14 Inserts, Updates and Deletes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Correlated Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449Multiple Table Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449Parameter-Ordered Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450Deletes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450Matched Row Counts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

3.1.15 Further Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4513.2 SQL Statements and Expressions API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

3.2.1 Column Elements and Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4513.2.2 Selectables, Tables, FROM objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4963.2.3 Insert, Updates, Deletes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5573.2.4 SQL and Generic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5883.2.5 Custom SQL Constructs and Compilation Extension . . . . . . . . . . . . . . . . . . . . . 595

Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595Dialect-specific compilation rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595Compiling sub-elements of a custom expression construct . . . . . . . . . . . . . . . . . . . 596Enabling Autocommit on a Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597Changing the default compilation of existing constructs . . . . . . . . . . . . . . . . . . . . . 598Changing Compilation of Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598Subclassing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598Further Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

3.2.6 Expression Serializer Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6013.3 Schema Definition Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602

3.3.1 Describing Databases with MetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602Accessing Tables and Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603Creating and Dropping Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604Altering Schemas through Migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606Specifying the Schema Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606Backend-Specific Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606Column, Table, MetaData API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607

vi

3.3.2 Reflecting Database Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632Overriding Reflected Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633Reflecting Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633Reflecting All Tables at Once . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633Fine Grained Reflection with Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634Limitations of Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638

3.3.3 Column Insert/Update Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638Scalar Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639Python-Executed Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639SQL Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640Server Side Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641Triggered Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642Defining Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642Default Objects API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644

3.3.4 Defining Constraints and Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647Defining Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647UNIQUE Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651CHECK Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652PRIMARY KEY Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652Setting up Constraints when using the Declarative ORM Extension . . . . . . . . . . . . . . 653Configuring Constraint Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 653Constraints API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675Index API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

3.3.5 Customizing DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679Custom DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680Controlling DDL Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680Using the built-in DDLElement Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681DDL Expression Constructs API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683

3.4 Column and Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6903.4.1 Column and Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690

Generic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691SQL Standard Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699Vendor-Specific Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701

3.4.2 Custom Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701Overriding Type Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702Augmenting Existing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702TypeDecorator Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708Replacing the Bind/Result Processing of Existing Types . . . . . . . . . . . . . . . . . . . . 711Applying SQL-level Bind/Result Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 711Redefining and Creating New Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713Creating New Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715

3.4.3 Base Type API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7163.5 Engine and Connection Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720

3.5.1 Engine Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720Supported Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721Database Urls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721Engine Creation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728Custom DBAPI connect() arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728Configuring Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728

3.5.2 Working with Engines and Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729Using Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731

vii

Understanding Autocommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732Connectionless Execution, Implicit Execution . . . . . . . . . . . . . . . . . . . . . . . . . . 732Engine Disposal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734Using the Threadlocal Execution Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735Working with Raw DBAPI Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736Registering New Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737Connection / Engine API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738

3.5.3 Connection Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756Connection Pool Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756Switching Pool Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757Using a Custom Connection Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757Constructing a Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757Pool Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758Dealing with Disconnects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758Using Connection Pools with Multiprocessing . . . . . . . . . . . . . . . . . . . . . . . . . 761API Documentation - Available Pool Implementations . . . . . . . . . . . . . . . . . . . . . 762Pooling Plain DB-API Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768

3.5.4 Core Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768Connection Pool Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769SQL Execution and Connection Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772Schema Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787

3.6 Core API Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7913.6.1 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791

Event Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791Named Argument Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793Event Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794

3.6.2 Runtime Inspection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796Available Inspection Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796

3.6.3 Deprecated Event Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797Execution, Connection and Cursor Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797Connection Pool Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798

3.6.4 Core Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7993.6.5 Core Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802

4 Dialects 8214.1 Included Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821

4.1.1 Firebird . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821Firebird Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821Locking Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821RETURNING support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822fdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822kinterbasdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823

4.1.2 Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824Auto Increment Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824Rendering of SQL statements that include schema qualifiers . . . . . . . . . . . . . . . . . . 826Collation Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827LIMIT/OFFSET Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827Nullability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828Date / Time Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828

viii

Large Text/Binary Type Deprecation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828Clustered Index Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829MSSQL-Specific Index Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829Compatibility Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830Rowcount Support / ORM Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830Enabling Snapshot Isolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831SQL Server Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831PyODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836mxODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838pymssql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838zxjdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839AdoDBAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839

4.1.3 MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840Supported Versions and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840Connection Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840CREATE TABLE arguments including Storage Engines . . . . . . . . . . . . . . . . . . . . 840Case Sensitivity and Table Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841Transaction Isolation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841AUTO_INCREMENT Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842Ansi Quoting Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843MySQL SQL Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843rowcount Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844CAST Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844MySQL Specific Index Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844MySQL Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845MySQL Unique Constraints and Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . 846TIMESTAMP Columns and NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846MySQL Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848MySQL-Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858pymysql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859MySQL-Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859cymysql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860OurSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860Google App Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861pyodbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861zxjdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862

4.1.4 Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862Connect Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863Auto Increment Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863Identifier Casing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863LIMIT/OFFSET Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863RETURNING Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864ON UPDATE CASCADE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864Oracle 8 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865Synonym/DBLINK Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865DateTime Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865Oracle Table Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865Oracle Specific Index Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866Oracle Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866

ix

cx_Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869zxjdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873

4.1.5 PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873Sequences/SERIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874Transaction Isolation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874Remote-Schema Table Introspection and Postgresql search_path . . . . . . . . . . . . . . . . 875INSERT/UPDATE...RETURNING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877Full Text Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877FROM ONLY ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878Postgresql-Specific Index Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879Postgresql Index Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880Special Reflection Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880PostgreSQL Table Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881ENUM Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882PostgreSQL Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883PostgreSQL Constraint Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898psycopg2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899pg8000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903psycopg2cffi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904py-postgresql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905zxjdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905

4.1.6 SQLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906Date and Time Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906SQLite Auto Incrementing Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906Database Locking Behavior / Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . 907Transaction Isolation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908SAVEPOINT Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908Transactional DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909Foreign Key Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909Type Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910Partial Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910Dotted Column Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910SQLite Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912Pysqlite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914Pysqlcipher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918

4.1.7 Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919python-sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919pyodbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920mxodbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921

4.2 External Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9214.2.1 Production Ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9214.2.2 Experimental / Incomplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9214.2.3 Attic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922

5 Frequently Asked Questions 9235.1 Connections / Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923

5.1.1 How do I configure logging? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9235.1.2 How do I pool database connections? Are my connections pooled? . . . . . . . . . . . . . . 9235.1.3 How do I pass custom connect arguments to my database API? . . . . . . . . . . . . . . . . 9235.1.4 MySQL Server has gone away . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9245.1.5 Why does SQLAlchemy issue so many ROLLBACKs? . . . . . . . . . . . . . . . . . . . . 924

x

Im on MyISAM - how do I turn it off? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924Im on SQL Server - how do I turn those ROLLBACKs into COMMITs? . . . . . . . . . . . 924

5.1.6 I am using multiple connections with a SQLite database (typically to test transaction opera-tion), and my test program is not working! . . . . . . . . . . . . . . . . . . . . . . . . . . . 925

5.1.7 How do I get at the raw DBAPI connection when using an Engine? . . . . . . . . . . . . . . 9255.1.8 How do I use engines / connections / sessions with Python multiprocessing, or os.fork()? . . 925

5.2 MetaData / Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9265.2.1 My program is hanging when I say table.drop() / metadata.drop_all() . . . . . 9275.2.2 Does SQLAlchemy support ALTER TABLE, CREATE VIEW, CREATE TRIGGER,

Schema Upgrade Functionality? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9275.2.3 How can I sort Table objects in order of their dependency? . . . . . . . . . . . . . . . . . . 9275.2.4 How can I get the CREATE TABLE/ DROP TABLE output as a string? . . . . . . . . . . . 9285.2.5 How can I subclass Table/Column to provide certain behaviors/configurations? . . . . . . . 928

5.3 SQL Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9285.3.1 How do I render SQL expressions as strings, possibly with bound parameters inlined? . . . . 9285.3.2 Why does .col.in_([]) Produce col != col? Why not 1=0? . . . . . . . . . . . . 930

5.4 ORM Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9315.4.1 How do I map a table that has no primary key? . . . . . . . . . . . . . . . . . . . . . . . . 9315.4.2 How do I configure a Column that is a Python reserved word or similar? . . . . . . . . . . . 9325.4.3 How do I get a list of all columns, relationships, mapped attributes, etc. given a mapped class? 9325.4.4 Im getting a warning or error about Implicitly combining column X under attribute Y . . 9325.4.5 Im using Declarative and setting primaryjoin/secondaryjoin using an and_() or or_(),

and I am getting an error message about foreign keys. . . . . . . . . . . . . . . . . . . . . . 9345.4.6 Why is ORDER BY required with LIMIT (especially with subqueryload())? . . . . . . 934

5.5 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9365.5.1 How can I profile a SQLAlchemy powered application? . . . . . . . . . . . . . . . . . . . . 936

Query Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936Code Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937Execution Slowness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938Result Fetching Slowness - Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938Result Fetching Slowness - ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939

5.5.2 Im inserting 400,000 rows with the ORM and its really slow! . . . . . . . . . . . . . . . . 9405.6 Sessions / Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943

5.6.1 Im re-loading data with my Session but it isnt seeing changes that I committed elsewhere . 9435.6.2 This Sessions transaction has been rolled back due to a previous exception during flush.

(or similar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944But why does flush() insist on issuing a ROLLBACK? . . . . . . . . . . . . . . . . . . . . . 945But why isnt the one automatic call to ROLLBACK enough? Why must I ROLLBACK again? 946

5.6.3 How do I make a Query that always adds a certain filter to every query? . . . . . . . . . . . 9475.6.4 Ive created a mapping against an Outer Join, and while the query returns rows, no objects

are returned. Why not? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9475.6.5 Im using joinedload() or lazy=False to create a JOIN/OUTER JOIN and

SQLAlchemy is not constructing the correct query when I try to add a WHERE, ORDERBY, LIMIT, etc. (which relies upon the (OUTER) JOIN) . . . . . . . . . . . . . . . . . . . 947

5.6.6 Query has no __len__(), why not? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9475.6.7 How Do I use Textual SQL with ORM Queries? . . . . . . . . . . . . . . . . . . . . . . . . 9485.6.8 Im calling Session.delete(myobject) and it isnt removed from the parent collection!9485.6.9 why isnt my __init__() called when I load objects? . . . . . . . . . . . . . . . . . . . 9485.6.10 how do I use ON DELETE CASCADE with SAs ORM? . . . . . . . . . . . . . . . . . . . 9485.6.11 I set the foo_id attribute on my instance to 7, but the foo attribute is still None -

shouldnt it have loaded Foo with id #7? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9485.6.12 How do I walk all objects that are related to a given object? . . . . . . . . . . . . . . . . . . 9505.6.13 Is there a way to automagically have only unique keywords (or other kinds of objects) without

doing a query for the keyword and getting a reference to the row containing that keyword? . 951

xi

6 Changes and Migration 9536.1 Current Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953

6.1.1 Whats New in SQLAlchemy 1.0? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953New Features and Improvements - ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953New Features and Improvements - Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962Key Behavioral Changes - ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968Key Behavioral Changes - Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980Dialect Improvements and Changes - Postgresql . . . . . . . . . . . . . . . . . . . . . . . . 986Dialect Improvements and Changes - MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . 989Dialect Improvements and Changes - SQLite . . . . . . . . . . . . . . . . . . . . . . . . . . 991Dialect Improvements and Changes - SQL Server . . . . . . . . . . . . . . . . . . . . . . . . 991Dialect Improvements and Changes - Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . 992

6.2 Change logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9926.2.1 1.0 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992

1.0.13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9921.0.12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9931.0.11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9951.0.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9961.0.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9981.0.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9991.0.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10001.0.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10011.0.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10021.0.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10041.0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10051.0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10071.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10071.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10091.0.0b5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10101.0.0b4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10111.0.0b3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10121.0.0b2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10121.0.0b1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013

6.2.2 0.9 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10400.9.11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10400.9.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10400.9.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10420.9.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10450.9.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10480.9.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10510.9.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10510.9.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10550.9.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10600.9.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10620.9.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10670.9.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10680.9.0b1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074

6.2.3 0.8 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10870.8.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10870.8.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10890.8.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10900.8.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10920.8.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094

xii

0.8.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10970.8.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11010.8.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11030.8.0b2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11070.8.0b1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111

6.2.4 0.7 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11200.7.11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11200.7.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11210.7.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11230.7.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11250.7.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11260.7.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11280.7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11310.7.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11330.7.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11370.7.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11410.7.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11440.7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11450.7.0b4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11470.7.0b3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11490.7.0b2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11510.7.0b1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152

6.2.5 0.6 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11560.6.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11560.6.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11580.6.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11590.6.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11620.6.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11640.6.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11680.6.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11710.6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11720.6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11750.6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11770.6beta3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11790.6beta2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11810.6beta1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186

6.2.6 0.5 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11980.5.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11980.5.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11980.5.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11990.5.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12010.5.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12030.5.4p2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12040.5.4p1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12040.5.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12050.5.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12070.5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12090.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12100.5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12120.5.0rc4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12170.5.0rc3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12180.5.0rc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12200.5.0rc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12210.5.0beta3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224

xiii

0.5.0beta2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12250.5.0beta1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227

6.2.7 0.4 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12290.4.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12290.4.7p1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12290.4.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12300.4.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12310.4.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12330.4.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12370.4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12380.4.2p3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12420.4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12430.4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12470.4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12500.4.0beta6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12520.4.0beta5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12530.4.0beta4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12530.4.0beta3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12540.4.0beta2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12550.4.0beta1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255

6.2.8 0.3 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12600.3.11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12600.3.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12620.3.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12620.3.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12650.3.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12670.3.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12690.3.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12720.3.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12750.3.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12770.3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12770.3.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12780.3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1279

6.2.9 0.2 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12830.2.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12830.2.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12840.2.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12850.2.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12860.2.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12860.2.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12870.2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12880.2.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12880.2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289

6.2.10 0.1 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12900.1.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12900.1.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12910.1.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12910.1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12930.1.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12940.1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12950.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1295

6.3 Older Migration Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12966.3.1 Whats New in SQLAlchemy 0.9? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296

xiv

Platform Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296Behavioral Changes - ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1297Behavioral Changes - Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306Behavioral Improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313Dialect Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323

6.3.2 Whats New in SQLAlchemy 0.8? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323Platform Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324New ORM Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324New Core Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1332Behavioral Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1338Removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344

6.3.3 Whats New in SQLAlchemy 0.7? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346Behavioral Changes (Backwards Compatible) . . . . . . . . . . . . . . . . . . . . . . . . . . 1351Behavioral Changes (Backwards Incompatible) . . . . . . . . . . . . . . . . . . . . . . . . . 1354Deprecated API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359Backwards Incompatible API Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360Previously Deprecated, Now Removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361

6.3.4 Whats New in SQLAlchemy 0.6? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362Platform Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362New Dialect System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362Expression Language Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363C Extensions for Result Fetching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365New Schema Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366Logging opened up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368Reflection/Inspector API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368RETURNING Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369Type System Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369ORM Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376

6.3.5 Whats new in SQLAlchemy 0.5? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376Major Documentation Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376Deprecations Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377Requirements Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377Object Relational Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377Extending the ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380Schema/Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380Connection Pool no longer threadlocal by default . . . . . . . . . . . . . . . . . . . . . . . . 1382*args Accepted, *args No Longer Accepted . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382Removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382Renamed or Moved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384Deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384

6.3.6 Whats new in SQLAlchemy 0.4? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385First Things First . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385Module Imports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385Object Relational Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386SQL Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394Schema and Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395SQL Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395

7 Indices and tables 1397

xv

Python Module Index 1399

xvi

SQLAlchemy Documentation, Release 1.0.12

Full table of contents. For a high level overview of all documentation, see index_toplevel.

Contents 1

SQLAlchemy Documentation, Release 1.0.12

2 Contents

CHAPTER 1

Overview

The SQLAlchemy SQL Toolkit and Object Relational Mapper is a comprehensive set of tools for working withdatabases and Python. It has several distinct areas of functionality which can be used individually or combinedtogether. Its major components are illustrated in below, with component dependencies organized into layers:

Above, the two most significant front-facing portions of SQLAlchemy are the Object Relational Mapper and theSQL Expression Language. SQL Expressions can be used independently of the ORM. When using the ORM, theSQL Expression language remains part of the public facing API as it is used within object-relational configurationsand queries.

3

SQLAlchemy Documentation, Release 1.0.12

1.1 Documentation Overview

The documentation is separated into three sections: SQLAlchemy ORM, SQLAlchemy Core, and Dialects.

In SQLAlchemy ORM, the Object Relational Mapper is introduced and fully described. New users should begin withthe Object Relational Tutorial. If you want to work with higher-level SQL which is constructed automatically for you,as well as management of Python objects, proceed to this tutorial.

In SQLAlchemy Core, the breadth of SQLAlchemys SQL and database integration and description services are doc-umented, the core of which is the SQL Expression language. The SQL Expression Language is a toolkit all itsown, independent of the ORM package, which can be used to construct manipulable SQL expressions which can beprogrammatically constructed, modified, and executed, returning cursor-like result sets. In contrast to the ORMsdomain-centric mode of usage, the expression language provides a schema-centric usage paradigm. New users shouldbegin here with SQL Expression Language Tutorial. SQLAlchemy engine, connection, and pooling services are alsodescribed in SQLAlchemy Core.

In Dialects, reference documentation for all provided database and DBAPI backends is provided.

1.2 Code Examples

Working code examples, mostly regarding the ORM, are included in the SQLAlchemy distribution. A description ofall the included example applications is at ORM Examples.

There is also a wide variety of examples involving both core SQLAlchemy constructs as well as the ORM on the wiki.See Theatrum Chemicum.

1.3 Installation Guide

1.3.1 Supported Platforms

SQLAlchemy has been tested against the following platforms:

cPython since version 2.6, through the 2.xx series

cPython version 3, throughout all 3.xx series

Pypy 2.1 or greater

Changed in version 0.9: Python 2.6 is now the minimum Python version supported.

Platforms that dont currently have support include Jython, IronPython. Jython has been supported in the past and maybe supported in future releases as well, depending on the state of Jython itself.

1.3.2 Supported Installation Methods

SQLAlchemy supports installation using standard Python distutils or setuptools methodologies. An overview ofpotential setups is as follows:

Plain Python Distutils - SQLAlchemy can be installed with a clean Python install using the services providedvia Python Distutils, using the setup.py script. The C extensions as well as Python 3 builds are supported.

Setuptools or Distribute - When using setuptools, SQLAlchemy can be installed via setup.py oreasy_install, and the C extensions are supported.

4 Chapter 1. Overview

http://www.sqlalchemy.org/trac/wiki/UsageRecipeshttp://pypy.org/http://docs.python.org/distutils/http://pypi.python.org/pypi/setuptools/

SQLAlchemy Documentation, Release 1.0.12

pip - pip is an installer that rides on top of setuptools or distribute, replacing the usage ofeasy_install. It is often preferred for its simpler mode of usage.

1.3.3 Install via pip

When pip is available, the distribution can be downloaded from Pypi and installed in one step:

pip install SQLAlchemy

This command will download the latest released version of SQLAlchemy from the Python Cheese Shop and install itto your system.

In order to install the latest prerelease version, such as 1.0.0b1, pip requires that the --pre flag be used:

pip install --pre SQLAlchemy

Where above, if the most recent version is a prerelease, it will be installed instead of the latest released version.

1.3.4 Installing using setup.py

Otherwise, you can install from the distribution using the setup.py script:

python setup.py install

1.3.5 Installing the C Extensions

SQLAlchemy includes C extensions which provide an extra speed boost for dealing with result sets. The extensionsare supported on both the 2.xx and 3.xx series of cPython.

Changed in version 0.9.0: The C extensions now compile on Python 3 as well as Python 2.

setup.py will automatically build the extensions if an appropriate platform is detected. If the build of the C exten-sions fails, due to missing compiler or other issue, the setup process will output a warning message, and re-run thebuild without the C extensions, upon completion reporting final status.

To run the build/install without even attempting to compile the C extensions, the DISABLE_SQLALCHEMY_CEXTenvironment variable may be specified. The use case for this is either for special testing circumstances, or in the rarecase of compatibility/build issues not overcome by the usual rebuild mechanism:

# *** only in SQLAlchemy 0.9.4 / 0.8.6 or greater ***export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install

New in version 0.9.4,0.8.6: Support for disabling the build of C extensions using theDISABLE_SQLALCHEMY_CEXT environment variable has been added. This allows control of C extensionbuilding whether or not setuptools is available, and additionally works around the fact that setuptools will possibly beremoving support for command-line switches such as --without-extensions in a future release.

For versions of SQLAlchemy prior to 0.9.4 or 0.8.6, the --without-cextensions option may be used to disablethe attempt to build C extensions, provided setupools is in use, and provided the Feature construct is supported bythe installed version of setuptools:

python setup.py --without-cextensions install

Or with pip:

pip install --global-option='--without-cextensions' SQLAlchemy

1.3. Installation Guide 5

http://pypi.python.org/pypi/pip/http://pypi.python.org/pypi/SQLAlchemy

SQLAlchemy Documentation, Release 1.0.12

1.3.6 Installing on Python 3

SQLAlchemy runs directly on Python 2 or Python 3, and can be installed in either environment without any adjust-ments or code conversion.

Changed in version 0.9.0: Python 3 is now supported in place with no 2to3 step required.

1.3.7 Installing a Database API

SQLAlchemy is designed to operate with a DBAPI implementation built for a particular database, and includes supportfor the most popular databases. The individual database sections in Dialects enumerate the available DBAPIs for eachdatabase, including external links.

1.3.8 Checking the Installed SQLAlchemy Version

This documentation covers SQLAlchemy version 1.0. If youre working on a system that already has SQLAlchemyinstalled, check the version from your Python prompt like this:

>>> import sqlalchemy>>> sqlalchemy.__version__ # doctest: +SKIP1.0.0

1.4 0.9 to 1.0 Migration

Notes on whats changed from 0.9 to 1.0 is available here at Whats New in SQLAlchemy 1.0?.

6 Chapter 1. Overview

CHAPTER 2

SQLAlchemy ORM

Here, the Object Relational Mapper is introduced and fully described. If you want to work with higher-level SQLwhich is constructed automatically for you, as well as automated persistence of Python objects, proceed first to thetutorial.

2.1 Object Relational Tutorial

The SQLAlchemy Object Relational Mapper presents a method of associating user-defined Python classes withdatabase tables, and instances of those classes (objects) with rows in their corresponding tables. It includes a sys-tem that transparently synchronizes all changes in state between objects and their related rows, called a unit of work,as well