SQLAlchemy DocumentationRelease 1.0.7

Mike Bayer

September 09, 2015

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 New Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.1.8 Rolling Back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.1.9 Querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Common Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Returning Lists and Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Using Literal 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Using EXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Common Relationship Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

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

i

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

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

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

2.2 Mapper Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382.2.1 Types of Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

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

2.2.2 Mapping Columns and Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Mapping Table Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41SQL Expressions as Mapped Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Changing Attribute Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Composite Column Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

2.2.3 Mapping Class Inheritance Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Joined Table Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Single Table Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Concrete Table Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Using Relationships with Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Using Inheritance with Declarative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

2.2.4 Non-Traditional Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Mapping a Class against Multiple Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Mapping a Class against Arbitrary Selects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Multiple Mappers for One Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

2.2.5 Configuring a Version Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Simple Version Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Custom Version Counters / Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Server Side Version Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Programmatic or Conditional Version Counters . . . . . . . . . . . . . . . . . . . . . . . . . 74

2.2.6 Class Mapping API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752.3 Relationship Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

2.3.1 Basic Relationship Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89One To Many . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Many To One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90One To One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Many To Many . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Association Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

2.3.2 Adjacency List Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Composite Adjacency Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Self-Referential Query Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Configuring Self-Referential Eager Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

2.3.3 Linking Relationships with Backref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Backref Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99One Way Backrefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

2.3.4 Configuring how Relationship Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Handling Multiple Join Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Specifying Alternate Join Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Creating Custom Foreign Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Using custom operators in join conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Overlapping Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Non-relational Comparisons / Materialized Path . . . . . . . . . . . . . . . . . . . . . . . . . 107

ii

Self-Referential Many-to-Many Relationship . . . . . . . . . . . . . . . . . . . . . . . . . . 108Composite Secondary Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Relationship to Non Primary Mapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Building Query-Enabled Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

2.3.5 Collection Configuration and Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Working with Large Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Customizing Collection Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Custom Collection Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Collection Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

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

2.3.7 Relationships API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1282.4 Loading Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

2.4.1 Loading Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Deferred Column Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Column Bundles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

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

2.4.3 Constructors and Object Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1542.4.4 Query API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

The Query Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155ORM-Specific Query Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

2.5 Using the Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1832.5.1 Session Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

What does the Session do ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Getting a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Session Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Basics of Using a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

2.5.2 State Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Quickie Intro to Object States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Session Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Merging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Expunging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Refreshing / Expiring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

2.5.3 Cascades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200save-update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202delete-orphan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205refresh-expire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205expunge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Controlling Cascade on Backrefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

2.5.4 Transactions and Connection Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Managing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

iii

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

Embedding SQL Insert/Update Expressions into a Flush . . . . . . . . . . . . . . . . . . . . 213Using SQL Expressions with Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Partitioning Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Bulk Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

2.5.6 Contextual/Thread-local Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Implicit Method Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Thread-Local Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Using Thread-Local Scope with Web Applications . . . . . . . . . . . . . . . . . . . . . . . 219Using Custom Created Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Contextual Session API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

2.5.7 Session API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Session and sessionmaker() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Session Utilites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240Attribute and State Management Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

2.6 Events and Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2422.6.1 ORM Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Attribute Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Mapper Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Instance Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Query Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Instrumentation Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

2.6.2 ORM Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2692.6.3 ORM Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3082.6.4 Deprecated ORM Event Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Mapper Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Attribute Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

2.7 ORM Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3142.7.1 Association Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Simplifying Scalar Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Creation of New Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Simplifying Association Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Proxying to Dictionary Based Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Composite Association Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Querying with Association Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

2.7.2 Automap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Basic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Generating Mappings from an Existing MetaData . . . . . . . . . . . . . . . . . . . . . . . . 326Specifying Classes Explcitly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326Overriding Naming Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Relationship Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Using Automap with Explicit Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . 332API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

2.7.3 Baked Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Lazy Loading Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

2.7.4 Declarative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

iv

Basic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Configuring Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344Table Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Inheritance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Mixin and Custom Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Declarative API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

