Repository files navigation

The Python SQL Toolkit and Object Relational Mapper

SQLAlchemy is the Python SQL toolkit and Object Relational Mapperthat gives application developers the full power andflexibility of SQL. SQLAlchemy provides a full suiteof well known enterprise-level persistence patterns,designed for efficient and high-performing databaseaccess, adapted into a simple and Pythonic domainlanguage.

Major SQLAlchemy features include:

• An industrial strength ORM, builtfrom the core on the identity map, unit of work,and data mapper patterns. These patternsallow transparent persistence of objectsusing a declarative configuration system.Domain modelscan be constructed and manipulated naturally,and changes are synchronized with thecurrent transaction automatically.
• A relationally-oriented query system, exposingthe full range of SQL's capabilitiesexplicitly, including joins, subqueries,correlation, and most everything else,in terms of the object model.Writing queries with the ORM uses the sametechniques of relational composition you usewhen writing SQL. While you can drop intoliteral SQL at any time, it's virtually neverneeded.
• A comprehensive and flexible systemof eager loading for related collections and objects.Collections are cached within a session,and can be loaded on individual access, allat once using joins, or by query per collectionacross the full result set.
• A Core SQL construction system and DBAPIinteraction layer. The SQLAlchemy Core isseparate from the ORM and is a full databaseabstraction layer in its own right, and includesan extensible Python-based SQL expressionlanguage, schema metadata, connection pooling,type coercion, and custom types.
• All primary and foreign key constraints areassumed to be composite and natural. Surrogateinteger primary keys are of course still thenorm, but SQLAlchemy never assumes or hardcodesto this model.
• Database introspection and generation. Databaseschemas can be "reflected" in one step intoPython structures representing database metadata;those same structures can then generateCREATE statements right back out - all withinthe Core, independent of the ORM.

SQLAlchemy's philosophy:

• SQL databases behave less and less like objectcollections the more size and performance start tomatter; object collections behave less and less liketables and rows the more abstraction starts to matter.SQLAlchemy aims to accommodate both of theseprinciples.
• An ORM doesn't need to hide the "R". A relationaldatabase provides rich, set-based functionalitythat should be fully exposed. SQLAlchemy'sORM provides an open-ended set of patternsthat allow a developer to construct a custommediation layer between a domain model anda relational schema, turning the so-called"object relational impedance" issue intoa distant memory.
• The developer, in all cases, makes all decisionsregarding the design, structure, and naming conventionsof both the object model as well as the relationalschema. SQLAlchemy only provides the meansto automate the execution of these decisions.
• With SQLAlchemy, there's no such thing as"the ORM generated a bad query" - youretain full control over the structure ofqueries, including how joins are organized,how subqueries and correlation is used, whatcolumns are requested. Everything SQLAlchemydoes is ultimately the result of a developer-initiateddecision.
• Don't use an ORM if the problem doesn't need one.SQLAlchemy consists of a Core and separate ORMcomponent. The Core offers a full SQL expressionlanguage that allows Pythonic constructionof SQL constructs that render directly to SQLstrings for a target database, returningresult sets that are essentially enhanced DBAPIcursors.
• Transactions should be the norm. With SQLAlchemy'sORM, nothing goes to permanent storage untilcommit() is called. SQLAlchemy encourages applicationsto create a consistent means of delineatingthe start and end of a series of operations.
• Never render a literal value in a SQL statement.Bound parameters are used to the greatest degreepossible, allowing query optimizers to cachequery plans effectively and making SQL injectionattacks a non-issue.

Latest documentation is at:

https://www.sqlalchemy.org/docs/

Full documentation for installation is atInstallation.

Please refer to theSQLAlchemy Community Guide.

Above all, SQLAlchemy places great emphasis on polite, thoughtful, andconstructive communication between users and developers.Please see our current Code of Conduct atCode of Conduct.

SQLAlchemy is distributed under theMIT license.