16d333bc5SMike BayerSQLAlchemy
26d333bc5SMike Bayer==========
36d333bc5SMike Bayer
4826303baSMike Bayer|PyPI| |Python| |Downloads|
5826303baSMike Bayer
6826303baSMike Bayer.. |PyPI| image:: https://img.shields.io/pypi/v/sqlalchemy
7826303baSMike Bayer    :target: https://pypi.org/project/sqlalchemy
8826303baSMike Bayer    :alt: PyPI
9826303baSMike Bayer
10826303baSMike Bayer.. |Python| image:: https://img.shields.io/pypi/pyversions/sqlalchemy
11826303baSMike Bayer    :target: https://pypi.org/project/sqlalchemy
12826303baSMike Bayer    :alt: PyPI - Python Version
13826303baSMike Bayer
14826303baSMike Bayer.. |Downloads| image:: https://img.shields.io/pypi/dm/sqlalchemy
15826303baSMike Bayer    :target: https://pypi.org/project/sqlalchemy
16826303baSMike Bayer    :alt: PyPI - Downloads
17826303baSMike Bayer
18826303baSMike Bayer
196d333bc5SMike BayerThe Python SQL Toolkit and Object Relational Mapper
206d333bc5SMike Bayer
216d333bc5SMike BayerIntroduction
226d333bc5SMike Bayer-------------
236d333bc5SMike Bayer
246d333bc5SMike BayerSQLAlchemy is the Python SQL toolkit and Object Relational Mapper
256d333bc5SMike Bayerthat gives application developers the full power and
266d333bc5SMike Bayerflexibility of SQL. SQLAlchemy provides a full suite
276d333bc5SMike Bayerof well known enterprise-level persistence patterns,
286d333bc5SMike Bayerdesigned for efficient and high-performing database
296d333bc5SMike Bayeraccess, adapted into a simple and Pythonic domain
306d333bc5SMike Bayerlanguage.
316d333bc5SMike Bayer
326d333bc5SMike BayerMajor SQLAlchemy features include:
336d333bc5SMike Bayer
3429d54ab6SMike Bayer* An industrial strength ORM, built
356d333bc5SMike Bayer  from the core on the identity map, unit of work,
366d333bc5SMike Bayer  and data mapper patterns.   These patterns
3729d54ab6SMike Bayer  allow transparent persistence of objects
3840f77086SMike Bayer  using a declarative configuration system.
3940f77086SMike Bayer  Domain models
406d333bc5SMike Bayer  can be constructed and manipulated naturally,
416d333bc5SMike Bayer  and changes are synchronized with the
426d333bc5SMike Bayer  current transaction automatically.
436d333bc5SMike Bayer* A relationally-oriented query system, exposing
4429d54ab6SMike Bayer  the full range of SQL's capabilities
4529d54ab6SMike Bayer  explicitly, including joins, subqueries,
4629d54ab6SMike Bayer  correlation, and most everything else,
4740f77086SMike Bayer  in terms of the object model.
4829d54ab6SMike Bayer  Writing queries with the ORM uses the same
4929d54ab6SMike Bayer  techniques of relational composition you use
506d333bc5SMike Bayer  when writing SQL.  While you can drop into
516d333bc5SMike Bayer  literal SQL at any time, it's virtually never
526d333bc5SMike Bayer  needed.
5329d54ab6SMike Bayer* A comprehensive and flexible system
5440f77086SMike Bayer  of eager loading for related collections and objects.
5540f77086SMike Bayer  Collections are cached within a session,
5629d54ab6SMike Bayer  and can be loaded on individual access, all
576d333bc5SMike Bayer  at once using joins, or by query per collection
586d333bc5SMike Bayer  across the full result set.
5929d54ab6SMike Bayer* A Core SQL construction system and DBAPI
606d333bc5SMike Bayer  interaction layer.  The SQLAlchemy Core is
616d333bc5SMike Bayer  separate from the ORM and is a full database
6240f77086SMike Bayer  abstraction layer in its own right, and includes
6329d54ab6SMike Bayer  an extensible Python-based SQL expression
6429d54ab6SMike Bayer  language, schema metadata, connection pooling,
656d333bc5SMike Bayer  type coercion, and custom types.
6629d54ab6SMike Bayer* All primary and foreign key constraints are
676d333bc5SMike Bayer  assumed to be composite and natural.  Surrogate
6829d54ab6SMike Bayer  integer primary keys are of course still the
696d333bc5SMike Bayer  norm, but SQLAlchemy never assumes or hardcodes
706d333bc5SMike Bayer  to this model.
716d333bc5SMike Bayer* Database introspection and generation.  Database
726d333bc5SMike Bayer  schemas can be "reflected" in one step into
736d333bc5SMike Bayer  Python structures representing database metadata;
7429d54ab6SMike Bayer  those same structures can then generate
756d333bc5SMike Bayer  CREATE statements right back out - all within
766d333bc5SMike Bayer  the Core, independent of the ORM.
776d333bc5SMike Bayer
786d333bc5SMike BayerSQLAlchemy's philosophy:
796d333bc5SMike Bayer
806d333bc5SMike Bayer* SQL databases behave less and less like object
816d333bc5SMike Bayer  collections the more size and performance start to
826d333bc5SMike Bayer  matter; object collections behave less and less like
836d333bc5SMike Bayer  tables and rows the more abstraction starts to matter.
846d333bc5SMike Bayer  SQLAlchemy aims to accommodate both of these
856d333bc5SMike Bayer  principles.
866d333bc5SMike Bayer* An ORM doesn't need to hide the "R".   A relational
876d333bc5SMike Bayer  database provides rich, set-based functionality
886d333bc5SMike Bayer  that should be fully exposed.   SQLAlchemy's
896d333bc5SMike Bayer  ORM provides an open-ended set of patterns
906d333bc5SMike Bayer  that allow a developer to construct a custom
9129d54ab6SMike Bayer  mediation layer between a domain model and
926d333bc5SMike Bayer  a relational schema, turning the so-called
936d333bc5SMike Bayer  "object relational impedance" issue into
946d333bc5SMike Bayer  a distant memory.
956d333bc5SMike Bayer* The developer, in all cases, makes all decisions
966d333bc5SMike Bayer  regarding the design, structure, and naming conventions
976d333bc5SMike Bayer  of both the object model as well as the relational
986d333bc5SMike Bayer  schema.   SQLAlchemy only provides the means
996d333bc5SMike Bayer  to automate the execution of these decisions.
10029d54ab6SMike Bayer* With SQLAlchemy, there's no such thing as
10129d54ab6SMike Bayer  "the ORM generated a bad query" - you
10229d54ab6SMike Bayer  retain full control over the structure of
1036d333bc5SMike Bayer  queries, including how joins are organized,
10429d54ab6SMike Bayer  how subqueries and correlation is used, what
10506da64f1SMike Bayer  columns are requested.  Everything SQLAlchemy
10606da64f1SMike Bayer  does is ultimately the result of a developer-
10706da64f1SMike Bayer  initiated decision.
1086d333bc5SMike Bayer* Don't use an ORM if the problem doesn't need one.
1096d333bc5SMike Bayer  SQLAlchemy consists of a Core and separate ORM
1106d333bc5SMike Bayer  component.   The Core offers a full SQL expression
11129d54ab6SMike Bayer  language that allows Pythonic construction
1126d333bc5SMike Bayer  of SQL constructs that render directly to SQL
1136d333bc5SMike Bayer  strings for a target database, returning
1146d333bc5SMike Bayer  result sets that are essentially enhanced DBAPI
1156d333bc5SMike Bayer  cursors.
1166d333bc5SMike Bayer* Transactions should be the norm.  With SQLAlchemy's
1176d333bc5SMike Bayer  ORM, nothing goes to permanent storage until
1186d333bc5SMike Bayer  commit() is called.  SQLAlchemy encourages applications
1196d333bc5SMike Bayer  to create a consistent means of delineating
1206d333bc5SMike Bayer  the start and end of a series of operations.
1216d333bc5SMike Bayer* Never render a literal value in a SQL statement.
1226d333bc5SMike Bayer  Bound parameters are used to the greatest degree
12329d54ab6SMike Bayer  possible, allowing query optimizers to cache
124535fc8b1SMike Bayer  query plans effectively and making SQL injection
1256d333bc5SMike Bayer  attacks a non-issue.
1266d333bc5SMike Bayer
1276d333bc5SMike BayerDocumentation
1286d333bc5SMike Bayer-------------
1296d333bc5SMike Bayer
1306d333bc5SMike BayerLatest documentation is at:
1316d333bc5SMike Bayer
132fb81f9c8SFederico Casellihttps://www.sqlalchemy.org/docs/
1336d333bc5SMike Bayer
1346d333bc5SMike BayerInstallation / Requirements
1356d333bc5SMike Bayer---------------------------
1366d333bc5SMike Bayer
13729d54ab6SMike BayerFull documentation for installation is at
138fb81f9c8SFederico Caselli`Installation <https://www.sqlalchemy.org/docs/intro.html#installation>`_.
1396d333bc5SMike Bayer
1406d333bc5SMike BayerGetting Help / Development / Bug reporting
1416d333bc5SMike Bayer------------------------------------------
1426d333bc5SMike Bayer
143fb81f9c8SFederico CaselliPlease refer to the `SQLAlchemy Community Guide <https://www.sqlalchemy.org/support.html>`_.
1446d333bc5SMike Bayer
14529d54ab6SMike BayerCode of Conduct
14629d54ab6SMike Bayer---------------
14729d54ab6SMike Bayer
14829d54ab6SMike BayerAbove all, SQLAlchemy places great emphasis on polite, thoughtful, and
14929d54ab6SMike Bayerconstructive communication between users and developers.
15029d54ab6SMike BayerPlease see our current Code of Conduct at
151fb81f9c8SFederico Caselli`Code of Conduct <https://www.sqlalchemy.org/codeofconduct.html>`_.
15229d54ab6SMike Bayer
1536d333bc5SMike BayerLicense
1546d333bc5SMike Bayer-------
1556d333bc5SMike Bayer
1566d333bc5SMike BayerSQLAlchemy is distributed under the `MIT license
157fb81f9c8SFederico Caselli<https://www.opensource.org/licenses/mit-license.php>`_.
1586d333bc5SMike Bayer