2.7.5 Mutation Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Establishing Mutability on Scalar Column Values . . . . . . . . . . . . . . . . . . . . . . . . 369Establishing Mutability on Composites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

2.7.6 Ordering List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

2.7.7 Horizontal Sharding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

2.7.8 Hybrid Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381Defining Expression Behavior Distinct from Attribute Behavior . . . . . . . . . . . . . . . . 383Defining Setters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Working with Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Building Custom Comparators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Hybrid Value Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387Building Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

2.7.9 Alternate Class Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

2.8 ORM Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3942.8.1 Mapping Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

Adjacency List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Directed Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Dynamic Relations as Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Generic Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Large Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Materialized Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Nested Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Relationship Join Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400XML Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Versioning Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Vertical Attribute Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

2.8.2 Inheritance Mapping Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403Basic Inheritance Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

2.8.3 Special APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403Attribute Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403Horizontal Sharding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

2.8.4 Extending the ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404Dogpile Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404PostGIS Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

3 SQLAlchemy Core 4073.1 SQL Expression Language Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

3.1.1 Version Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4073.1.2 Connecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4083.1.3 Define and Create Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4083.1.4 Insert Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

v

3.1.5 Executing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4103.1.6 Executing Multiple Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4113.1.7 Selecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4123.1.8 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

Operator Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4163.1.9 Conjunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4163.1.10 Using Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

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

3.1.11 Using Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4203.1.12 Using Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4213.1.13 Everything Else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

Bind Parameter Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424Window Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425Unions and Other Set Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426Scalar Selects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427Correlated Subqueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428Ordering, Grouping, Limiting, Offset...ing... . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

3.1.14 Inserts, Updates and Deletes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Correlated Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432Multiple Table Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432Deletes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433Matched Row Counts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

3.1.15 Further Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4343.2 SQL Statements and Expressions API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

3.2.1 Column Elements and Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4343.2.2 Selectables, Tables, FROM objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4793.2.3 Insert, Updates, Deletes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5403.2.4 SQL and Generic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5703.2.5 Custom SQL Constructs and Compilation Extension . . . . . . . . . . . . . . . . . . . . . 577

Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577Dialect-specific compilation rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577Compiling sub-elements of a custom expression construct . . . . . . . . . . . . . . . . . . . 578Enabling Autocommit on a Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579Changing the default compilation of existing constructs . . . . . . . . . . . . . . . . . . . . . 579Changing Compilation of Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580Subclassing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580Further Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581

3.2.6 Expression Serializer Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5833.3 Schema Definition Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

3.3.1 Describing Databases with MetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584Accessing Tables and Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585Creating and Dropping Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586Altering Schemas through Migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588Specifying the Schema Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588Backend-Specific Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588Column, Table, MetaData API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

3.3.2 Reflecting Database Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615Overriding Reflected Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616Reflecting Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616Reflecting All Tables at Once . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616Fine Grained Reflection with Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617Limitations of Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

vi

3.3.3 Column Insert/Update Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621Scalar Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622Python-Executed Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622SQL Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623Server Side Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624Triggered Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625Defining Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625Default Objects API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

3.3.4 Defining Constraints and Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630Defining Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630UNIQUE Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634CHECK Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635PRIMARY KEY Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635Setting up Constraints when using the Declarative ORM Extension . . . . . . . . . . . . . . 635Configuring Constraint Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 636Constraints API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658Index API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

3.3.5 Customizing DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662Controlling DDL Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663Custom DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665DDL Expression Constructs API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

3.4 Column and Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6733.4.1 Column and Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

Generic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673SQL Standard Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681Vendor-Specific Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683

3.4.2 Custom Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684Overriding Type Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684Augmenting Existing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685TypeDecorator Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691Replacing the Bind/Result Processing of Existing Types . . . . . . . . . . . . . . . . . . . . 693Applying SQL-level Bind/Result Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 694Redefining and Creating New Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696Creating New Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697

3.4.3 Base Type API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6983.5 Engine and Connection Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

3.5.1 Engine Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702Supported Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703Database Urls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703Engine Creation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710Custom DBAPI connect() arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710Configuring Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710

