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

# SQLAlchemy 2.1 Documentation

# 0.2 Changelog

## 0.2.8

Released: Tue Sep 05 2006

- [no_tags]

  cleanup on connection methods + documentation. custom DBAPI arguments specified in query string, ‘connect_args’ argument to ‘create_engine’, or custom creation function via ‘creator’ function to ‘create_engine’.

- [no_tags]

  added “recycle” argument to Pool, is “pool_recycle” on create_engine, defaults to 3600 seconds; connections after this age will be closed and replaced with a new one, to handle db’s that automatically close stale connections

  References: #274

- [no_tags]

  changed “invalidate” semantics with pooled connection; will instruct the underlying connection record to reconnect the next time its called. “invalidate” will also automatically be called if any error is thrown in the underlying call to connection.cursor(). this will hopefully allow the connection pool to reconnect to a database that had been stopped and started without restarting the connecting application

  References: #121

- [no_tags]

  eesh ! the tutorial doctest was broken for quite some time.

- [no_tags]

  add_property() method on mapper does a “compile all mappers” step in case the given property references a non-compiled mapper (as it did in the case of the tutorial !)

- [no_tags]

  check for pg sequence already existing before create

  References: #277

- [no_tags]

  if a contextual session is established via MapperExtension.get_session (as it is using the sessioncontext plugin, etc), a lazy load operation will use that session by default if the parent object is not persistent with a session already.

