1SQLAlchemy
2==========
3
4|PyPI| |Python| |Downloads|
5
6.. |PyPI| image:: https://img.shields.io/pypi/v/sqlalchemy
7    :target: https://pypi.org/project/sqlalchemy
8    :alt: PyPI
9
10.. |Python| image:: https://img.shields.io/pypi/pyversions/sqlalchemy
11    :target: https://pypi.org/project/sqlalchemy
12    :alt: PyPI - Python Version
13
14.. |Downloads| image:: https://img.shields.io/pypi/dm/sqlalchemy
15    :target: https://pypi.org/project/sqlalchemy
16    :alt: PyPI - Downloads
17
18
19The Python SQL Toolkit and Object Relational Mapper
20
21Introduction
22-------------
23
24SQLAlchemy is the Python SQL toolkit and Object Relational Mapper
25that gives application developers the full power and
26flexibility of SQL. SQLAlchemy provides a full suite
27of well known enterprise-level persistence patterns,
28designed for efficient and high-performing database
29access, adapted into a simple and Pythonic domain
30language.
31
32Major SQLAlchemy features include:
33
34* An industrial strength ORM, built
35  from the core on the identity map, unit of work,
36  and data mapper patterns.   These patterns
37  allow transparent persistence of objects
38  using a declarative configuration system.
39  Domain models
40  can be constructed and manipulated naturally,
41  and changes are synchronized with the
42  current transaction automatically.
43* A relationally-oriented query system, exposing
44  the full range of SQL's capabilities
45  explicitly, including joins, subqueries,
46  correlation, and most everything else,
47  in terms of the object model.
48  Writing queries with the ORM uses the same
49  techniques of relational composition you use
50  when writing SQL.  While you can drop into
51  literal SQL at any time, it's virtually never
52  needed.
53* A comprehensive and flexible system
54  of eager loading for related collections and objects.
55  Collections are cached within a session,
56  and can be loaded on individual access, all
57  at once using joins, or by query per collection
58  across the full result set.
59* A Core SQL construction system and DBAPI
60  interaction layer.  The SQLAlchemy Core is
61  separate from the ORM and is a full database
62  abstraction layer in its own right, and includes
63  an extensible Python-based SQL expression
64  language, schema metadata, connection pooling,
65  type coercion, and custom types.
66* All primary and foreign key constraints are
67  assumed to be composite and natural.  Surrogate
68  integer primary keys are of course still the
69  norm, but SQLAlchemy never assumes or hardcodes
70  to this model.
71* Database introspection and generation.  Database
72  schemas can be "reflected" in one step into
73  Python structures representing database metadata;
74  those same structures can then generate
75  CREATE statements right back out - all within
76  the Core, independent of the ORM.
77
78SQLAlchemy's philosophy:
79
80* SQL databases behave less and less like object
81  collections the more size and performance start to
82  matter; object collections behave less and less like
83  tables and rows the more abstraction starts to matter.
84  SQLAlchemy aims to accommodate both of these
85  principles.
86* An ORM doesn't need to hide the "R".   A relational
87  database provides rich, set-based functionality
88  that should be fully exposed.   SQLAlchemy's
89  ORM provides an open-ended set of patterns
90  that allow a developer to construct a custom
91  mediation layer between a domain model and
92  a relational schema, turning the so-called
93  "object relational impedance" issue into
94  a distant memory.
95* The developer, in all cases, makes all decisions
96  regarding the design, structure, and naming conventions
97  of both the object model as well as the relational
98  schema.   SQLAlchemy only provides the means
99  to automate the execution of these decisions.
100* With SQLAlchemy, there's no such thing as
101  "the ORM generated a bad query" - you
102  retain full control over the structure of
103  queries, including how joins are organized,
104  how subqueries and correlation is used, what
105  columns are requested.  Everything SQLAlchemy
106  does is ultimately the result of a developer-
107  initiated decision.
108* Don't use an ORM if the problem doesn't need one.
109  SQLAlchemy consists of a Core and separate ORM
110  component.   The Core offers a full SQL expression
111  language that allows Pythonic construction
112  of SQL constructs that render directly to SQL
113  strings for a target database, returning
114  result sets that are essentially enhanced DBAPI
115  cursors.
116* Transactions should be the norm.  With SQLAlchemy's
117  ORM, nothing goes to permanent storage until
118  commit() is called.  SQLAlchemy encourages applications
119  to create a consistent means of delineating
120  the start and end of a series of operations.
121* Never render a literal value in a SQL statement.
122  Bound parameters are used to the greatest degree
123  possible, allowing query optimizers to cache
124  query plans effectively and making SQL injection
125  attacks a non-issue.
126
127Documentation
128-------------
129
130Latest documentation is at:
131
132https://www.sqlalchemy.org/docs/
133
134Installation / Requirements
135---------------------------
136
137Full documentation for installation is at
138`Installation <https://www.sqlalchemy.org/docs/intro.html#installation>`_.
139
140Getting Help / Development / Bug reporting
141------------------------------------------
142
143Please refer to the `SQLAlchemy Community Guide <https://www.sqlalchemy.org/support.html>`_.
144
145Code of Conduct
146---------------
147
148Above all, SQLAlchemy places great emphasis on polite, thoughtful, and
149constructive communication between users and developers.
150Please see our current Code of Conduct at
151`Code of Conduct <https://www.sqlalchemy.org/codeofconduct.html>`_.
152
153License
154-------
155
156SQLAlchemy is distributed under the `MIT license
157<https://www.opensource.org/licenses/mit-license.php>`_.
158
159