3.5.2 Working with Engines and Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711Using Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713Understanding Autocommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714Connectionless Execution, Implicit Execution . . . . . . . . . . . . . . . . . . . . . . . . . . 714Engine Disposal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716Using the Threadlocal Execution Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717Working with Raw DBAPI Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718Registering New Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719Connection / Engine API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720

vii

3.5.3 Connection Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738Connection Pool Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738Switching Pool Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738Using a Custom Connection Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739Constructing a Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739Pool Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740Dealing with Disconnects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740Using Connection Pools with Multiprocessing . . . . . . . . . . . . . . . . . . . . . . . . . 742API Documentation - Available Pool Implementations . . . . . . . . . . . . . . . . . . . . . 743Pooling Plain DB-API Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749

3.5.4 Core Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750Connection Pool Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750SQL Execution and Connection Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754Schema Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768

3.6 Core API Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7733.6.1 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773

Event Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773Named Argument Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774Event Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775

3.6.2 Runtime Inspection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777Available Inspection Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777

3.6.3 Deprecated Event Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778Execution, Connection and Cursor Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778Connection Pool Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779

3.6.4 Core Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7803.6.5 Core Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

4 Dialects 8034.1 Included Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

4.1.1 Firebird . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803Firebird Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803Locking Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803RETURNING support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804fdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804kinterbasdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805

4.1.2 Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806Auto Increment Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806Rendering of SQL statements that include schema qualifiers . . . . . . . . . . . . . . . . . . 808Collation Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809LIMIT/OFFSET Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809Nullability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810Date / Time Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810Large Text/Binary Type Deprecation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810Clustered Index Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811MSSQL-Specific Index Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811Compatibility Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812Enabling Snapshot Isolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813

viii

SQL Server Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813PyODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817mxODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819pymssql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820zxjdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820AdoDBAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820

4.1.3 MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821Supported Versions and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821Connection Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821CREATE TABLE arguments including Storage Engines . . . . . . . . . . . . . . . . . . . . 821Case Sensitivity and Table Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822Transaction Isolation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822AUTO_INCREMENT Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823Ansi Quoting Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824MySQL SQL Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824rowcount Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825CAST Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825MySQL Specific Index Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825MySQL Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826MySQL Unique Constraints and Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . 827TIMESTAMP Columns and NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827MySQL Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829MySQL-Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839pymysql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840MySQL-Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840cymysql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841OurSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841Google App Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842pyodbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842zxjdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843

4.1.4 Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843Connect Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843Auto Increment Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844Identifier Casing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844LIMIT/OFFSET Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844RETURNING Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845ON UPDATE CASCADE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845Oracle 8 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845Synonym/DBLINK Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846DateTime Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846Oracle Table Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846Oracle Specific Index Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847Oracle Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847cx_Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850zxjdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854

4.1.5 PostgreSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854Sequences/SERIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854Transaction Isolation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855Remote-Schema Table Introspection and Postgresql search_path . . . . . . . . . . . . . . . . 855INSERT/UPDATE...RETURNING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857

ix

Full Text Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858FROM ONLY ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859Postgresql-Specific Index Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859Postgresql Index Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861Special Reflection Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861PostgreSQL Table Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862ENUM Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862PostgreSQL Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863PostgreSQL Constraint Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878psycopg2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879pg8000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883psycopg2cffi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884py-postgresql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885zxjdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885

4.1.6 SQLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886Date and Time Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886SQLite Auto Incrementing Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886Database Locking Behavior / Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . 887Transaction Isolation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888SAVEPOINT Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888Transactional DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889Foreign Key Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889Type Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889Partial Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890Dotted Column Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890SQLite Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892Pysqlite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894Pysqlcipher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898

4.1.7 Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899DBAPI Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899python-sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899pyodbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899mxodbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900

4.2 External Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9014.2.1 Production Ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9014.2.2 Experimental / Incomplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9014.2.3 Attic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901

5 Frequently Asked Questions 9035.1 Connections / Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903

