| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351 |
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
- <html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-
- <title>
-
-
- Overview
- —
- SQLAlchemy 1.3 Documentation
- </title>
-
- <!-- begin iterate through site-imported + sphinx environment css_files -->
- <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
- <link rel="stylesheet" href="_static/docs.css" type="text/css" />
- <link rel="stylesheet" href="_static/changelog.css" type="text/css" />
- <link rel="stylesheet" href="_static/sphinx_paramlinks.css" type="text/css" />
- <!-- end iterate through site-imported + sphinx environment css_files -->
-
-
-
- <!-- begin layout.mako headers -->
- <link rel="index" title="Index" href="genindex.html" />
- <link rel="search" title="Search" href="search.html" />
- <link rel="copyright" title="Copyright" href="copyright.html" />
- <link rel="top" title="SQLAlchemy 1.3 Documentation" href="index.html" />
- <link rel="next" title="SQLAlchemy ORM" href="orm/index.html" />
- <link rel="prev" title="Table of Contents" href="contents.html" />
- <!-- end layout.mako headers -->
- </head>
- <body>
-
- <div id="docs-container">
- <div id="docs-top-navigation-container" class="body-background">
- <div id="docs-header">
- <div id="docs-version-header">
- Release: <span class="version-num">1.3.17</span>
- | Release Date: May 13, 2020
- </div>
- <h1>SQLAlchemy 1.3 Documentation</h1>
- </div>
- </div>
- <div id="docs-body-container">
- <div id="fixed-sidebar" class="withsidebar">
- <div id="docs-sidebar-popout">
- <h3><a href="index.html">SQLAlchemy 1.3 Documentation</a></h3>
- <p id="sidebar-topnav">
- <a href="contents.html">Contents</a> |
- <a href="genindex.html">Index</a>
- </p>
- <div id="sidebar-search">
- <form class="search" action="search.html" method="get">
- <label>
- Search terms:
- <input type="text" placeholder="search..." name="q" size="12" />
- </label>
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
- </form>
- </div>
- </div>
- <div id="docs-sidebar">
- <div id="sidebar-banner">
-
- </div>
- <div id="docs-sidebar-inner">
-
- <h3>
- <a href="index.html" title="SQLAlchemy 1.3 Documentation">SQLAlchemy 1.3 Documentation</a>
- </h3>
- <ul>
- <li class="selected"><span class="link-container"><strong>Overview</strong><a class="paramlink headerlink reference internal" href="#">¶</a></span><ul>
- <li><span class="link-container"><a class="reference external" href="#documentation-overview">Documentation Overview</a></span></li>
- <li><span class="link-container"><a class="reference external" href="#code-examples">Code Examples</a></span></li>
- <li><span class="link-container"><a class="reference external" href="#installation-guide">Installation Guide</a></span><ul>
- <li><span class="link-container"><a class="reference external" href="#supported-platforms">Supported Platforms</a></span></li>
- <li><span class="link-container"><a class="reference external" href="#supported-installation-methods">Supported Installation Methods</a></span></li>
- <li><span class="link-container"><a class="reference external" href="#install-via-pip">Install via pip</a></span></li>
- <li><span class="link-container"><a class="reference external" href="#installing-using-setup-py">Installing using setup.py</a></span></li>
- <li><span class="link-container"><a class="reference external" href="#installing-the-c-extensions">Installing the C Extensions</a></span></li>
- <li><span class="link-container"><a class="reference external" href="#installing-a-database-api">Installing a Database API</a></span></li>
- <li><span class="link-container"><a class="reference external" href="#checking-the-installed-sqlalchemy-version">Checking the Installed SQLAlchemy Version</a></span></li>
- </ul>
- </li>
- <li><span class="link-container"><a class="reference external" href="#to-1-3-migration">1.2 to 1.3 Migration</a></span></li>
- </ul>
- </li>
- <li><span class="link-container"><a class="reference external" href="orm/index.html">SQLAlchemy ORM</a></span></li>
- <li><span class="link-container"><a class="reference external" href="core/index.html">SQLAlchemy Core</a></span></li>
- <li><span class="link-container"><a class="reference external" href="dialects/index.html">Dialects</a></span></li>
- <li><span class="link-container"><a class="reference external" href="faq/index.html">Frequently Asked Questions</a></span></li>
- <li><span class="link-container"><a class="reference external" href="errors.html">Error Messages</a></span></li>
- <li><span class="link-container"><a class="reference external" href="changelog/index.html">Changes and Migration</a></span></li>
- </ul>
- </div>
- </div>
- </div>
-
- <div id="docs-body" class="withsidebar" >
-
- <div class="section" id="overview">
- <span id="overview-toplevel"></span><span id="id1"></span><h1>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h1>
- <p>The SQLAlchemy SQL Toolkit and Object Relational Mapper
- is a comprehensive set of tools for working with
- databases and Python. It has several distinct areas of
- functionality which can be used individually or combined
- together. Its major components are illustrated below,
- with component dependencies organized into layers:</p>
- <img alt="_images/sqla_arch_small.png" src="_images/sqla_arch_small.png" />
- <p>Above, the two most significant front-facing portions of
- SQLAlchemy are the <strong>Object Relational Mapper</strong> and the
- <strong>SQL Expression Language</strong>. SQL Expressions can be used
- independently of the ORM. When using the ORM, the SQL
- Expression language remains part of the public facing API
- as it is used within object-relational configurations and
- queries.</p>
- <div class="section" id="documentation-overview">
- <span id="doc-overview"></span><h2>Documentation Overview<a class="headerlink" href="#documentation-overview" title="Permalink to this headline">¶</a></h2>
- <p>The documentation is separated into three sections: <a class="reference internal" href="orm/index.html"><span class="std std-ref">SQLAlchemy ORM</span></a>,
- <a class="reference internal" href="core/index.html"><span class="std std-ref">SQLAlchemy Core</span></a>, and <a class="reference internal" href="dialects/index.html"><span class="std std-ref">Dialects</span></a>.</p>
- <p>In <a class="reference internal" href="orm/index.html"><span class="std std-ref">SQLAlchemy ORM</span></a>, the Object Relational Mapper is introduced and fully
- described. New users should begin with the <a class="reference internal" href="orm/tutorial.html"><span class="std std-ref">Object Relational Tutorial</span></a>. If you
- want to work with higher-level SQL which is constructed automatically for you,
- as well as management of Python objects, proceed to this tutorial.</p>
- <p>In <a class="reference internal" href="core/index.html"><span class="std std-ref">SQLAlchemy Core</span></a>, the breadth of SQLAlchemy’s SQL and database
- integration and description services are documented, the core of which is the
- SQL Expression language. The SQL Expression Language is a toolkit all its own,
- independent of the ORM package, which can be used to construct manipulable SQL
- expressions which can be programmatically constructed, modified, and executed,
- returning cursor-like result sets. In contrast to the ORM’s domain-centric
- mode of usage, the expression language provides a schema-centric usage
- paradigm. New users should begin here with <a class="reference internal" href="core/tutorial.html"><span class="std std-ref">SQL Expression Language Tutorial</span></a>.
- SQLAlchemy engine, connection, and pooling services are also described in
- <a class="reference internal" href="core/index.html"><span class="std std-ref">SQLAlchemy Core</span></a>.</p>
- <p>In <a class="reference internal" href="dialects/index.html"><span class="std std-ref">Dialects</span></a>, reference documentation for all provided
- database and DBAPI backends is provided.</p>
- </div>
- <div class="section" id="code-examples">
- <h2>Code Examples<a class="headerlink" href="#code-examples" title="Permalink to this headline">¶</a></h2>
- <p>Working code examples, mostly regarding the ORM, are included in the
- SQLAlchemy distribution. A description of all the included example
- applications is at <a class="reference internal" href="orm/examples.html"><span class="std std-ref">ORM Examples</span></a>.</p>
- <p>There is also a wide variety of examples involving both core SQLAlchemy
- constructs as well as the ORM on the wiki. See
- <a class="reference external" href="http://www.sqlalchemy.org/trac/wiki/UsageRecipes">Theatrum Chemicum</a>.</p>
- </div>
- <div class="section" id="installation-guide">
- <span id="installation"></span><h2>Installation Guide<a class="headerlink" href="#installation-guide" title="Permalink to this headline">¶</a></h2>
- <div class="section" id="supported-platforms">
- <h3>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h3>
- <p>SQLAlchemy has been tested against the following platforms:</p>
- <ul class="simple">
- <li><p>cPython 2.7</p></li>
- <li><p>cPython 3.4 and higher</p></li>
- <li><p><a class="reference external" href="http://pypy.org/">PyPy</a> 2.1 or greater</p></li>
- </ul>
- <div class="versionchanged">
- <p><span class="versionmodified changed">Changed in version 1.2: </span>Python 2.7 is now the minimum Python version supported.</p>
- </div>
- <div class="versionchanged">
- <p><span class="versionmodified changed">Changed in version 1.3: </span>Within the Python 3 series, 3.4 is now the minimum Python 3 version supported.</p>
- </div>
- <p>Platforms that don’t currently have support include Jython and IronPython.
- Jython has been supported in the past and may be supported in future
- releases as well, depending on the state of Jython itself.</p>
- </div>
- <div class="section" id="supported-installation-methods">
- <h3>Supported Installation Methods<a class="headerlink" href="#supported-installation-methods" title="Permalink to this headline">¶</a></h3>
- <p>SQLAlchemy installation is via standard Python methodologies that are
- based on <a class="reference external" href="http://pypi.python.org/pypi/setuptools/">setuptools</a>, either
- by referring to <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> directly or by using
- <a class="reference external" href="http://pypi.python.org/pypi/pip/">pip</a> or other setuptools-compatible
- approaches.</p>
- <div class="versionchanged">
- <p><span class="versionmodified changed">Changed in version 1.1: </span>setuptools is now required by the setup.py file;
- plain distutils installs are no longer supported.</p>
- </div>
- </div>
- <div class="section" id="install-via-pip">
- <h3>Install via pip<a class="headerlink" href="#install-via-pip" title="Permalink to this headline">¶</a></h3>
- <p>When <code class="docutils literal notranslate"><span class="pre">pip</span></code> is available, the distribution can be
- downloaded from PyPI and installed in one step:</p>
- <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">SQLAlchemy</span></pre></div>
- </div>
- <p>This command will download the latest <strong>released</strong> version of SQLAlchemy from the <a class="reference external" href="http://pypi.python.org/pypi/SQLAlchemy">Python
- Cheese Shop</a> and install it to your system.</p>
- <p>In order to install the latest <strong>prerelease</strong> version, such as <code class="docutils literal notranslate"><span class="pre">1.3.0b1</span></code>,
- pip requires that the <code class="docutils literal notranslate"><span class="pre">--pre</span></code> flag be used:</p>
- <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">pre</span> <span class="n">SQLAlchemy</span></pre></div>
- </div>
- <p>Where above, if the most recent version is a prerelease, it will be installed
- instead of the latest released version.</p>
- </div>
- <div class="section" id="installing-using-setup-py">
- <h3>Installing using setup.py<a class="headerlink" href="#installing-using-setup-py" title="Permalink to this headline">¶</a></h3>
- <p>Otherwise, you can install from the distribution using the <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> script:</p>
- <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span></pre></div>
- </div>
- </div>
- <div class="section" id="installing-the-c-extensions">
- <span id="c-extensions"></span><h3>Installing the C Extensions<a class="headerlink" href="#installing-the-c-extensions" title="Permalink to this headline">¶</a></h3>
- <p>SQLAlchemy includes C extensions which provide an extra speed boost for
- dealing with result sets. The extensions are supported on both the 2.xx
- and 3.xx series of cPython.</p>
- <p><code class="docutils literal notranslate"><span class="pre">setup.py</span></code> will automatically build the extensions if an appropriate platform is
- detected. If the build of the C extensions fails due to a missing compiler or
- other issue, the setup process will output a warning message and re-run the
- build without the C extensions upon completion, reporting final status.</p>
- <p>To run the build/install without even attempting to compile the C extensions,
- the <code class="docutils literal notranslate"><span class="pre">DISABLE_SQLALCHEMY_CEXT</span></code> environment variable may be specified. The
- use case for this is either for special testing circumstances, or in the rare
- case of compatibility/build issues not overcome by the usual “rebuild”
- mechanism:</p>
- <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">DISABLE_SQLALCHEMY_CEXT</span><span class="o">=</span><span class="mi">1</span><span class="p">;</span> <span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span></pre></div>
- </div>
- <div class="versionchanged">
- <p><span class="versionmodified changed">Changed in version 1.1: </span>The legacy <code class="docutils literal notranslate"><span class="pre">--without-cextensions</span></code> flag has been
- removed from the installer as it relies on deprecated features of
- setuptools.</p>
- </div>
- </div>
- <div class="section" id="installing-a-database-api">
- <h3>Installing a Database API<a class="headerlink" href="#installing-a-database-api" title="Permalink to this headline">¶</a></h3>
- <p>SQLAlchemy is designed to operate with a <a class="reference internal" href="glossary.html#term-DBAPI"><span class="xref std std-term">DBAPI</span></a> implementation built for a
- particular database, and includes support for the most popular databases.
- The individual database sections in <a class="reference internal" href="dialects/index.html"><span class="doc">Dialects</span></a> enumerate
- the available DBAPIs for each database, including external links.</p>
- </div>
- <div class="section" id="checking-the-installed-sqlalchemy-version">
- <h3>Checking the Installed SQLAlchemy Version<a class="headerlink" href="#checking-the-installed-sqlalchemy-version" title="Permalink to this headline">¶</a></h3>
- <p>This documentation covers SQLAlchemy version 1.3. If you’re working on a
- system that already has SQLAlchemy installed, check the version from your
- Python prompt like this:</p>
- <div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="o">>>></span> <span class="kn">import</span> <span class="nn">sqlalchemy</span>
- <span class="o">>>></span> <span class="n">sqlalchemy</span><span class="o">.</span><span class="n">__version__</span>
- <span class="mf">1.3</span><span class="o">.</span><span class="mi">0</span></pre></div>
- </div>
- </div>
- </div>
- <div class="section" id="to-1-3-migration">
- <span id="migration"></span><h2>1.2 to 1.3 Migration<a class="headerlink" href="#to-1-3-migration" title="Permalink to this headline">¶</a></h2>
- <p>Notes on what’s changed from 1.2 to 1.3 is available here at <a class="reference internal" href="changelog/migration_13.html"><span class="doc">What’s New in SQLAlchemy 1.3?</span></a>.</p>
- </div>
- </div>
- </div>
- </div>
- <div id="docs-bottom-navigation" class="docs-navigation-links, withsidebar">
- Previous:
- <a href="contents.html" title="previous chapter">Table of Contents</a>
- Next:
- <a href="orm/index.html" title="next chapter">SQLAlchemy ORM</a>
- <div id="docs-copyright">
- © <a href="copyright.html">Copyright</a> 2007-2020, the SQLAlchemy authors and contributors.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 3.0.3.
- </div>
- </div>
- </div>
-
-
- <script type="text/javascript">
- var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
- VERSION: '1.3.17',
- COLLAPSE_MODINDEX: false,
- FILE_SUFFIX: '.html'
- };
- </script>
- <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
- <!-- begin iterate through sphinx environment script_files -->
- <script type="text/javascript" src="_static/jquery.js"></script>
- <script type="text/javascript" src="_static/underscore.js"></script>
- <script type="text/javascript" src="_static/doctools.js"></script>
- <script type="text/javascript" src="_static/language_data.js"></script>
- <!-- end iterate through sphinx environment script_files -->
- <script type="text/javascript" src="_static/detectmobile.js"></script>
- <script type="text/javascript" src="_static/init.js"></script>
- </body>
- </html>
|