Release: 2.1.0b1 | Release Date: January 21, 2026

# SQLAlchemy 2.1 Documentation

# 0.1 Changelog

## 0.1.7

Released: Fri May 05 2006

- [no_tags]

  some fixes to topological sort algorithm

- [no_tags]

  added DISTINCT ON support to Postgres (just supply distinct=[col1,col2..])

- [no_tags]

  added __mod__ (% operator) to sql expressions

- [no_tags]

  ”order_by” mapper property inherited from inheriting mapper

- [no_tags]

  fix to column type used when mapper UPDATES/DELETEs

- [no_tags]

  with convert_unicode=True, reflection was failing, has been fixed

- [no_tags]

  types types types! still weren’t working….have to use TypeDecorator again :(

- [no_tags]

  mysql binary type converts array output to buffer, fixes PickleType

- [no_tags]

  fixed the attributes.py memory leak once and for all

- [no_tags]

  unittests are qualified based on the databases that support each one

- [no_tags]

  fixed bug where column defaults would clobber VALUES clause of insert objects

- [no_tags]

  fixed bug where table def w/ schema name would force engine connection

- [no_tags]

  fix for parenthesis to work correctly with subqueries in INSERT/UPDATE

- [no_tags]

  HistoryArraySet gets extend() method

- [no_tags]

  fixed lazyload support for other comparison operators besides =

- [no_tags]

  lazyload fix where two comparisons in the join condition point to the samem column

- [no_tags]

  added “construct_new” flag to mapper, will use __new__ to create instances instead of __init__ (standard in 0.2)

- [no_tags]

  added selectresults.py to SVN, missed it last time

- [no_tags]

  tweak to allow a many-to-many relationship from a table to itself via an association table

- [no_tags]

  small fix to “translate_row” function used by polymorphic example

- [no_tags]

  create_engine uses cgi.parse_qsl to read query string (out the window in 0.2)

- [no_tags]

  tweaks to CAST operator

- [no_tags]

  fixed function names LOCAL_TIME/LOCAL_TIMESTAMP -> LOCALTIME/LOCALTIMESTAMP

- [no_tags]

  fixed order of ORDER BY/HAVING in compile

## 0.1.6

Released: Wed Apr 12 2006

- [no_tags]

  support for MS-SQL added courtesy Rick Morrison, Runar Petursson

- [no_tags]

  the latest SQLSoup from J. Ellis

- [no_tags]

  ActiveMapper has preliminary support for inheritance (Jeff Watkins)

- [no_tags]

  added a “mods” system which allows pluggable modules that modify/augment core functionality, using the function “install_mods(*modnames)”.

- [no_tags]

  added the first “mod”, SelectResults, which modifies mapper selects to return generators that turn ranges into LIMIT/OFFSET queries (Jonas Borgstr?

- [no_tags]

  factored out querying capabilities of Mapper into a separate Query object which is Session-centric. this improves the performance of mapper.using(session) and makes other things possible.

- [no_tags]

  objectstore/Session refactored, the official way to save objects is now via the flush() method. The begin/commit functionality of Session is factored into LegacySession which is still established as the default behavior, until the 0.2 series.

- [no_tags]

  types system is bound to an engine at query compile time, not schema construction time. this simplifies the types system as well as the ProxyEngine.

- [no_tags]

  added ‘version_id’ keyword argument to mapper. this keyword should reference a Column object with type Integer, preferably non-nullable, which will be used on the mapped table to track version numbers. this number is incremented on each save operation and is specified in the UPDATE/DELETE conditions so that it factors into the returned row count, which results in a ConcurrencyError if the value received is not the expected count.

- [no_tags]

  added ‘entity_name’ keyword argument to mapper. a mapper is now associated with a class via the class object as well as an optional entity_name parameter, which is a string defaulting to None. any number of primary mappers can be created for a class, qualified by the entity name. instances of those classes will issue all of their load and save operations through their entity_name-qualified mapper, and maintain separate a identity in the identity map for an otherwise equivalent object.

- [no_tags]

  overhaul to the attributes system. code has been clarified, and also fixed to support proper polymorphic behavior on object attributes.

- [no_tags]

  added “for_update” flag to Select objects

- [no_tags]

  some fixes for backrefs

- [no_tags]

  fix for postgres1 DateTime type

- [no_tags]

  documentation pages mostly switched over to Markdown syntax

## 0.1.5

Released: Mon Mar 27 2006

- [no_tags]

  added SQLSession concept to SQLEngine. this object keeps track of retrieving a connection from the connection pool as well as an in-progress transaction. methods push_session() and pop_session() added to SQLEngine which push/pop a new SQLSession onto the engine, allowing operation upon a second connection “nested” within the previous one, allowing nested transactions. Other tricks are sure to come later regarding SQLSession.

- [no_tags]

  added nest_on argument to objectstore.Session. This is a single SQLEngine or list of engines for which push_session()/pop_session() will be called each time this Session becomes the active session (via objectstore.push_session() or equivalent). This allows a unit of work Session to take advantage of the nested transaction feature without explicitly calling push_session/pop_session on the engine.

- [no_tags]

  factored apart objectstore/unitofwork to separate “Session scoping” from “uow commit heavy lifting”

- [no_tags]

  added populate_instance() method to MapperExtension. allows an extension to modify the population of object attributes. this method can call the populate_instance() method on another mapper to proxy the attribute population from one mapper to another; some row translation logic is also built in to help with this.

- [no_tags]

  fixed Oracle8-compatibility “use_ansi” flag which converts JOINs to comparisons with the = and (+) operators, passes basic unittests

- [no_tags]

  tweaks to Oracle LIMIT/OFFSET support

- [no_tags]

  Oracle reflection uses ALL_** views instead of USER_** to get larger list of stuff to reflect from

- [no_tags]

  fixes to Oracle foreign key reflection

  References: #105

- [no_tags]

  objectstore.commit(obj1, obj2,…) adds an extra step to seek out private relations on properties and delete child objects, even though its not a global commit

- [no_tags]

  lots and lots of fixes to mappers which use inheritance, strengthened the concept of relations on a mapper being made towards the “local” table for that mapper, not the tables it inherits. allows more complex compositional patterns to work with lazy/eager loading.

- [no_tags]

  added support for mappers to inherit from others based on the same table, just specify the same table as that of both parent/child mapper.

- [no_tags]

  some minor speed improvements to the attributes system with regards to instantiating and populating new objects.

- [no_tags]

  fixed MySQL binary unit test

- [no_tags]

  INSERTs can receive clause elements as VALUES arguments, not just literal values

- [no_tags]

  support for calling multi-tokened functions, i.e. schema.mypkg.func()

- [no_tags]

  added J. Ellis’ SQLSoup module to extensions package

- [no_tags]

  added “polymorphic” examples illustrating methods to load multiple object types from one mapper, the second of which uses the new populate_instance() method. small improvements to mapper, UNION construct to help the examples along

- [no_tags]

  improvements/fixes to session.refresh()/session.expire() (which may have been called “invalidate” earlier..)

- [no_tags]

  added session.expunge() which totally removes an object from the current session

- [no_tags]

  added *args, **kwargs pass-through to engine.transaction(func) allowing easier creation of transactionalizing decorator functions

- [no_tags]

  added iterator interface to ResultProxy: “for row in result:…”

- [no_tags]

  added assertion to tx = session.begin(); tx.rollback(); tx.begin(), i.e. can’t use it after a rollback()

- [no_tags]

  added date conversion on bind parameter fix to SQLite enabling dates to work with pysqlite1

- [no_tags]

  improvements to subqueries to more intelligently construct their FROM clauses

  References: #116

- [no_tags]

  added PickleType to types.

- [no_tags]

  fixed two bugs with column labels with regards to bind parameters: bind param keynames they are now generated from a column “label” in all relevant cases to take advantage of excess-name-length rules, and checks for a peculiar collision against a column named the same as “tablename_colname” added

- [no_tags]

  major overhaul to unit of work documentation, other documentation sections.

- [no_tags]

  fixed attributes bug where if an object is committed, its lazy-loaded list got blown away if it hadn’t been loaded

- [no_tags]

  added unique_connection() method to engine, connection pool to return a connection that is not part of the thread-local context or any current transaction

- [no_tags]

  added invalidate() function to pooled connection. will remove the connection from the pool. still need work for engines to auto-reconnect to a stale DB though.

- [no_tags]

  added distinct() function to column elements so you can do func.count(mycol.distinct())

- [no_tags]

  added “always_refresh” flag to Mapper, creates a mapper that will always refresh the attributes of objects it gets/selects from the DB, overwriting any changes made.

## 0.1.4

Released: Mon Mar 13 2006

- [no_tags]

  create_engine() now uses genericized parameters; host/hostname, db/dbname/database, password/passwd, etc. for all engine connections. makes engine URIs much more “universal”

- [no_tags]

  added support for SELECT statements embedded into a column clause, using the flag “scalar=True”

- [no_tags]

  another overhaul to EagerLoading when used in conjunction with mappers that inherit; improvements to eager loads figuring out their aliased queries correctly, also relations set up against a mapper with inherited mappers will create joins against the table that is specific to the mapper itself (i.e. and not any tables that are inherited/are further down the inheritance chain), this can be overridden by using custom primary/secondary joins.

- [no_tags]

  added J.Ellis patch to mapper.py so that selectone() throws an exception if query returns more than one object row, selectfirst() to not throw the exception. also adds selectfirst_by (synonymous with get_by) and selectone_by

- [no_tags]

  added onupdate parameter to Column, will exec SQL/python upon an update statement.Also adds “for_update=True” to all DefaultGenerator subclasses

- [no_tags]

  added support for Oracle table reflection contributed by Andrija Zaric; still some bugs to work out regarding composite primary keys/dictionary selection

- [no_tags]

  checked in an initial Firebird module, awaiting testing.

- [no_tags]

  added sql.ClauseParameters dictionary object as the result for compiled.get_params(), does late-typeprocessing of bind parameters so that the original values are easier to access

- [no_tags]

  more docs for indexes, column defaults, connection pooling, engine construction

- [no_tags]

  overhaul to the construction of the types system. uses a simpler inheritance pattern so that any of the generic types can be easily subclassed, with no need for TypeDecorator.

- [no_tags]

  added “convert_unicode=False” parameter to SQLEngine, will cause all String types to perform unicode encoding/decoding (makes Strings act like Unicodes)

- [no_tags]

  added ‘encoding=”utf8”’ parameter to engine. the given encoding will be used for all encode/decode calls within Unicode types as well as Strings when convert_unicode=True.

- [no_tags]

  improved support for mapping against UNIONs, added polymorph.py example to illustrate multi-class mapping against a UNION

- [no_tags]

  fix to SQLite LIMIT/OFFSET syntax

- [no_tags]

  fix to Oracle LIMIT syntax

- [no_tags]

  added backref() function, allows backreferences to have keyword arguments that will be passed to the backref.

- [no_tags]

  Sequences and ColumnDefault objects can do execute()/scalar() standalone

- [no_tags]

  SQL functions (i.e. func.foo()) can do execute()/scalar() standalone

- [no_tags]

  fix to SQL functions so that the ANSI-standard functions, i.e. current_timestamp etc., do not specify parenthesis. all other functions do.

- [no_tags]

  added settattr_clean and append_clean to SmartProperty, which set attributes without triggering a “dirty” event or any history. used as: myclass.prop1.setattr_clean(myobject, ‘hi’)

- [no_tags]

  improved support to column defaults when used by mappers; mappers will pull pre-executed defaults from statement’s executed bind parameters (pre-conversion) to populate them into a saved object’s attributes; if any PassiveDefaults have fired off, will instead post-fetch the row from the DB to populate the object.

- [no_tags]

  added ‘get_session().invalidate(*obj)’ method to objectstore, instances will refresh() themselves upon the next attribute access.

- [no_tags]

  improvements to SQL func calls including an “engine” keyword argument so they can be execute()d or scalar()ed standalone, also added func accessor to SQLEngine

- [no_tags]

  fix to MySQL4 custom table engines, i.e. TYPE instead of ENGINE

- [no_tags]

  slightly enhanced logging, includes timestamps and a somewhat configurable formatting system, in lieu of a full-blown logging system

- [no_tags]

  improvements to the ActiveMapper class from the TG gang, including many-to-many relationships

- [no_tags]

  added Double and TinyInt support to mysql

## 0.1.3

Released: Thu Mar 02 2006

- [no_tags]

  completed “post_update” feature, will add a second update statement before inserts and after deletes in order to reconcile a relationship without any dependencies being created; used when persisting two rows that are dependent on each other

- [no_tags]

  completed mapper.using(session) function, localized per-object Session functionality; objects can be declared and manipulated as local to any user-defined Session

- [no_tags]

  fix to Oracle “row_number over” clause with multiple tables

- [no_tags]

  mapper.get() was not selecting multiple-keyed objects if the mapper’s table was a join, such as in an inheritance relationship, this is fixed.

- [no_tags]

  overhaul to sql/schema packages so that the sql package can run all on its own, producing selects, inserts, etc. without any engine dependencies. builds upon new TableClause/ColumnClause lexical objects. Schema’s Table/Column objects are the “physical” subclasses of them. simplifies schema/sql relationship, extensions (like proxyengine), and speeds overall performance by a large margin. removes the entire getattr() behavior that plagued 0.1.1.

- [no_tags]

  refactoring of how the mapper “synchronizes” data between two objects into a separate module, works better with properties attached to a mapper that has an additional inheritance relationship to one of the related tables, also the same methodology used to synchronize parent/child objects now used by mapper to synchronize between inherited and inheriting mappers.

- [no_tags]

  made objectstore “check for out-of-identitymap” more aggressive, will perform the check when object attributes are modified or the object is deleted

- [no_tags]

  Index object fully implemented, can be constructed standalone, or via “index” and “unique” arguments on Columns.

- [no_tags]

  added “convert_unicode” flag to SQLEngine, will treat all String/CHAR types as Unicode types, with raw-byte/utf-8 translation on the bind parameter and result set side.

- [no_tags]

  postgres maintains a list of ANSI functions that must have no parenthesis so function calls with no arguments work consistently

- [no_tags]

  tables can be created with no engine specified. this will default their engine to a module-scoped “default engine” which is a ProxyEngine. this engine can be connected via the function “global_connect”.

- [no_tags]

  added “refresh(*obj)” method to objectstore / Session to reload the attributes of any set of objects from the database unconditionally

## 0.1.2

Released: Fri Feb 24 2006

- [no_tags]

  fixed a recursive call in schema that was somehow running 994 times then returning normally. broke nothing, slowed down everything. thanks to jpellerin for finding this.

## 0.1.1

Released: Thu Feb 23 2006

- [no_tags]

  small fix to Function class so that expressions with a func.foo() use the type of the Function object (i.e. the left side) as the type of the boolean expression, not the other side which is more of a moving target (changeset 1020).

- [no_tags]

  creating self-referring mappers with backrefs slightly easier (but still not that easy - changeset 1019)

- [no_tags]

  fixes to one-to-one mappings (changeset 1015)

- [no_tags]

  psycopg1 date/time issue with None fixed (changeset 1005)

- [no_tags]

  two issues related to postgres, which doesn’t want to give you the “lastrowid” since oids are deprecated:

  > - postgres database-side defaults that are on primary key cols do execute explicitly beforehand, even though that’s not the idea of a PassiveDefault. this is because sequences on columns get reflected as PassiveDefaults, but need to be explicitly executed on a primary key col so we know what we just inserted.

  > - if you did add a row that has a bunch of database-side defaults on it, and the PassiveDefault thing was working the old way, i.e. they just execute on the DB side, the “can’t get the row back without an OID” exception that occurred also will not happen unless someone (usually the ORM) explicitly asks for it.

- [no_tags]

  fixed a glitch with engine.execute_compiled where it was making a second ResultProxy that just got thrown away.

- [no_tags]

  began to implement newer logic in object properties. you can now say myclass.attr.property, which will give you the PropertyLoader corresponding to that attribute, i.e. myclass.mapper.props[‘attr’]

- [no_tags]

  eager loading has been internally overhauled to use aliases at all times. more complicated chains of eager loads can now be created without any need for explicit “use aliases”-type instructions. EagerLoader code is also much simpler now.

- [no_tags]

  a new somewhat experimental flag “use_update” added to relations, indicates that this relationship should be handled by a second UPDATE statement, either after a primary INSERT or before a primary DELETE. handles circular row dependencies.

- [no_tags]

  added exceptions module, all raised exceptions (except for some KeyError/AttributeError exceptions) descend from these classes.

- [no_tags]

  fix to date types with MySQL, returned timedelta converted to datetime.time

- [no_tags]

  two-phase objectstore.commit operations (i.e. begin/commit) now return a transactional object (SessionTrans), to more clearly indicate transaction boundaries.

- [no_tags]

  Index object with create/drop support added to schema

- [no_tags]

  fix to postgres, where it will explicitly pre-execute a PassiveDefault on a table if it is a primary key column, pursuant to the ongoing “we can’t get inserted rows back from postgres” issue

- [no_tags]

  change to information_schema query that gets back postgres table defs, now uses explicit JOIN keyword, since one user had faster performance with 8.1

- [no_tags]

  fix to engine.process_defaults so it works correctly with a table that has different column name/column keys (changeset 982)

- [no_tags]

  a column can only be attached to one table - this is now asserted

- [no_tags]

  postgres time types descend from Time type

- [no_tags]

  fix to alltests so that it runs types test (now named testtypes)

- [no_tags]

  fix to Join object so that it correctly exports its foreign keys (cs 973)

- [no_tags]

  creating relationships against mappers that use inheritance fixed (cs 973)