- [no_tags]

  lazy loads will not fire off for an object that does not have a database identity (why? see https://www.sqlalchemy.org/trac/wiki/WhyDontForeignKeysLoadData)

- [no_tags]

  unit-of-work does a better check for “orphaned” objects that are part of a “delete-orphan” cascade, for certain conditions where the parent isn’t available to cascade from.

- [no_tags]

  mappers can tell if one of their objects is an “orphan” based on interactions with the attribute package. this check is based on a status flag maintained for each relationship when objects are attached and detached from each other.

- [no_tags]

  it is now invalid to declare a self-referential relationship with “delete-orphan” (as the abovementioned check would make them impossible to save)

- [no_tags]

  improved the check for objects being part of a session when the unit of work seeks to flush() them as part of a relationship..

- [no_tags]

  statement execution supports using the same BindParam object more than once in an expression; simplified handling of positional parameters. nice job by Bill Noon figuring out the basic idea.

  References: #280

- [no_tags]

  postgres reflection moved to use pg_schema tables, can be overridden with use_information_schema=True argument to create_engine.

  References: #60, #71

- [no_tags]

  added case_sensitive argument to MetaData, Table, Column, determines itself automatically based on if a parent schemaitem has a non-None setting for the flag, or if not, then whether the identifier name is all lower case or not. when set to True, quoting is applied to identifiers with mixed or uppercase identifiers. quoting is also applied automatically in all cases to identifiers that are known to be reserved words or contain other non-standard characters. various database dialects can override all of this behavior, but currently they are all using the default behavior. tested with postgres, mysql, sqlite, oracle. needs more testing with firebird, ms-sql. part of the ongoing work with

  References: #155

- [no_tags]

  unit tests updated to run without any pysqlite installed; pool test uses a mock DBAPI

- [no_tags]

  urls support escaped characters in passwords

  References: #281

- [no_tags]

  added limit/offset to UNION queries (though not yet in oracle)

- [no_tags]

  added “timezone=True” flag to DateTime and Time types. postgres so far will convert this to “TIME[STAMP] (WITH|WITHOUT) TIME ZONE”, so that control over timezone presence is more controllable (psycopg2 returns datetimes with tzinfo’s if available, which can create confusion against datetimes that don’t).

- [no_tags]

  fix to using query.count() with distinct, **kwargs with SelectResults count()

  References: #287

- [no_tags]

  deregister Table from MetaData when autoload fails;

  References: #289

- [no_tags]

  import of py2.5s sqlite3

  References: #293

- [no_tags]

  unicode fix for startswith()/endswith()

  References: #296

## 0.2.7

Released: Sat Aug 12 2006

- [no_tags]

  quoting facilities set up so that database-specific quoting can be turned on for individual table, schema, and column identifiers when used in all queries/creates/drops. Enabled via “quote=True” in Table or Column, as well as “quote_schema=True” in Table. Thanks to Aaron Spike for the excellent efforts.

- [no_tags]

  assignmapper was setting is_primary=True, causing all sorts of mayhem by not raising an error when redundant mappers were set up, fixed

- [no_tags]

  added allow_null_pks option to Mapper, allows rows where some primary key columns are null (i.e. when mapping to outer joins etc)

- [no_tags]

  modification to unitofwork to not maintain ordering within the “new” list or within the UOWTask “objects” list; instead, new objects are tagged with an ordering identifier as they are registered as new with the session, and the INSERT statements are then sorted within the mapper save_obj. the INSERT ordering has basically been pushed all the way to the end of the flush cycle. that way the various sorts and organizations occurring within UOWTask (particularly the circular task sort) don’t have to worry about maintaining order (which they weren’t anyway)

- [no_tags]

  fixed reflection of foreign keys to autoload the referenced table if it was not loaded already

- [no_tags]

  - pass URL query string arguments to connect() function

  References: #256

- [no_tags]

  - oracle boolean type

  References: #257

- [no_tags]

  custom primary/secondary join conditions in a relation will be propagated to backrefs by default. specifying a backref() will override this behavior.

- [no_tags]

  better check for ambiguous join conditions in sql.Join; propagates to a better error message in PropertyLoader (i.e. relation()/backref()) for when the join condition can’t be reasonably determined.

- [no_tags]

  sqlite creates ForeignKeyConstraint objects properly upon table reflection.

- [no_tags]

  adjustments to pool stemming from changes made for. overflow counter should only be decremented if the connection actually succeeded. added a test script to attempt testing this.

  References: #224

- [no_tags]

  fixed mysql reflection of default values to be PassiveDefault

- [no_tags]

  added reflected ‘tinyint’, ‘mediumint’ type to MS-SQL.

  References: #263, #264

- [no_tags]

  SingletonThreadPool has a size and does a cleanup pass, so that only a given number of thread-local connections stay around (needed for sqlite applications that dispose of threads en masse)

- [no_tags]

  fixed small pickle bug(s) with lazy loaders

  References: #265, #267

- [no_tags]

  fixed possible error in mysql reflection where certain versions return an array instead of string for SHOW CREATE TABLE call

- [no_tags]

  fix to lazy loads when mapping to joins

  References: #1770

- [no_tags]

  all create()/drop() calls have a keyword argument of “connectable”. “engine” is deprecated.

- [no_tags]

  fixed ms-sql connect() to work with adodbapi

- [no_tags]

  added “nowait” flag to Select()

- [no_tags]

  inheritance check uses issubclass() instead of direct __mro__ check to make sure class A inherits from B, allowing mapper inheritance to more flexibly correspond to class inheritance

  References: #271

- [no_tags]

  SelectResults will use a subselect, when calling an aggregate (i.e. max, min, etc.) on a SelectResults that has an ORDER BY clause

  References: #252

- [no_tags]

  fixes to types so that database-specific types more easily used; fixes to mysql text types to work with this methodology

  References: #269

- [no_tags]

  some fixes to sqlite date type organization

- [no_tags]

  added MSTinyInteger to MS-SQL

  References: #263

## 0.2.6

Released: Thu Jul 20 2006

- [no_tags]

  big overhaul to schema to allow truly composite primary and foreign key constraints, via new ForeignKeyConstraint and PrimaryKeyConstraint objects. Existing methods of primary/foreign key creation have not been changed but use these new objects behind the scenes. table creation and reflection is now more table oriented rather than column oriented.

  References: #76

- [no_tags]

  overhaul to MapperExtension calling scheme, wasn’t working very well previously

- [no_tags]

  tweaks to ActiveMapper, supports self-referential relationships

- [no_tags]

  slight rearrangement to objectstore (in activemapper/threadlocal) so that the SessionContext is referenced by ‘.context’ instead of subclassed directly.

- [no_tags]

  activemapper will use threadlocal’s objectstore if the mod is activated when activemapper is imported

- [no_tags]

  small fix to URL regexp to allow filenames with ‘@’ in them

- [no_tags]

  fixes to Session expunge/update/etc…needs more cleanup.

- [no_tags]

  select_table mappers still weren’t always compiling

- [no_tags]

  fixed up Boolean datatype

- [no_tags]

  added count()/count_by() to list of methods proxied by assignmapper; this also adds them to activemapper

- [no_tags]

  connection exceptions wrapped in DBAPIError

- [no_tags]

  ActiveMapper now supports autoloading column definitions from the database if you supply a __autoload__ = True attribute in your mapping inner-class. Currently this does not support reflecting any relationships.

- [no_tags]

  deferred column load could screw up the connection status in a flush() under some circumstances, this was fixed

- [no_tags]

  expunge() was not working with cascade, fixed.

- [no_tags]

  potential endless loop in cascading operations fixed.

- [no_tags]

  added “synonym()” function, applied to properties to have a propname the same as another, for the purposes of overriding props and allowing the original propname to be accessible in select_by().

- [no_tags]

  fix to typing in clause construction which specifically helps type issues with polymorphic_union (CAST/ColumnClause propagates its type to proxy columns)

- [no_tags]

  mapper compilation work ongoing, someday it’ll work….moved around the initialization of MapperProperty objects to be after all mappers are created to better handle circular compilations. do_init() method is called on all properties now which are more aware of their “inherited” status if so.

- [no_tags]

  eager loads explicitly disallowed on self-referential relationships, or relationships to an inheriting mapper (which is also self-referential)

- [no_tags]

  reduced bind param size in query._get to appease the picky oracle

  References: #244

- [no_tags]

  added ‘checkfirst’ argument to table.create()/table.drop(), as well as table.exists()

  References: #234

- [no_tags]

  some other ongoing fixes to inheritance

  References: #245

- [no_tags]

  attribute/backref/orphan/history-tracking tweaks as usual…

## 0.2.5

Released: Sat Jul 08 2006

- [no_tags]

  fixed endless loop bug in select_by(), if the traversal hit two mappers that referenced each other

- [no_tags]

  upgraded all unittests to insert ‘./lib/’ into sys.path, working around new setuptools PYTHONPATH-killing behavior

- [no_tags]

  further fixes with attributes/dependencies/etc….

- [no_tags]

  improved error handling for when DynamicMetaData is not connected

- [no_tags]

  MS-SQL support largely working (tested with pymssql)

- [no_tags]

  ordering of UPDATE and DELETE statements within groups is now in order of primary key values, for more deterministic ordering

- [no_tags]

  after_insert/delete/update mapper extensions now called per object, not per-object-per-table

- [no_tags]

  further fixes/refactorings to mapper compilation

## 0.2.4

Released: Tue Jun 27 2006

- [no_tags]

  try/except when the mapper sets init.__name__ on a mapped class, supports python 2.3

- [no_tags]

  fixed bug where threadlocal engine would still autocommit despite a transaction in progress

- [no_tags]

  lazy load and deferred load operations require the parent object to be in a Session to do the operation; whereas before the operation would just return a blank list or None, it now raises an exception.

- [no_tags]

  Session.update() is slightly more lenient if the session to which the given object was formerly attached to was garbage collected; otherwise still requires you explicitly remove the instance from the previous Session.

- [no_tags]

  fixes to mapper compilation, checking for more error conditions

- [no_tags]

  small fix to eager loading combined with ordering/limit/offset

- [no_tags]

  utterly remarkable: added a single space between ‘CREATE TABLE’ and ‘(<the rest of it>’ since that’s how MySQL indicates a non- reserved word tablename…..

  References: #206

- [no_tags]

  more fixes to inheritance, related to many-to-many relations properly saving

- [no_tags]

  fixed bug when specifying explicit module to mysql dialect

- [no_tags]

  when QueuePool times out it raises a TimeoutError instead of erroneously making another connection

- [no_tags]

  Queue.Queue usage in pool has been replaced with a locally modified version (works in py2.3/2.4!) that uses a threading.RLock for a mutex. this is to fix a reported case where a ConnectionFairy’s __del__() method got called within the Queue’s get() method, which then returns its connection to the Queue via the put() method, causing a reentrant hang unless threading.RLock is used.

- [no_tags]

  postgres will not place SERIAL keyword on a primary key column if it has a foreign key constraint

- [no_tags]

  cursor() method on ConnectionFairy allows db-specific extension arguments to be propagated

  References: #221

- [no_tags]

  lazy load bind params properly propagate column type

  References: #225

- [no_tags]

  new MySQL types: MSEnum, MSTinyText, MSMediumText, MSLongText, etc. more support for MS-specific length/precision params in numeric types patch courtesy Mike Bernson

- [no_tags]

  some fixes to connection pool invalidate()

  References: #224

## 0.2.3

Released: Sat Jun 17 2006

- [no_tags]

  overhaul to mapper compilation to be deferred. this allows mappers to be constructed in any order, and their relationships to each other are compiled when the mappers are first used.

- [no_tags]

  fixed a pretty big speed bottleneck in cascading behavior particularly when backrefs were in use

- [no_tags]

  the attribute instrumentation module has been completely rewritten; its now a large degree simpler and clearer, slightly faster. the “history” of an attribute is no longer micromanaged with each change and is instead part of a “CommittedState” object created when the instance is first loaded. HistoryArraySet is gone, the behavior of list attributes is now more open ended (i.e. they’re not sets anymore).

- [no_tags]

  py2.4 “set” construct used internally, falls back to sets.Set when “set” not available/ordering is needed.

- [no_tags]

  fix to transaction control, so that repeated rollback() calls don’t fail (was failing pretty badly when flush() would raise an exception in a larger try/except transaction block)

- [no_tags]

  ”foreignkey” argument to relation() can also be a list. fixed auto-foreignkey detection

  References: #151

- [no_tags]

  fixed bug where tables with schema names weren’t getting indexed in the MetaData object properly

- [no_tags]

  fixed bug where Column with redefined “key” property wasn’t getting type conversion happening in the ResultProxy

  References: #207

- [no_tags]

  fixed ‘port’ attribute of URL to be an integer if present

- [no_tags]

  fixed old bug where if a many-to-many table mapped as “secondary” had extra columns, delete operations didn’t work

- [no_tags]

  bugfixes for mapping against UNION queries

- [no_tags]

  fixed incorrect exception class thrown when no DB driver present

- [no_tags]

  added NonExistentTable exception thrown when reflecting a table that doesn’t exist

  References: #138

- [no_tags]

  small fix to ActiveMapper regarding one-to-one backrefs, other refactorings

- [no_tags]

  overridden constructor in mapped classes gets __name__ and __doc__ from the original class

- [no_tags]

  fixed small bug in selectresult.py regarding mapper extension

  References: #200

- [no_tags]

  small tweak to cascade_mappers, not very strongly supported function at the moment

- [no_tags]

  some fixes to between(), column.between() to propagate typing information better

  References: #202

- [no_tags]

  if an object fails to be constructed, is not added to the session

  References: #203

- [no_tags]

  CAST function has been made into its own clause object with its own compilation function in ansicompiler; allows MySQL to silently ignore most CAST calls since MySQL seems to only support the standard CAST syntax with Date types. MySQL-compatible CAST support for strings, ints, etc. a TODO

## 0.2.2

Released: Mon Jun 05 2006

- [no_tags]

  big improvements to polymorphic inheritance behavior, enabling it to work with adjacency list table structures

  References: #190

- [no_tags]

  major fixes and refactorings to inheritance relationships overall, more unit tests

- [no_tags]

  fixed “echo_pool” flag on create_engine()

- [no_tags]

  fix to docs, removed incorrect info that close() is unsafe to use with threadlocal strategy (its totally safe !)

- [no_tags]

  create_engine() can take URLs as string or unicode

  References: #188

- [no_tags]

  firebird support partially completed; thanks to James Ralston and Brad Clements for their efforts.

- [no_tags]

  Oracle url translation was broken, fixed, will feed host/port/sid into cx_oracle makedsn() if ‘database’ field is present, else uses straight TNS name from the ‘host’ field

- [no_tags]

  fix to using unicode criterion for query.get()/query.load()

- [no_tags]

  count() function on selectables now uses table primary key or first column instead of “1” for criterion, also uses label “rowcount” instead of “count”.

- [no_tags]

  got rudimental “mapping to multiple tables” functionality cleaned up, more correctly documented

- [no_tags]

  restored global_connect() function, attaches to a DynamicMetaData instance called “default_metadata”. leaving MetaData arg to Table out will use the default metadata.

- [no_tags]

  fixes to session cascade behavior, entity_name propagation

- [no_tags]

  reorganized unittests into subdirectories

- [no_tags]

  more fixes to threadlocal connection nesting patterns

## 0.2.1

Released: Mon May 29 2006

- [no_tags]

  ”pool” argument to create_engine() properly propagates

- [no_tags]

  fixes to URL, raises exception if not parsed, does not pass blank fields along to the DB connect string (a string such as user:host@/db was breaking on postgres)

- [no_tags]

  small fixes to Mapper when it inserts and tries to get new primary key values back

- [no_tags]

  rewrote half of TLEngine, the ComposedSQLEngine used with ‘strategy=”threadlocal”’. it now properly implements engine.begin()/ engine.commit(), which nest fully with connection.begin()/trans.commit(). added about six unittests.

- [no_tags]

  major “duh” in pool.Pool, forgot to put back the WeakValueDictionary. unittest which was supposed to check for this was also silently missing it. fixed unittest to ensure that ConnectionFairy properly falls out of scope.

- [no_tags]

  placeholder dispose() method added to SingletonThreadPool, doesn’t do anything yet

- [no_tags]

  rollback() is automatically called when an exception is raised, but only if there’s no transaction in process (i.e. works more like autocommit).

- [no_tags]

  fixed exception raise in sqlite if no sqlite module present

- [no_tags]

  added extra example detail for association object doc

- [no_tags]

  Connection adds checks for already being closed

## 0.2.0

Released: Sat May 27 2006

- [no_tags]

  overhaul to Engine system so that what was formerly the SQLEngine is now a ComposedSQLEngine which consists of a variety of components, including a Dialect, ConnectionProvider, etc. This impacted all the db modules as well as Session and Mapper.

- [no_tags]

  create_engine now takes only RFC-1738-style strings: `driver://user:password@host:port/database`

  update this format is generally but not exactly RFC-1738, including that underscores, not dashes or periods, are accepted in the “scheme” portion.

- [no_tags]

  total rewrite of connection-scoping methodology, Connection objects can now execute clause elements directly, added explicit “close” as well as support throughout Engine/ORM to handle closing properly, no longer relying upon __del__ internally to return connections to the pool.

  References: #152

- [no_tags]

  overhaul to Session interface and scoping. uses hibernate-style methods, including query(class), save(), save_or_update(), etc. no threadlocal scope is installed by default. Provides a binding interface to specific Engines and/or Connections so that underlying Schema objects do not need to be bound to an Engine. Added a basic SessionTransaction object that can simplistically aggregate transactions across multiple engines.

- [no_tags]

  overhaul to mapper’s dependency and “cascade” behavior; dependency logic factored out of properties.py into a separate module “dependency.py”. “cascade” behavior is now explicitly controllable, proper implementation of “delete”, “delete-orphan”, etc. dependency system can now determine at flush time if a child object has a parent or not so that it makes better decisions on how that child should be updated in the DB with regards to deletes.

- [no_tags]

  overhaul to Schema to build upon MetaData object instead of an Engine. Entire SQL/Schema system can be used with no Engines whatsoever, executed solely by an explicit Connection object. the “bound” methodology exists via the BoundMetaData for schema objects. ProxyEngine is generally not needed anymore and is replaced by DynamicMetaData.

- [no_tags]

  true polymorphic behavior implemented, fixes

  References: #167

- [no_tags]

  ”oid” system has been totally moved into compile-time behavior; if they are used in an order_by where they are not available, the order_by doesn’t get compiled, fixes

  References: #147

- [no_tags]

  overhaul to packaging; “mapping” is now “orm”, “objectstore” is now “session”, the old “objectstore” namespace gets loaded in via the “threadlocal” mod if used

- [no_tags]

  mods now called in via “import <modname>”. extensions favored over mods as mods are globally-monkeypatching

- [no_tags]

  fix to add_property so that it propagates properties to inheriting mappers

  References: #154

- [no_tags]

  backrefs create themselves against primary mapper of its originating property, primary/secondary join arguments can be specified to override. helps their usage with polymorphic mappers

- [no_tags]

  ”table exists” function has been implemented

  References: #31

- [no_tags]

  ”create_all/drop_all” added to MetaData object

  References: #98

- [no_tags]

  improvements and fixes to topological sort algorithm, as well as more unit tests

- [no_tags]

  tutorial page added to docs which also can be run with a custom doctest runner to ensure its properly working. docs generally overhauled to deal with new code patterns

- [no_tags]

  many more fixes, refactorings.

- [no_tags]

  migration guide is available on the Wiki at https://www.sqlalchemy.org/trac/wiki/02Migration