5.1.1 How do I configure logging? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9035.1.2 How do I pool database connections? Are my connections pooled? . . . . . . . . . . . . . . 9035.1.3 How do I pass custom connect arguments to my database API? . . . . . . . . . . . . . . . . 9035.1.4 MySQL Server has gone away . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9045.1.5 Why does SQLAlchemy issue so many ROLLBACKs? . . . . . . . . . . . . . . . . . . . . 904

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

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! . . . . . . . . . . . . . . . . . . . . . . . . . . . 905

5.1.7 How do I get at the raw DBAPI connection when using an Engine? . . . . . . . . . . . . . . 9055.2 MetaData / Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905

5.2.1 My program is hanging when I say table.drop() / metadata.drop_all() . . . . . 905

x

5.2.2 Does SQLAlchemy support ALTER TABLE, CREATE VIEW, CREATE TRIGGER,Schema Upgrade Functionality? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906

5.2.3 How can I sort Table objects in order of their dependency? . . . . . . . . . . . . . . . . . . 9065.2.4 How can I get the CREATE TABLE/ DROP TABLE output as a string? . . . . . . . . . . . 9065.2.5 How can I subclass Table/Column to provide certain behaviors/configurations? . . . . . . . 907

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

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

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

5.5 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9145.5.1 How can I profile a SQLAlchemy powered application? . . . . . . . . . . . . . . . . . . . . 915

Query Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915Code Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916Execution Slowness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917Result Fetching Slowness - Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917Result Fetching Slowness - ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918

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

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

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

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

are returned. Why not? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9265.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) . . . . . . . . . . . . . . . . . . . 926

5.6.6 Query has no __len__(), why not? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9265.6.7 How Do I use Textual SQL with ORM Queries? . . . . . . . . . . . . . . . . . . . . . . . . 9265.6.8 Im calling Session.delete(myobject) and it isnt removed from the parent collection!9265.6.9 why isnt my __init__() called when I load objects? . . . . . . . . . . . . . . . . . . . 9275.6.10 how do I use ON DELETE CASCADE with SAs ORM? . . . . . . . . . . . . . . . . . . . 9275.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? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9275.6.12 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? . 928

6 Changes and Migration 9296.1 Current Migration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929

6.1.1 Whats New in SQLAlchemy 1.0? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929New Features and Improvements - ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929New Features and Improvements - Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938Key Behavioral Changes - ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944Key Behavioral Changes - Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956

xi

Dialect Improvements and Changes - Postgresql . . . . . . . . . . . . . . . . . . . . . . . . 962Dialect Improvements and Changes - MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . 965Dialect Improvements and Changes - SQLite . . . . . . . . . . . . . . . . . . . . . . . . . . 967Dialect Improvements and Changes - SQL Server . . . . . . . . . . . . . . . . . . . . . . . . 967Dialect Improvements and Changes - Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . 968

6.2 Change logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9686.2.1 1.0 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968

1.0.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9681.0.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9691.0.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9711.0.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9731.0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9741.0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9751.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9761.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9781.0.0b5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9791.0.0b4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9801.0.0b3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9811.0.0b2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9811.0.0b1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982

6.2.2 0.9 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10080.9.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10080.9.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10100.9.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10130.9.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10160.9.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10190.9.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10190.9.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10230.9.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10280.9.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10300.9.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10350.9.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10360.9.0b1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042

6.2.3 0.8 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10550.8.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10550.8.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10570.8.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10580.8.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10600.8.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10620.8.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10650.8.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10690.8.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10710.8.0b2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10750.8.0b1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079

6.2.4 0.7 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10880.7.11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10880.7.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10890.7.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10910.7.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10930.7.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10940.7.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10960.7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10990.7.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11010.7.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105

xii

0.7.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11090.7.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11120.7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11130.7.0b4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11150.7.0b3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11170.7.0b2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11190.7.0b1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1120

6.2.5 0.6 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11240.6.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11240.6.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11260.6.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11270.6.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11300.6.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11320.6.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11360.6.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11390.6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11400.6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11430.6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11450.6beta3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11470.6beta2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11490.6beta1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154

