<!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>
PostgreSQL
—
SQLAlchemy 1.2 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.2 Documentation" href="../index.html" />
<link rel="up" title="Dialects" href="index.html" />
<link rel="next" title="MySQL" href="mysql.html" />
<link rel="prev" title="Dialects" href="index.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.2.19</span>
| Release Date: April 15, 2019
</div>
<h1>SQLAlchemy 1.2 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.2 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="Dialects">Dialects</a>
</h3>
<ul>
<li class="selected"><span class="link-container"><strong>PostgreSQL</strong><a class="paramlink headerlink reference internal" href="#">¶</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql">Support for the PostgreSQL database.</a></span></li>
<li><span class="link-container"><a class="reference external" href="#sequences-serial-identity">Sequences/SERIAL/IDENTITY</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#postgresql-10-identity-columns">Postgresql 10 IDENTITY columns</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#transaction-isolation-level">Transaction Isolation Level</a></span></li>
<li><span class="link-container"><a class="reference external" href="#remote-schema-table-introspection-and-postgresql-search-path">Remote-Schema Table Introspection and PostgreSQL search_path</a></span></li>
<li><span class="link-container"><a class="reference external" href="#insert-update-returning">INSERT/UPDATE…RETURNING</a></span></li>
<li><span class="link-container"><a class="reference external" href="#insert-on-conflict-upsert">INSERT…ON CONFLICT (Upsert)</a></span></li>
<li><span class="link-container"><a class="reference external" href="#full-text-search">Full Text Search</a></span></li>
<li><span class="link-container"><a class="reference external" href="#from-only">FROM ONLY …</a></span></li>
<li><span class="link-container"><a class="reference external" href="#postgresql-specific-index-options">PostgreSQL-Specific Index Options</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#partial-indexes">Partial Indexes</a></span></li>
<li><span class="link-container"><a class="reference external" href="#operator-classes">Operator Classes</a></span></li>
<li><span class="link-container"><a class="reference external" href="#index-types">Index Types</a></span></li>
<li><span class="link-container"><a class="reference external" href="#index-storage-parameters">Index Storage Parameters</a></span></li>
<li><span class="link-container"><a class="reference external" href="#indexes-with-concurrently">Indexes with CONCURRENTLY</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#postgresql-index-reflection">PostgreSQL Index Reflection</a></span></li>
<li><span class="link-container"><a class="reference external" href="#special-reflection-options">Special Reflection Options</a></span></li>
<li><span class="link-container"><a class="reference external" href="#postgresql-table-options">PostgreSQL Table Options</a></span></li>
<li><span class="link-container"><a class="reference external" href="#array-types">ARRAY Types</a></span></li>
<li><span class="link-container"><a class="reference external" href="#json-types">JSON Types</a></span></li>
<li><span class="link-container"><a class="reference external" href="#hstore-type">HSTORE Type</a></span></li>
<li><span class="link-container"><a class="reference external" href="#enum-types">ENUM Types</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#using-enum-with-array">Using ENUM with ARRAY</a></span></li>
<li><span class="link-container"><a class="reference external" href="#using-json-jsonb-with-array">Using JSON/JSONB with ARRAY</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#postgresql-data-types">PostgreSQL Data Types</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#range-types">Range Types</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#postgresql-constraint-types">PostgreSQL Constraint Types</a></span></li>
<li><span class="link-container"><a class="reference external" href="#postgresql-dml-constructs">PostgreSQL DML Constructs</a></span></li>
<li><span class="link-container"><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.psycopg2">psycopg2</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-psycopg2-url">DBAPI</a></span></li>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-psycopg2-connect">Connecting</a></span></li>
<li><span class="link-container"><a class="reference external" href="#psycopg2-connect-arguments">psycopg2 Connect Arguments</a></span></li>
<li><span class="link-container"><a class="reference external" href="#unix-domain-connections">Unix Domain Connections</a></span></li>
<li><span class="link-container"><a class="reference external" href="#per-statement-connection-execution-options">Per-Statement/Connection Execution Options</a></span></li>
<li><span class="link-container"><a class="reference external" href="#psycopg2-batch-mode-fast-execution">Psycopg2 Batch Mode (Fast Execution)</a></span></li>
<li><span class="link-container"><a class="reference external" href="#unicode-with-psycopg2">Unicode with Psycopg2</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#disabling-native-unicode">Disabling Native Unicode</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#bound-parameter-styles">Bound Parameter Styles</a></span></li>
<li><span class="link-container"><a class="reference external" href="#transactions">Transactions</a></span></li>
<li><span class="link-container"><a class="reference external" href="#psycopg2-transaction-isolation-level">Psycopg2 Transaction Isolation Level</a></span></li>
<li><span class="link-container"><a class="reference external" href="#notice-logging">NOTICE logging</a></span></li>
<li><span class="link-container"><a class="reference external" href="#psycopg2-hstore">HSTORE type</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.pg8000">pg8000</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-pg8000-url">DBAPI</a></span></li>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-pg8000-connect">Connecting</a></span></li>
<li><span class="link-container"><a class="reference external" href="#unicode">Unicode</a></span></li>
<li><span class="link-container"><a class="reference external" href="#pg8000-transaction-isolation-level">pg8000 Transaction Isolation Level</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.psycopg2cffi">psycopg2cffi</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-psycopg2cffi-url">DBAPI</a></span></li>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-psycopg2cffi-connect">Connecting</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.pypostgresql">py-postgresql</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-pypostgresql-url">DBAPI</a></span></li>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-pypostgresql-connect">Connecting</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.pygresql">pygresql</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-pygresql-url">DBAPI</a></span></li>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-pygresql-connect">Connecting</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.zxjdbc">zxjdbc</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-zxjdbc-url">DBAPI</a></span></li>
<li><span class="link-container"><a class="reference external" href="#dialect-postgresql-zxjdbc-connect">Connecting</a></span></li>
</ul>
</li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="mysql.html">MySQL</a></span></li>
<li><span class="link-container"><a class="reference external" href="sqlite.html">SQLite</a></span></li>
<li><span class="link-container"><a class="reference external" href="oracle.html">Oracle</a></span></li>
<li><span class="link-container"><a class="reference external" href="mssql.html">Microsoft SQL Server</a></span></li>
<li><span class="link-container"><a class="reference external" href="firebird.html">Firebird</a></span></li>
<li><span class="link-container"><a class="reference external" href="sybase.html">Sybase</a></span></li>
</ul>
</div>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="module-sqlalchemy.dialects.postgresql.base">
<span id="postgresql"></span><span id="postgresql-toplevel"></span><h1>PostgreSQL<a class="headerlink" href="#module-sqlalchemy.dialects.postgresql.base" title="Permalink to this headline">¶</a></h1>
<div class="section" id="dialect-postgresql">
<p>Support for the PostgreSQL database.</p>
<h2>DBAPI Support<a class="headerlink" href="#dialect-postgresql" title="Permalink to this headline">¶</a></h2>
<p>The following dialect/DBAPI options are available. Please refer to individual DBAPI sections for connect information.<ul class="simple">
<li><p><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.psycopg2">psycopg2</a></p></li>
<li><p><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.pg8000">pg8000</a></p></li>
<li><p><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.psycopg2cffi">psycopg2cffi</a></p></li>
<li><p><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.pypostgresql">py-postgresql</a></p></li>
<li><p><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.pygresql">pygresql</a></p></li>
<li><p><a class="reference external" href="#module-sqlalchemy.dialects.postgresql.zxjdbc">zxJDBC for Jython</a></p></li>
</ul>
</p>
</div>
<div class="section" id="sequences-serial-identity">
<span id="postgresql-sequences"></span><h2>Sequences/SERIAL/IDENTITY<a class="headerlink" href="#sequences-serial-identity" title="Permalink to this headline">¶</a></h2>
<p>PostgreSQL supports sequences, and SQLAlchemy uses these as the default means
of creating new primary key values for integer-based primary key columns. When
creating tables, SQLAlchemy will issue the <code class="docutils literal notranslate"><span class="pre">SERIAL</span></code> datatype for
integer-based primary key columns, which generates a sequence and server side
default corresponding to the column.</p>
<p>To specify a specific named sequence to be used for primary key generation,
use the <a class="reference internal" href="../core/defaults.html#sqlalchemy.schema.Sequence" title="sqlalchemy.schema.Sequence"><code class="xref py py-func docutils literal notranslate"><span class="pre">Sequence()</span></code></a> construct:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s1">'sometable'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">Sequence</span><span class="p">(</span><span class="s1">'some_id_seq'</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>When SQLAlchemy issues a single INSERT statement, to fulfill the contract of
having the “last insert identifier” available, a RETURNING clause is added to
the INSERT statement which specifies the primary key columns should be
returned after the statement completes. The RETURNING functionality only takes
place if PostgreSQL 8.2 or later is in use. As a fallback approach, the
sequence, whether specified explicitly or implicitly via <code class="docutils literal notranslate"><span class="pre">SERIAL</span></code>, is
executed independently beforehand, the returned value to be used in the
subsequent insert. Note that when an
<a class="reference internal" href="../core/dml.html#sqlalchemy.sql.expression.insert" title="sqlalchemy.sql.expression.insert"><code class="xref py py-func docutils literal notranslate"><span class="pre">insert()</span></code></a> construct is executed using
“executemany” semantics, the “last inserted identifier” functionality does not
apply; no RETURNING clause is emitted nor is the sequence pre-executed in this
case.</p>
<p>To force the usage of RETURNING by default off, specify the flag
<code class="docutils literal notranslate"><span class="pre">implicit_returning=False</span></code> to <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a>.</p>
<div class="section" id="postgresql-10-identity-columns">
<h3>Postgresql 10 IDENTITY columns<a class="headerlink" href="#postgresql-10-identity-columns" title="Permalink to this headline">¶</a></h3>
<p>Postgresql 10 has a new IDENTITY feature that supersedes the use of SERIAL.
Built-in support for rendering of IDENTITY is not available yet, however the
following compilation hook may be used to replace occurrences of SERIAL with
IDENTITY:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.schema</span> <span class="k">import</span> <span class="n">CreateColumn</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.ext.compiler</span> <span class="k">import</span> <span class="n">compiles</span>
<span class="nd">@compiles</span><span class="p">(</span><span class="n">CreateColumn</span><span class="p">,</span> <span class="s1">'postgresql'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">use_identity</span><span class="p">(</span><span class="n">element</span><span class="p">,</span> <span class="n">compiler</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="n">text</span> <span class="o">=</span> <span class="n">compiler</span><span class="o">.</span><span class="n">visit_create_column</span><span class="p">(</span><span class="n">element</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
<span class="n">text</span> <span class="o">=</span> <span class="n">text</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s2">"SERIAL"</span><span class="p">,</span> <span class="s2">"INT GENERATED BY DEFAULT AS IDENTITY"</span><span class="p">)</span>
<span class="k">return</span> <span class="n">text</span></pre></div>
</div>
<p>Using the above, a table such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span>
<span class="s1">'t'</span><span class="p">,</span> <span class="n">m</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'data'</span><span class="p">,</span> <span class="n">String</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Will generate on the backing database as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">CREATE</span> <span class="n">TABLE</span> <span class="n">t</span> <span class="p">(</span>
<span class="nb">id</span> <span class="n">INT</span> <span class="n">GENERATED</span> <span class="n">BY</span> <span class="n">DEFAULT</span> <span class="n">AS</span> <span class="n">IDENTITY</span> <span class="n">NOT</span> <span class="n">NULL</span><span class="p">,</span>
<span class="n">data</span> <span class="n">VARCHAR</span><span class="p">,</span>
<span class="n">PRIMARY</span> <span class="n">KEY</span> <span class="p">(</span><span class="nb">id</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</div>
</div>
<div class="section" id="transaction-isolation-level">
<span id="postgresql-isolation-level"></span><h2>Transaction Isolation Level<a class="headerlink" href="#transaction-isolation-level" title="Permalink to this headline">¶</a></h2>
<p>All PostgreSQL dialects support setting of transaction isolation level
both via a dialect-specific parameter
<a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine.params.isolation_level" title="sqlalchemy.create_engine"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">create_engine.isolation_level</span></code></a> accepted by <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a>,
as well as the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection.execution_options.params.isolation_level" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Connection.execution_options.isolation_level</span></code></a>
argument as passed to <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a>.
When using a non-psycopg2 dialect, this feature works by issuing the command
<code class="docutils literal notranslate"><span class="pre">SET</span> <span class="pre">SESSION</span> <span class="pre">CHARACTERISTICS</span> <span class="pre">AS</span> <span class="pre">TRANSACTION</span> <span class="pre">ISOLATION</span> <span class="pre">LEVEL</span> <span class="pre"><level></span></code> for
each new connection. For the special AUTOCOMMIT isolation level,
DBAPI-specific techniques are used.</p>
<p>To set isolation level using <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span>
<span class="s2">"postgresql+pg8000://scott:tiger@localhost/test"</span><span class="p">,</span>
<span class="n">isolation_level</span><span class="o">=</span><span class="s2">"READ UNCOMMITTED"</span>
<span class="p">)</span></pre></div>
</div>
<p>To set using per-connection execution options:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">connection</span> <span class="o">=</span> <span class="n">engine</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span>
<span class="n">connection</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execution_options</span><span class="p">(</span>
<span class="n">isolation_level</span><span class="o">=</span><span class="s2">"READ COMMITTED"</span>
<span class="p">)</span></pre></div>
</div>
<p>Valid values for <code class="docutils literal notranslate"><span class="pre">isolation_level</span></code> include:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">READ</span> <span class="pre">COMMITTED</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">READ</span> <span class="pre">UNCOMMITTED</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">REPEATABLE</span> <span class="pre">READ</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">SERIALIZABLE</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">AUTOCOMMIT</span></code> - on psycopg2 / pg8000 only</p></li>
</ul>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#psycopg2-isolation-level"><span class="std std-ref">Psycopg2 Transaction Isolation Level</span></a></p>
<p><a class="reference internal" href="#pg8000-isolation-level"><span class="std std-ref">pg8000 Transaction Isolation Level</span></a></p>
</div>
</div>
<div class="section" id="remote-schema-table-introspection-and-postgresql-search-path">
<span id="postgresql-schema-reflection"></span><h2>Remote-Schema Table Introspection and PostgreSQL search_path<a class="headerlink" href="#remote-schema-table-introspection-and-postgresql-search-path" title="Permalink to this headline">¶</a></h2>
<p><strong>TL;DR;</strong>: keep the <code class="docutils literal notranslate"><span class="pre">search_path</span></code> variable set to its default of <code class="docutils literal notranslate"><span class="pre">public</span></code>,
name schemas <strong>other</strong> than <code class="docutils literal notranslate"><span class="pre">public</span></code> explicitly within <code class="docutils literal notranslate"><span class="pre">Table</span></code> definitions.</p>
<p>The PostgreSQL dialect can reflect tables from any schema. The
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table.params.schema" title="sqlalchemy.schema.Table"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Table.schema</span></code></a> argument, or alternatively the
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.MetaData.reflect.params.schema" title="sqlalchemy.schema.MetaData.reflect"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">MetaData.reflect.schema</span></code></a> argument determines which schema will
be searched for the table or tables. The reflected <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> objects
will in all cases retain this <code class="docutils literal notranslate"><span class="pre">.schema</span></code> attribute as was specified.
However, with regards to tables which these <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> objects refer to
via foreign key constraint, a decision must be made as to how the <code class="docutils literal notranslate"><span class="pre">.schema</span></code>
is represented in those remote tables, in the case where that remote
schema name is also a member of the current
<a class="reference external" href="http://www.postgresql.org/docs/current/static/ddl-schemas.html#DDL-SCHEMAS-PATH">PostgreSQL search path</a>.</p>
<p>By default, the PostgreSQL dialect mimics the behavior encouraged by
PostgreSQL’s own <code class="docutils literal notranslate"><span class="pre">pg_get_constraintdef()</span></code> builtin procedure. This function
returns a sample definition for a particular foreign key constraint,
omitting the referenced schema name from that definition when the name is
also in the PostgreSQL schema search path. The interaction below
illustrates this behavior:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">=></span> <span class="n">CREATE</span> <span class="n">TABLE</span> <span class="n">test_schema</span><span class="o">.</span><span class="n">referred</span><span class="p">(</span><span class="nb">id</span> <span class="n">INTEGER</span> <span class="n">PRIMARY</span> <span class="n">KEY</span><span class="p">);</span>
<span class="n">CREATE</span> <span class="n">TABLE</span>
<span class="n">test</span><span class="o">=></span> <span class="n">CREATE</span> <span class="n">TABLE</span> <span class="n">referring</span><span class="p">(</span>
<span class="n">test</span><span class="p">(</span><span class="o">></span> <span class="nb">id</span> <span class="n">INTEGER</span> <span class="n">PRIMARY</span> <span class="n">KEY</span><span class="p">,</span>
<span class="n">test</span><span class="p">(</span><span class="o">></span> <span class="n">referred_id</span> <span class="n">INTEGER</span> <span class="n">REFERENCES</span> <span class="n">test_schema</span><span class="o">.</span><span class="n">referred</span><span class="p">(</span><span class="nb">id</span><span class="p">));</span>
<span class="n">CREATE</span> <span class="n">TABLE</span>
<span class="n">test</span><span class="o">=></span> <span class="n">SET</span> <span class="n">search_path</span> <span class="n">TO</span> <span class="n">public</span><span class="p">,</span> <span class="n">test_schema</span><span class="p">;</span>
<span class="n">test</span><span class="o">=></span> <span class="n">SELECT</span> <span class="n">pg_catalog</span><span class="o">.</span><span class="n">pg_get_constraintdef</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">oid</span><span class="p">,</span> <span class="n">true</span><span class="p">)</span> <span class="n">FROM</span>
<span class="n">test</span><span class="o">-></span> <span class="n">pg_catalog</span><span class="o">.</span><span class="n">pg_class</span> <span class="n">c</span> <span class="n">JOIN</span> <span class="n">pg_catalog</span><span class="o">.</span><span class="n">pg_namespace</span> <span class="n">n</span>
<span class="n">test</span><span class="o">-></span> <span class="n">ON</span> <span class="n">n</span><span class="o">.</span><span class="n">oid</span> <span class="o">=</span> <span class="n">c</span><span class="o">.</span><span class="n">relnamespace</span>
<span class="n">test</span><span class="o">-></span> <span class="n">JOIN</span> <span class="n">pg_catalog</span><span class="o">.</span><span class="n">pg_constraint</span> <span class="n">r</span> <span class="n">ON</span> <span class="n">c</span><span class="o">.</span><span class="n">oid</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">conrelid</span>
<span class="n">test</span><span class="o">-></span> <span class="n">WHERE</span> <span class="n">c</span><span class="o">.</span><span class="n">relname</span><span class="o">=</span><span class="s1">'referring'</span> <span class="n">AND</span> <span class="n">r</span><span class="o">.</span><span class="n">contype</span> <span class="o">=</span> <span class="s1">'f'</span>
<span class="n">test</span><span class="o">-></span> <span class="p">;</span>
<span class="n">pg_get_constraintdef</span>
<span class="o">---------------------------------------------------</span>
<span class="n">FOREIGN</span> <span class="n">KEY</span> <span class="p">(</span><span class="n">referred_id</span><span class="p">)</span> <span class="n">REFERENCES</span> <span class="n">referred</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
<span class="p">(</span><span class="mi">1</span> <span class="n">row</span><span class="p">)</span></pre></div>
</div>
<p>Above, we created a table <code class="docutils literal notranslate"><span class="pre">referred</span></code> as a member of the remote schema
<code class="docutils literal notranslate"><span class="pre">test_schema</span></code>, however when we added <code class="docutils literal notranslate"><span class="pre">test_schema</span></code> to the
PG <code class="docutils literal notranslate"><span class="pre">search_path</span></code> and then asked <code class="docutils literal notranslate"><span class="pre">pg_get_constraintdef()</span></code> for the
<code class="docutils literal notranslate"><span class="pre">FOREIGN</span> <span class="pre">KEY</span></code> syntax, <code class="docutils literal notranslate"><span class="pre">test_schema</span></code> was not included in the output of
the function.</p>
<p>On the other hand, if we set the search path back to the typical default
of <code class="docutils literal notranslate"><span class="pre">public</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">=></span> <span class="n">SET</span> <span class="n">search_path</span> <span class="n">TO</span> <span class="n">public</span><span class="p">;</span>
<span class="n">SET</span></pre></div>
</div>
<p>The same query against <code class="docutils literal notranslate"><span class="pre">pg_get_constraintdef()</span></code> now returns the fully
schema-qualified name for us:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">=></span> <span class="n">SELECT</span> <span class="n">pg_catalog</span><span class="o">.</span><span class="n">pg_get_constraintdef</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">oid</span><span class="p">,</span> <span class="n">true</span><span class="p">)</span> <span class="n">FROM</span>
<span class="n">test</span><span class="o">-></span> <span class="n">pg_catalog</span><span class="o">.</span><span class="n">pg_class</span> <span class="n">c</span> <span class="n">JOIN</span> <span class="n">pg_catalog</span><span class="o">.</span><span class="n">pg_namespace</span> <span class="n">n</span>
<span class="n">test</span><span class="o">-></span> <span class="n">ON</span> <span class="n">n</span><span class="o">.</span><span class="n">oid</span> <span class="o">=</span> <span class="n">c</span><span class="o">.</span><span class="n">relnamespace</span>
<span class="n">test</span><span class="o">-></span> <span class="n">JOIN</span> <span class="n">pg_catalog</span><span class="o">.</span><span class="n">pg_constraint</span> <span class="n">r</span> <span class="n">ON</span> <span class="n">c</span><span class="o">.</span><span class="n">oid</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">conrelid</span>
<span class="n">test</span><span class="o">-></span> <span class="n">WHERE</span> <span class="n">c</span><span class="o">.</span><span class="n">relname</span><span class="o">=</span><span class="s1">'referring'</span> <span class="n">AND</span> <span class="n">r</span><span class="o">.</span><span class="n">contype</span> <span class="o">=</span> <span class="s1">'f'</span><span class="p">;</span>
<span class="n">pg_get_constraintdef</span>
<span class="o">---------------------------------------------------------------</span>
<span class="n">FOREIGN</span> <span class="n">KEY</span> <span class="p">(</span><span class="n">referred_id</span><span class="p">)</span> <span class="n">REFERENCES</span> <span class="n">test_schema</span><span class="o">.</span><span class="n">referred</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
<span class="p">(</span><span class="mi">1</span> <span class="n">row</span><span class="p">)</span></pre></div>
</div>
<p>SQLAlchemy will by default use the return value of <code class="docutils literal notranslate"><span class="pre">pg_get_constraintdef()</span></code>
in order to determine the remote schema name. That is, if our <code class="docutils literal notranslate"><span class="pre">search_path</span></code>
were set to include <code class="docutils literal notranslate"><span class="pre">test_schema</span></code>, and we invoked a table
reflection process as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">Table</span><span class="p">,</span> <span class="n">MetaData</span><span class="p">,</span> <span class="n">create_engine</span>
<span class="gp">>>> </span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql://scott:tiger@localhost/test"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"SET search_path TO test_schema, public"</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">meta</span> <span class="o">=</span> <span class="n">MetaData</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">referring</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'referring'</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">autoload</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">autoload_with</span><span class="o">=</span><span class="n">conn</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go"><sqlalchemy.engine.result.ResultProxy object at 0x101612ed0></span></pre></div>
</div>
<p>The above process would deliver to the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.MetaData.tables" title="sqlalchemy.schema.MetaData.tables"><code class="xref py py-attr docutils literal notranslate"><span class="pre">MetaData.tables</span></code></a> collection
<code class="docutils literal notranslate"><span class="pre">referred</span></code> table named <strong>without</strong> the schema:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">meta</span><span class="o">.</span><span class="n">tables</span><span class="p">[</span><span class="s1">'referred'</span><span class="p">]</span><span class="o">.</span><span class="n">schema</span> <span class="ow">is</span> <span class="kc">None</span>
<span class="go">True</span></pre></div>
</div>
<p>To alter the behavior of reflection such that the referred schema is
maintained regardless of the <code class="docutils literal notranslate"><span class="pre">search_path</span></code> setting, use the
<code class="docutils literal notranslate"><span class="pre">postgresql_ignore_search_path</span></code> option, which can be specified as a
dialect-specific argument to both <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> as well as
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.MetaData.reflect" title="sqlalchemy.schema.MetaData.reflect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">MetaData.reflect()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"SET search_path TO test_schema, public"</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">meta</span> <span class="o">=</span> <span class="n">MetaData</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">referring</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'referring'</span><span class="p">,</span> <span class="n">meta</span><span class="p">,</span> <span class="n">autoload</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">autoload_with</span><span class="o">=</span><span class="n">conn</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">postgresql_ignore_search_path</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go"><sqlalchemy.engine.result.ResultProxy object at 0x1016126d0></span></pre></div>
</div>
<p>We will now have <code class="docutils literal notranslate"><span class="pre">test_schema.referred</span></code> stored as schema-qualified:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">meta</span><span class="o">.</span><span class="n">tables</span><span class="p">[</span><span class="s1">'test_schema.referred'</span><span class="p">]</span><span class="o">.</span><span class="n">schema</span>
<span class="go">'test_schema'</span></pre></div>
</div>
<div class="sidebar">
<p class="sidebar-title">Best Practices for PostgreSQL Schema reflection</p>
<p>The description of PostgreSQL schema reflection behavior is complex, and
is the product of many years of dealing with widely varied use cases and
user preferences. But in fact, there’s no need to understand any of it if
you just stick to the simplest use pattern: leave the <code class="docutils literal notranslate"><span class="pre">search_path</span></code> set
to its default of <code class="docutils literal notranslate"><span class="pre">public</span></code> only, never refer to the name <code class="docutils literal notranslate"><span class="pre">public</span></code> as
an explicit schema name otherwise, and refer to all other schema names
explicitly when building up a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> object. The options
described here are only for those users who can’t, or prefer not to, stay
within these guidelines.</p>
</div>
<p>Note that <strong>in all cases</strong>, the “default” schema is always reflected as
<code class="docutils literal notranslate"><span class="pre">None</span></code>. The “default” schema on PostgreSQL is that which is returned by the
PostgreSQL <code class="docutils literal notranslate"><span class="pre">current_schema()</span></code> function. On a typical PostgreSQL
installation, this is the name <code class="docutils literal notranslate"><span class="pre">public</span></code>. So a table that refers to another
which is in the <code class="docutils literal notranslate"><span class="pre">public</span></code> (i.e. default) schema will always have the
<code class="docutils literal notranslate"><span class="pre">.schema</span></code> attribute set to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.2: </span>Added the <code class="docutils literal notranslate"><span class="pre">postgresql_ignore_search_path</span></code>
dialect-level option accepted by <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> and
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.MetaData.reflect" title="sqlalchemy.schema.MetaData.reflect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">MetaData.reflect()</span></code></a>.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference external" href="http://www.postgresql.org/docs/9.0/static/ddl-schemas.html#DDL-SCHEMAS-PATH">The Schema Search Path</a>
- on the PostgreSQL website.</p>
</div>
</div>
<div class="section" id="insert-update-returning">
<h2>INSERT/UPDATE…RETURNING<a class="headerlink" href="#insert-update-returning" title="Permalink to this headline">¶</a></h2>
<p>The dialect supports PG 8.2’s <code class="docutils literal notranslate"><span class="pre">INSERT..RETURNING</span></code>, <code class="docutils literal notranslate"><span class="pre">UPDATE..RETURNING</span></code> and
<code class="docutils literal notranslate"><span class="pre">DELETE..RETURNING</span></code> syntaxes. <code class="docutils literal notranslate"><span class="pre">INSERT..RETURNING</span></code> is used by default
for single-row INSERT statements in order to fetch newly generated
primary key identifiers. To specify an explicit <code class="docutils literal notranslate"><span class="pre">RETURNING</span></code> clause,
use the <code class="xref py py-meth docutils literal notranslate"><span class="pre">_UpdateBase.returning()</span></code> method on a per-statement basis:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># INSERT..RETURNING</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">returning</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">col1</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">col2</span><span class="p">)</span><span class="o">.</span>\
<span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foo'</span><span class="p">)</span>
<span class="nb">print</span> <span class="n">result</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span>
<span class="c1"># UPDATE..RETURNING</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span><span class="n">returning</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">col1</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">col2</span><span class="p">)</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="o">==</span><span class="s1">'foo'</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span>
<span class="nb">print</span> <span class="n">result</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span>
<span class="c1"># DELETE..RETURNING</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span><span class="o">.</span><span class="n">returning</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">col1</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">col2</span><span class="p">)</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="o">==</span><span class="s1">'foo'</span><span class="p">)</span>
<span class="nb">print</span> <span class="n">result</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span></pre></div>
</div>
</div>
<div class="section" id="insert-on-conflict-upsert">
<span id="postgresql-insert-on-conflict"></span><h2>INSERT…ON CONFLICT (Upsert)<a class="headerlink" href="#insert-on-conflict-upsert" title="Permalink to this headline">¶</a></h2>
<p>Starting with version 9.5, PostgreSQL allows “upserts” (update or insert) of
rows into a table via the <code class="docutils literal notranslate"><span class="pre">ON</span> <span class="pre">CONFLICT</span></code> clause of the <code class="docutils literal notranslate"><span class="pre">INSERT</span></code> statement. A
candidate row will only be inserted if that row does not violate any unique
constraints. In the case of a unique constraint violation, a secondary action
can occur which can be either “DO UPDATE”, indicating that the data in the
target row should be updated, or “DO NOTHING”, which indicates to silently skip
this row.</p>
<p>Conflicts are determined using existing unique constraints and indexes. These
constraints may be identified either using their name as stated in DDL,
or they may be <em>inferred</em> by stating the columns and conditions that comprise
the indexes.</p>
<p>SQLAlchemy provides <code class="docutils literal notranslate"><span class="pre">ON</span> <span class="pre">CONFLICT</span></code> support via the PostgreSQL-specific
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.insert" title="sqlalchemy.dialects.postgresql.dml.insert"><code class="xref py py-func docutils literal notranslate"><span class="pre">postgresql.dml.insert()</span></code></a> function, which provides
the generative methods <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">on_conflict_do_update()</span></code></a>
and <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">on_conflict_do_nothing()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">insert</span>
<span class="n">insert_stmt</span> <span class="o">=</span> <span class="n">insert</span><span class="p">(</span><span class="n">my_table</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span>
<span class="nb">id</span><span class="o">=</span><span class="s1">'some_existing_id'</span><span class="p">,</span>
<span class="n">data</span><span class="o">=</span><span class="s1">'inserted value'</span><span class="p">)</span>
<span class="n">do_nothing_stmt</span> <span class="o">=</span> <span class="n">insert_stmt</span><span class="o">.</span><span class="n">on_conflict_do_nothing</span><span class="p">(</span>
<span class="n">index_elements</span><span class="o">=</span><span class="p">[</span><span class="s1">'id'</span><span class="p">]</span>
<span class="p">)</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">do_nothing_stmt</span><span class="p">)</span>
<span class="n">do_update_stmt</span> <span class="o">=</span> <span class="n">insert_stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">constraint</span><span class="o">=</span><span class="s1">'pk_my_table'</span><span class="p">,</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">do_update_stmt</span><span class="p">)</span></pre></div>
</div>
<p>Both methods supply the “target” of the conflict using either the
named constraint or by column inference:</p>
<ul>
<li><p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.index_elements" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.index_elements</span></code></a> argument
specifies a sequence containing string column names, <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a>
objects, and/or SQL expression elements, which would identify a unique
index:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">do_update_stmt</span> <span class="o">=</span> <span class="n">insert_stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">index_elements</span><span class="o">=</span><span class="p">[</span><span class="s1">'id'</span><span class="p">],</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">do_update_stmt</span> <span class="o">=</span> <span class="n">insert_stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">index_elements</span><span class="o">=</span><span class="p">[</span><span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">],</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</li>
<li><p>When using <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.index_elements" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.index_elements</span></code></a> to
infer an index, a partial index can be inferred by also specifying the
use the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.index_where" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.index_where</span></code></a> parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">insert</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">insert</span><span class="p">(</span><span class="n">my_table</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">user_email</span><span class="o">=</span><span class="s1">'a@b.com'</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="s1">'inserted data'</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">index_elements</span><span class="o">=</span><span class="p">[</span><span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">user_email</span><span class="p">],</span>
<span class="n">index_where</span><span class="o">=</span><span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">user_email</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'%@gmail.com'</span><span class="p">),</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="n">stmt</span><span class="o">.</span><span class="n">excluded</span><span class="o">.</span><span class="n">data</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">)</span></pre></div>
</div>
</li>
<li><p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.constraint" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.constraint</span></code></a> argument is
used to specify an index directly rather than inferring it. This can be
the name of a UNIQUE constraint, a PRIMARY KEY constraint, or an INDEX:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">do_update_stmt</span> <span class="o">=</span> <span class="n">insert_stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">constraint</span><span class="o">=</span><span class="s1">'my_table_idx_1'</span><span class="p">,</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">do_update_stmt</span> <span class="o">=</span> <span class="n">insert_stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">constraint</span><span class="o">=</span><span class="s1">'my_table_pk'</span><span class="p">,</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</li>
<li><p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.constraint" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.constraint</span></code></a> argument may
also refer to a SQLAlchemy construct representing a constraint,
e.g. <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.UniqueConstraint" title="sqlalchemy.schema.UniqueConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">UniqueConstraint</span></code></a>, <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.PrimaryKeyConstraint" title="sqlalchemy.schema.PrimaryKeyConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">PrimaryKeyConstraint</span></code></a>,
<a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a>, or <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint" title="sqlalchemy.dialects.postgresql.ExcludeConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExcludeConstraint</span></code></a>. In this use,
if the constraint has a name, it is used directly. Otherwise, if the
constraint is unnamed, then inference will be used, where the expressions
and optional WHERE clause of the constraint will be spelled out in the
construct. This use is especially convenient
to refer to the named or unnamed primary key of a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> using the
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table.primary_key" title="sqlalchemy.schema.Table.primary_key"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Table.primary_key</span></code></a> attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">do_update_stmt</span> <span class="o">=</span> <span class="n">insert_stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">constraint</span><span class="o">=</span><span class="n">my_table</span><span class="o">.</span><span class="n">primary_key</span><span class="p">,</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">ON</span> <span class="pre">CONFLICT...DO</span> <span class="pre">UPDATE</span></code> is used to perform an update of the already
existing row, using any combination of new values as well as values
from the proposed insertion. These values are specified using the
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.set_" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.set_</span></code></a> parameter. This
parameter accepts a dictionary which consists of direct values
for UPDATE:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">insert</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">insert</span><span class="p">(</span><span class="n">my_table</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s1">'some_id'</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="s1">'inserted value'</span><span class="p">)</span>
<span class="n">do_update_stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">index_elements</span><span class="o">=</span><span class="p">[</span><span class="s1">'id'</span><span class="p">],</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">do_update_stmt</span><span class="p">)</span></pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update()</span></code></a> method does <strong>not</strong> take into
account Python-side default UPDATE values or generation functions, e.g.
e.g. those specified using <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column.params.onupdate" title="sqlalchemy.schema.Column"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Column.onupdate</span></code></a>.
These values will not be exercised for an ON CONFLICT style of UPDATE,
unless they are manually specified in the
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.set_" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.set_</span></code></a> dictionary.</p>
</div>
<p>In order to refer to the proposed insertion row, the special alias
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.excluded" title="sqlalchemy.dialects.postgresql.dml.Insert.excluded"><code class="xref py py-attr docutils literal notranslate"><span class="pre">excluded</span></code></a> is available as an attribute on
the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert" title="sqlalchemy.dialects.postgresql.dml.Insert"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.dml.Insert</span></code></a> object; this object is a
<a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.ColumnCollection" title="sqlalchemy.sql.expression.ColumnCollection"><code class="xref py py-class docutils literal notranslate"><span class="pre">ColumnCollection</span></code></a> which alias contains all columns of the target
table:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">insert</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">insert</span><span class="p">(</span><span class="n">my_table</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span>
<span class="nb">id</span><span class="o">=</span><span class="s1">'some_id'</span><span class="p">,</span>
<span class="n">data</span><span class="o">=</span><span class="s1">'inserted value'</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s1">'jlh'</span><span class="p">)</span>
<span class="n">do_update_stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">index_elements</span><span class="o">=</span><span class="p">[</span><span class="s1">'id'</span><span class="p">],</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">,</span> <span class="n">author</span><span class="o">=</span><span class="n">stmt</span><span class="o">.</span><span class="n">excluded</span><span class="o">.</span><span class="n">author</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">do_update_stmt</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update()</span></code></a> method also accepts
a WHERE clause using the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.where" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.where</span></code></a>
parameter, which will limit those rows which receive an UPDATE:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">insert</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">insert</span><span class="p">(</span><span class="n">my_table</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span>
<span class="nb">id</span><span class="o">=</span><span class="s1">'some_id'</span><span class="p">,</span>
<span class="n">data</span><span class="o">=</span><span class="s1">'inserted value'</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s1">'jlh'</span><span class="p">)</span>
<span class="n">on_update_stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">on_conflict_do_update</span><span class="p">(</span>
<span class="n">index_elements</span><span class="o">=</span><span class="p">[</span><span class="s1">'id'</span><span class="p">],</span>
<span class="n">set_</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s1">'updated value'</span><span class="p">,</span> <span class="n">author</span><span class="o">=</span><span class="n">stmt</span><span class="o">.</span><span class="n">excluded</span><span class="o">.</span><span class="n">author</span><span class="p">)</span>
<span class="n">where</span><span class="o">=</span><span class="p">(</span><span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">status</span> <span class="o">==</span> <span class="mi">2</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">on_update_stmt</span><span class="p">)</span></pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">ON</span> <span class="pre">CONFLICT</span></code> may also be used to skip inserting a row entirely
if any conflict with a unique or exclusion constraint occurs; below
this is illustrated using the
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">on_conflict_do_nothing()</span></code></a> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">insert</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">insert</span><span class="p">(</span><span class="n">my_table</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s1">'some_id'</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="s1">'inserted value'</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">on_conflict_do_nothing</span><span class="p">(</span><span class="n">index_elements</span><span class="o">=</span><span class="p">[</span><span class="s1">'id'</span><span class="p">])</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">)</span></pre></div>
</div>
<p>If <code class="docutils literal notranslate"><span class="pre">DO</span> <span class="pre">NOTHING</span></code> is used without specifying any columns or constraint,
it has the effect of skipping the INSERT for any unique or exclusion
constraint violation which occurs:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">insert</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">insert</span><span class="p">(</span><span class="n">my_table</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s1">'some_id'</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="s1">'inserted value'</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">on_conflict_do_nothing</span><span class="p">()</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1: </span>Added support for PostgreSQL ON CONFLICT clauses</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference external" href="http://www.postgresql.org/docs/current/static/sql-insert.html#SQL-ON-CONFLICT">INSERT .. ON CONFLICT</a>
- in the PostgreSQL documentation.</p>
</div>
</div>
<div class="section" id="full-text-search">
<span id="postgresql-match"></span><h2>Full Text Search<a class="headerlink" href="#full-text-search" title="Permalink to this headline">¶</a></h2>
<p>SQLAlchemy makes available the PostgreSQL <code class="docutils literal notranslate"><span class="pre">@@</span></code> operator via the
<a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.ColumnElement.match" title="sqlalchemy.sql.expression.ColumnElement.match"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ColumnElement.match()</span></code></a> method on any textual column expression.
On a PostgreSQL dialect, an expression like the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">select</span><span class="p">([</span><span class="n">sometable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">text</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s2">"search string"</span><span class="p">)])</span></pre></div>
</div>
<p>will emit to the database:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">text</span> <span class="o">@@</span> <span class="n">to_tsquery</span><span class="p">(</span><span class="s1">'search string'</span><span class="p">)</span> <span class="n">FROM</span> <span class="n">table</span></pre></div>
</div>
<p>The PostgreSQL text search functions such as <code class="docutils literal notranslate"><span class="pre">to_tsquery()</span></code>
and <code class="docutils literal notranslate"><span class="pre">to_tsvector()</span></code> are available
explicitly using the standard <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><code class="xref py py-data docutils literal notranslate"><span class="pre">func</span></code></a> construct. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">select</span><span class="p">([</span>
<span class="n">func</span><span class="o">.</span><span class="n">to_tsvector</span><span class="p">(</span><span class="s1">'fat cats ate rats'</span><span class="p">)</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s1">'cat & rat'</span><span class="p">)</span>
<span class="p">])</span></pre></div>
</div>
<p>Emits the equivalent of:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">to_tsvector</span><span class="p">(</span><span class="s1">'fat cats ate rats'</span><span class="p">)</span> <span class="o">@@</span> <span class="n">to_tsquery</span><span class="p">(</span><span class="s1">'cat & rat'</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.TSVECTOR" title="sqlalchemy.dialects.postgresql.TSVECTOR"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.TSVECTOR</span></code></a> type can provide for explicit CAST:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">TSVECTOR</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">select</span><span class="p">,</span> <span class="n">cast</span>
<span class="n">select</span><span class="p">([</span><span class="n">cast</span><span class="p">(</span><span class="s2">"some text"</span><span class="p">,</span> <span class="n">TSVECTOR</span><span class="p">)])</span></pre></div>
</div>
<p>produces a statement equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">CAST</span><span class="p">(</span><span class="s1">'some text'</span> <span class="n">AS</span> <span class="n">TSVECTOR</span><span class="p">)</span> <span class="n">AS</span> <span class="n">anon_1</span></pre></div>
</div>
<p>Full Text Searches in PostgreSQL are influenced by a combination of: the
PostgresSQL setting of <code class="docutils literal notranslate"><span class="pre">default_text_search_config</span></code>, the <code class="docutils literal notranslate"><span class="pre">regconfig</span></code> used
to build the GIN/GiST indexes, and the <code class="docutils literal notranslate"><span class="pre">regconfig</span></code> optionally passed in
during a query.</p>
<p>When performing a Full Text Search against a column that has a GIN or
GiST index that is already pre-computed (which is common on full text
searches) one may need to explicitly pass in a particular PostgresSQL
<code class="docutils literal notranslate"><span class="pre">regconfig</span></code> value to ensure the query-planner utilizes the index and does
not re-compute the column on demand.</p>
<p>In order to provide for this explicit query planning, or to use different
search strategies, the <code class="docutils literal notranslate"><span class="pre">match</span></code> method accepts a <code class="docutils literal notranslate"><span class="pre">postgresql_regconfig</span></code>
keyword argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">select</span><span class="p">([</span><span class="n">mytable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span>
<span class="n">mytable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">title</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s1">'somestring'</span><span class="p">,</span> <span class="n">postgresql_regconfig</span><span class="o">=</span><span class="s1">'english'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Emits the equivalent of:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">mytable</span><span class="o">.</span><span class="n">id</span> <span class="n">FROM</span> <span class="n">mytable</span>
<span class="n">WHERE</span> <span class="n">mytable</span><span class="o">.</span><span class="n">title</span> <span class="o">@@</span> <span class="n">to_tsquery</span><span class="p">(</span><span class="s1">'english'</span><span class="p">,</span> <span class="s1">'somestring'</span><span class="p">)</span></pre></div>
</div>
<p>One can also specifically pass in a <cite>‘regconfig’</cite> value to the
<code class="docutils literal notranslate"><span class="pre">to_tsvector()</span></code> command as the initial argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">select</span><span class="p">([</span><span class="n">mytable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span>
<span class="n">func</span><span class="o">.</span><span class="n">to_tsvector</span><span class="p">(</span><span class="s1">'english'</span><span class="p">,</span> <span class="n">mytable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">title</span> <span class="p">)</span>\
<span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s1">'somestring'</span><span class="p">,</span> <span class="n">postgresql_regconfig</span><span class="o">=</span><span class="s1">'english'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>produces a statement equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">mytable</span><span class="o">.</span><span class="n">id</span> <span class="n">FROM</span> <span class="n">mytable</span>
<span class="n">WHERE</span> <span class="n">to_tsvector</span><span class="p">(</span><span class="s1">'english'</span><span class="p">,</span> <span class="n">mytable</span><span class="o">.</span><span class="n">title</span><span class="p">)</span> <span class="o">@@</span>
<span class="n">to_tsquery</span><span class="p">(</span><span class="s1">'english'</span><span class="p">,</span> <span class="s1">'somestring'</span><span class="p">)</span></pre></div>
</div>
<p>It is recommended that you use the <code class="docutils literal notranslate"><span class="pre">EXPLAIN</span> <span class="pre">ANALYZE...</span></code> tool from
PostgresSQL to ensure that you are generating queries with SQLAlchemy that
take full advantage of any indexes you may have created for full text search.</p>
</div>
<div class="section" id="from-only">
<h2>FROM ONLY …<a class="headerlink" href="#from-only" title="Permalink to this headline">¶</a></h2>
<p>The dialect supports PostgreSQL’s ONLY keyword for targeting only a particular
table in an inheritance hierarchy. This can be used to produce the
<code class="docutils literal notranslate"><span class="pre">SELECT</span> <span class="pre">...</span> <span class="pre">FROM</span> <span class="pre">ONLY</span></code>, <code class="docutils literal notranslate"><span class="pre">UPDATE</span> <span class="pre">ONLY</span> <span class="pre">...</span></code>, and <code class="docutils literal notranslate"><span class="pre">DELETE</span> <span class="pre">FROM</span> <span class="pre">ONLY</span> <span class="pre">...</span></code>
syntaxes. It uses SQLAlchemy’s hints mechanism:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># SELECT ... FROM ONLY ...</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">select</span><span class="p">()</span><span class="o">.</span><span class="n">with_hint</span><span class="p">(</span><span class="n">table</span><span class="p">,</span> <span class="s1">'ONLY'</span><span class="p">,</span> <span class="s1">'postgresql'</span><span class="p">)</span>
<span class="nb">print</span> <span class="n">result</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span>
<span class="c1"># UPDATE ONLY ...</span>
<span class="n">table</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">values</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">))</span><span class="o">.</span><span class="n">with_hint</span><span class="p">(</span><span class="s1">'ONLY'</span><span class="p">,</span>
<span class="n">dialect_name</span><span class="o">=</span><span class="s1">'postgresql'</span><span class="p">)</span>
<span class="c1"># DELETE FROM ONLY ...</span>
<span class="n">table</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span><span class="o">.</span><span class="n">with_hint</span><span class="p">(</span><span class="s1">'ONLY'</span><span class="p">,</span> <span class="n">dialect_name</span><span class="o">=</span><span class="s1">'postgresql'</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="postgresql-specific-index-options">
<span id="postgresql-indexes"></span><h2>PostgreSQL-Specific Index Options<a class="headerlink" href="#postgresql-specific-index-options" title="Permalink to this headline">¶</a></h2>
<p>Several extensions to the <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a> construct are available, specific
to the PostgreSQL dialect.</p>
<div class="section" id="partial-indexes">
<span id="postgresql-partial-indexes"></span><h3>Partial Indexes<a class="headerlink" href="#partial-indexes" title="Permalink to this headline">¶</a></h3>
<p>Partial indexes add criterion to the index definition so that the index is
applied to a subset of rows. These can be specified on <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a>
using the <code class="docutils literal notranslate"><span class="pre">postgresql_where</span></code> keyword argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Index</span><span class="p">(</span><span class="s1">'my_index'</span><span class="p">,</span> <span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">postgresql_where</span><span class="o">=</span><span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">value</span> <span class="o">></span> <span class="mi">10</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="operator-classes">
<h3>Operator Classes<a class="headerlink" href="#operator-classes" title="Permalink to this headline">¶</a></h3>
<p>PostgreSQL allows the specification of an <em>operator class</em> for each column of
an index (see
<a class="reference external" href="http://www.postgresql.org/docs/8.3/interactive/indexes-opclass.html">http://www.postgresql.org/docs/8.3/interactive/indexes-opclass.html</a>).
The <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a> construct allows these to be specified via the
<code class="docutils literal notranslate"><span class="pre">postgresql_ops</span></code> keyword argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Index</span><span class="p">(</span>
<span class="s1">'my_index'</span><span class="p">,</span> <span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">,</span>
<span class="n">postgresql_ops</span><span class="o">=</span><span class="p">{</span>
<span class="s1">'data'</span><span class="p">:</span> <span class="s1">'text_pattern_ops'</span><span class="p">,</span>
<span class="s1">'id'</span><span class="p">:</span> <span class="s1">'int4_ops'</span>
<span class="p">})</span></pre></div>
</div>
<p>Note that the keys in the <code class="docutils literal notranslate"><span class="pre">postgresql_ops</span></code> dictionary are the “key” name of
the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a>, i.e. the name used to access it from the <code class="docutils literal notranslate"><span class="pre">.c</span></code>
collection of <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>, which can be configured to be different than
the actual name of the column as expressed in the database.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">postgresql_ops</span></code> is to be used against a complex SQL expression such
as a function call, then to apply to the column it must be given a label
that is identified in the dictionary by name, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Index</span><span class="p">(</span>
<span class="s1">'my_index'</span><span class="p">,</span> <span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">,</span>
<span class="n">func</span><span class="o">.</span><span class="n">lower</span><span class="p">(</span><span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">)</span><span class="o">.</span><span class="n">label</span><span class="p">(</span><span class="s1">'data_lower'</span><span class="p">),</span>
<span class="n">postgresql_ops</span><span class="o">=</span><span class="p">{</span>
<span class="s1">'data_lower'</span><span class="p">:</span> <span class="s1">'text_pattern_ops'</span><span class="p">,</span>
<span class="s1">'id'</span><span class="p">:</span> <span class="s1">'int4_ops'</span>
<span class="p">})</span></pre></div>
</div>
</div>
<div class="section" id="index-types">
<h3>Index Types<a class="headerlink" href="#index-types" title="Permalink to this headline">¶</a></h3>
<p>PostgreSQL provides several index types: B-Tree, Hash, GiST, and GIN, as well
as the ability for users to create their own (see
<a class="reference external" href="http://www.postgresql.org/docs/8.3/static/indexes-types.html">http://www.postgresql.org/docs/8.3/static/indexes-types.html</a>). These can be
specified on <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a> using the <code class="docutils literal notranslate"><span class="pre">postgresql_using</span></code> keyword argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Index</span><span class="p">(</span><span class="s1">'my_index'</span><span class="p">,</span> <span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">,</span> <span class="n">postgresql_using</span><span class="o">=</span><span class="s1">'gin'</span><span class="p">)</span></pre></div>
</div>
<p>The value passed to the keyword argument will be simply passed through to the
underlying CREATE INDEX command, so it <em>must</em> be a valid index type for your
version of PostgreSQL.</p>
</div>
<div class="section" id="index-storage-parameters">
<span id="postgresql-index-storage"></span><h3>Index Storage Parameters<a class="headerlink" href="#index-storage-parameters" title="Permalink to this headline">¶</a></h3>
<p>PostgreSQL allows storage parameters to be set on indexes. The storage
parameters available depend on the index method used by the index. Storage
parameters can be specified on <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a> using the <code class="docutils literal notranslate"><span class="pre">postgresql_with</span></code>
keyword argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Index</span><span class="p">(</span><span class="s1">'my_index'</span><span class="p">,</span> <span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">,</span> <span class="n">postgresql_with</span><span class="o">=</span><span class="p">{</span><span class="s2">"fillfactor"</span><span class="p">:</span> <span class="mi">50</span><span class="p">})</span></pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.6.</span></p>
</div>
<p>PostgreSQL allows to define the tablespace in which to create the index.
The tablespace can be specified on <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a> using the
<code class="docutils literal notranslate"><span class="pre">postgresql_tablespace</span></code> keyword argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Index</span><span class="p">(</span><span class="s1">'my_index'</span><span class="p">,</span> <span class="n">my_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">,</span> <span class="n">postgresql_tablespace</span><span class="o">=</span><span class="s1">'my_tablespace'</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
<p>Note that the same option is available on <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> as well.</p>
</div>
<div class="section" id="indexes-with-concurrently">
<span id="postgresql-index-concurrently"></span><h3>Indexes with CONCURRENTLY<a class="headerlink" href="#indexes-with-concurrently" title="Permalink to this headline">¶</a></h3>
<p>The PostgreSQL index option CONCURRENTLY is supported by passing the
flag <code class="docutils literal notranslate"><span class="pre">postgresql_concurrently</span></code> to the <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a> construct:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">tbl</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'testtbl'</span><span class="p">,</span> <span class="n">m</span><span class="p">,</span> <span class="n">Column</span><span class="p">(</span><span class="s1">'data'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">))</span>
<span class="n">idx1</span> <span class="o">=</span> <span class="n">Index</span><span class="p">(</span><span class="s1">'test_idx1'</span><span class="p">,</span> <span class="n">tbl</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">,</span> <span class="n">postgresql_concurrently</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></pre></div>
</div>
<p>The above index construct will render DDL for CREATE INDEX, assuming
PostgreSQL 8.2 or higher is detected or for a connection-less dialect, as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">CREATE</span> <span class="n">INDEX</span> <span class="n">CONCURRENTLY</span> <span class="n">test_idx1</span> <span class="n">ON</span> <span class="n">testtbl</span> <span class="p">(</span><span class="n">data</span><span class="p">)</span></pre></div>
</div>
<p>For DROP INDEX, assuming PostgreSQL 9.2 or higher is detected or for
a connection-less dialect, it will emit:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">DROP</span> <span class="n">INDEX</span> <span class="n">CONCURRENTLY</span> <span class="n">test_idx1</span></pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1: </span>support for CONCURRENTLY on DROP INDEX. The
CONCURRENTLY keyword is now only emitted if a high enough version
of PostgreSQL is detected on the connection (or for a connection-less
dialect).</p>
</div>
<p>When using CONCURRENTLY, the Postgresql database requires that the statement
be invoked outside of a transaction block. The Python DBAPI enforces that
even for a single statement, a transaction is present, so to use this
construct, the DBAPI’s “autocommit” mode must be used:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">metadata</span> <span class="o">=</span> <span class="n">MetaData</span><span class="p">()</span>
<span class="n">table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span>
<span class="s2">"foo"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s2">"id"</span><span class="p">,</span> <span class="n">String</span><span class="p">))</span>
<span class="n">index</span> <span class="o">=</span> <span class="n">Index</span><span class="p">(</span>
<span class="s2">"foo_idx"</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">postgresql_concurrently</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="k">with</span> <span class="n">conn</span><span class="o">.</span><span class="n">execution_options</span><span class="p">(</span><span class="n">isolation_level</span><span class="o">=</span><span class="s1">'AUTOCOMMIT'</span><span class="p">):</span>
<span class="n">table</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">conn</span><span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#postgresql-isolation-level"><span class="std std-ref">Transaction Isolation Level</span></a></p>
</div>
</div>
</div>
<div class="section" id="postgresql-index-reflection">
<span id="id1"></span><h2>PostgreSQL Index Reflection<a class="headerlink" href="#postgresql-index-reflection" title="Permalink to this headline">¶</a></h2>
<p>The PostgreSQL database creates a UNIQUE INDEX implicitly whenever the
UNIQUE CONSTRAINT construct is used. When inspecting a table using
<a class="reference internal" href="../core/reflection.html#sqlalchemy.engine.reflection.Inspector" title="sqlalchemy.engine.reflection.Inspector"><code class="xref py py-class docutils literal notranslate"><span class="pre">Inspector</span></code></a>, the <a class="reference internal" href="../core/reflection.html#sqlalchemy.engine.reflection.Inspector.get_indexes" title="sqlalchemy.engine.reflection.Inspector.get_indexes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Inspector.get_indexes()</span></code></a>
and the <a class="reference internal" href="../core/reflection.html#sqlalchemy.engine.reflection.Inspector.get_unique_constraints" title="sqlalchemy.engine.reflection.Inspector.get_unique_constraints"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Inspector.get_unique_constraints()</span></code></a> will report on these
two constructs distinctly; in the case of the index, the key
<code class="docutils literal notranslate"><span class="pre">duplicates_constraint</span></code> will be present in the index entry if it is
detected as mirroring a constraint. When performing reflection using
<code class="docutils literal notranslate"><span class="pre">Table(...,</span> <span class="pre">autoload=True)</span></code>, the UNIQUE INDEX is <strong>not</strong> returned
in <code class="xref py py-attr docutils literal notranslate"><span class="pre">Table.indexes</span></code> when it is detected as mirroring a
<a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.UniqueConstraint" title="sqlalchemy.schema.UniqueConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">UniqueConstraint</span></code></a> in the <code class="xref py py-attr docutils literal notranslate"><span class="pre">Table.constraints</span></code> collection.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.0.0: </span>- <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> reflection now includes
<a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.UniqueConstraint" title="sqlalchemy.schema.UniqueConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">UniqueConstraint</span></code></a> objects present in the <code class="xref py py-attr docutils literal notranslate"><span class="pre">Table.constraints</span></code>
collection; the PostgreSQL backend will no longer include a “mirrored”
<a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a> construct in <code class="xref py py-attr docutils literal notranslate"><span class="pre">Table.indexes</span></code> if it is detected
as corresponding to a unique constraint.</p>
</div>
</div>
<div class="section" id="special-reflection-options">
<h2>Special Reflection Options<a class="headerlink" href="#special-reflection-options" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="../core/reflection.html#sqlalchemy.engine.reflection.Inspector" title="sqlalchemy.engine.reflection.Inspector"><code class="xref py py-class docutils literal notranslate"><span class="pre">Inspector</span></code></a> used for the PostgreSQL backend is an instance
of <a class="reference internal" href="#sqlalchemy.dialects.postgresql.base.PGInspector" title="sqlalchemy.dialects.postgresql.base.PGInspector"><code class="xref py py-class docutils literal notranslate"><span class="pre">PGInspector</span></code></a>, which offers additional methods:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">create_engine</span><span class="p">,</span> <span class="n">inspect</span>
<span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql+psycopg2://localhost/test"</span><span class="p">)</span>
<span class="n">insp</span> <span class="o">=</span> <span class="n">inspect</span><span class="p">(</span><span class="n">engine</span><span class="p">)</span> <span class="c1"># will be a PGInspector</span>
<span class="nb">print</span><span class="p">(</span><span class="n">insp</span><span class="o">.</span><span class="n">get_enums</span><span class="p">())</span></pre></div>
</div>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.base.PGInspector">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.base.</code><code class="descname">PGInspector</code><span class="sig-paren">(</span><em>conn</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.base.PGInspector" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/reflection.html#sqlalchemy.engine.reflection.Inspector" title="sqlalchemy.engine.reflection.Inspector"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.engine.reflection.Inspector</span></code></a></p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.base.PGInspector.get_enums">
<code class="descname">get_enums</code><span class="sig-paren">(</span><em>schema=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.base.PGInspector.get_enums" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a list of ENUM objects.</p>
<p>Each member is a dictionary containing these fields:</p>
<blockquote>
<div><ul class="simple">
<li><p>name - name of the enum</p></li>
<li><p>schema - the schema name for the enum.</p></li>
<li><p>visible - boolean, whether or not this enum is visible
in the default search path.</p></li>
<li><p>labels - a list of string labels that apply to the enum.</p></li>
</ul>
</div></blockquote>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.dialects.postgresql.base.PGInspector.get_enums.params.schema"></span><strong>schema</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.base.PGInspector.get_enums.params.schema">¶</a> – schema name. If None, the default schema
(typically ‘public’) is used. May also be set to ‘*’ to
indicate load enums for all schemas.</p>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.0.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.base.PGInspector.get_foreign_table_names">
<code class="descname">get_foreign_table_names</code><span class="sig-paren">(</span><em>schema=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.base.PGInspector.get_foreign_table_names" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a list of FOREIGN TABLE names.</p>
<p>Behavior is similar to that of <a class="reference internal" href="../core/reflection.html#sqlalchemy.engine.reflection.Inspector.get_table_names" title="sqlalchemy.engine.reflection.Inspector.get_table_names"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Inspector.get_table_names()</span></code></a>,
except that the list is limited to those tables that report a
<code class="docutils literal notranslate"><span class="pre">relkind</span></code> value of <code class="docutils literal notranslate"><span class="pre">f</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.0.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.base.PGInspector.get_table_oid">
<code class="descname">get_table_oid</code><span class="sig-paren">(</span><em>table_name</em>, <em>schema=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.base.PGInspector.get_table_oid" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the OID for the given table name.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.base.PGInspector.get_view_names">
<code class="descname">get_view_names</code><span class="sig-paren">(</span><em>schema=None</em>, <em>include=('plain'</em>, <em>'materialized')</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.base.PGInspector.get_view_names" title="Permalink to this definition">¶</a></dt>
<dd><p>Return all view names in <cite>schema</cite>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.base.PGInspector.get_view_names.params.schema"></span><strong>schema</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.base.PGInspector.get_view_names.params.schema">¶</a> – Optional, retrieve names from a non-default schema.
For special quoting, use <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.elements.quoted_name" title="sqlalchemy.sql.elements.quoted_name"><code class="xref py py-class docutils literal notranslate"><span class="pre">quoted_name</span></code></a>.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.base.PGInspector.get_view_names.params.include"></span><strong>include</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.base.PGInspector.get_view_names.params.include">¶</a> – <p>specify which types of views to return. Passed
as a string value (for a single type) or a tuple (for any number
of types). Defaults to <code class="docutils literal notranslate"><span class="pre">('plain',</span> <span class="pre">'materialized')</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="postgresql-table-options">
<span id="id2"></span><h2>PostgreSQL Table Options<a class="headerlink" href="#postgresql-table-options" title="Permalink to this headline">¶</a></h2>
<p>Several options for CREATE TABLE are supported directly by the PostgreSQL
dialect in conjunction with the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> construct:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">TABLESPACE</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s2">"some_table"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">postgresql_tablespace</span><span class="o">=</span><span class="s1">'some_tablespace'</span><span class="p">)</span></pre></div>
</div>
<p>The above option is also available on the <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><code class="xref py py-class docutils literal notranslate"><span class="pre">Index</span></code></a> construct.</p>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">ON</span> <span class="pre">COMMIT</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s2">"some_table"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">postgresql_on_commit</span><span class="o">=</span><span class="s1">'PRESERVE ROWS'</span><span class="p">)</span></pre></div>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">WITH</span> <span class="pre">OIDS</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s2">"some_table"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">postgresql_with_oids</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></pre></div>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">WITHOUT</span> <span class="pre">OIDS</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s2">"some_table"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">postgresql_with_oids</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span></pre></div>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">INHERITS</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s2">"some_table"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">postgresql_inherits</span><span class="o">=</span><span class="s2">"some_supertable"</span><span class="p">)</span>
<span class="n">Table</span><span class="p">(</span><span class="s2">"some_table"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">postgresql_inherits</span><span class="o">=</span><span class="p">(</span><span class="s2">"t1"</span><span class="p">,</span> <span class="s2">"t2"</span><span class="p">,</span> <span class="o">...</span><span class="p">))</span>
<span class="o">..</span> <span class="n">versionadded</span><span class="p">::</span> <span class="mf">1.0</span><span class="o">.</span><span class="mi">0</span></pre></div>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">PARTITION</span> <span class="pre">BY</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s2">"some_table"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span>
<span class="n">postgresql_partition_by</span><span class="o">=</span><span class="s1">'LIST (part_column)'</span><span class="p">)</span>
<span class="o">..</span> <span class="n">versionadded</span><span class="p">::</span> <span class="mf">1.2</span><span class="o">.</span><span class="mi">6</span></pre></div>
</div>
</li>
</ul>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference external" href="http://www.postgresql.org/docs/current/static/sql-createtable.html">PostgreSQL CREATE TABLE options</a></p>
</div>
</div>
<div class="section" id="array-types">
<h2>ARRAY Types<a class="headerlink" href="#array-types" title="Permalink to this headline">¶</a></h2>
<p>The PostgreSQL dialect supports arrays, both as multidimensional column types
as well as array literals:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a> - ARRAY datatype</p></li>
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.array" title="sqlalchemy.dialects.postgresql.array"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.array</span></code></a> - array literal</p></li>
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.array_agg" title="sqlalchemy.dialects.postgresql.array_agg"><code class="xref py py-func docutils literal notranslate"><span class="pre">postgresql.array_agg()</span></code></a> - ARRAY_AGG SQL function</p></li>
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.aggregate_order_by" title="sqlalchemy.dialects.postgresql.aggregate_order_by"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.aggregate_order_by</span></code></a> - helper for PG’s ORDER BY aggregate
function syntax.</p></li>
</ul>
</div>
<div class="section" id="json-types">
<h2>JSON Types<a class="headerlink" href="#json-types" title="Permalink to this headline">¶</a></h2>
<p>The PostgreSQL dialect supports both JSON and JSONB datatypes, including
psycopg2’s native support and support for all of PostgreSQL’s special
operators:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.JSON</span></code></a></p></li>
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB" title="sqlalchemy.dialects.postgresql.JSONB"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.JSONB</span></code></a></p></li>
</ul>
</div>
<div class="section" id="hstore-type">
<h2>HSTORE Type<a class="headerlink" href="#hstore-type" title="Permalink to this headline">¶</a></h2>
<p>The PostgreSQL HSTORE type as well as hstore literals are supported:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE" title="sqlalchemy.dialects.postgresql.HSTORE"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.HSTORE</span></code></a> - HSTORE datatype</p></li>
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.hstore" title="sqlalchemy.dialects.postgresql.hstore"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.hstore</span></code></a> - hstore literal</p></li>
</ul>
</div>
<div class="section" id="enum-types">
<h2>ENUM Types<a class="headerlink" href="#enum-types" title="Permalink to this headline">¶</a></h2>
<p>PostgreSQL has an independently creatable TYPE structure which is used
to implement an enumerated type. This approach introduces significant
complexity on the SQLAlchemy side in terms of when this type should be
CREATED and DROPPED. The type object is also an independently reflectable
entity. The following sections should be consulted:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ENUM</span></code></a> - DDL and typing support for ENUM.</p></li>
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.base.PGInspector.get_enums" title="sqlalchemy.dialects.postgresql.base.PGInspector.get_enums"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PGInspector.get_enums()</span></code></a> - retrieve a listing of current ENUM types</p></li>
<li><p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.create" title="sqlalchemy.dialects.postgresql.ENUM.create"><code class="xref py py-meth docutils literal notranslate"><span class="pre">postgresql.ENUM.create()</span></code></a> , <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.drop" title="sqlalchemy.dialects.postgresql.ENUM.drop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">postgresql.ENUM.drop()</span></code></a> - individual
CREATE and DROP commands for ENUM.</p></li>
</ul>
<div class="section" id="using-enum-with-array">
<span id="postgresql-array-of-enum"></span><h3>Using ENUM with ARRAY<a class="headerlink" href="#using-enum-with-array" title="Permalink to this headline">¶</a></h3>
<p>The combination of ENUM and ARRAY is not directly supported by backend
DBAPIs at this time. In order to send and receive an ARRAY of ENUM,
use the following workaround type:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ArrayOfEnum</span><span class="p">(</span><span class="n">ARRAY</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">bind_expression</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">bindvalue</span><span class="p">):</span>
<span class="k">return</span> <span class="n">sa</span><span class="o">.</span><span class="n">cast</span><span class="p">(</span><span class="n">bindvalue</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">result_processor</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dialect</span><span class="p">,</span> <span class="n">coltype</span><span class="p">):</span>
<span class="n">super_rp</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">ArrayOfEnum</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">result_processor</span><span class="p">(</span>
<span class="n">dialect</span><span class="p">,</span> <span class="n">coltype</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">handle_raw_string</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="n">inner</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="sa">r</span><span class="s2">"^{(.*)}$"</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">return</span> <span class="n">inner</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">","</span><span class="p">)</span> <span class="k">if</span> <span class="n">inner</span> <span class="k">else</span> <span class="p">[]</span>
<span class="k">def</span> <span class="nf">process</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="k">return</span> <span class="kc">None</span>
<span class="k">return</span> <span class="n">super_rp</span><span class="p">(</span><span class="n">handle_raw_string</span><span class="p">(</span><span class="n">value</span><span class="p">))</span>
<span class="k">return</span> <span class="n">process</span></pre></div>
</div>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span>
<span class="s1">'mydata'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'data'</span><span class="p">,</span> <span class="n">ArrayOfEnum</span><span class="p">(</span><span class="n">ENUM</span><span class="p">(</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'b, '</span><span class="n">c</span><span class="s1">', name='</span><span class="n">myenum</span><span class="s1">')))</span>
<span class="p">)</span></pre></div>
</div>
<p>This type is not included as a built-in type as it would be incompatible
with a DBAPI that suddenly decides to support ARRAY of ENUM directly in
a new version.</p>
</div>
<div class="section" id="using-json-jsonb-with-array">
<span id="postgresql-array-of-json"></span><h3>Using JSON/JSONB with ARRAY<a class="headerlink" href="#using-json-jsonb-with-array" title="Permalink to this headline">¶</a></h3>
<p>Similar to using ENUM, for an ARRAY of JSON/JSONB we need to render the
appropriate CAST, however current psycopg2 drivers seem to handle the result
for ARRAY of JSON automatically, so the type is simpler:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">CastingArray</span><span class="p">(</span><span class="n">ARRAY</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">bind_expression</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">bindvalue</span><span class="p">):</span>
<span class="k">return</span> <span class="n">sa</span><span class="o">.</span><span class="n">cast</span><span class="p">(</span><span class="n">bindvalue</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span></pre></div>
</div>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span>
<span class="s1">'mydata'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'data'</span><span class="p">,</span> <span class="n">CastingArray</span><span class="p">(</span><span class="n">JSONB</span><span class="p">))</span>
<span class="p">)</span></pre></div>
</div>
</div>
</div>
<div class="section" id="postgresql-data-types">
<h2>PostgreSQL Data Types<a class="headerlink" href="#postgresql-data-types" title="Permalink to this headline">¶</a></h2>
<p>As with all SQLAlchemy dialects, all UPPERCASE types that are known to be
valid with PostgreSQL are importable from the top level dialect, whether
they originate from <a class="reference internal" href="../core/type_basics.html#module-sqlalchemy.types" title="sqlalchemy.types"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlalchemy.types</span></code></a> or from the local dialect:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> \
<span class="n">ARRAY</span><span class="p">,</span> <span class="n">BIGINT</span><span class="p">,</span> <span class="n">BIT</span><span class="p">,</span> <span class="n">BOOLEAN</span><span class="p">,</span> <span class="n">BYTEA</span><span class="p">,</span> <span class="n">CHAR</span><span class="p">,</span> <span class="n">CIDR</span><span class="p">,</span> <span class="n">DATE</span><span class="p">,</span> \
<span class="n">DOUBLE_PRECISION</span><span class="p">,</span> <span class="n">ENUM</span><span class="p">,</span> <span class="n">FLOAT</span><span class="p">,</span> <span class="n">HSTORE</span><span class="p">,</span> <span class="n">INET</span><span class="p">,</span> <span class="n">INTEGER</span><span class="p">,</span> \
<span class="n">INTERVAL</span><span class="p">,</span> <span class="n">JSON</span><span class="p">,</span> <span class="n">JSONB</span><span class="p">,</span> <span class="n">MACADDR</span><span class="p">,</span> <span class="n">MONEY</span><span class="p">,</span> <span class="n">NUMERIC</span><span class="p">,</span> <span class="n">OID</span><span class="p">,</span> <span class="n">REAL</span><span class="p">,</span> <span class="n">SMALLINT</span><span class="p">,</span> <span class="n">TEXT</span><span class="p">,</span> \
<span class="n">TIME</span><span class="p">,</span> <span class="n">TIMESTAMP</span><span class="p">,</span> <span class="n">UUID</span><span class="p">,</span> <span class="n">VARCHAR</span><span class="p">,</span> <span class="n">INT4RANGE</span><span class="p">,</span> <span class="n">INT8RANGE</span><span class="p">,</span> <span class="n">NUMRANGE</span><span class="p">,</span> \
<span class="n">DATERANGE</span><span class="p">,</span> <span class="n">TSRANGE</span><span class="p">,</span> <span class="n">TSTZRANGE</span><span class="p">,</span> <span class="n">TSVECTOR</span></pre></div>
</div>
<p>Types which are specific to PostgreSQL, or have PostgreSQL-specific
construction arguments, are as follows:</p>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.aggregate_order_by">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">aggregate_order_by</code><span class="sig-paren">(</span><em>target</em>, <em>*order_by</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.aggregate_order_by" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></code></a></p>
<p>Represent a PostgreSQL aggregate order by expression.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">aggregate_order_by</span>
<span class="n">expr</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">array_agg</span><span class="p">(</span><span class="n">aggregate_order_by</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">a</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">desc</span><span class="p">()))</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">expr</span><span class="p">])</span></pre></div>
</div>
<p>would represent the expression:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">array_agg</span><span class="p">(</span><span class="n">a</span> <span class="n">ORDER</span> <span class="n">BY</span> <span class="n">b</span> <span class="n">DESC</span><span class="p">)</span> <span class="n">FROM</span> <span class="n">table</span><span class="p">;</span></pre></div>
</div>
<p>Similarly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">expr</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">string_agg</span><span class="p">(</span>
<span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">a</span><span class="p">,</span>
<span class="n">aggregate_order_by</span><span class="p">(</span><span class="n">literal_column</span><span class="p">(</span><span class="s2">"','"</span><span class="p">),</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">expr</span><span class="p">])</span></pre></div>
</div>
<p>Would represent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">string_agg</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="s1">','</span> <span class="n">ORDER</span> <span class="n">BY</span> <span class="n">a</span><span class="p">)</span> <span class="n">FROM</span> <span class="n">table</span><span class="p">;</span></pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.2.13: </span>- the ORDER BY argument may be multiple terms</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/functions.html#sqlalchemy.sql.functions.array_agg" title="sqlalchemy.sql.functions.array_agg"><code class="xref py py-class docutils literal notranslate"><span class="pre">array_agg</span></code></a></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.array">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">array</code><span class="sig-paren">(</span><em>clauses</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.array" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.Tuple" title="sqlalchemy.sql.expression.Tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.sql.expression.Tuple</span></code></a></p>
<p>A PostgreSQL ARRAY literal.</p>
<p>This is used to produce ARRAY literals in SQL expressions, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">array</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.dialects</span> <span class="k">import</span> <span class="n">postgresql</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">select</span><span class="p">,</span> <span class="n">func</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span>
<span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])</span> <span class="o">+</span> <span class="n">array</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">])</span>
<span class="p">])</span>
<span class="nb">print</span> <span class="n">stmt</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">dialect</span><span class="o">=</span><span class="n">postgresql</span><span class="o">.</span><span class="n">dialect</span><span class="p">())</span></pre></div>
</div>
<p>Produces the SQL:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">ARRAY</span><span class="p">[</span><span class="o">%</span><span class="p">(</span><span class="n">param_1</span><span class="p">)</span><span class="n">s</span><span class="p">,</span> <span class="o">%</span><span class="p">(</span><span class="n">param_2</span><span class="p">)</span><span class="n">s</span><span class="p">]</span> <span class="o">||</span>
<span class="n">ARRAY</span><span class="p">[</span><span class="o">%</span><span class="p">(</span><span class="n">param_3</span><span class="p">)</span><span class="n">s</span><span class="p">,</span> <span class="o">%</span><span class="p">(</span><span class="n">param_4</span><span class="p">)</span><span class="n">s</span><span class="p">,</span> <span class="o">%</span><span class="p">(</span><span class="n">param_5</span><span class="p">)</span><span class="n">s</span><span class="p">])</span> <span class="n">AS</span> <span class="n">anon_1</span></pre></div>
</div>
<p>An instance of <a class="reference internal" href="#sqlalchemy.dialects.postgresql.array" title="sqlalchemy.dialects.postgresql.array"><code class="xref py py-class docutils literal notranslate"><span class="pre">array</span></code></a> will always have the datatype
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">ARRAY</span></code></a>. The “inner” type of the array is inferred from
the values present, unless the <code class="docutils literal notranslate"><span class="pre">type_</span></code> keyword argument is passed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">array</span><span class="p">([</span><span class="s1">'foo'</span><span class="p">,</span> <span class="s1">'bar'</span><span class="p">],</span> <span class="n">type_</span><span class="o">=</span><span class="n">CHAR</span><span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.ARRAY">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">ARRAY</code><span class="sig-paren">(</span><em>item_type</em>, <em>as_tuple=False</em>, <em>dimensions=None</em>, <em>zero_indexes=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ARRAY" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY" title="sqlalchemy.types.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.ARRAY</span></code></a></p>
<p>PostgreSQL ARRAY type.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.1: </span>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a> type is now
a subclass of the core <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY" title="sqlalchemy.types.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ARRAY</span></code></a> type.</p>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a> type is constructed in the same way
as the core <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY" title="sqlalchemy.types.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ARRAY</span></code></a> type; a member type is required, and a
number of dimensions is recommended if the type is to be used for more
than one dimension:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects</span> <span class="k">import</span> <span class="n">postgresql</span>
<span class="n">mytable</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s2">"mytable"</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s2">"data"</span><span class="p">,</span> <span class="n">postgresql</span><span class="o">.</span><span class="n">ARRAY</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">dimensions</span><span class="o">=</span><span class="mi">2</span><span class="p">))</span>
<span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a> type provides all operations defined on the
core <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY" title="sqlalchemy.types.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ARRAY</span></code></a> type, including support for “dimensions”,
indexed access, and simple matching such as
<a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY.Comparator.any" title="sqlalchemy.types.ARRAY.Comparator.any"><code class="xref py py-meth docutils literal notranslate"><span class="pre">types.ARRAY.Comparator.any()</span></code></a> and
<a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY.Comparator.all" title="sqlalchemy.types.ARRAY.Comparator.all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">types.ARRAY.Comparator.all()</span></code></a>. <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a> class also
provides PostgreSQL-specific methods for containment operations, including
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY.Comparator.contains" title="sqlalchemy.dialects.postgresql.ARRAY.Comparator.contains"><code class="xref py py-meth docutils literal notranslate"><span class="pre">postgresql.ARRAY.Comparator.contains()</span></code></a>
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY.Comparator.contained_by" title="sqlalchemy.dialects.postgresql.ARRAY.Comparator.contained_by"><code class="xref py py-meth docutils literal notranslate"><span class="pre">postgresql.ARRAY.Comparator.contained_by()</span></code></a>, and
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY.Comparator.overlap" title="sqlalchemy.dialects.postgresql.ARRAY.Comparator.overlap"><code class="xref py py-meth docutils literal notranslate"><span class="pre">postgresql.ARRAY.Comparator.overlap()</span></code></a>, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mytable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">contains</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">])</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a> type may not be supported on all
PostgreSQL DBAPIs; it is currently known to work on psycopg2 only.</p>
<p>Additionally, the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a> type does not work directly in
conjunction with the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">ENUM</span></code></a> type. For a workaround, see the
special type at <a class="reference internal" href="#postgresql-array-of-enum"><span class="std std-ref">Using ENUM with ARRAY</span></a>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY" title="sqlalchemy.types.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ARRAY</span></code></a> - base array type</p>
<p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.array" title="sqlalchemy.dialects.postgresql.array"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.array</span></code></a> - produces a literal array value.</p>
</div>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.ARRAY.Comparator">
<em class="property">class </em><code class="descname">Comparator</code><span class="sig-paren">(</span><em>expr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ARRAY.Comparator" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Comparator</span></code></p>
<p>Define comparison operations for <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">ARRAY</span></code></a>.</p>
<p>Note that these operations are in addition to those provided
by the base <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY.Comparator" title="sqlalchemy.types.ARRAY.Comparator"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ARRAY.Comparator</span></code></a> class, including
<a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY.Comparator.any" title="sqlalchemy.types.ARRAY.Comparator.any"><code class="xref py py-meth docutils literal notranslate"><span class="pre">types.ARRAY.Comparator.any()</span></code></a> and
<a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY.Comparator.all" title="sqlalchemy.types.ARRAY.Comparator.all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">types.ARRAY.Comparator.all()</span></code></a>.</p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ARRAY.Comparator.contained_by">
<code class="descname">contained_by</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ARRAY.Comparator.contained_by" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test if elements are a proper subset of the
elements of the argument array expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ARRAY.Comparator.contains">
<code class="descname">contains</code><span class="sig-paren">(</span><em>other</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ARRAY.Comparator.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test if elements are a superset of the
elements of the argument array expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ARRAY.Comparator.overlap">
<code class="descname">overlap</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ARRAY.Comparator.overlap" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test if array has elements in common with
an argument array expression.</p>
</dd></dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ARRAY.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>item_type</em>, <em>as_tuple=False</em>, <em>dimensions=None</em>, <em>zero_indexes=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ARRAY.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct an ARRAY.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Column</span><span class="p">(</span><span class="s1">'myarray'</span><span class="p">,</span> <span class="n">ARRAY</span><span class="p">(</span><span class="n">Integer</span><span class="p">))</span></pre></div>
</div>
<p>Arguments are:</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ARRAY.params.item_type"></span><strong>item_type</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY.params.item_type">¶</a> – The data type of items of this array. Note that
dimensionality is irrelevant here, so multi-dimensional arrays like
<code class="docutils literal notranslate"><span class="pre">INTEGER[][]</span></code>, are constructed as <code class="docutils literal notranslate"><span class="pre">ARRAY(Integer)</span></code>, not as
<code class="docutils literal notranslate"><span class="pre">ARRAY(ARRAY(Integer))</span></code> or such.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ARRAY.params.as_tuple"></span><strong>as_tuple=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY.params.as_tuple">¶</a> – Specify whether return results
should be converted to tuples from lists. DBAPIs such
as psycopg2 return lists by default. When tuples are
returned, the results are hashable.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ARRAY.params.dimensions"></span><strong>dimensions</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY.params.dimensions">¶</a> – if non-None, the ARRAY will assume a fixed
number of dimensions. This will cause the DDL emitted for this
ARRAY to include the exact number of bracket clauses <code class="docutils literal notranslate"><span class="pre">[]</span></code>,
and will also optimize the performance of the type overall.
Note that PG arrays are always implicitly “non-dimensioned”,
meaning they can store any number of dimensions no matter how
they were declared.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ARRAY.params.zero_indexes"></span><strong>zero_indexes=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY.params.zero_indexes">¶</a> – <p>when True, index values will be converted
between Python zero-based and PostgreSQL one-based indexes, e.g.
a value of one will be added to all index values before passing
to the database.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.5.</span></p>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.dialects.postgresql.array_agg">
<code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">array_agg</code><span class="sig-paren">(</span><em>*arg</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.array_agg" title="Permalink to this definition">¶</a></dt>
<dd><p>PostgreSQL-specific form of <a class="reference internal" href="../core/functions.html#sqlalchemy.sql.functions.array_agg" title="sqlalchemy.sql.functions.array_agg"><code class="xref py py-class docutils literal notranslate"><span class="pre">array_agg</span></code></a>, ensures
return type is <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ARRAY" title="sqlalchemy.dialects.postgresql.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code></a> and not
the plain <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY" title="sqlalchemy.types.ARRAY"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.ARRAY</span></code></a>, unless an explicit <code class="docutils literal notranslate"><span class="pre">type_</span></code>
is passed.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.dialects.postgresql.Any">
<code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">Any</code><span class="sig-paren">(</span><em>other</em>, <em>arrexpr</em>, <em>operator=<built-in function eq></em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.Any" title="Permalink to this definition">¶</a></dt>
<dd><p>A synonym for the <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY.Comparator.any" title="sqlalchemy.types.ARRAY.Comparator.any"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ARRAY.Comparator.any()</span></code></a> method.</p>
<p>This method is legacy and is here for backwards-compatibility.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.any_" title="sqlalchemy.sql.expression.any_"><code class="xref py py-func docutils literal notranslate"><span class="pre">expression.any_()</span></code></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.dialects.postgresql.All">
<code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">All</code><span class="sig-paren">(</span><em>other</em>, <em>arrexpr</em>, <em>operator=<built-in function eq></em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.All" title="Permalink to this definition">¶</a></dt>
<dd><p>A synonym for the <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.ARRAY.Comparator.all" title="sqlalchemy.types.ARRAY.Comparator.all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ARRAY.Comparator.all()</span></code></a> method.</p>
<p>This method is legacy and is here for backwards-compatibility.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.all_" title="sqlalchemy.sql.expression.all_"><code class="xref py py-func docutils literal notranslate"><span class="pre">expression.all_()</span></code></a></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.BIT">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">BIT</code><span class="sig-paren">(</span><em>length=None</em>, <em>varying=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.BIT" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.BYTEA">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">BYTEA</code><span class="sig-paren">(</span><em>length=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.BYTEA" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.LargeBinary" title="sqlalchemy.types.LargeBinary"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.LargeBinary</span></code></a></p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.BYTEA.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>length=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.BYTEA.__init__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member docutils container">
<p><em>inherited from the</em> <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.LargeBinary.__init__" title="sqlalchemy.types.LargeBinary.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> <em>method of</em> <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.LargeBinary" title="sqlalchemy.types.LargeBinary"><code class="xref py py-class docutils literal notranslate"><span class="pre">LargeBinary</span></code></a></p>
</div>
<p>Construct a LargeBinary type.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.dialects.postgresql.BYTEA.params.length"></span><strong>length</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.BYTEA.params.length">¶</a> – optional, a length for the column for use in
DDL statements, for those binary types that accept a length,
such as the MySQL BLOB type.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.CIDR">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">CIDR</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.CIDR" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.DOUBLE_PRECISION">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">DOUBLE_PRECISION</code><span class="sig-paren">(</span><em>precision=None</em>, <em>asdecimal=False</em>, <em>decimal_return_scale=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.DOUBLE_PRECISION" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Float</span></code></a></p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>precision=None</em>, <em>asdecimal=False</em>, <em>decimal_return_scale=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.__init__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member docutils container">
<p><em>inherited from the</em> <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Float.__init__" title="sqlalchemy.types.Float.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> <em>method of</em> <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><code class="xref py py-class docutils literal notranslate"><span class="pre">Float</span></code></a></p>
</div>
<p>Construct a Float.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.params.precision"></span><strong>precision</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.params.precision">¶</a> – the numeric precision for use in DDL <code class="docutils literal notranslate"><span class="pre">CREATE</span>
<span class="pre">TABLE</span></code>.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.params.asdecimal"></span><strong>asdecimal</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.params.asdecimal">¶</a> – the same flag as that of <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Numeric" title="sqlalchemy.types.Numeric"><code class="xref py py-class docutils literal notranslate"><span class="pre">Numeric</span></code></a>, but
defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. Note that setting this flag to <code class="docutils literal notranslate"><span class="pre">True</span></code>
results in floating point conversion.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.params.decimal_return_scale"></span><strong>decimal_return_scale</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.params.decimal_return_scale">¶</a> – <p>Default scale to use when converting
from floats to Python decimals. Floating point values will typically
be much longer due to decimal inaccuracy, and most floating point
database types don’t have a notion of “scale”, so by default the
float type looks for the first ten decimal places when converting.
Specifying this value will override that length. Note that the
MySQL float types, which do include “scale”, will use “scale”
as the default for decimal_return_scale, if not otherwise specified.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0.</span></p>
</div>
</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.params.**kwargs"></span><strong>**kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.params.**kwargs">¶</a> – <div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 0.9: </span>Additional keyword arguments are ignored by the base
<a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><code class="xref py py-class docutils literal notranslate"><span class="pre">Float</span></code></a> type, and keyword arguments will no longer
be accepted in a future release. For database specific floats
that support additional arguments, see that dialect’s
documentation for details, such as
<a class="reference internal" href="mysql.html#sqlalchemy.dialects.mysql.FLOAT" title="sqlalchemy.dialects.mysql.FLOAT"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.mysql.FLOAT</span></code></a>.</p>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.ENUM">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">ENUM</code><span class="sig-paren">(</span><em>*enums</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ENUM" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.NativeForEmulated</span></code>, <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Enum</span></code></a></p>
<p>PostgreSQL ENUM type.</p>
<p>This is a subclass of <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.Enum</span></code></a> which includes
support for PG’s <code class="docutils literal notranslate"><span class="pre">CREATE</span> <span class="pre">TYPE</span></code> and <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">TYPE</span></code>.</p>
<p>When the builtin type <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.Enum</span></code></a> is used and the
<a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Enum.params.native_enum" title="sqlalchemy.types.Enum"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Enum.native_enum</span></code></a> flag is left at its default of
True, the PostgreSQL backend will use a <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ENUM</span></code></a>
type as the implementation, so the special create/drop rules
will be used.</p>
<p>The create/drop behavior of ENUM is necessarily intricate, due to the
awkward relationship the ENUM type has in relationship to the
parent table, in that it may be “owned” by just a single table, or
may be shared among many tables.</p>
<p>When using <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.Enum</span></code></a> or <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ENUM</span></code></a>
in an “inline” fashion, the <code class="docutils literal notranslate"><span class="pre">CREATE</span> <span class="pre">TYPE</span></code> and <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">TYPE</span></code> is emitted
corresponding to when the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table.create" title="sqlalchemy.schema.Table.create"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.create()</span></code></a> and <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table.drop" title="sqlalchemy.schema.Table.drop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.drop()</span></code></a>
methods are called:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'sometable'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'some_enum'</span><span class="p">,</span> <span class="n">ENUM</span><span class="p">(</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">,</span> <span class="s1">'c'</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'myenum'</span><span class="p">))</span>
<span class="p">)</span>
<span class="n">table</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">engine</span><span class="p">)</span> <span class="c1"># will emit CREATE ENUM and CREATE TABLE</span>
<span class="n">table</span><span class="o">.</span><span class="n">drop</span><span class="p">(</span><span class="n">engine</span><span class="p">)</span> <span class="c1"># will emit DROP TABLE and DROP ENUM</span></pre></div>
</div>
<p>To use a common enumerated type between multiple tables, the best
practice is to declare the <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.Enum</span></code></a> or
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ENUM</span></code></a> independently, and associate it with the
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetaData</span></code></a> object itself:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">my_enum</span> <span class="o">=</span> <span class="n">ENUM</span><span class="p">(</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">,</span> <span class="s1">'c'</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'myenum'</span><span class="p">,</span> <span class="n">metadata</span><span class="o">=</span><span class="n">metadata</span><span class="p">)</span>
<span class="n">t1</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'sometable_one'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'some_enum'</span><span class="p">,</span> <span class="n">myenum</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">t2</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'sometable_two'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'some_enum'</span><span class="p">,</span> <span class="n">myenum</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>When this pattern is used, care must still be taken at the level
of individual table creates. Emitting CREATE TABLE without also
specifying <code class="docutils literal notranslate"><span class="pre">checkfirst=True</span></code> will still cause issues:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t1</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">engine</span><span class="p">)</span> <span class="c1"># will fail: no such type 'myenum'</span></pre></div>
</div>
<p>If we specify <code class="docutils literal notranslate"><span class="pre">checkfirst=True</span></code>, the individual table-level create
operation will check for the <code class="docutils literal notranslate"><span class="pre">ENUM</span></code> and create if not exists:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># will check if enum exists, and emit CREATE TYPE if not</span>
<span class="n">t1</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="n">checkfirst</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></pre></div>
</div>
<p>When using a metadata-level ENUM type, the type will always be created
and dropped if either the metadata-wide create/drop is called:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">metadata</span><span class="o">.</span><span class="n">create_all</span><span class="p">(</span><span class="n">engine</span><span class="p">)</span> <span class="c1"># will emit CREATE TYPE</span>
<span class="n">metadata</span><span class="o">.</span><span class="n">drop_all</span><span class="p">(</span><span class="n">engine</span><span class="p">)</span> <span class="c1"># will emit DROP TYPE</span></pre></div>
</div>
<p>The type can also be created and dropped directly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">my_enum</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">engine</span><span class="p">)</span>
<span class="n">my_enum</span><span class="o">.</span><span class="n">drop</span><span class="p">(</span><span class="n">engine</span><span class="p">)</span></pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.0.0: </span>The PostgreSQL <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.ENUM</span></code></a> type
now behaves more strictly with regards to CREATE/DROP. A metadata-level
ENUM type will only be created and dropped at the metadata level,
not the table level, with the exception of
<code class="docutils literal notranslate"><span class="pre">table.create(checkfirst=True)</span></code>.
The <code class="docutils literal notranslate"><span class="pre">table.drop()</span></code> call will now emit a DROP TYPE for a table-level
enumerated type.</p>
</div>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ENUM.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>*enums</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ENUM.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct an <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">ENUM</span></code></a>.</p>
<p>Arguments are the same as that of
<a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Enum" title="sqlalchemy.types.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.Enum</span></code></a>, but also including
the following parameters.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.dialects.postgresql.ENUM.params.create_type"></span><strong>create_type</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.params.create_type">¶</a> – Defaults to True.
Indicates that <code class="docutils literal notranslate"><span class="pre">CREATE</span> <span class="pre">TYPE</span></code> should be
emitted, after optionally checking for the
presence of the type, when the parent
table is being created; and additionally
that <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">TYPE</span></code> is called when the table
is dropped. When <code class="docutils literal notranslate"><span class="pre">False</span></code>, no check
will be performed and no <code class="docutils literal notranslate"><span class="pre">CREATE</span> <span class="pre">TYPE</span></code>
or <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">TYPE</span></code> is emitted, unless
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.create" title="sqlalchemy.dialects.postgresql.ENUM.create"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create()</span></code></a>
or <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.drop" title="sqlalchemy.dialects.postgresql.ENUM.drop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">drop()</span></code></a>
are called directly.
Setting to <code class="docutils literal notranslate"><span class="pre">False</span></code> is helpful
when invoking a creation scheme to a SQL file
without access to the actual database -
the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.create" title="sqlalchemy.dialects.postgresql.ENUM.create"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create()</span></code></a> and
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.drop" title="sqlalchemy.dialects.postgresql.ENUM.drop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">drop()</span></code></a> methods can
be used to emit SQL to a target bind.</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ENUM.create">
<code class="descname">create</code><span class="sig-paren">(</span><em>bind=None</em>, <em>checkfirst=True</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ENUM.create" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit <code class="docutils literal notranslate"><span class="pre">CREATE</span> <span class="pre">TYPE</span></code> for this
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">ENUM</span></code></a>.</p>
<p>If the underlying dialect does not support
PostgreSQL CREATE TYPE, no action is taken.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ENUM.create.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.create.params.bind">¶</a> – a connectable <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>,
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>, or similar object to emit
SQL.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ENUM.create.params.checkfirst"></span><strong>checkfirst</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.create.params.checkfirst">¶</a> – if <code class="docutils literal notranslate"><span class="pre">True</span></code>, a query against
the PG catalog will be first performed to see
if the type does not exist already before
creating.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ENUM.drop">
<code class="descname">drop</code><span class="sig-paren">(</span><em>bind=None</em>, <em>checkfirst=True</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ENUM.drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit <code class="docutils literal notranslate"><span class="pre">DROP</span> <span class="pre">TYPE</span></code> for this
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ENUM" title="sqlalchemy.dialects.postgresql.ENUM"><code class="xref py py-class docutils literal notranslate"><span class="pre">ENUM</span></code></a>.</p>
<p>If the underlying dialect does not support
PostgreSQL DROP TYPE, no action is taken.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ENUM.drop.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.drop.params.bind">¶</a> – a connectable <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>,
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a>, or similar object to emit
SQL.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ENUM.drop.params.checkfirst"></span><strong>checkfirst</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ENUM.drop.params.checkfirst">¶</a> – if <code class="docutils literal notranslate"><span class="pre">True</span></code>, a query against
the PG catalog will be first performed to see
if the type actually exists before dropping.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.HSTORE">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">HSTORE</code><span class="sig-paren">(</span><em>text_type=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.Indexable" title="sqlalchemy.types.Indexable"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Indexable</span></code></a>, <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.Concatenable" title="sqlalchemy.types.Concatenable"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Concatenable</span></code></a>, <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Represent the PostgreSQL HSTORE type.</p>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE" title="sqlalchemy.dialects.postgresql.HSTORE"><code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE</span></code></a> type stores dictionaries containing strings, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'data_table'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'data'</span><span class="p">,</span> <span class="n">HSTORE</span><span class="p">)</span>
<span class="p">)</span>
<span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
<span class="n">data_table</span><span class="o">.</span><span class="n">insert</span><span class="p">(),</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"key1"</span><span class="p">:</span> <span class="s2">"value1"</span><span class="p">,</span> <span class="s2">"key2"</span><span class="p">:</span> <span class="s2">"value2"</span><span class="p">}</span>
<span class="p">)</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE" title="sqlalchemy.dialects.postgresql.HSTORE"><code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE</span></code></a> provides for a wide range of operations, including:</p>
<ul>
<li><p>Index operations:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">[</span><span class="s1">'some key'</span><span class="p">]</span> <span class="o">==</span> <span class="s1">'some value'</span></pre></div>
</div>
</li>
<li><p>Containment operations:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">has_key</span><span class="p">(</span><span class="s1">'some key'</span><span class="p">)</span>
<span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">has_all</span><span class="p">([</span><span class="s1">'one'</span><span class="p">,</span> <span class="s1">'two'</span><span class="p">,</span> <span class="s1">'three'</span><span class="p">])</span></pre></div>
</div>
</li>
<li><p>Concatenation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span> <span class="o">+</span> <span class="p">{</span><span class="s2">"k1"</span><span class="p">:</span> <span class="s2">"v1"</span><span class="p">}</span></pre></div>
</div>
</li>
</ul>
<p>For a full list of special methods see
<code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE.comparator_factory</span></code>.</p>
<p>For usage with the SQLAlchemy ORM, it may be desirable to combine
the usage of <a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE" title="sqlalchemy.dialects.postgresql.HSTORE"><code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE</span></code></a> with <a class="reference internal" href="../orm/extensions/mutable.html#sqlalchemy.ext.mutable.MutableDict" title="sqlalchemy.ext.mutable.MutableDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableDict</span></code></a> dictionary
now part of the <a class="reference internal" href="../orm/extensions/mutable.html#module-sqlalchemy.ext.mutable" title="sqlalchemy.ext.mutable"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlalchemy.ext.mutable</span></code></a>
extension. This extension will allow “in-place” changes to the
dictionary, e.g. addition of new keys or replacement/removal of existing
keys to/from the current dictionary, to produce events which will be
detected by the unit of work:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.ext.mutable</span> <span class="k">import</span> <span class="n">MutableDict</span>
<span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'data_table'</span>
<span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">MutableDict</span><span class="o">.</span><span class="n">as_mutable</span><span class="p">(</span><span class="n">HSTORE</span><span class="p">))</span>
<span class="n">my_object</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span><span class="o">.</span><span class="n">one</span><span class="p">()</span>
<span class="c1"># in-place mutation, requires Mutable extension</span>
<span class="c1"># in order for the ORM to detect</span>
<span class="n">my_object</span><span class="o">.</span><span class="n">data</span><span class="p">[</span><span class="s1">'some_key'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'some value'</span>
<span class="n">session</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span></pre></div>
</div>
<p>When the <a class="reference internal" href="../orm/extensions/mutable.html#module-sqlalchemy.ext.mutable" title="sqlalchemy.ext.mutable"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlalchemy.ext.mutable</span></code></a> extension is not used, the ORM
will not be alerted to any changes to the contents of an existing
dictionary, unless that dictionary value is re-assigned to the
HSTORE-attribute itself, thus generating a change event.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.hstore" title="sqlalchemy.dialects.postgresql.hstore"><code class="xref py py-class docutils literal notranslate"><span class="pre">hstore</span></code></a> - render the PostgreSQL <code class="docutils literal notranslate"><span class="pre">hstore()</span></code> function.</p>
</div>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator">
<em class="property">class </em><code class="descname">Comparator</code><span class="sig-paren">(</span><em>expr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Comparator</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Comparator</span></code></p>
<p>Define comparison operations for <a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE" title="sqlalchemy.dialects.postgresql.HSTORE"><code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE</span></code></a>.</p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.array">
<code class="descname">array</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.array" title="Permalink to this definition">¶</a></dt>
<dd><p>Text array expression. Returns array of alternating keys and
values.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.contained_by">
<code class="descname">contained_by</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.contained_by" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test if keys are a proper subset of the
keys of the argument jsonb expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.contains">
<code class="descname">contains</code><span class="sig-paren">(</span><em>other</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test if keys (or array) are a superset
of/contained the keys of the argument jsonb expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.defined">
<code class="descname">defined</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.defined" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test for presence of a non-NULL value for
the key. Note that the key may be a SQLA expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.delete">
<code class="descname">delete</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>HStore expression. Returns the contents of this hstore with the
given key deleted. Note that the key may be a SQLA expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.has_all">
<code class="descname">has_all</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.has_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test for presence of all keys in jsonb</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.has_any">
<code class="descname">has_any</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.has_any" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test for presence of any key in jsonb</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.has_key">
<code class="descname">has_key</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.has_key" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test for presence of a key. Note that the
key may be a SQLA expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.keys">
<code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.keys" title="Permalink to this definition">¶</a></dt>
<dd><p>Text array expression. Returns array of keys.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.matrix">
<code class="descname">matrix</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.matrix" title="Permalink to this definition">¶</a></dt>
<dd><p>Text array expression. Returns array of [key, value] pairs.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.slice">
<code class="descname">slice</code><span class="sig-paren">(</span><em>array</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.slice" title="Permalink to this definition">¶</a></dt>
<dd><p>HStore expression. Returns a subset of an hstore defined by
array of keys.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.Comparator.vals">
<code class="descname">vals</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator.vals" title="Permalink to this definition">¶</a></dt>
<dd><p>Text array expression. Returns array of values.</p>
</dd></dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>text_type=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE" title="sqlalchemy.dialects.postgresql.HSTORE"><code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.dialects.postgresql.HSTORE.params.text_type"></span><strong>text_type</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE.params.text_type">¶</a> – <p>the type that should be used for indexed values.
Defaults to <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Text" title="sqlalchemy.types.Text"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.Text</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.0.</span></p>
</div>
</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.bind_processor">
<code class="descname">bind_processor</code><span class="sig-paren">(</span><em>dialect</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.bind_processor" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a conversion function for processing bind values.</p>
<p>Returns a callable which will receive a bind parameter value
as the sole positional argument and will return a value to
send to the DB-API.</p>
<p>If processing is not necessary, the method should return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.dialects.postgresql.HSTORE.bind_processor.params.dialect"></span><strong>dialect</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE.bind_processor.params.dialect">¶</a> – Dialect instance in use.</p>
</dd>
</dl>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.comparator_factory">
<code class="descname">comparator_factory</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.comparator_factory" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE.Comparator" title="sqlalchemy.dialects.postgresql.HSTORE.Comparator"><code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE.Comparator</span></code></a></p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.HSTORE.result_processor">
<code class="descname">result_processor</code><span class="sig-paren">(</span><em>dialect</em>, <em>coltype</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.HSTORE.result_processor" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a conversion function for processing result row values.</p>
<p>Returns a callable which will receive a result row column
value as the sole positional argument and will return a value
to return to the user.</p>
<p>If processing is not necessary, the method should return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.HSTORE.result_processor.params.dialect"></span><strong>dialect</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE.result_processor.params.dialect">¶</a> – Dialect instance in use.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.HSTORE.result_processor.params.coltype"></span><strong>coltype</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE.result_processor.params.coltype">¶</a> – DBAPI coltype argument received in cursor.description.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.hstore">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">hstore</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.hstore" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/functions.html#sqlalchemy.sql.functions.GenericFunction" title="sqlalchemy.sql.functions.GenericFunction"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.sql.functions.GenericFunction</span></code></a></p>
<p>Construct an hstore value within a SQL expression using the
PostgreSQL <code class="docutils literal notranslate"><span class="pre">hstore()</span></code> function.</p>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.hstore" title="sqlalchemy.dialects.postgresql.hstore"><code class="xref py py-class docutils literal notranslate"><span class="pre">hstore</span></code></a> function accepts one or two arguments as described
in the PostgreSQL documentation.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">array</span><span class="p">,</span> <span class="n">hstore</span>
<span class="n">select</span><span class="p">([</span><span class="n">hstore</span><span class="p">(</span><span class="s1">'key1'</span><span class="p">,</span> <span class="s1">'value1'</span><span class="p">)])</span>
<span class="n">select</span><span class="p">([</span>
<span class="n">hstore</span><span class="p">(</span>
<span class="n">array</span><span class="p">([</span><span class="s1">'key1'</span><span class="p">,</span> <span class="s1">'key2'</span><span class="p">,</span> <span class="s1">'key3'</span><span class="p">]),</span>
<span class="n">array</span><span class="p">([</span><span class="s1">'value1'</span><span class="p">,</span> <span class="s1">'value2'</span><span class="p">,</span> <span class="s1">'value3'</span><span class="p">])</span>
<span class="p">)</span>
<span class="p">])</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE" title="sqlalchemy.dialects.postgresql.HSTORE"><code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE</span></code></a> - the PostgreSQL <code class="docutils literal notranslate"><span class="pre">HSTORE</span></code> datatype.</p>
</div>
<dl class="attribute">
<dt id="sqlalchemy.dialects.postgresql.hstore.type">
<code class="descname">type</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.hstore.type" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <a class="reference internal" href="#sqlalchemy.dialects.postgresql.HSTORE" title="sqlalchemy.dialects.postgresql.HSTORE"><code class="xref py py-class docutils literal notranslate"><span class="pre">HSTORE</span></code></a></p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.INET">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">INET</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.INET" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.INTERVAL">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">INTERVAL</code><span class="sig-paren">(</span><em>precision=None</em>, <em>fields=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.INTERVAL" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.NativeForEmulated</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types._AbstractInterval</span></code></p>
<p>PostgreSQL INTERVAL type.</p>
<p>The INTERVAL type may not be supported on all DBAPIs.
It is known to work on psycopg2 and not pg8000 or zxjdbc.</p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.INTERVAL.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>precision=None</em>, <em>fields=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.INTERVAL.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct an INTERVAL.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.INTERVAL.params.precision"></span><strong>precision</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.INTERVAL.params.precision">¶</a> – optional integer precision value</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.INTERVAL.params.fields"></span><strong>fields</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.INTERVAL.params.fields">¶</a> – <p>string fields specifier. allows storage of fields
to be limited, such as <code class="docutils literal notranslate"><span class="pre">"YEAR"</span></code>, <code class="docutils literal notranslate"><span class="pre">"MONTH"</span></code>, <code class="docutils literal notranslate"><span class="pre">"DAY</span> <span class="pre">TO</span> <span class="pre">HOUR"</span></code>,
etc.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.</span></p>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.JSON">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">JSON</code><span class="sig-paren">(</span><em>none_as_null=False</em>, <em>astext_type=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSON" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.JSON" title="sqlalchemy.types.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.JSON</span></code></a></p>
<p>Represent the PostgreSQL JSON type.</p>
<p>This type is a specialization of the Core-level <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.JSON" title="sqlalchemy.types.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.JSON</span></code></a>
type. Be sure to read the documentation for <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.JSON" title="sqlalchemy.types.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.JSON</span></code></a> for
important tips regarding treatment of NULL values and ORM use.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.1: </span><a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.JSON</span></code></a> is now a PostgreSQL-
specific specialization of the new <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.JSON" title="sqlalchemy.types.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.JSON</span></code></a> type.</p>
</div>
<p>The operators provided by the PostgreSQL version of <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a>
include:</p>
<ul>
<li><p>Index operations (the <code class="docutils literal notranslate"><span class="pre">-></span></code> operator):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">[</span><span class="s1">'some key'</span><span class="p">]</span>
<span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span></pre></div>
</div>
</li>
<li><p>Index operations returning text (the <code class="docutils literal notranslate"><span class="pre">->></span></code> operator):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">[</span><span class="s1">'some key'</span><span class="p">]</span><span class="o">.</span><span class="n">astext</span> <span class="o">==</span> <span class="s1">'some value'</span></pre></div>
</div>
</li>
<li><p>Index operations with CAST
(equivalent to <code class="docutils literal notranslate"><span class="pre">CAST(col</span> <span class="pre">->></span> <span class="pre">['some</span> <span class="pre">key']</span> <span class="pre">AS</span> <span class="pre"><type>)</span></code>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">[</span><span class="s1">'some key'</span><span class="p">]</span><span class="o">.</span><span class="n">astext</span><span class="o">.</span><span class="n">cast</span><span class="p">(</span><span class="n">Integer</span><span class="p">)</span> <span class="o">==</span> <span class="mi">5</span></pre></div>
</div>
</li>
<li><p>Path index operations (the <code class="docutils literal notranslate"><span class="pre">#></span></code> operator):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">[(</span><span class="s1">'key_1'</span><span class="p">,</span> <span class="s1">'key_2'</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="s1">'key_n'</span><span class="p">)]</span></pre></div>
</div>
</li>
<li><p>Path index operations returning text (the <code class="docutils literal notranslate"><span class="pre">#>></span></code> operator):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">[(</span><span class="s1">'key_1'</span><span class="p">,</span> <span class="s1">'key_2'</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="s1">'key_n'</span><span class="p">)]</span><span class="o">.</span><span class="n">astext</span> <span class="o">==</span> <span class="s1">'some value'</span></pre></div>
</div>
</li>
</ul>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.1: </span>The <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.ColumnElement.cast" title="sqlalchemy.sql.expression.ColumnElement.cast"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ColumnElement.cast()</span></code></a> operator on
JSON objects now requires that the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON.Comparator.astext" title="sqlalchemy.dialects.postgresql.JSON.Comparator.astext"><code class="xref py py-attr docutils literal notranslate"><span class="pre">JSON.Comparator.astext</span></code></a>
modifier be called explicitly, if the cast works only from a textual
string.</p>
</div>
<p>Index operations return an expression object whose type defaults to
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a> by default, so that further JSON-oriented instructions
may be called upon the result type.</p>
<p>Custom serializers and deserializers are specified at the dialect level,
that is using <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a>. The reason for this is that when
using psycopg2, the DBAPI only allows serializers at the per-cursor
or per-connection level. E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql://scott:tiger@localhost/test"</span><span class="p">,</span>
<span class="n">json_serializer</span><span class="o">=</span><span class="n">my_serialize_fn</span><span class="p">,</span>
<span class="n">json_deserializer</span><span class="o">=</span><span class="n">my_deserialize_fn</span>
<span class="p">)</span></pre></div>
</div>
<p>When using the psycopg2 dialect, the json_deserializer is registered
against the database using <code class="docutils literal notranslate"><span class="pre">psycopg2.extras.register_default_json</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.JSON" title="sqlalchemy.types.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.JSON</span></code></a> - Core level JSON type</p>
<p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB" title="sqlalchemy.dialects.postgresql.JSONB"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONB</span></code></a></p>
</div>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.JSON.Comparator">
<em class="property">class </em><code class="descname">Comparator</code><span class="sig-paren">(</span><em>expr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSON.Comparator" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Comparator</span></code></p>
<p>Define comparison operations for <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a>.</p>
<dl class="attribute">
<dt id="sqlalchemy.dialects.postgresql.JSON.Comparator.astext">
<code class="descname">astext</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSON.Comparator.astext" title="Permalink to this definition">¶</a></dt>
<dd><p>On an indexed expression, use the “astext” (e.g. “->>”)
conversion when rendered in SQL.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">select</span><span class="p">([</span><span class="n">data_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span><span class="p">[</span><span class="s1">'some key'</span><span class="p">]</span><span class="o">.</span><span class="n">astext</span><span class="p">])</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.ColumnElement.cast" title="sqlalchemy.sql.expression.ColumnElement.cast"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ColumnElement.cast()</span></code></a></p>
</div>
</dd></dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.JSON.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>none_as_null=False</em>, <em>astext_type=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSON.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a> type.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.JSON.params.none_as_null"></span><strong>none_as_null</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.JSON.params.none_as_null">¶</a> – <p>if True, persist the value <code class="docutils literal notranslate"><span class="pre">None</span></code> as a
SQL NULL value, not the JSON encoding of <code class="docutils literal notranslate"><span class="pre">null</span></code>. Note that
when this flag is False, the <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.null" title="sqlalchemy.sql.expression.null"><code class="xref py py-func docutils literal notranslate"><span class="pre">null()</span></code></a> construct can still
be used to persist a NULL value:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">null</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">(),</span> <span class="n">data</span><span class="o">=</span><span class="n">null</span><span class="p">())</span></pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.9.8: </span>- Added <code class="docutils literal notranslate"><span class="pre">none_as_null</span></code>, and <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.null" title="sqlalchemy.sql.expression.null"><code class="xref py py-func docutils literal notranslate"><span class="pre">null()</span></code></a>
is now supported in order to persist a NULL value.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.JSON.NULL" title="sqlalchemy.types.JSON.NULL"><code class="xref py py-attr docutils literal notranslate"><span class="pre">JSON.NULL</span></code></a></p>
</div>
</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.JSON.params.astext_type"></span><strong>astext_type</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.JSON.params.astext_type">¶</a> – <p>the type to use for the
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON.Comparator.astext" title="sqlalchemy.dialects.postgresql.JSON.Comparator.astext"><code class="xref py py-attr docutils literal notranslate"><span class="pre">JSON.Comparator.astext</span></code></a>
accessor on indexed attributes. Defaults to <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Text" title="sqlalchemy.types.Text"><code class="xref py py-class docutils literal notranslate"><span class="pre">types.Text</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.dialects.postgresql.JSON.comparator_factory">
<code class="descname">comparator_factory</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSON.comparator_factory" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON.Comparator" title="sqlalchemy.dialects.postgresql.JSON.Comparator"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON.Comparator</span></code></a></p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.JSONB">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">JSONB</code><span class="sig-paren">(</span><em>none_as_null=False</em>, <em>astext_type=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSONB" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.json.JSON</span></code></p>
<p>Represent the PostgreSQL JSONB type.</p>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB" title="sqlalchemy.dialects.postgresql.JSONB"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONB</span></code></a> type stores arbitrary JSONB format data, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">data_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'data_table'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'data'</span><span class="p">,</span> <span class="n">JSONB</span><span class="p">)</span>
<span class="p">)</span>
<span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="n">conn</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
<span class="n">data_table</span><span class="o">.</span><span class="n">insert</span><span class="p">(),</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"key1"</span><span class="p">:</span> <span class="s2">"value1"</span><span class="p">,</span> <span class="s2">"key2"</span><span class="p">:</span> <span class="s2">"value2"</span><span class="p">}</span>
<span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB" title="sqlalchemy.dialects.postgresql.JSONB"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONB</span></code></a> type includes all operations provided by
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a>, including the same behaviors for indexing operations.
It also adds additional operators specific to JSONB, including
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.has_key" title="sqlalchemy.dialects.postgresql.JSONB.Comparator.has_key"><code class="xref py py-meth docutils literal notranslate"><span class="pre">JSONB.Comparator.has_key()</span></code></a>, <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.has_all" title="sqlalchemy.dialects.postgresql.JSONB.Comparator.has_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">JSONB.Comparator.has_all()</span></code></a>,
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.has_any" title="sqlalchemy.dialects.postgresql.JSONB.Comparator.has_any"><code class="xref py py-meth docutils literal notranslate"><span class="pre">JSONB.Comparator.has_any()</span></code></a>, <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.contains" title="sqlalchemy.dialects.postgresql.JSONB.Comparator.contains"><code class="xref py py-meth docutils literal notranslate"><span class="pre">JSONB.Comparator.contains()</span></code></a>,
and <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.contained_by" title="sqlalchemy.dialects.postgresql.JSONB.Comparator.contained_by"><code class="xref py py-meth docutils literal notranslate"><span class="pre">JSONB.Comparator.contained_by()</span></code></a>.</p>
<p>Like the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a> type, the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB" title="sqlalchemy.dialects.postgresql.JSONB"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONB</span></code></a> type does not detect
in-place changes when used with the ORM, unless the
<a class="reference internal" href="../orm/extensions/mutable.html#module-sqlalchemy.ext.mutable" title="sqlalchemy.ext.mutable"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlalchemy.ext.mutable</span></code></a> extension is used.</p>
<p>Custom serializers and deserializers
are shared with the <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a> class, using the <code class="docutils literal notranslate"><span class="pre">json_serializer</span></code>
and <code class="docutils literal notranslate"><span class="pre">json_deserializer</span></code> keyword arguments. These must be specified
at the dialect level using <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a>. When using
psycopg2, the serializers are associated with the jsonb type using
<code class="docutils literal notranslate"><span class="pre">psycopg2.extras.register_default_jsonb</span></code> on a per-connection basis,
in the same way that <code class="docutils literal notranslate"><span class="pre">psycopg2.extras.register_default_json</span></code> is used
to register these handlers with the json type.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.7.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a></p>
</div>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.JSONB.Comparator">
<em class="property">class </em><code class="descname">Comparator</code><span class="sig-paren">(</span><em>expr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.json.Comparator</span></code></p>
<p>Define comparison operations for <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSON" title="sqlalchemy.dialects.postgresql.JSON"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSON</span></code></a>.</p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.JSONB.Comparator.contained_by">
<code class="descname">contained_by</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.contained_by" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test if keys are a proper subset of the
keys of the argument jsonb expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.JSONB.Comparator.contains">
<code class="descname">contains</code><span class="sig-paren">(</span><em>other</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test if keys (or array) are a superset
of/contained the keys of the argument jsonb expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.JSONB.Comparator.has_all">
<code class="descname">has_all</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.has_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test for presence of all keys in jsonb</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.JSONB.Comparator.has_any">
<code class="descname">has_any</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.has_any" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test for presence of any key in jsonb</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.JSONB.Comparator.has_key">
<code class="descname">has_key</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator.has_key" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Test for presence of a key. Note that the
key may be a SQLA expression.</p>
</dd></dl>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.dialects.postgresql.JSONB.comparator_factory">
<code class="descname">comparator_factory</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.JSONB.comparator_factory" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <a class="reference internal" href="#sqlalchemy.dialects.postgresql.JSONB.Comparator" title="sqlalchemy.dialects.postgresql.JSONB.Comparator"><code class="xref py py-class docutils literal notranslate"><span class="pre">JSONB.Comparator</span></code></a></p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.MACADDR">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">MACADDR</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.MACADDR" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.MONEY">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">MONEY</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.MONEY" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Provide the PostgreSQL MONEY type.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.</span></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.OID">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">OID</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.OID" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Provide the PostgreSQL OID type.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.5.</span></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.REAL">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">REAL</code><span class="sig-paren">(</span><em>precision=None</em>, <em>asdecimal=False</em>, <em>decimal_return_scale=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.REAL" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Float</span></code></a></p>
<p>The SQL REAL type.</p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.REAL.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>precision=None</em>, <em>asdecimal=False</em>, <em>decimal_return_scale=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.REAL.__init__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member docutils container">
<p><em>inherited from the</em> <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Float.__init__" title="sqlalchemy.types.Float.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> <em>method of</em> <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><code class="xref py py-class docutils literal notranslate"><span class="pre">Float</span></code></a></p>
</div>
<p>Construct a Float.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.REAL.params.precision"></span><strong>precision</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.REAL.params.precision">¶</a> – the numeric precision for use in DDL <code class="docutils literal notranslate"><span class="pre">CREATE</span>
<span class="pre">TABLE</span></code>.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.REAL.params.asdecimal"></span><strong>asdecimal</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.REAL.params.asdecimal">¶</a> – the same flag as that of <a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Numeric" title="sqlalchemy.types.Numeric"><code class="xref py py-class docutils literal notranslate"><span class="pre">Numeric</span></code></a>, but
defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. Note that setting this flag to <code class="docutils literal notranslate"><span class="pre">True</span></code>
results in floating point conversion.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.REAL.params.decimal_return_scale"></span><strong>decimal_return_scale</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.REAL.params.decimal_return_scale">¶</a> – <p>Default scale to use when converting
from floats to Python decimals. Floating point values will typically
be much longer due to decimal inaccuracy, and most floating point
database types don’t have a notion of “scale”, so by default the
float type looks for the first ten decimal places when converting.
Specifying this value will override that length. Note that the
MySQL float types, which do include “scale”, will use “scale”
as the default for decimal_return_scale, if not otherwise specified.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0.</span></p>
</div>
</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.REAL.params.**kwargs"></span><strong>**kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.REAL.params.**kwargs">¶</a> – <div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 0.9: </span>Additional keyword arguments are ignored by the base
<a class="reference internal" href="../core/type_basics.html#sqlalchemy.types.Float" title="sqlalchemy.types.Float"><code class="xref py py-class docutils literal notranslate"><span class="pre">Float</span></code></a> type, and keyword arguments will no longer
be accepted in a future release. For database specific floats
that support additional arguments, see that dialect’s
documentation for details, such as
<a class="reference internal" href="mysql.html#sqlalchemy.dialects.mysql.FLOAT" title="sqlalchemy.dialects.mysql.FLOAT"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.mysql.FLOAT</span></code></a>.</p>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.REGCLASS">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">REGCLASS</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.REGCLASS" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Provide the PostgreSQL REGCLASS type.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.7.</span></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.TSVECTOR">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">TSVECTOR</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.TSVECTOR" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>The <a class="reference internal" href="#sqlalchemy.dialects.postgresql.TSVECTOR" title="sqlalchemy.dialects.postgresql.TSVECTOR"><code class="xref py py-class docutils literal notranslate"><span class="pre">postgresql.TSVECTOR</span></code></a> type implements the PostgreSQL
text search type TSVECTOR.</p>
<p>It can be used to do full text queries on natural language
documents.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#postgresql-match"><span class="std std-ref">Full Text Search</span></a></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.UUID">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">UUID</code><span class="sig-paren">(</span><em>as_uuid=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.UUID" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>PostgreSQL UUID type.</p>
<p>Represents the UUID column type, interpreting
data either as natively returned by the DBAPI
or as Python uuid objects.</p>
<p>The UUID type may not be supported on all DBAPIs.
It is known to work on psycopg2 and not pg8000.</p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.UUID.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>as_uuid=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.UUID.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a UUID type.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.dialects.postgresql.UUID.params.as_uuid"></span><strong>as_uuid=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.UUID.params.as_uuid">¶</a> – if True, values will be interpreted
as Python uuid objects, converting to/from string via the
DBAPI.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
<div class="section" id="range-types">
<h3>Range Types<a class="headerlink" href="#range-types" title="Permalink to this headline">¶</a></h3>
<p>The new range column types found in PostgreSQL 9.2 onwards are
catered for by the following types:</p>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.INT4RANGE">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">INT4RANGE</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.INT4RANGE" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators" title="sqlalchemy.dialects.postgresql.ranges.RangeOperators"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.ranges.RangeOperators</span></code></a>, <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Represent the PostgreSQL INT4RANGE type.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.INT8RANGE">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">INT8RANGE</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.INT8RANGE" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators" title="sqlalchemy.dialects.postgresql.ranges.RangeOperators"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.ranges.RangeOperators</span></code></a>, <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Represent the PostgreSQL INT8RANGE type.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.NUMRANGE">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">NUMRANGE</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.NUMRANGE" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators" title="sqlalchemy.dialects.postgresql.ranges.RangeOperators"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.ranges.RangeOperators</span></code></a>, <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Represent the PostgreSQL NUMRANGE type.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.DATERANGE">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">DATERANGE</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.DATERANGE" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators" title="sqlalchemy.dialects.postgresql.ranges.RangeOperators"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.ranges.RangeOperators</span></code></a>, <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Represent the PostgreSQL DATERANGE type.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.TSRANGE">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">TSRANGE</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.TSRANGE" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators" title="sqlalchemy.dialects.postgresql.ranges.RangeOperators"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.ranges.RangeOperators</span></code></a>, <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Represent the PostgreSQL TSRANGE type.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.TSTZRANGE">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">TSTZRANGE</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.TSTZRANGE" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators" title="sqlalchemy.dialects.postgresql.ranges.RangeOperators"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.ranges.RangeOperators</span></code></a>, <a class="reference internal" href="../core/type_api.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.TypeEngine</span></code></a></p>
<p>Represent the PostgreSQL TSTZRANGE type.</p>
</dd></dl>
<p>The types above get most of their functionality from the following
mixin:</p>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.ranges.</code><code class="descname">RangeOperators</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators" title="Permalink to this definition">¶</a></dt>
<dd><p>This mixin provides functionality for the Range Operators
listed in Table 9-44 of the <a class="reference external" href="http://www.postgresql.org/docs/devel/static/functions-range.html">postgres documentation</a> for Range
Functions and Operators. It is used by all the range types
provided in the <code class="docutils literal notranslate"><span class="pre">postgres</span></code> dialect and can likely be used for
any range types you create yourself.</p>
<p>No extra support is provided for the Range Functions listed in
Table 9-45 of the postgres documentation. For these, the normal
<a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><code class="xref py py-func docutils literal notranslate"><span class="pre">func()</span></code></a> object should be used.</p>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory">
<em class="property">class </em><code class="descname">comparator_factory</code><span class="sig-paren">(</span><em>expr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.types.Comparator</span></code></p>
<p>Define comparison operations for range types.</p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.__ne__">
<code class="descname">__ne__</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.__ne__" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if two ranges are not equal</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.adjacent_to">
<code class="descname">adjacent_to</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.adjacent_to" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if the range in the column
is adjacent to the range in the operand.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.contained_by">
<code class="descname">contained_by</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.contained_by" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if the column is contained
within the right hand operand.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.contains">
<code class="descname">contains</code><span class="sig-paren">(</span><em>other</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if the right hand operand,
which can be an element or a range, is contained within the
column.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.not_extend_left_of">
<code class="descname">not_extend_left_of</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.not_extend_left_of" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if the range in the column
does not extend left of the range in the operand.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.not_extend_right_of">
<code class="descname">not_extend_right_of</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.not_extend_right_of" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if the range in the column
does not extend right of the range in the operand.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.overlaps">
<code class="descname">overlaps</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.overlaps" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if the column overlaps
(has points in common with) the right hand operand.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.strictly_left_of">
<code class="descname">strictly_left_of</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.strictly_left_of" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if the column is strictly
left of the right hand operand.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.strictly_right_of">
<code class="descname">strictly_right_of</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.strictly_right_of" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean expression. Returns true if the column is strictly
right of the right hand operand.</p>
</dd></dl>
</dd></dl>
</dd></dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The range type DDL support should work with any PostgreSQL DBAPI
driver, however the data types returned may vary. If you are using
<code class="docutils literal notranslate"><span class="pre">psycopg2</span></code>, it’s recommended to upgrade to version 2.5 or later
before using these column types.</p>
</div>
<p>When instantiating models that use these column types, you should pass
whatever data type is expected by the DBAPI driver you’re using for
the column type. For <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code> these are
<code class="docutils literal notranslate"><span class="pre">psycopg2.extras.NumericRange</span></code>,
<code class="docutils literal notranslate"><span class="pre">psycopg2.extras.DateRange</span></code>,
<code class="docutils literal notranslate"><span class="pre">psycopg2.extras.DateTimeRange</span></code> and
<code class="docutils literal notranslate"><span class="pre">psycopg2.extras.DateTimeTZRange</span></code> or the class you’ve
registered with <code class="docutils literal notranslate"><span class="pre">psycopg2.extras.register_range</span></code>.</p>
<p>For example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">psycopg2.extras</span> <span class="kn">import</span> <span class="n">DateTimeRange</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="kn">import</span> <span class="n">TSRANGE</span>
<span class="k">class</span> <span class="nc">RoomBooking</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'room_booking'</span>
<span class="n">room</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">(),</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">during</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">TSRANGE</span><span class="p">())</span>
<span class="n">booking</span> <span class="o">=</span> <span class="n">RoomBooking</span><span class="p">(</span>
<span class="n">room</span><span class="o">=</span><span class="mi">101</span><span class="p">,</span>
<span class="n">during</span><span class="o">=</span><span class="n">DateTimeRange</span><span class="p">(</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2013</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">23</span><span class="p">),</span> <span class="bp">None</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</div>
</div>
<div class="section" id="postgresql-constraint-types">
<h2>PostgreSQL Constraint Types<a class="headerlink" href="#postgresql-constraint-types" title="Permalink to this headline">¶</a></h2>
<p>SQLAlchemy supports PostgreSQL EXCLUDE constraints via the
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint" title="sqlalchemy.dialects.postgresql.ExcludeConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExcludeConstraint</span></code></a> class:</p>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.ExcludeConstraint">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.</code><code class="descname">ExcludeConstraint</code><span class="sig-paren">(</span><em>*elements</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/constraints.html#sqlalchemy.schema.ColumnCollectionConstraint" title="sqlalchemy.schema.ColumnCollectionConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.schema.ColumnCollectionConstraint</span></code></a></p>
<p>A table-level EXCLUDE constraint.</p>
<p>Defines an EXCLUDE constraint as described in the <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/sql-createtable.html#SQL-CREATETABLE-EXCLUDE">postgres
documentation</a>.</p>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.ExcludeConstraint.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>*elements</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an <a class="reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint" title="sqlalchemy.dialects.postgresql.ExcludeConstraint"><code class="xref py py-class docutils literal notranslate"><span class="pre">ExcludeConstraint</span></code></a> object.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">const</span> <span class="o">=</span> <span class="n">ExcludeConstraint</span><span class="p">(</span>
<span class="p">(</span><span class="n">Column</span><span class="p">(</span><span class="s1">'period'</span><span class="p">),</span> <span class="s1">'&&'</span><span class="p">),</span>
<span class="p">(</span><span class="n">Column</span><span class="p">(</span><span class="s1">'group'</span><span class="p">),</span> <span class="s1">'='</span><span class="p">),</span>
<span class="n">where</span><span class="o">=</span><span class="p">(</span><span class="n">Column</span><span class="p">(</span><span class="s1">'group'</span><span class="p">)</span> <span class="o">!=</span> <span class="s1">'some group'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The constraint is normally embedded into the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> construct
directly, or added later using <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table.append_constraint" title="sqlalchemy.schema.Table.append_constraint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">append_constraint()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">some_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span>
<span class="s1">'some_table'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">),</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'period'</span><span class="p">,</span> <span class="n">TSRANGE</span><span class="p">()),</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'group'</span><span class="p">,</span> <span class="n">String</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">some_table</span><span class="o">.</span><span class="n">append_constraint</span><span class="p">(</span>
<span class="n">ExcludeConstraint</span><span class="p">(</span>
<span class="p">(</span><span class="n">some_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">period</span><span class="p">,</span> <span class="s1">'&&'</span><span class="p">),</span>
<span class="p">(</span><span class="n">some_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">group</span><span class="p">,</span> <span class="s1">'='</span><span class="p">),</span>
<span class="n">where</span><span class="o">=</span><span class="n">some_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">group</span> <span class="o">!=</span> <span class="s1">'some group'</span><span class="p">,</span>
<span class="n">name</span><span class="o">=</span><span class="s1">'some_table_excl_const'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ExcludeConstraint.params.*elements"></span><strong>*elements</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint.params.*elements">¶</a> – <p>A sequence of two tuples of the form <code class="docutils literal notranslate"><span class="pre">(column,</span> <span class="pre">operator)</span></code> where
“column” is a SQL expression element or a raw SQL string, most
typically a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a> object,
and “operator” is a string containing the operator to use.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>A plain string passed for the value of “column” is interpreted
as an arbitrary SQL expression; when passing a plain string,
any necessary quoting and escaping syntaxes must be applied
manually. In order to specify a column name when a
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a> object is not available, while ensuring that
any necessary quoting rules take effect, an ad-hoc
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a> or <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><code class="xref py py-func docutils literal notranslate"><span class="pre">sql.expression.column()</span></code></a> object may
be used.</p>
</div>
</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ExcludeConstraint.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint.params.name">¶</a> – Optional, the in-database name of this constraint.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ExcludeConstraint.params.deferrable"></span><strong>deferrable</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint.params.deferrable">¶</a> – Optional bool. If set, emit DEFERRABLE or NOT DEFERRABLE when
issuing DDL for this constraint.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ExcludeConstraint.params.initially"></span><strong>initially</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint.params.initially">¶</a> – Optional string. If set, emit INITIALLY <value> when issuing DDL
for this constraint.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ExcludeConstraint.params.using"></span><strong>using</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint.params.using">¶</a> – Optional string. If set, emit USING <index_method> when issuing DDL
for this constraint. Defaults to ‘gist’.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.ExcludeConstraint.params.where"></span><strong>where</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.ExcludeConstraint.params.where">¶</a> – <p>Optional SQL expression construct or literal SQL string.
If set, emit WHERE <predicate> when issuing DDL
for this constraint.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>A plain string passed here is interpreted as an arbitrary SQL
expression; when passing a plain string, any necessary quoting
and escaping syntaxes must be applied manually.</p>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</dd></dl>
<p>For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.dialects.postgresql</span> <span class="k">import</span> <span class="n">ExcludeConstraint</span><span class="p">,</span> <span class="n">TSRANGE</span>
<span class="k">class</span> <span class="nc">RoomBooking</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'room_booking'</span>
<span class="n">room</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">(),</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">during</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">TSRANGE</span><span class="p">())</span>
<span class="n">__table_args__</span> <span class="o">=</span> <span class="p">(</span>
<span class="n">ExcludeConstraint</span><span class="p">((</span><span class="s1">'room'</span><span class="p">,</span> <span class="s1">'='</span><span class="p">),</span> <span class="p">(</span><span class="s1">'during'</span><span class="p">,</span> <span class="s1">'&&'</span><span class="p">)),</span>
<span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="postgresql-dml-constructs">
<h2>PostgreSQL DML Constructs<a class="headerlink" href="#postgresql-dml-constructs" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="sqlalchemy.dialects.postgresql.dml.insert">
<code class="descclassname">sqlalchemy.dialects.postgresql.dml.</code><code class="descname">insert</code><span class="sig-paren">(</span><em>table</em>, <em>values=None</em>, <em>inline=False</em>, <em>bind=None</em>, <em>prefixes=None</em>, <em>returning=None</em>, <em>return_defaults=False</em>, <em>**dialect_kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.dml.insert" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert" title="sqlalchemy.dialects.postgresql.dml.Insert"><code class="xref py py-class docutils literal notranslate"><span class="pre">Insert</span></code></a> object.</p>
<p>This constructor is mirrored as a public API function; see <code class="xref py py-func docutils literal notranslate"><span class="pre">insert()</span></code> for a full usage and argument description.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.dialects.postgresql.dml.Insert">
<em class="property">class </em><code class="descclassname">sqlalchemy.dialects.postgresql.dml.</code><code class="descname">Insert</code><span class="sig-paren">(</span><em>table</em>, <em>values=None</em>, <em>inline=False</em>, <em>bind=None</em>, <em>prefixes=None</em>, <em>returning=None</em>, <em>return_defaults=False</em>, <em>**dialect_kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.dml.Insert" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="../core/dml.html#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.sql.expression.Insert</span></code></a></p>
<p>PostgreSQL-specific implementation of INSERT.</p>
<p>Adds methods for PG-specific syntaxes such as ON CONFLICT.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
<dl class="attribute">
<dt id="sqlalchemy.dialects.postgresql.dml.Insert.excluded">
<code class="descname">excluded</code><a class="headerlink" href="#sqlalchemy.dialects.postgresql.dml.Insert.excluded" title="Permalink to this definition">¶</a></dt>
<dd><p>Provide the <code class="docutils literal notranslate"><span class="pre">excluded</span></code> namespace for an ON CONFLICT statement</p>
<p>PG’s ON CONFLICT clause allows reference to the row that would
be inserted, known as <code class="docutils literal notranslate"><span class="pre">excluded</span></code>. This attribute provides
all columns in this row to be referenceable.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#postgresql-insert-on-conflict"><span class="std std-ref">INSERT…ON CONFLICT (Upsert)</span></a> - example of how
to use <a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.excluded" title="sqlalchemy.dialects.postgresql.dml.Insert.excluded"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Insert.excluded</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing">
<code class="descname">on_conflict_do_nothing</code><span class="sig-paren">(</span><em>constraint=None</em>, <em>index_elements=None</em>, <em>index_where=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies a DO NOTHING action for ON CONFLICT clause.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">constraint</span></code> and <code class="docutils literal notranslate"><span class="pre">index_elements</span></code> arguments
are optional, but only one of these can be specified.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing.params.constraint"></span><strong>constraint</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing.params.constraint">¶</a> – The name of a unique or exclusion constraint on the table,
or the constraint object itself if it has a .name attribute.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing.params.index_elements"></span><strong>index_elements</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing.params.index_elements">¶</a> – A sequence consisting of string column names, <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a>
objects, or other column expression objects that will be used
to infer a target index.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing.params.index_where"></span><strong>index_where</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_nothing.params.index_where">¶</a> – <p>Additional WHERE criterion that can be used to infer a
conditional target index.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#postgresql-insert-on-conflict"><span class="std std-ref">INSERT…ON CONFLICT (Upsert)</span></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update">
<code class="descname">on_conflict_do_update</code><span class="sig-paren">(</span><em>constraint=None</em>, <em>index_elements=None</em>, <em>index_where=None</em>, <em>set_=None</em>, <em>where=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies a DO UPDATE SET action for ON CONFLICT clause.</p>
<p>Either the <code class="docutils literal notranslate"><span class="pre">constraint</span></code> or <code class="docutils literal notranslate"><span class="pre">index_elements</span></code> argument is
required, but only one of these can be specified.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.constraint"></span><strong>constraint</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.constraint">¶</a> – The name of a unique or exclusion constraint on the table,
or the constraint object itself if it has a .name attribute.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.index_elements"></span><strong>index_elements</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.index_elements">¶</a> – A sequence consisting of string column names, <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a>
objects, or other column expression objects that will be used
to infer a target index.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.index_where"></span><strong>index_where</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.index_where">¶</a> – Additional WHERE criterion that can be used to infer a
conditional target index.</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.set_"></span><strong>set_</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.set_">¶</a> – <p>Required argument. A dictionary or other mapping object
with column names as keys and expressions or literals as values,
specifying the <code class="docutils literal notranslate"><span class="pre">SET</span></code> actions to take.
If the target <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a> specifies a “.key” attribute distinct
from the column name, that key should be used.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This dictionary does <strong>not</strong> take into account
Python-specified default UPDATE values or generation functions,
e.g. those specified using <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column.params.onupdate" title="sqlalchemy.schema.Column"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Column.onupdate</span></code></a>.
These values will not be exercised for an ON CONFLICT style of
UPDATE, unless they are manually specified in the
<a class="reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.set_" title="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Insert.on_conflict_do_update.set_</span></code></a> dictionary.</p>
</div>
</p></li>
<li><p><span class="target" id="sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.where"></span><strong>where</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.dialects.postgresql.dml.Insert.on_conflict_do_update.params.where">¶</a> – <p>Optional argument. If present, can be a literal SQL
string or an acceptable expression for a <code class="docutils literal notranslate"><span class="pre">WHERE</span></code> clause
that restricts the rows affected by <code class="docutils literal notranslate"><span class="pre">DO</span> <span class="pre">UPDATE</span> <span class="pre">SET</span></code>. Rows
not meeting the <code class="docutils literal notranslate"><span class="pre">WHERE</span></code> condition will not be updated
(effectively a <code class="docutils literal notranslate"><span class="pre">DO</span> <span class="pre">NOTHING</span></code> for those rows).</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#postgresql-insert-on-conflict"><span class="std std-ref">INSERT…ON CONFLICT (Upsert)</span></a></p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="module-sqlalchemy.dialects.postgresql.psycopg2">
<span id="psycopg2"></span><h2>psycopg2<a class="headerlink" href="#module-sqlalchemy.dialects.postgresql.psycopg2" title="Permalink to this headline">¶</a></h2>
<p>Support for the PostgreSQL database via the psycopg2 driver.</p>
<div class="section" id="dialect-postgresql-psycopg2-url">
<h3>DBAPI<a class="headerlink" href="#dialect-postgresql-psycopg2-url" title="Permalink to this headline">¶</a></h3>
<p>Documentation and download information (if applicable) for psycopg2 is available at:
<a class="reference external" href="http://pypi.python.org/pypi/psycopg2/">http://pypi.python.org/pypi/psycopg2/</a></p>
</div>
<div class="section" id="dialect-postgresql-psycopg2-connect">
<h3>Connecting<a class="headerlink" href="#dialect-postgresql-psycopg2-connect" title="Permalink to this headline">¶</a></h3>
<p>Connect String:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...]</pre></div>
</div>
</p>
</div>
<div class="section" id="psycopg2-connect-arguments">
<h3>psycopg2 Connect Arguments<a class="headerlink" href="#psycopg2-connect-arguments" title="Permalink to this headline">¶</a></h3>
<p>psycopg2-specific keyword arguments which are accepted by
<a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a> are:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">server_side_cursors</span></code>: Enable the usage of “server side cursors” for SQL
statements which support this feature. What this essentially means from a
psycopg2 point of view is that the cursor is created using a name, e.g.
<code class="docutils literal notranslate"><span class="pre">connection.cursor('some</span> <span class="pre">name')</span></code>, which has the effect that result rows
are not immediately pre-fetched and buffered after statement execution, but
are instead left on the server and only retrieved as needed. SQLAlchemy’s
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">ResultProxy</span></code></a> uses special row-buffering
behavior when this feature is enabled, such that groups of 100 rows at a
time are fetched over the wire to reduce conversational overhead.
Note that the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection.execution_options.params.stream_results" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Connection.execution_options.stream_results</span></code></a>
execution option is a more targeted
way of enabling this mode on a per-execution basis.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">use_native_unicode</span></code>: Enable the usage of Psycopg2 “native unicode” mode
per connection. True by default.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#psycopg2-disable-native-unicode"><span class="std std-ref">Disabling Native Unicode</span></a></p>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">isolation_level</span></code>: This option, available for all PostgreSQL dialects,
includes the <code class="docutils literal notranslate"><span class="pre">AUTOCOMMIT</span></code> isolation level when using the psycopg2
dialect.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#psycopg2-isolation-level"><span class="std std-ref">Psycopg2 Transaction Isolation Level</span></a></p>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">client_encoding</span></code>: sets the client encoding in a libpq-agnostic way,
using psycopg2’s <code class="docutils literal notranslate"><span class="pre">set_client_encoding()</span></code> method.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#psycopg2-unicode"><span class="std std-ref">Unicode with Psycopg2</span></a></p>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">use_batch_mode</span></code>: This flag allows <code class="docutils literal notranslate"><span class="pre">psycopg2.extras.execute_batch</span></code>
for <code class="docutils literal notranslate"><span class="pre">cursor.executemany()</span></code> calls performed by the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>.
It is currently experimental but
may well become True by default as it is critical for executemany
performance.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#psycopg2-batch-mode"><span class="std std-ref">Psycopg2 Batch Mode (Fast Execution)</span></a></p>
</div>
</li>
</ul>
</div>
<div class="section" id="unix-domain-connections">
<h3>Unix Domain Connections<a class="headerlink" href="#unix-domain-connections" title="Permalink to this headline">¶</a></h3>
<p>psycopg2 supports connecting via Unix domain connections. When the <code class="docutils literal notranslate"><span class="pre">host</span></code>
portion of the URL is omitted, SQLAlchemy passes <code class="docutils literal notranslate"><span class="pre">None</span></code> to psycopg2,
which specifies Unix-domain communication rather than TCP/IP communication:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql+psycopg2://user:password@/dbname"</span><span class="p">)</span></pre></div>
</div>
<p>By default, the socket file used is to connect to a Unix-domain socket
in <code class="docutils literal notranslate"><span class="pre">/tmp</span></code>, or whatever socket directory was specified when PostgreSQL
was built. This value can be overridden by passing a pathname to psycopg2,
using <code class="docutils literal notranslate"><span class="pre">host</span></code> as an additional keyword argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql+psycopg2://user:password@/dbname?host=/var/lib/postgresql"</span><span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference external" href="http://www.postgresql.org/docs/9.1/static/libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS">PQconnectdbParams </a></p>
</div>
</div>
<div class="section" id="per-statement-connection-execution-options">
<span id="psycopg2-execution-options"></span><h3>Per-Statement/Connection Execution Options<a class="headerlink" href="#per-statement-connection-execution-options" title="Permalink to this headline">¶</a></h3>
<p>The following DBAPI-specific options are respected when used with
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a>, <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Executable.execution_options()</span></code></a>,
<a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query.execution_options" title="sqlalchemy.orm.query.Query.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.execution_options()</span></code></a>, in addition to those not specific to DBAPIs:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">isolation_level</span></code> - Set the transaction isolation level for the lifespan
of a <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> (can only be set on a connection, not a statement
or query). See <a class="reference internal" href="#psycopg2-isolation-level"><span class="std std-ref">Psycopg2 Transaction Isolation Level</span></a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stream_results</span></code> - Enable or disable usage of psycopg2 server side
cursors - this feature makes use of “named” cursors in combination with
special result handling methods so that result rows are not fully buffered.
If <code class="docutils literal notranslate"><span class="pre">None</span></code> or not set, the <code class="docutils literal notranslate"><span class="pre">server_side_cursors</span></code> option of the
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> is used.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">max_row_buffer</span></code> - when using <code class="docutils literal notranslate"><span class="pre">stream_results</span></code>, an integer value that
specifies the maximum number of rows to buffer at a time. This is
interpreted by the <code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRowResultProxy</span></code>, and if omitted the
buffer will grow to ultimately store 1000 rows at a time.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.6.</span></p>
</div>
</li>
</ul>
</div>
<div class="section" id="psycopg2-batch-mode-fast-execution">
<span id="psycopg2-batch-mode"></span><h3>Psycopg2 Batch Mode (Fast Execution)<a class="headerlink" href="#psycopg2-batch-mode-fast-execution" title="Permalink to this headline">¶</a></h3>
<p>Modern versions of psycopg2 include a feature known as
<a class="reference external" href="http://initd.org/psycopg/docs/extras.html#fast-execution-helpers">Fast Execution Helpers </a>,
which have been shown in benchmarking to improve psycopg2’s executemany()
performance with INSERTS by multiple orders of magnitude. SQLAlchemy
allows this extension to be used for all <code class="docutils literal notranslate"><span class="pre">executemany()</span></code> style calls
invoked by an <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> when used with <a class="reference internal" href="../core/tutorial.html#execute-multiple"><span class="std std-ref">multiple parameter sets</span></a>,
by adding the <code class="docutils literal notranslate"><span class="pre">use_batch_mode</span></code> flag to <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span>
<span class="s2">"postgresql+psycopg2://scott:tiger@host/dbname"</span><span class="p">,</span>
<span class="n">use_batch_mode</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></pre></div>
</div>
<p>Batch mode is considered to be <strong>experimental</strong> at this time, however may
be enabled by default in a future release.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/tutorial.html#execute-multiple"><span class="std std-ref">Executing Multiple Statements</span></a> - demonstrates how to use DBAPI <code class="docutils literal notranslate"><span class="pre">executemany()</span></code>
with the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">Connection</span></code></a> object.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.0.</span></p>
</div>
</div>
<div class="section" id="unicode-with-psycopg2">
<span id="psycopg2-unicode"></span><h3>Unicode with Psycopg2<a class="headerlink" href="#unicode-with-psycopg2" title="Permalink to this headline">¶</a></h3>
<p>By default, the psycopg2 driver uses the <code class="docutils literal notranslate"><span class="pre">psycopg2.extensions.UNICODE</span></code>
extension, such that the DBAPI receives and returns all strings as Python
Unicode objects directly - SQLAlchemy passes these values through without
change. Psycopg2 here will encode/decode string values based on the
current “client encoding” setting; by default this is the value in
the <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code> file, which often defaults to <code class="docutils literal notranslate"><span class="pre">SQL_ASCII</span></code>.
Typically, this can be changed to <code class="docutils literal notranslate"><span class="pre">utf8</span></code>, as a more useful default:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># postgresql.conf file</span>
<span class="c1"># client_encoding = sql_ascii # actually, defaults to database</span>
<span class="c1"># encoding</span>
<span class="n">client_encoding</span> <span class="o">=</span> <span class="n">utf8</span></pre></div>
</div>
<p>A second way to affect the client encoding is to set it within Psycopg2
locally. SQLAlchemy will call psycopg2’s
<code class="xref py py-meth docutils literal notranslate"><span class="pre">psycopg2:connection.set_client_encoding()</span></code> method
on all new connections based on the value passed to
<a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a> using the <code class="docutils literal notranslate"><span class="pre">client_encoding</span></code> parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># set_client_encoding() setting;</span>
<span class="c1"># works for *all* PostgreSQL versions</span>
<span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql://user:pass@host/dbname"</span><span class="p">,</span>
<span class="n">client_encoding</span><span class="o">=</span><span class="s1">'utf8'</span><span class="p">)</span></pre></div>
</div>
<p>This overrides the encoding specified in the PostgreSQL client configuration.
When using the parameter in this way, the psycopg2 driver emits
<code class="docutils literal notranslate"><span class="pre">SET</span> <span class="pre">client_encoding</span> <span class="pre">TO</span> <span class="pre">'utf8'</span></code> on the connection explicitly, and works
in all PostgreSQL versions.</p>
<p>Note that the <code class="docutils literal notranslate"><span class="pre">client_encoding</span></code> setting as passed to <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a>
is <strong>not the same</strong> as the more recently added <code class="docutils literal notranslate"><span class="pre">client_encoding</span></code> parameter
now supported by libpq directly. This is enabled when <code class="docutils literal notranslate"><span class="pre">client_encoding</span></code>
is passed directly to <code class="docutils literal notranslate"><span class="pre">psycopg2.connect()</span></code>, and from SQLAlchemy is passed
using the <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine.params.connect_args" title="sqlalchemy.create_engine"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">create_engine.connect_args</span></code></a> parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span>
<span class="s2">"postgresql://user:pass@host/dbname"</span><span class="p">,</span>
<span class="n">connect_args</span><span class="o">=</span><span class="p">{</span><span class="s1">'client_encoding'</span><span class="p">:</span> <span class="s1">'utf8'</span><span class="p">})</span>
<span class="c1"># using the query string is equivalent</span>
<span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql://user:pass@host/dbname?client_encoding=utf8"</span><span class="p">)</span></pre></div>
</div>
<p>The above parameter was only added to libpq as of version 9.1 of PostgreSQL,
so using the previous method is better for cross-version support.</p>
<div class="section" id="disabling-native-unicode">
<span id="psycopg2-disable-native-unicode"></span><h4>Disabling Native Unicode<a class="headerlink" href="#disabling-native-unicode" title="Permalink to this headline">¶</a></h4>
<p>SQLAlchemy can also be instructed to skip the usage of the psycopg2
<code class="docutils literal notranslate"><span class="pre">UNICODE</span></code> extension and to instead utilize its own unicode encode/decode
services, which are normally reserved only for those DBAPIs that don’t
fully support unicode directly. Passing <code class="docutils literal notranslate"><span class="pre">use_native_unicode=False</span></code> to
<a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a> will disable usage of <code class="docutils literal notranslate"><span class="pre">psycopg2.extensions.UNICODE</span></code>.
SQLAlchemy will instead encode data itself into Python bytestrings on the way
in and coerce from bytes on the way back,
using the value of the <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a> <code class="docutils literal notranslate"><span class="pre">encoding</span></code> parameter, which
defaults to <code class="docutils literal notranslate"><span class="pre">utf-8</span></code>.
SQLAlchemy’s own unicode encode/decode functionality is steadily becoming
obsolete as most DBAPIs now support unicode fully.</p>
</div>
</div>
<div class="section" id="bound-parameter-styles">
<h3>Bound Parameter Styles<a class="headerlink" href="#bound-parameter-styles" title="Permalink to this headline">¶</a></h3>
<p>The default parameter style for the psycopg2 dialect is “pyformat”, where
SQL is rendered using <code class="docutils literal notranslate"><span class="pre">%(paramname)s</span></code> style. This format has the limitation
that it does not accommodate the unusual case of parameter names that
actually contain percent or parenthesis symbols; as SQLAlchemy in many cases
generates bound parameter names based on the name of a column, the presence
of these characters in a column name can lead to problems.</p>
<p>There are two solutions to the issue of a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">schema.Column</span></code></a> that contains
one of these characters in its name. One is to specify the
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column.params.key" title="sqlalchemy.schema.Column"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">schema.Column.key</span></code></a> for columns that have such names:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">measurement</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'measurement'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">Column</span><span class="p">(</span><span class="s1">'Size (meters)'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s1">'size_meters'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Above, an INSERT statement such as <code class="docutils literal notranslate"><span class="pre">measurement.insert()</span></code> will use
<code class="docutils literal notranslate"><span class="pre">size_meters</span></code> as the parameter name, and a SQL expression such as
<code class="docutils literal notranslate"><span class="pre">measurement.c.size_meters</span> <span class="pre">></span> <span class="pre">10</span></code> will derive the bound parameter name
from the <code class="docutils literal notranslate"><span class="pre">size_meters</span></code> key as well.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.0.0: </span>- SQL expressions will use <code class="xref py py-attr docutils literal notranslate"><span class="pre">Column.key</span></code>
as the source of naming when anonymous bound parameters are created
in SQL expressions; previously, this behavior only applied to
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table.insert" title="sqlalchemy.schema.Table.insert"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.insert()</span></code></a> and <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table.update" title="sqlalchemy.schema.Table.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.update()</span></code></a> parameter names.</p>
</div>
<p>The other solution is to use a positional format; psycopg2 allows use of the
“format” paramstyle, which can be passed to
<a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine.params.paramstyle" title="sqlalchemy.create_engine"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">create_engine.paramstyle</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span>
<span class="s1">'postgresql://scott:tiger@localhost:5432/test'</span><span class="p">,</span> <span class="n">paramstyle</span><span class="o">=</span><span class="s1">'format'</span><span class="p">)</span></pre></div>
</div>
<p>With the above engine, instead of a statement like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">INSERT</span> <span class="n">INTO</span> <span class="n">measurement</span> <span class="p">(</span><span class="s2">"Size (meters)"</span><span class="p">)</span> <span class="n">VALUES</span> <span class="p">(</span><span class="o">%</span><span class="p">(</span><span class="n">Size</span> <span class="p">(</span><span class="n">meters</span><span class="p">))</span><span class="n">s</span><span class="p">)</span>
<span class="p">{</span><span class="s1">'Size (meters)'</span><span class="p">:</span> <span class="mi">1</span><span class="p">}</span></pre></div>
</div>
<p>we instead see:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">INSERT</span> <span class="n">INTO</span> <span class="n">measurement</span> <span class="p">(</span><span class="s2">"Size (meters)"</span><span class="p">)</span> <span class="n">VALUES</span> <span class="p">(</span><span class="o">%</span><span class="n">s</span><span class="p">)</span>
<span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="p">)</span></pre></div>
</div>
<p>Where above, the dictionary style is converted into a tuple with positional
style.</p>
</div>
<div class="section" id="transactions">
<h3>Transactions<a class="headerlink" href="#transactions" title="Permalink to this headline">¶</a></h3>
<p>The psycopg2 dialect fully supports SAVEPOINT and two-phase commit operations.</p>
</div>
<div class="section" id="psycopg2-transaction-isolation-level">
<span id="psycopg2-isolation-level"></span><h3>Psycopg2 Transaction Isolation Level<a class="headerlink" href="#psycopg2-transaction-isolation-level" title="Permalink to this headline">¶</a></h3>
<p>As discussed in <a class="reference internal" href="#postgresql-isolation-level"><span class="std std-ref">Transaction Isolation Level</span></a>,
all PostgreSQL dialects support setting of transaction isolation level
both via the <code class="docutils literal notranslate"><span class="pre">isolation_level</span></code> parameter passed to <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a>,
as well as the <code class="docutils literal notranslate"><span class="pre">isolation_level</span></code> argument used by
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a>. When using the psycopg2 dialect, these
options make use of psycopg2’s <code class="docutils literal notranslate"><span class="pre">set_isolation_level()</span></code> connection method,
rather than emitting a PostgreSQL directive; this is because psycopg2’s
API-level setting is always emitted at the start of each transaction in any
case.</p>
<p>The psycopg2 dialect supports these constants for isolation level:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">READ</span> <span class="pre">COMMITTED</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">READ</span> <span class="pre">UNCOMMITTED</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">REPEATABLE</span> <span class="pre">READ</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">SERIALIZABLE</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">AUTOCOMMIT</span></code></p></li>
</ul>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#postgresql-isolation-level"><span class="std std-ref">Transaction Isolation Level</span></a></p>
<p><a class="reference internal" href="#pg8000-isolation-level"><span class="std std-ref">pg8000 Transaction Isolation Level</span></a></p>
</div>
</div>
<div class="section" id="notice-logging">
<h3>NOTICE logging<a class="headerlink" href="#notice-logging" title="Permalink to this headline">¶</a></h3>
<p>The psycopg2 dialect will log PostgreSQL NOTICE messages
via the <code class="docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql</span></code> logger:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>
<span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">'sqlalchemy.dialects.postgresql'</span><span class="p">)</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="psycopg2-hstore">
<span id="id5"></span><h3>HSTORE type<a class="headerlink" href="#psycopg2-hstore" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code> DBAPI includes an extension to natively handle marshalling of
the HSTORE type. The SQLAlchemy psycopg2 dialect will enable this extension
by default when psycopg2 version 2.4 or greater is used, and
it is detected that the target database has the HSTORE type set up for use.
In other words, when the dialect makes the first
connection, a sequence like the following is performed:</p>
<ol class="arabic simple">
<li><p>Request the available HSTORE oids using
<code class="docutils literal notranslate"><span class="pre">psycopg2.extras.HstoreAdapter.get_oids()</span></code>.
If this function returns a list of HSTORE identifiers, we then determine
that the <code class="docutils literal notranslate"><span class="pre">HSTORE</span></code> extension is present.
This function is <strong>skipped</strong> if the version of psycopg2 installed is
less than version 2.4.</p></li>
<li><p>If the <code class="docutils literal notranslate"><span class="pre">use_native_hstore</span></code> flag is at its default of <code class="docutils literal notranslate"><span class="pre">True</span></code>, and
we’ve detected that <code class="docutils literal notranslate"><span class="pre">HSTORE</span></code> oids are available, the
<code class="docutils literal notranslate"><span class="pre">psycopg2.extensions.register_hstore()</span></code> extension is invoked for all
connections.</p></li>
</ol>
<p>The <code class="docutils literal notranslate"><span class="pre">register_hstore()</span></code> extension has the effect of <strong>all Python
dictionaries being accepted as parameters regardless of the type of target
column in SQL</strong>. The dictionaries are converted by this extension into a
textual HSTORE expression. If this behavior is not desired, disable the
use of the hstore extension by setting <code class="docutils literal notranslate"><span class="pre">use_native_hstore</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code> as
follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s2">"postgresql+psycopg2://scott:tiger@localhost/test"</span><span class="p">,</span>
<span class="n">use_native_hstore</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span></pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">HSTORE</span></code> type is <strong>still supported</strong> when the
<code class="docutils literal notranslate"><span class="pre">psycopg2.extensions.register_hstore()</span></code> extension is not used. It merely
means that the coercion between Python dictionaries and the HSTORE
string format, on both the parameter side and the result side, will take
place within SQLAlchemy’s own marshalling logic, and not that of <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code>
which may be more performant.</p>
</div>
</div>
<div class="section" id="module-sqlalchemy.dialects.postgresql.pg8000">
<span id="pg8000"></span><h2>pg8000<a class="headerlink" href="#module-sqlalchemy.dialects.postgresql.pg8000" title="Permalink to this headline">¶</a></h2>
<p>Support for the PostgreSQL database via the pg8000 driver.</p>
<div class="section" id="dialect-postgresql-pg8000-url">
<h3>DBAPI<a class="headerlink" href="#dialect-postgresql-pg8000-url" title="Permalink to this headline">¶</a></h3>
<p>Documentation and download information (if applicable) for pg8000 is available at:
<a class="reference external" href="https://pythonhosted.org/pg8000/">https://pythonhosted.org/pg8000/</a></p>
</div>
<div class="section" id="dialect-postgresql-pg8000-connect">
<h3>Connecting<a class="headerlink" href="#dialect-postgresql-pg8000-connect" title="Permalink to this headline">¶</a></h3>
<p>Connect String:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...]</pre></div>
</div>
</p>
</div>
<div class="section" id="unicode">
<span id="pg8000-unicode"></span><h3>Unicode<a class="headerlink" href="#unicode" title="Permalink to this headline">¶</a></h3>
<p>pg8000 will encode / decode string values between it and the server using the
PostgreSQL <code class="docutils literal notranslate"><span class="pre">client_encoding</span></code> parameter; by default this is the value in
the <code class="docutils literal notranslate"><span class="pre">postgresql.conf</span></code> file, which often defaults to <code class="docutils literal notranslate"><span class="pre">SQL_ASCII</span></code>.
Typically, this can be changed to <code class="docutils literal notranslate"><span class="pre">utf-8</span></code>, as a more useful default:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#client_encoding = sql_ascii # actually, defaults to database</span>
<span class="c1"># encoding</span>
<span class="n">client_encoding</span> <span class="o">=</span> <span class="n">utf8</span></pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">client_encoding</span></code> can be overridden for a session by executing the SQL:</p>
<p>SET CLIENT_ENCODING TO ‘utf8’;</p>
<p>SQLAlchemy will execute this SQL on all new connections based on the value
passed to <a class="reference internal" href="../core/engines.html#sqlalchemy.create_engine" title="sqlalchemy.create_engine"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_engine()</span></code></a> using the <code class="docutils literal notranslate"><span class="pre">client_encoding</span></code> parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span>
<span class="s2">"postgresql+pg8000://user:pass@host/dbname"</span><span class="p">,</span> <span class="n">client_encoding</span><span class="o">=</span><span class="s1">'utf8'</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="pg8000-transaction-isolation-level">
<span id="pg8000-isolation-level"></span><h3>pg8000 Transaction Isolation Level<a class="headerlink" href="#pg8000-transaction-isolation-level" title="Permalink to this headline">¶</a></h3>
<p>The pg8000 dialect offers the same isolation level settings as that
of the <a class="reference internal" href="#psycopg2-isolation-level"><span class="std std-ref">psycopg2</span></a> dialect:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">READ</span> <span class="pre">COMMITTED</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">READ</span> <span class="pre">UNCOMMITTED</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">REPEATABLE</span> <span class="pre">READ</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">SERIALIZABLE</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">AUTOCOMMIT</span></code></p></li>
</ul>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.5: </span>support for AUTOCOMMIT isolation level when using
pg8000.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#postgresql-isolation-level"><span class="std std-ref">Transaction Isolation Level</span></a></p>
<p><a class="reference internal" href="#psycopg2-isolation-level"><span class="std std-ref">Psycopg2 Transaction Isolation Level</span></a></p>
</div>
</div>
</div>
<div class="section" id="module-sqlalchemy.dialects.postgresql.psycopg2cffi">
<span id="psycopg2cffi"></span><h2>psycopg2cffi<a class="headerlink" href="#module-sqlalchemy.dialects.postgresql.psycopg2cffi" title="Permalink to this headline">¶</a></h2>
<p>Support for the PostgreSQL database via the psycopg2cffi driver.</p>
<div class="section" id="dialect-postgresql-psycopg2cffi-url">
<h3>DBAPI<a class="headerlink" href="#dialect-postgresql-psycopg2cffi-url" title="Permalink to this headline">¶</a></h3>
<p>Documentation and download information (if applicable) for psycopg2cffi is available at:
<a class="reference external" href="http://pypi.python.org/pypi/psycopg2cffi/">http://pypi.python.org/pypi/psycopg2cffi/</a></p>
</div>
<div class="section" id="dialect-postgresql-psycopg2cffi-connect">
<h3>Connecting<a class="headerlink" href="#dialect-postgresql-psycopg2cffi-connect" title="Permalink to this headline">¶</a></h3>
<p>Connect String:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>postgresql+psycopg2cffi://user:password@host:port/dbname[?key=value&key=value...]</pre></div>
</div>
</p>
</div>
<p><code class="docutils literal notranslate"><span class="pre">psycopg2cffi</span></code> is an adaptation of <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code>, using CFFI for the C
layer. This makes it suitable for use in e.g. PyPy. Documentation
is as per <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#module-sqlalchemy.dialects.postgresql.psycopg2" title="sqlalchemy.dialects.postgresql.psycopg2"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlalchemy.dialects.postgresql.psycopg2</span></code></a></p>
</div>
</div>
<div class="section" id="module-sqlalchemy.dialects.postgresql.pypostgresql">
<span id="py-postgresql"></span><h2>py-postgresql<a class="headerlink" href="#module-sqlalchemy.dialects.postgresql.pypostgresql" title="Permalink to this headline">¶</a></h2>
<p>Support for the PostgreSQL database via the py-postgresql driver.</p>
<div class="section" id="dialect-postgresql-pypostgresql-url">
<h3>DBAPI<a class="headerlink" href="#dialect-postgresql-pypostgresql-url" title="Permalink to this headline">¶</a></h3>
<p>Documentation and download information (if applicable) for py-postgresql is available at:
<a class="reference external" href="http://python.projects.pgfoundry.org/">http://python.projects.pgfoundry.org/</a></p>
</div>
<div class="section" id="dialect-postgresql-pypostgresql-connect">
<h3>Connecting<a class="headerlink" href="#dialect-postgresql-pypostgresql-connect" title="Permalink to this headline">¶</a></h3>
<p>Connect String:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>postgresql+pypostgresql://user:password@host:port/dbname[?key=value&key=value...]</pre></div>
</div>
</p>
</div>
</div>
<div class="section" id="module-sqlalchemy.dialects.postgresql.pygresql">
<span id="pygresql"></span><span id="dialect-postgresql-pygresql"></span><h2>pygresql<a class="headerlink" href="#module-sqlalchemy.dialects.postgresql.pygresql" title="Permalink to this headline">¶</a></h2>
<p>Support for the PostgreSQL database via the pygresql driver.</p>
<div class="section" id="dialect-postgresql-pygresql-url">
<h3>DBAPI<a class="headerlink" href="#dialect-postgresql-pygresql-url" title="Permalink to this headline">¶</a></h3>
<p>Documentation and download information (if applicable) for pygresql is available at:
<a class="reference external" href="http://www.pygresql.org/">http://www.pygresql.org/</a></p>
</div>
<div class="section" id="dialect-postgresql-pygresql-connect">
<h3>Connecting<a class="headerlink" href="#dialect-postgresql-pygresql-connect" title="Permalink to this headline">¶</a></h3>
<p>Connect String:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>postgresql+pygresql://user:password@host:port/dbname[?key=value&key=value...]</pre></div>
</div>
</p>
</div>
</div>
<div class="section" id="module-sqlalchemy.dialects.postgresql.zxjdbc">
<span id="zxjdbc"></span><h2>zxjdbc<a class="headerlink" href="#module-sqlalchemy.dialects.postgresql.zxjdbc" title="Permalink to this headline">¶</a></h2>
<p>Support for the PostgreSQL database via the zxJDBC for Jython driver.</p>
<div class="section" id="dialect-postgresql-zxjdbc-url">
<h3>DBAPI<a class="headerlink" href="#dialect-postgresql-zxjdbc-url" title="Permalink to this headline">¶</a></h3>
<p>Drivers for this database are available at:
<a class="reference external" href="http://jdbc.postgresql.org/">http://jdbc.postgresql.org/</a></p>
</div>
<div class="section" id="dialect-postgresql-zxjdbc-connect">
<h3>Connecting<a class="headerlink" href="#dialect-postgresql-zxjdbc-connect" title="Permalink to this headline">¶</a></h3>
<p>Connect String:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">postgresql</span><span class="o">+</span><span class="n">zxjdbc</span><span class="p">:</span><span class="o">//</span><span class="n">scott</span><span class="p">:</span><span class="n">tiger</span><span class="nd">@localhost</span><span class="o">/</span><span class="n">db</span></pre></div>
</div>
</p>
</div>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links, withsidebar">
Previous:
<a href="index.html" title="previous chapter">Dialects</a>
Next:
<a href="mysql.html" title="next chapter">MySQL</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2019, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
</div>
</div>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.2.19',
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>