6.2.6 0.5 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11660.5.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11660.5.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11660.5.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11670.5.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11690.5.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11710.5.4p2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11720.5.4p1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11720.5.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11730.5.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11750.5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11770.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11780.5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11800.5.0rc4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11850.5.0rc3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11860.5.0rc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11880.5.0rc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11890.5.0beta3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11920.5.0beta2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11930.5.0beta1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195

6.2.7 0.4 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11970.4.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11970.4.7p1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11970.4.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11980.4.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11990.4.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12010.4.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12050.4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12060.4.2p3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12100.4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12110.4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12150.4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12180.4.0beta6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220

xiii

0.4.0beta5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12210.4.0beta4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12210.4.0beta3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12220.4.0beta2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12230.4.0beta1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223

6.2.8 0.3 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12280.3.11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12280.3.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12300.3.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12300.3.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12330.3.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12350.3.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12370.3.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12400.3.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12430.3.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12450.3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12450.3.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12460.3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1247

6.2.9 0.2 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12510.2.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12510.2.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12520.2.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12530.2.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12540.2.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12540.2.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12550.2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12560.2.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12560.2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257

6.2.10 0.1 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12580.1.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12580.1.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12590.1.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12590.1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12610.1.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12620.1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12630.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263

6.3 Older Migration Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12646.3.1 Whats New in SQLAlchemy 0.9? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264Platform Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264Behavioral Changes - ORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265Behavioral Changes - Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274Behavioral Improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1281Dialect Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291

6.3.2 Whats New in SQLAlchemy 0.8? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291Platform Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1292New ORM Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1292New Core Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1300Behavioral Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306Removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312

6.3.3 Whats New in SQLAlchemy 0.7? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313

xiv

New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314Behavioral Changes (Backwards Compatible) . . . . . . . . . . . . . . . . . . . . . . . . . . 1319Behavioral Changes (Backwards Incompatible) . . . . . . . . . . . . . . . . . . . . . . . . . 1322Deprecated API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1327Backwards Incompatible API Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328Previously Deprecated, Now Removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1329

6.3.4 Whats New in SQLAlchemy 0.6? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330Platform Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330New Dialect System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330Expression Language Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331C Extensions for Result Fetching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333New Schema Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334Logging opened up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336Reflection/Inspector API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336RETURNING Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1337Type System Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1337ORM Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1340Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344

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

6.3.6 Whats new in SQLAlchemy 0.4? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353First Things First . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353Module Imports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353Object Relational Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354SQL Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362Schema and Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363SQL Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363

7 Indices and tables 1365

Python Module Index 1367

xv

xvi

SQLAlchemy Documentation, Release 1.0.7

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

Contents 1

SQLAlchemy Documentation, Release 1.0.7

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.7

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.7

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.7

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__1.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 as a system for expressing database queries in terms of the user defined classes and their defined relationshipsbetween each other.

The ORM is in contrast to the SQLAlchemy Expression Language, upon which the ORM is constructed. Whereas theSQL Expression Language, introduced in SQL Expression Language Tutorial, presents a system of representing theprimitive constructs of the relational database directly without opinion, the ORM presents a high level and abstractedpattern of usage, which itself is an example of applied usage of the Expression Language.

While there is overlap among the usage patterns of the ORM and the Expression Language, the similarities are moresuperficial than they may at first appear. One approaches the structure and content of data from the perspective ofa user-defined domain model which is transparently persisted and refreshed from its underlying storage model. Theother approaches it from the perspective of literal schema and SQL expression representations which are explicitlycomposed into messages consumed individually by the database.

A successful application may be constructed using the Object Relational Mapper exclusively. In advanced situations,an application constructed with the ORM may make occasional usage of the Expression Language directly in certainareas where specific database interactions are required.

The following tutorial is in doctest format, meaning each >>> line represents something you can type at a Pythoncommand prompt, and the following text represents the expected return value.

2.1.1 Version Check

A quick check to verify that we are on at least version 1.0 of SQLAlchemy:

>>> import sqlalchemy>>> sqlalchemy.__version__1.0.0