Working With Engines and Connections

30/6/22, 17:10 Working with Engines and Connections — SQLAlchemy 1.
4 Documentation
SQLAlchemy 1.4 Documentation

CURRENT RELEASE
Home
| Download this Documentation The Database Toolkit for Python
Search terms:
search...
Release: 1.4.39
CURRENT RELEASE
| Release Date: June 24, 2022
Your new development
career awaits. Check out the
latest listings.
Working with Engines and Connections
ADS VIA CARBON
This section details direct usage of the Engine ,
Connection , and related objects. Its
important to note that when
using the SQLAlchemy ORM, these objects are not
SQLAlchemy Core generally accessed; instead,
the Session object is used as the interface to the
database.
However, for applications that are built around direct usage of textual SQL
SQL Expression Language Tutorial (1.x API)
statements and/or SQL expression constructs without involvement by the ORM’s
SQL Statements and Expressions API higher level management services, the Engine and
Connection are king (and queen?) -
read on.
Schema Definition Language
Column and Data Types
Engine and Connection Use

Basic Usage
Recall from Engine Configuration that an Engine is created via
the create_engine()
Engine Configuration
call:
engine = create_engine('mysql://scott:tiger@localhost/test')
Basic Usage
Using Transactions
The typical usage of create_engine() is once per particular database
URL, held
Nesting of Transaction Blocks globally for the lifetime of a single application process. A single
Engine manages
many individual DBAPI connections on behalf of
the process and is intended to be
Arbitrary Transaction Nesting as
called upon in a concurrent fashion. The
Engine is not synonymous to the DBAPI
an Antipattern connect function, which
represents just one connection resource - the Engine is most
efficient when created just once at the module level of an application, not
per-object
Migrating from the “nesting”
or per-function call.
pattern
tip
Library Level (e.g. emulated)
Autocommit
When using an Engine with multiple Python processes, such as when
using os.fork or
Setting Transaction Isolation Levels Python multiprocessing , it’s important that the
engine is initialized per process. See
including DBAPI Autocommit Using Connection Pools with Multiprocessing or os.fork() for
details.
Understanding the DBAPI-Level

The most basic function of the Engine is to provide access to a
Connection , which can
Autocommit Isolation Level
then invoke SQL statements. To emit
a textual statement to the database looks like:
Using Server Side Cursors (a.k.a. stream
results) from sqlalchemy import text
Connectionless Execution, Implicit

with engine.connect() as connection:
Execution result = connection.execute(text("select username from use

Translation of Schema Names
for row in result:
print("username:", row['username'])
SQL Compilation Caching
Configuration
Above, the Engine.connect() method returns a Connection
object, and by using it in a
Estimating Cache Performance Python context manager (e.g. the with:
statement) the Connection.close() method is
Using Logging automatically invoked at the
end of the block. The Connection , is a proxy object for an
actual DBAPI connection. The DBAPI connection is retrieved from the connection
How much memory does the cache
pool at the point at which Connection is created.
use?
The object returned is known as CursorResult , which
references a DBAPI cursor and
Disabling or using an alternate
provides methods for fetching rows
similar to that of the DBAPI cursor. The DBAPI
dictionary to cache some (or all) cursor will be closed
by the CursorResult when all of its result rows (if any) are
https://docs.sqlalchemy.org/en/14/core/connections.html 1/96
30/6/22, 17:10 Working with Engines and Connections — SQLAlchemy 1.4 Documentation
exhausted. A CursorResult that returns no rows, such as that of
an UPDATE
SQLAlchemy 1.4 Documentation statement (without any returned rows),
releases cursor resources immediately upon
construction.
CURRENT RELEASE
Home
| Download this Documentation When the Connection is closed at the end of the with: block, the
referenced DBAPI
connection is released to the connection pool. From
the perspective of the database
Search terms:
search... itself, the connection pool will not actually
“close” the connection assuming the pool
has room to store this connection for
the next use. When the connection is returned
to the pool for re-use, the
pooling mechanism issues a rollback() call on the DBAPI
Your new development connection so that
any transactional state or locks are removed, and the connection
career awaits. Check out the is ready for
its next use.
latest listings.
Our example above illustrated the execution of a textual SQL string, which
should be
ADS VIA CARBON
invoked by using the text() construct to indicate that
we’d like to use textual SQL.
SQLAlchemy Core The Connection.execute() method can of
course accommodate more than that,
including the variety of SQL expression
constructs described in SQL Expression
SQL Expression Language Tutorial (1.x API) Language Tutorial (1.x API).
SQL Statements and Expressions API

Using Transactions
Note
This section describes how to use transactions when working
directly
with Engine and Connection objects. When using the
Working with Engines and Connections SQLAlchemy ORM, the public API for transaction control is via
the
Session object, which makes usage of the Transaction
object
Basic Usage
internally. See Managing Transactions for further
information.
Using Transactions
Nesting of Transaction Blocks The Connection object provides a Connection.begin()

method which returns a
Transaction object. Like the Connection
itself, this object is usually used within a
Python with: block so
that its scope is managed:
an Antipattern
Migrating from the “nesting” with engine.connect() as connection:
pattern with connection.begin():
r1 = connection.execute(table1.select())
Library Level (e.g. emulated) connection.execute(table1.insert(), {"col1": 7, "col2"

Autocommit
Setting Transaction Isolation Levels

The above block can be stated more simply by using the Engine.begin()
method of
including DBAPI Autocommit
Engine :

Autocommit Isolation Level # runs a transaction
with engine.begin() as connection:
Using Server Side Cursors (a.k.a. stream r1 = connection.execute(table1.select())
results) connection.execute(table1.insert(), {"col1": 7, "col2": "t

Execution
The block managed by each .begin() method has the behavior such that
the
Translation of Schema Names transaction is committed when the block completes. If an exception is
raised, the
transaction is instead rolled back, and the exception propagated
outwards.
The underlying object used to represent the transaction is the
Transaction object.
Configuration
This object is returned by the
Connection.begin() method and includes the methods
Estimating Cache Performance Transaction.commit() and Transaction.rollback() . The context
manager calling form,
Using Logging which invokes these methods automatically, is recommended

as a best practice.
How much memory does the cache Nesting of Transaction Blocks

use?
Deprecated since version 1.4: The “transaction nesting” feature of
SQLAlchemy is a legacy feature
that is deprecated in the 1.4 release and will be
dictionary to cache some (or all) removed in SQLAlchemy 2.0.
The pattern has proven to be a little too awkward
and complicated, unless an
application makes more of a first-class framework
SQLAlchemy 1.4 Documentation around the behavior. See
the following subsection Arbitrary Transaction
Nesting as an Antipattern.
CURRENT RELEASE
Home
| Download this Documentation
The Transaction object also handles “nested” behavior by keeping
track of the
Search terms:
search... outermost begin/commit pair. In this example, two functions both
issue a transaction
on a Connection , but only the outermost
Transaction object actually takes effect
when it is committed.
career awaits. Check out the # method_a starts a transaction and calls method_b
latest listings.
def method_a(connection):
ADS VIA CARBON with connection.begin(): # open a transaction
method_b(connection)
SQLAlchemy Core
# method_b also starts a transaction

def method_b(connection):
SQL Statements and Expressions API with connection.begin(): # open a transaction - this runs
# context of method_a's transacti
connection.execute(text("insert into mytable values ('
Column and Data Types connection.execute(mytable.insert(), {"col1": "bat", "
Engine and Connection Use # open a Connection and call method_a
Engine Configuration with engine.connect() as conn:
method_a(conn)
Basic Usage
Above, method_a is called first, which calls connection.begin() . Then
it calls method_b .
Using Transactions When method_b calls connection.begin() , it just
increments a counter that is
Nesting of Transaction Blocks decremented when it calls commit() . If either
method_a or method_b calls rollback() ,
the whole transaction is
rolled back. The transaction is not committed until method_a
Arbitrary Transaction Nesting as calls the
commit() method. This “nesting” behavior allows the creation of functions
an Antipattern which “guarantee” that a transaction will be used if one was not already
available, but
will automatically participate in an enclosing transaction if
one exists.
pattern Arbitrary Transaction Nesting as an Antipattern
Library Level (e.g. emulated) With many years of experience, the above “nesting” pattern has not proven to
be
very popular, and where it has been observed in large projects such
as Openstack, it
Autocommit
tends to be complicated.
The most ideal way to organize an application would have a single, or at
least very
few, points at which the “beginning” and “commit” of all
database transactions is
Understanding the DBAPI-Level demarcated. This is also the general
idea discussed in terms of the ORM at When do I
Autocommit Isolation Level construct a Session, when do I commit it, and when do I close it?. To
adapt the
example from the previous section to this practice looks like:
results) # method_a calls method_b
Connectionless Execution, Implicit def method_a(connection):
method_b(connection)
Execution
Translation of Schema Names # method_b uses the connection and assumes the transaction
# is external
SQL Compilation Caching def method_b(connection):
Configuration connection.execute(text("insert into mytable values ('bat'

connection.execute(mytable.insert(), {"col1": "bat", "col2
Estimating Cache Performance
Using Logging # open a Connection inside of a transaction and call method_a
with engine.begin() as conn:
How much memory does the cache method_a(conn)

use?

dictionary to cache some (or all)
That is, method_a() and method_b() do not deal with the details
of the transaction at
SQLAlchemy 1.4 Documentation all; the transactional scope of the connection is
defined externally to the functions
that have a SQL dialogue with the
connection.
CURRENT RELEASE
Home
| Download this Documentation It may be observed that the above code has fewer lines, and less indentation
which
tends to correlate with lower cyclomatic complexity. The
above code is organized
Search terms:
search... such that method_a() and method_b() are always
invoked from a point at which a
transaction is begun. The previous
version of the example features a method_a() and
a method_b() that are
trying to be agnostic of this fact, which suggests they are
Your new development prepared for
at least twice as many potential codepaths through them.
latest listings. Migrating from the “nesting” pattern
ADS VIA CARBON As SQLAlchemy’s intrinsic-nested pattern is considered legacy, an application
that
for either legacy or novel reasons still seeks to have a context that
automatically
SQLAlchemy Core
frames transactions should seek to maintain this functionality
through the use of a
custom Python context manager. A similar example is also
provided in terms of the
ORM in the “seealso” section below.
To provide backwards compatibility for applications that make use of this
pattern, the
following context manager or a similar implementation based on
a decorator may be
Column and Data Types used:

import contextlib
@contextlib.contextmanager

def transaction(connection):
Basic Usage if not connection.in_transaction():
with connection.begin():
Using Transactions yield connection
Nesting of Transaction Blocks else:
yield connection
an Antipattern The above contextmanager would be used as:
pattern # method_a starts a transaction and calls method_b
def method_a(connection):
Library Level (e.g. emulated) with transaction(connection): # open a transaction
Autocommit method_b(connection)
Setting Transaction Isolation Levels # method_b either starts a transaction, or uses the one alread
including DBAPI Autocommit # present
def method_b(connection):

with transaction(connection): # open a transaction
Autocommit Isolation Level connection.execute(text("insert into mytable values ('

connection.execute(mytable.insert(), {"col1": "bat", "
results) # open a Connection and call method_a

with engine.connect() as conn:
method_a(conn)
Execution

A similar approach may be taken such that connectivity is established
on demand as
well; the below approach features a single-use context manager
that accesses an
Configuration enclosing state in order to test if connectivity is already
present:

import contextlib
Using Logging
How much memory does the cache def connectivity(engine):
use?
connection = None
Disabling or using an alternate @contextlib.contextmanager
dictionary to cache some (or all) def connect():
nonlocal connection

if connection is None:
CURRENT RELEASE connection = engine.connect()
Home
| Download this Documentation with connection:
Search terms:
search... yield connection
else:
yield connection

career awaits. Check out the return connect
latest listings.
ADS VIA CARBON Using the above would look like:

SQLAlchemy Core
# method_a passes along connectivity context, at the same time
SQL Expression Language Tutorial (1.x API) # it chooses to establish a connection by calling "with"
def method_a(connectivity):

with connectivity():
Schema Definition Language method_b(connectivity)
Column and Data Types # method_b also wants to use a connection from the context, so
Engine and Connection Use # also calls "with:", but also it actually uses the connection
def method_b(connectivity):
Engine Configuration with connectivity() as connection:
connection.execute(text("insert into mytable values ('

connection.execute(mytable.insert(), {"col1": "bat", "
Basic Usage
# create a new connection/transaction context object and call
Using Transactions
# method_a
Nesting of Transaction Blocks method_a(connectivity(engine))

an Antipattern The above context manager acts not only as a “transaction” context but also
as a

context that manages having an open connection against a particular
Engine . When
using the ORM Session , this
connectivty management is provided by the Session
pattern
itself.
An overview of ORM connectivity patterns is at Managing Transactions.
See also
Autocommit
Setting Transaction Isolation Levels Migrating from the “subtransaction” pattern - ORM version

Autocommit Isolation Level Library Level (e.g. emulated) Autocommit
Deprecated since version 1.4: The “autocommit” feature of SQLAlchemy Core
results)
is deprecated
and will not be present in version 2.0 of SQLAlchemy. DBAPI-
Connectionless Execution, Implicit level
AUTOCOMMIT is now widely available which offers superior performance
Execution and occurs transparently. See Library-level (but not driver level) “Autocommit”
removed from both Core and ORM for background.

Note
Configuration
This section discusses the feature within SQLAlchemy that
automatically
invokes the .commit() method on a DBAPI
Using Logging connection, however this is against
a DBAPI connection that is
How much memory does the cache itself transactional. For true AUTOCOMMIT,
see the next section
Setting Transaction Isolation Levels including DBAPI
use?
Autocommit.
The previous transaction example illustrates how to use Transaction
so that several
SQLAlchemy 1.4 Documentation executions can take part in the same transaction. What happens
when we issue an
INSERT, UPDATE or DELETE call without using
Transaction ? While some DBAPI
CURRENT RELEASE
implementations provide various special “non-transactional” modes, the core
Home
behavior of DBAPI per PEP-0249 is that a transaction is always in progress,
providing only rollback() and commit() methods but no begin() .
SQLAlchemy
Search terms:
search...
assumes this is the case for any given DBAPI.
Given this requirement, SQLAlchemy implements its own “autocommit” feature

Your new development which
works completely consistently across all backends. This is achieved by
career awaits. Check out the detecting statements which represent data-changing operations, i.e. INSERT,
latest listings. UPDATE, DELETE, as well as data definition language (DDL) statements such as
ADS VIA CARBON CREATE TABLE, ALTER TABLE, and then issuing a COMMIT automatically if no
transaction is in progress. The detection is based on the presence of the
SQLAlchemy Core
autocommit=True execution option on the statement. If the statement
is a text-only
statement and the flag is not set, a regular expression is used
to detect INSERT,
UPDATE, DELETE, as well as a variety of other commands
for a particular backend:
Schema Definition Language conn = engine.connect()
conn.execute(text("INSERT INTO users VALUES (1, 'john')")) #


The “autocommit” feature is only in effect when no Transaction has
otherwise been
declared. This means the feature is not generally used with
the ORM, as the Session
Working with Engines and Connections object by default always maintains an
ongoing Transaction .
Basic Usage Full control of the “autocommit” behavior is available using the generative
Connection.execution_options() method provided on Connection
and Engine , using the
Using Transactions
“autocommit” flag which will
turn on or off the autocommit for the selected scope.
Nesting of Transaction Blocks For example, a
text() construct representing a stored procedure that commits might
use
it so that a SELECT statement will issue a COMMIT:
an Antipattern
with engine.connect().execution_options(autocommit=True) as co
Migrating from the “nesting” conn.execute(text("SELECT my_mutating_procedure()"))
pattern

Autocommit
Setting Transaction Isolation Levels including
DBAPI Autocommit
Most DBAPIs support the concept of configurable transaction isolation levels.
These
Understanding the DBAPI-Level are traditionally the four levels “READ UNCOMMITTED”, “READ COMMITTED”,
Autocommit Isolation Level “REPEATABLE READ” and “SERIALIZABLE”. These are usually applied to a
DBAPI
connection before it begins a new transaction, noting that most
DBAPIs will begin
Using Server Side Cursors (a.k.a. stream this transaction implicitly when SQL statements are first
emitted.
results)
DBAPIs that support isolation levels also usually support the concept of true
Connectionless Execution, Implicit “autocommit”, which means that the DBAPI connection itself will be placed into
a
Execution non-transactional autocommit mode. This usually means that the typical DBAPI
behavior of emitting “BEGIN” to the database automatically no longer occurs,
but it
may also include other directives. SQLAlchemy treats the concept of
“autocommit”
SQL Compilation Caching like any other isolation level; in that it is an isolation level
that loses not only “read
committed” but also loses atomicity.
Configuration
Estimating Cache Performance Tip
Using Logging
It is important to note, as will be discussed further in the section below at
How much memory does the cache Understanding the DBAPI-Level Autocommit Isolation Level, that “autocommit”
isolation level like
any other isolation level does not affect the “transactional” behavior
use?
of
the Connection object, which continues to call upon DBAPI
.commit() and
Disabling or using an alternate .rollback() methods (they just have no effect under
autocommit), and for which the
.begin() method assumes the DBAPI will
start a transaction implicitly (which means
SQLAlchemy 1.4 Documentation that SQLAlchemy’s “begin” does

not change autocommit mode).
CURRENT RELEASE
Home
| Download this Documentation SQLAlchemy dialects should support these isolation levels as well as autocommit
to
as great a degree as possible. The levels are set via family of
“execution_options”
Search terms:
search... parameters and methods that are throughout the Core, such
as the
Connection.execution_options() method. The parameter is
known as
Connection.execution_options.isolation_level and
the values are strings which are
Your new development typically a subset of the following names:
latest listings.
# possible values for Connection.execution_options(isolation_l
ADS VIA CARBON
"AUTOCOMMIT"
SQLAlchemy Core
"READ COMMITTED"
"READ UNCOMMITTED"

"REPEATABLE READ"
SQL Statements and Expressions API "SERIALIZABLE"

Column and Data Types Not every DBAPI supports every value; if an unsupported value is used for a
certain

backend, an error is raised.
Engine Configuration For example, to force REPEATABLE READ on a specific connection, then
begin a
transaction:
Basic Usage with engine.connect().execution_options(isolation_level="REPEA

Using Transactions
connection.execute(<statement>)
Nesting of Transaction Blocks

Note
an Antipattern
Migrating from the “nesting” The return value of

the Connection.execution_options() method is
a so-called
“branched” connection under the SQLAlchemy 1.x
pattern
series when not using
create_engine.future mode, which is a
Library Level (e.g. emulated) shallow
copy of the original Connection object. Despite this,
the
Autocommit isolation_level execution option applies to the
original
Connection object and all “branches” overall.

including DBAPI Autocommit When using create_engine.future mode (i.e. 2.0 style
usage), the
concept of these so-called “branched” connections is removed,
and Connection.execution_options() returns the same
Connection
object without creating any copies.
results)
The Connection.execution_options.isolation_level option may
also be set engine
Connectionless Execution, Implicit wide, as is often preferable. This is achieved by
passing it within the
create_engine.execution_options
parameter to create_engine() :
Execution
Translation of Schema Names from sqlalchemy import create_engine

eng = create_engine(
Configuration "postgresql://scott:tiger@localhost/test",
execution_options={

"isolation_level": "REPEATABLE READ"
Using Logging }

)
use?
With the above setting, the DBAPI connection will be set to use a
"REPEATABLE READ"
Disabling or using an alternate isolation level setting for each new transaction
begun.
An application that frequently chooses to run operations within different
isolation
SQLAlchemy 1.4 Documentation levels may wish to create multiple “sub-engines” of a lead
Engine , each of which will
be configured to a different
isolation level. One such use case is an application that
CURRENT RELEASE
has operations
that break into “transactional” and “read-only” operations, a separate
Home
Engine that makes use of "AUTOCOMMIT" may be
separated off from the main engine:
Search terms:
search...
from sqlalchemy import create_engine
eng = create_engine("postgresql://scott:tiger@localhost/test")
autocommit_engine = eng.execution_options(isolation_level="AUT
latest listings.
ADS VIA CARBON
SQLAlchemy Core Above, the Engine.execution_options() method creates a shallow

copy of the original
Engine . Both eng and
autocommit_engine share the same dialect and connection pool.
SQL Expression Language Tutorial (1.x API) However, the
“AUTOCOMMIT” mode will be set upon connections when they are
acquired from the
autocommit_engine .
Schema Definition Language The isolation level setting, regardless of which one it is, is unconditionally
reverted
when a connection is returned to the connection pool.
Note
Engine Configuration The Connection.execution_options.isolation_level

parameter
necessarily does not apply to statement level options, such as
that of Executable.execution_options() . This because the option
Basic Usage must be set on a DBAPI connection on a per-transaction basis.
Using Transactions
See also
Arbitrary Transaction Nesting as SQLite Transaction Isolation

an Antipattern
PostgreSQL Transaction Isolation
MySQL Transaction Isolation
pattern
Library Level (e.g. emulated) SQL Server Transaction Isolation
Autocommit Setting Transaction Isolation Levels / DBAPI AUTOCOMMIT - for the ORM

Using DBAPI Autocommit Allows for a Readonly Version of Transparent Reconnect - a
recipe that uses DBAPI autocommit
to transparently reconnect to the database for
Understanding the DBAPI-Level read-only operations
Using Server Side Cursors (a.k.a. stream Understanding the DBAPI-Level Autocommit Isolation Level
results) In the parent section, we introduced the concept of the
Connection.execution_options.isolation_level
parameter and how it can be used to
set database isolation levels, including
DBAPI-level “autocommit” which is treated by
Execution SQLAlchemy as another transaction
isolation level. In this section we will attempt to
clarify the implications
of this approach.
SQL Compilation Caching If we wanted to check out a Connection object and use it
“autocommit” mode, we
would proceed as follows:
Configuration
Estimating Cache Performance with engine.connect() as connection:
Using Logging connection.execution_options(isolation_level="AUTOCOMMIT")

How much memory does the cache connection.execute(<statement>)

use?

Above illustrates normal usage of “DBAPI autocommit” mode. There is no
need to
make use of methods such as Connection.begin()
or Connection.commit() (noting the
latter applies to 2.0 style usage).
What’s important to note however is that the above autocommit mode is
persistent
CURRENT RELEASE on that particular Connection until we change it directly using
isolation_level
Home
| Download this Documentation again. The isolation level is also reset on the DBAPI
connection when we release the
connection
back to the connection pool. However, calling upon Connection.begin()
Search terms:
search... will not change the isolation level, meaning we stay in autocommit. The
example
below illustrates this:
Your new development with engine.connect() as connection:
career awaits. Check out the connection = connection.execution_options(isolation_level=

latest listings.
ADS VIA CARBON # this begin() does nothing, isolation stays at AUTOCOMMIT
with connection.begin() as trans:
SQLAlchemy Core
Schema Definition Language When we run a block like the above with logging turned on, the logging
will attempt
to indicate that while a DBAPI level .commit() is called,
it probably will have no effect
Column and Data Types due to autocommit mode:

INFO sqlalchemy.engine.Engine BEGIN (implicit)
...
Working with Engines and Connections INFO sqlalchemy.engine.Engine COMMIT using DBAPI connection.co
Basic Usage
Using Transactions Similarly, when using 2.0 style create_engine.future

mode, the Connection will use
autobegin
behavior, meaning that the pattern below will raise an error:
Arbitrary Transaction Nesting as engine = create_engine(..., future=True)
an Antipattern
Migrating from the “nesting” connection = connection.execution_options(isolation_level=

pattern
# "transaction" is autobegin (but has no effect due to aut
Autocommit
# this will raise; "transaction" is already begun

including DBAPI Autocommit connection.execute(<statement>)

This is all to demonstrate that the autocommit isolation level setting is
completely
Using Server Side Cursors (a.k.a. stream independent from the begin/commit behavior of the SQLAlchemy
Connection
results) object. The “autocommit” mode will not interact with Connection.begin()
in any way
and the Connection does not consult this status
when performing its own state
Connectionless Execution, Implicit changes with regards to the transaction (with
the exception of suggesting within
Execution engine logging that these blocks are not
actually committing). The rationale for this
design is to maintain a
completely consistent usage pattern with the Connection
where
DBAPI-autocommit mode can be changed independently without indicating
SQL Compilation Caching any code
changes elsewhere.
Configuration Isolation level settings, including autocommit mode, are reset automatically
when
Estimating Cache Performance the connection is released back to the connection pool. Therefore it is
preferable to
avoid trying to switch isolation levels on a single
Connection object as this leads to
Using Logging
excess verbosity.
To illustrate how to use “autocommit” in an ad-hoc mode within the scope of a
single
use?
Connection checkout, the
Connection.execution_options.isolation_level parameter
Disabling or using an alternate must be re-applied with the previous isolation level.
We can write our above block
“correctly” as (noting 2.0 style usage below):
# if we wanted to flip autocommit on and off on a single conne

SQLAlchemy 1.4 Documentation # which... we usually don't.
CURRENT RELEASE
Home
| Download this Documentation engine = create_engine(..., future=True)
Search terms:
search... with engine.connect() as connection:
connection.execution_options(isolation_level="AUTOCOMMIT")

# run statement(s) in autocommit mode

latest listings.
ADS VIA CARBON # "commit" the autobegun "transaction" (2.0/future mode on

SQLAlchemy Core connection.commit()
SQL Expression Language Tutorial (1.x API) # switch to default isolation level
connection.execution_options(isolation_level=connection.de
# use a begin block

Column and Data Types connection.execute(<statement>)
Engine Configuration Above, to manually revert the isolation level we made use of
Connection.default_isolation_level to restore the default
isolation level (assuming
that’s what we want here). However, it’s
probably a better idea to work with the
Basic Usage architecture of of the
Connection which already handles resetting of isolation level
automatically upon checkin. The preferred way to write the above is to
use two
Using Transactions
blocks
Arbitrary Transaction Nesting as engine = create_engine(..., future=True)
an Antipattern
# use an autocommit block
Migrating from the “nesting” with engine.connect().execution_options(isolation_level="AUTOC

pattern
# run statement in autocommit mode
Library Level (e.g. emulated) connection.execute(<statement>)
Autocommit
# use a regular block
Setting Transaction Isolation Levels with engine.begin() as connection:
including DBAPI Autocommit connection.execute(<statement>)

Autocommit Isolation Level To sum up:
1. “DBAPI level autocommit” isolation level is entirely independent of the
results) Connection object’s notion of “begin” and “commit”

2. use individual Connection checkouts per isolation level.
Avoid trying to change
Execution back and forth between “autocommit” on a single
connection checkout; let the
engine do the work of restoring default
isolation levels
Configuration Using Server Side Cursors (a.k.a. stream results)

Estimating Cache Performance A limited number of dialects have explicit support for the concept of “server
side
cursors” vs. “buffered cursors”. While a server side cursor implies a
variety of
Using Logging
different capabilities, within SQLAlchemy’s engine and dialect
implementation, it
How much memory does the cache refers only to whether or not a particular set of results is
fully buffered in memory
use?
before they are fetched from the cursor, using a
method such as cursor.fetchall() .
SQLAlchemy has no direct support
for cursor behaviors such as scrolling; to make
Disabling or using an alternate use of these features for
a particular DBAPI, use the cursor directly as documented
dictionary to cache some (or all) at
Working with Driver SQL and Raw DBAPI Connections.
Some DBAPIs, such as the cx_Oracle DBAPI, exclusively use server side cursors
SQLAlchemy 1.4 Documentation internally. All result sets are essentially unbuffered across the total span
of a result
set, utilizing only a smaller buffer that is of a fixed size such
as 100 rows at a time.
CURRENT RELEASE
Home
| Download this Documentation For those dialects that have conditional support for buffered or unbuffered
results,
there are usually caveats to the use of the “unbuffered”, or server
side cursor mode.
Search terms:
search... When using the psycopg2 dialect for example, an error is
raised if a server side
cursor is used with any kind of DML or DDL statement.
When using MySQL drivers
with a server side cursor, the DBAPI connection is in
a more fragile state and does
Your new development not recover as gracefully from error conditions
nor will it allow a rollback to proceed
career awaits. Check out the until the cursor is fully closed.
latest listings.
For this reason, SQLAlchemy’s dialects will always default to the less error
prone
ADS VIA CARBON
version of a cursor, which means for PostgreSQL and MySQL dialects
it defaults to a
SQLAlchemy Core buffered, “client side” cursor where the full set of results
is pulled into memory
before any fetch methods are called from the cursor.
This mode of operation is
SQL Expression Language Tutorial (1.x API) appropriate in the vast majority of cases;
unbuffered cursors are not generally useful
SQL Statements and Expressions API except in the uncommon case
of an application fetching a very large number of rows
in chunks, where
the processing of these rows can be complete before more rows
Schema Definition Language are fetched.
To make use of a server side cursor for a particular execution, the
Engine and Connection Use Connection.execution_options.stream_results option
is used, which may be called on
the Connection object,
on the statement object, or in the ORM-level contexts
mentioned below.
When using this option for a statement, it’s usually appropriate to use
a method like
Basic Usage Result.partitions() to work on small sections
of the result set at a time, while also
fetching enough rows for each
pull so that the operation is efficient:
Using Transactions
Nesting of Transaction Blocks with engine.connect() as conn:
Arbitrary Transaction Nesting as result = conn.execution_options(stream_results=True).execu
an Antipattern
for partition in result.partitions(100):
Migrating from the “nesting” _process_rows(partition)

pattern
Library Level (e.g. emulated) If the Result is iterated directly, rows are fetched internally
using a default buffering
Autocommit scheme that buffers first a small set of rows,
then a larger and larger buffer on each
fetch up to a pre-configured limit
of 1000 rows. This can be affected using the
max_row_buffer execution
option:
Understanding the DBAPI-Level with engine.connect() as conn:

conn = conn.execution_options(stream_results=True, max_row
result = conn.execute(text("select * from table"))

results) for row in result:
_process_row(row)
Execution
The size of the buffer may also be set to a fixed size using the
Result.yield_per()
method. Calling this method with a number
of rows will cause all result-fetching
SQL Compilation Caching methods to work from
buffers of the given size, only fetching new rows when the
buffer is empty:
Configuration

Using Logging result = conn.execution_options(stream_results=True).execu

for row in result.yield_per(100):
use? _process_row(row)
The stream_results option is also available with the ORM. When using the
ORM,
SQLAlchemy 1.4 Documentation either the Result.yield_per() or Result.partitions()
methods should be used to set
the number of ORM rows to be buffered each time
while yielding:
CURRENT RELEASE
Home
with orm.Session(engine) as session:
Search terms:
search... result = session.execute(
select(User).order_by(User_id).execution_options(strea
)
for partition in result.partitions(100):
Your new development _process_rows(partition)

latest listings.
ADS VIA CARBON

Note
SQLAlchemy Core
ORM result sets currently must make use of Result.yield_per()
SQL Expression Language Tutorial (1.x API) or Result.partitions() in order to achieve streaming ORM results.
If either of these methods are not used to set the number of rows
to
fetch before yielding, the entire result is fetched before rows
Schema Definition Language are yielded.
This may change in a future release so that the
automatic buffer size used
by Connection takes place for ORM
results as well.
Engine Configuration When using a 1.x style ORM query with Query , yield_per is
available via
Working with Engines and Connections Query.yield_per() - this also sets the stream_results
execution option:
Basic Usage
for row in session.query(User).yield_per(100):
Using Transactions # process row

Connectionless Execution, Implicit Execution
an Antipattern
Migrating from the “nesting” Deprecated since version 2.0: The features of “connectionless” and “implicit”
pattern execution
in SQLAlchemy are deprecated and will be removed in version 2.0.
See
“Implicit” and “Connectionless” execution, “bound metadata” removed for
background.
Autocommit

Recall from the first section we mentioned executing with and without explicit
usage
including DBAPI Autocommit of Connection . “Connectionless” execution
refers to the usage of the execute()

method on an object
which is not a Connection . This was illustrated using the
Engine.execute() method of Engine :
Using Server Side Cursors (a.k.a. stream result = engine.execute(text("select username from users"))
results) for row in result:
print("username:", row['username'])
Execution
In addition to “connectionless” execution, it is also possible
to use the
Translation of Schema Names Executable.execute() method of
any Executable construct, which is a marker for SQL
expression objects
that support execution. The SQL expression object itself
references an
Engine or Connection known as the bind, which it uses
in order to
Configuration provide so-called “implicit” execution services.
Estimating Cache Performance Given a table as below:

Using Logging
from sqlalchemy import MetaData, Table, Column, Integer

use? metadata_obj = MetaData()

users_table = Table('users', metadata_obj,
Column('id', Integer, primary_key=True),
Column('name', String(50))
SQLAlchemy 1.4 Documentation )
CURRENT RELEASE
Home
| Download this Documentation Explicit execution delivers the SQL text or constructed SQL expression to the
Connection.execute() method of Connection :
Search terms:
search...
engine = create_engine('sqlite:///file.db')
Your new development result = connection.execute(users_table.select())
career awaits. Check out the for row in result:
latest listings. # ....
ADS VIA CARBON
Explicit, connectionless execution delivers the expression to the

Engine.execute()
SQLAlchemy Core
method of Engine :

engine = create_engine('sqlite:///file.db')

result = engine.execute(users_table.select())
Schema Definition Language for row in result:
# ....
Column and Data Types result.close()

Implicit execution is also connectionless, and makes usage of the
Executable.execute() method
on the expression itself. This method is provided as
Working with Engines and Connections part of the
Executable class, which refers to a SQL statement that is sufficient
for
being invoked against the database. The method makes usage of
the assumption
Basic Usage
that either an
Engine or
Connection has been bound to the expression
object. By
Using Transactions “bound” we mean that the special attribute MetaData.bind
has been used to associate
a series of
Table objects and all SQL constructs derived from them with a specific
engine:
an Antipattern engine = create_engine('sqlite:///file.db')
metadata_obj.bind = engine
Migrating from the “nesting” result = users_table.select().execute()
pattern for row in result:
# ....

result.close()
Autocommit
Setting Transaction Isolation Levels Above, we associate an Engine with a MetaData object using
the special attribute
including DBAPI Autocommit MetaData.bind . The select() construct produced
from the Table object has a method
Executable.execute() , which will
search for an Engine that’s “bound” to the Table .
Autocommit Isolation Level Overall, the usage of “bound metadata” has three general effects:
Using Server Side Cursors (a.k.a. stream SQL statement objects gain an Executable.execute() method which
results) automatically
locates a “bind” with which to execute themselves.
Connectionless Execution, Implicit The ORM Session object supports using “bound metadata” in order
to establish
Execution which Engine should be used to invoke SQL statements
on behalf of a particular
mapped class, though the Session
also features its own explicit system of
Translation of Schema Names establishing complex Engine /
mapped class configurations.
The MetaData.create_all() , MetaData.drop_all() , Table.create() ,
Table.drop() ,
Configuration and “autoload” features all make usage of the bound
Engine automatically
without the need to pass it explicitly.
Using Logging Note

The concepts of “bound metadata” and “implicit execution” are
use? not emphasized in modern SQLAlchemy.
While they offer some
convenience, they are no longer required by any API and
are
never necessary.
In applications where multiple Engine objects are present, each
SQLAlchemy 1.4 Documentation one logically associated
with a certain set of tables (i.e. vertical
sharding), the “bound metadata” technique can be used
so that
CURRENT RELEASE
individual Table can refer to the appropriate Engine automatically;
Home
in particular this is supported within the ORM via the Session
object
as a means to associate Table objects with an appropriate
Search terms:
search...
Engine ,
as an alternative to using the bind arguments accepted
directly by the Session .
Your new development However, the “implicit execution” technique is not at all
career awaits. Check out the appropriate for use with the
ORM, as it bypasses the transactional
latest listings.
context maintained by the Session .
ADS VIA CARBON
Overall, in the vast majority of cases, “bound metadata” and

SQLAlchemy Core
“implicit execution”
are not useful. While “bound metadata” has a
marginal level of usefulness with regards to
ORM configuration,
“implicit execution” is a very old usage pattern that in most
cases
SQL Statements and Expressions API is more confusing than it is helpful, and its usage is discouraged.
Both patterns seem to encourage the overuse of expedient
“short cuts” in application design
which lead to problems later on.
Modern SQLAlchemy usage, especially the ORM, places a heavy
Engine and Connection Use stress on working within the context
of a transaction at all times;
Engine Configuration the “implicit execution” concept makes the job of

associating
statement execution with a particular transaction much more
Working with Engines and Connections difficult.
The Executable.execute() method on a particular SQL
statement
usually implies that the execution is not part of any
Basic Usage
particular transaction, which is
usually not the desired effect.
Using Transactions

In both “connectionless” examples, the
Connection is created behind the scenes; the
Arbitrary Transaction Nesting as CursorResult returned by the execute()
call references the Connection used to issue
the SQL statement. When the CursorResult is closed, the underlying
Connection is
an Antipattern
closed for us, resulting in the
DBAPI connection being returned to the pool with
Migrating from the “nesting” transactional resources removed.
pattern

Autocommit
To support multi-tenancy applications that distribute common sets of tables
into
Setting Transaction Isolation Levels multiple schemas, the
Connection.execution_options.schema_translate_map
execution
including DBAPI Autocommit option may be used to repurpose a set of Table objects
to render under different
schema names without any changes.
Autocommit Isolation Level Given a table:

user_table = Table(
results)
'user', metadata_obj,
Connectionless Execution, Implicit Column('id', Integer, primary_key=True),
Column('name', String(50))
Execution
)
SQL Compilation Caching The “schema” of this Table as defined by the

Table.schema attribute is None . The
Connection.execution_options.schema_translate_map can specify
that all Table objects
Configuration with a schema of None would instead
render the schema as user_schema_one :
Using Logging connection = engine.connect().execution_options(
schema_translate_map={None: "user_schema_one"})

use? result = connection.execute(user_table.select())

The above code will invoke SQL on the database of the form:
SELECT user_schema_one.user.id, user_schema_one.user.name FROM

SQLAlchemy 1.4 Documentation user_schema_one.user
CURRENT RELEASE
Home
That is, the schema name is substituted with our translated name. The
map can
Search terms:
search... specify any number of target->destination schemas:
connection = engine.connect().execution_options(
Your new development schema_translate_map={
career awaits. Check out the None: "user_schema_one", # no schema name -> "user_
latest listings. "special": "special_schema", # schema="special" become
ADS VIA CARBON "public": None # Table objects with sche
})
SQLAlchemy Core

The Connection.execution_options.schema_translate_map parameter
affects all DDL
SQL Statements and Expressions API and SQL constructs generated from the SQL expression language,
as derived from

the Table or Sequence objects.
It does not impact literal string SQL used via the text()
construct nor via plain strings passed to Connection.execute() .
The feature takes effect only in those cases where the name of the
schema is
derived directly from that of a Table or Sequence ;
it does not impact methods where a
Engine Configuration string schema name is passed directly.
By this pattern, it takes effect within the “can
create” / “can drop” checks
performed by methods such as MetaData.create_all() or
Working with Engines and Connections MetaData.drop_all() are called, and it takes effect when
using table reflection given a
Basic Usage Table object. However it does

not affect the operations present on the Inspector
object,
as the schema name is passed to these methods explicitly.
Using Transactions
Tip
Arbitrary Transaction Nesting as To use the schema translation feature with the ORM Session ,
set this option at the
an Antipattern level of the Engine , then pass that engine

to the Session . The Session uses a new
Connection for each transaction:
pattern schema_engine = engine.execution_options(schema_translat
session = Session(schema_engine)
Autocommit
Setting Transaction Isolation Levels ...


Warning
When using the ORM Session without extensions, the
schema
translate feature is only supported as
a single
results)
schema translate map per Session. It will not work if
Connectionless Execution, Implicit different schema translate maps are given on a per-
statement basis, as
the ORM Session does not take
Execution
current schema translate
values into account for
Translation of Schema Names individual objects.

To use a single Session with multiple
Configuration schema_translate_map
configurations, the Horizontal
Sharding extension may
be used. See the example at
Horizontal Sharding.
Using Logging

use?
New in version 1.1.
SQLAlchemy 1.4 Documentation SQL Compilation Caching

CURRENT RELEASE
Home
| Download this Documentation New in version 1.4: SQLAlchemy now has a transparent query caching system
that substantially lowers the Python computational overhead involved in
Search terms:
search... converting SQL statement constructs into SQL strings across both
Core and
ORM. See the introduction at Transparent SQL Compilation Caching added to
All DQL, DML Statements in Core, ORM.
latest listings. SQLAlchemy includes a comprehensive caching system for the SQL compiler as well
as its ORM variants. This caching system is transparent within the
Engine and
ADS VIA CARBON
provides that the SQL compilation process for a given Core
or ORM SQL statement,
SQLAlchemy Core as well as related computations which assemble
result-fetching mechanics for that
statement, will only occur once for that
statement object and all others with the
SQL Expression Language Tutorial (1.x API) identical
structure, for the duration that the particular structure remains within the
SQL Statements and Expressions API engine’s “compiled cache”. By “statement objects that have the identical
structure”,
this generally corresponds to a SQL statement that is
constructed within a function
Schema Definition Language and is built each time that function runs:
def run_my_statement(connection, parameter):

stmt = select(table)
Engine Configuration stmt = stmt.where(table.c.col == parameter)
stmt = stmt.order_by(table.c.id)
Working with Engines and Connections return connection.execute(stmt)

Basic Usage
The above statement will generate SQL resembling
SELECT id, col FROM table WHERE
Using Transactions
col = :col ORDER BY id , noting that
while the value of parameter is a plain Python
Nesting of Transaction Blocks object such as a string
or an integer, the string SQL form of the statement does not
include this
value as it uses bound parameters. Subsequent invocations of the above
run_my_statement() function will use a cached compilation construct
within the scope
an Antipattern of the connection.execute() call for enhanced performance.
Note
pattern
Library Level (e.g. emulated) it is important to note that the SQL compilation cache is caching
the SQL string that is passed to the database only, and not the
Autocommit
data
returned by a query. It is in no way a data cache and does not
Setting Transaction Isolation Levels impact the results returned for a particular SQL statement nor
including DBAPI Autocommit does it

imply any memory use linked to fetching of result rows.

While SQLAlchemy has had a rudimentary statement cache since the early 1.x
series,
and additionally has featured the “Baked Query” extension for the ORM,
both of
Using Server Side Cursors (a.k.a. stream these systems required a high degree of special API use in order for
the cache to be
results) effective. The new cache as of 1.4 is instead completely
automatic and requires no
change in programming style to be effective.
Execution The cache is automatically used without any configurational changes and no
special
steps are needed in order to enable it. The following sections
detail the configuration
and advanced usage patterns for the cache.
Configuration
Configuration
The cache itself is a dictionary-like object called an LRUCache , which is
an internal
Estimating Cache Performance SQLAlchemy dictionary subclass that tracks the usage of particular
keys and
Using Logging features a periodic “pruning” step which removes the least recently
used items when
the size of the cache reaches a certain threshold. The size
of this cache defaults to
How much memory does the cache 500 and may be configured using the
create_engine.query_cache_size parameter:
use?
engine = create_engine("postgresql://scott:tiger@localhost/tes
The size of the cache can grow to be a factor of 150% of the size given, before
it’s
SQLAlchemy 1.4 Documentation pruned back down to the target size. A cache of size 1200 above can therefore
grow
to be 1800 elements in size at which point it will be pruned to 1200.
CURRENT RELEASE
Home
| Download this Documentation The sizing of the cache is based on a single entry per unique SQL statement
rendered,
per engine. SQL statements generated from both the Core and the ORM
Search terms:
search... are
treated equally. DDL statements will usually not be cached. In order to determine
what the cache is doing, engine logging will include details about the
cache’s
behavior, described in the next section.
career awaits. Check out the Estimating Cache Performance Using Logging
latest listings.
The above cache size of 1200 is actually fairly large. For small applications,
a size of
ADS VIA CARBON 100 is likely sufficient. To estimate the optimal size of the cache,
assuming enough
memory is present on the target host, the size of the cache
should be based on the
SQLAlchemy Core
number of unique SQL strings that may be rendered for the
target engine in use. The
most expedient way to see this is to use
SQL echoing, which is most directly enabled
by using the
create_engine.echo flag, or by using Python logging; see the
section
SQL Statements and Expressions API Configuring Logging for background on logging configuration.

As an example, we will examine the logging produced by the following program:

from sqlalchemy import Column
Engine Configuration from sqlalchemy import ForeignKey
from sqlalchemy import Integer

from sqlalchemy import String
Basic Usage from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import relationship
Using Transactions from sqlalchemy.orm import Session

Base = declarative_base()

an Antipattern
class A(Base):
Migrating from the “nesting” __tablename__ = "a"
pattern
id = Column(Integer, primary_key=True)
Library Level (e.g. emulated) data = Column(String)
Autocommit bs = relationship("B")

including DBAPI Autocommit class B(Base):
__tablename__ = "b"

id = Column(Integer, primary_key=True)
Autocommit Isolation Level a_id = Column(ForeignKey("a.id"))
Using Server Side Cursors (a.k.a. stream data = Column(String)
results)
Connectionless Execution, Implicit e = create_engine("sqlite://", echo=True)
Base.metadata.create_all(e)
Execution
Translation of Schema Names s = Session(e)

s.add_all(
Configuration [A(bs=[B(), B(), B()]), A(bs=[B(), B(), B()]), A(bs=[B(),

)
Estimating Cache Performance s.commit()
Using Logging
for a_rec in s.query(A):

print(a_rec.bs)
use?

When run, each SQL statement that’s logged will include a bracketed
cache statistics
SQLAlchemy 1.4 Documentation badge to the left of the parameters passed. The four
types of message we may see
are summarized as follows:
CURRENT RELEASE
Home
| Download this Documentation [raw sql] - the driver or the end-user emitted raw SQL using
Connection.exec_driver_sql() - caching does not apply
Search terms:
search...
[no key] - the statement object is a DDL statement that is not cached, or
the
statement object contains uncacheable elements such as user-defined
constructs or arbitrarily large VALUES clauses.
[generated in Xs] - the statement was a cache miss and had to be
compiled,
latest listings.
then stored in the cache. it took X seconds to produce the
compiled construct.
ADS VIA CARBON
The number X will be in the small fractional seconds.
SQLAlchemy Core
[cached since Xs ago] - the statement was a cache hit and did not
have to be
SQL Expression Language Tutorial (1.x API) recompiled. The statement has been stored in the cache since
X seconds ago.
The number X will be proportional to how long the application
has been running
SQL Statements and Expressions API and how long the statement has been cached, so for example
would be 86400
Schema Definition Language for a 24 hour period.
Column and Data Types Each badge is described in more detail below.
Engine and Connection Use The first statements we see for the above program will be the SQLite dialect
checking for the existence of the “a” and “b” tables:

INFO sqlalchemy.engine.Engine PRAGMA temp.table_info("a")
Basic Usage INFO sqlalchemy.engine.Engine [raw sql] ()
INFO sqlalchemy.engine.Engine PRAGMA main.table_info("b")
Using Transactions INFO sqlalchemy.engine.Engine [raw sql] ()

For the above two SQLite PRAGMA statements, the badge reads [raw sql] ,
which
indicates the driver is sending a Python string directly to the
database using
an Antipattern Connection.exec_driver_sql() . Caching does not apply
to such statements because
Migrating from the “nesting” they already exist in string form, and there
is nothing known about what kinds of
result rows will be returned since
SQLAlchemy does not parse SQL strings ahead of
pattern
time.
The next statements we see are the CREATE TABLE statements:
Autocommit
Setting Transaction Isolation Levels INFO sqlalchemy.engine.Engine
including DBAPI Autocommit CREATE TABLE a (
id INTEGER NOT NULL,

data VARCHAR,
Autocommit Isolation Level PRIMARY KEY (id)

results) INFO sqlalchemy.engine.Engine [no key 0.00007s] ()
INFO sqlalchemy.engine.Engine

CREATE TABLE b (
Execution id INTEGER NOT NULL,

a_id INTEGER,
data VARCHAR,
SQL Compilation Caching PRIMARY KEY (id),
FOREIGN KEY(a_id) REFERENCES a (id)
Configuration
)

Using Logging
INFO sqlalchemy.engine.Engine [no key 0.00006s] ()

For each of these statements, the badge reads [no key 0.00006s] . This
indicates that
use?
these two particular statements, caching did not occur because
the DDL-oriented
Disabling or using an alternate CreateTable construct did not produce a
cache key. DDL constructs generally do not
participate in caching because
they are not typically subject to being repeated a
second time and DDL
is also a database configurational step where performance is
SQLAlchemy 1.4 Documentation not as critical.
CURRENT RELEASE The [no key] badge is important for one other reason, as it can be produced
for SQL
Home
| Download this Documentation statements that are cacheable except for some particular sub-construct
that is not
currently cacheable. Examples of this include custom user-defined
SQL elements
Search terms:
search... that don’t define caching parameters, as well as some constructs
that generate
arbitrarily long and non-reproducible SQL strings, the main
examples being the
Values construct as well as when using “multivalued
inserts” with the Insert.values()
Your new development method.
latest listings. So far our cache is still empty. The next statements will be cached however,
a
segment looks like:
ADS VIA CARBON
SQLAlchemy Core
INFO sqlalchemy.engine.Engine INSERT INTO a (data) VALUES (?)
INFO sqlalchemy.engine.Engine [generated in 0.00011s] (None,)

SQL Statements and Expressions API INFO sqlalchemy.engine.Engine [cached since 0.0003533s ago] (N

INFO sqlalchemy.engine.Engine [cached since 0.0005326s ago] (N
Column and Data Types INFO sqlalchemy.engine.Engine INSERT INTO b (a_id, data) VALUE
INFO sqlalchemy.engine.Engine [generated in 0.00010s] (1, None
Engine and Connection Use INFO sqlalchemy.engine.Engine INSERT INTO b (a_id, data) VALUE
INFO sqlalchemy.engine.Engine [cached since 0.0003232s ago] (1
INFO sqlalchemy.engine.Engine INSERT INTO b (a_id, data) VALUE
Working with Engines and Connections INFO sqlalchemy.engine.Engine [cached since 0.0004887s ago] (1
Basic Usage
Using Transactions Above, we see essentially two unique SQL strings; "INSERT INTO a (data) VALUES (?)"
and "INSERT INTO b (a_id, data) VALUES (?, ?)" . Since SQLAlchemy uses
bound
parameters for all literal values, even though these statements are
repeated many
Arbitrary Transaction Nesting as times for different objects, because the parameters are separate,
the actual SQL
an Antipattern string stays the same.
Migrating from the “nesting” Note
pattern
the above two statements are generated by the ORM unit of work
Library Level (e.g. emulated) process, and in fact will be caching these in a separate cache that
Autocommit is
local to each mapper. However the mechanics and terminology
are the same.
The section Disabling or using an alternate
dictionary to cache some (or all) statements below will describe
including DBAPI Autocommit how user-facing
code can also use an alternate caching container
Understanding the DBAPI-Level on a per-statement basis.

The caching badge we see for the first occurrence of each of these two
statements
is [generated in 0.00011s] . This indicates that the statement
was not in the cache,
results)
was compiled into a String in .00011s and was then
cached. When we see the
Connectionless Execution, Implicit [generated] badge, we know that this means
there was a cache miss. This is to be
expected for the first occurrence of
a particular statement. However, if lots of new
Execution
[generated] badges are
observed for a long-running application that is generally
Translation of Schema Names using the same series
of SQL statements over and over, this may be a sign that the
create_engine.query_cache_size parameter is too small. When a
statement that was
cached is then evicted from the cache due to the LRU
cache pruning lesser used
Configuration items, it will display the [generated] badge
when it is next used.

The caching badge that we then see for the subsequent occurrences of each of
Using Logging these two statements looks like [cached since 0.0003533s ago] . This
indicates that
the statement was found in the cache, and was originally
placed into the cache
.0003533 seconds ago. It is important to note that
while the [generated] and
use? [cached since] badges refer to a number of
seconds, they mean different things; in
Disabling or using an alternate the case of [generated] , the number

is a rough timing of how long it took to compile
the statement, and will be an
extremely small amount of time. In the case of [cached
since] , this is
the total time that a statement has been present in the cache. For an
SQLAlchemy 1.4 Documentation application that’s been running for six hours, this number may read [cached
since
21600 seconds ago] , and that’s a good thing. Seeing high numbers for
“cached since”
CURRENT RELEASE
is an indication that these statements have not been subject to
cache misses for a
Home
long time. Statements that frequently have a low number of
“cached since” even if
the application has been running a long time may
indicate these statements are too
Search terms:
search...
frequently subject to cache misses, and that
the
create_engine.query_cache_size may
need to be increased.
Your new development Our example program then performs some SELECTs where we can see the same
career awaits. Check out the pattern of “generated” then “cached”, for the SELECT of the “a” table as well
as for
latest listings. subsequent lazy loads of the “b” table:
ADS VIA CARBON
SQLAlchemy Core INFO sqlalchemy.engine.Engine SELECT a.id AS a_id, a.data AS a

FROM a

INFO sqlalchemy.engine.Engine [generated in 0.00009s] ()
INFO sqlalchemy.engine.Engine SELECT b.id AS b_id, b.a_id AS b

SQL Statements and Expressions API FROM b
WHERE ? = b.a_id

INFO sqlalchemy.engine.Engine [generated in 0.00010s] (1,)
Column and Data Types INFO sqlalchemy.engine.Engine SELECT b.id AS b_id, b.a_id AS b
FROM b

WHERE ? = b.a_id
Engine Configuration INFO sqlalchemy.engine.Engine [cached since 0.0005922s ago] (2

INFO sqlalchemy.engine.Engine SELECT b.id AS b_id, b.a_id AS b
Working with Engines and Connections FROM b
WHERE ? = b.a_id
Basic Usage
Using Transactions
Nesting of Transaction Blocks From our above program, a full run shows a total of four distinct SQL strings
being
cached. Which indicates a cache size of four would be sufficient. This is
obviously an
Arbitrary Transaction Nesting as extremely small size, and the default size of 500 is fine to be left
at its default.
an Antipattern
How much memory does the cache use?
The previous section detailed some techniques to check if the
pattern
create_engine.query_cache_size needs to be bigger. How do we know
if the cache is
Library Level (e.g. emulated) not too large? The reason we may want to set
create_engine.query_cache_size to not
be higher than a certain
number would be because we have an application that may
Autocommit
make use of a very large
number of different statements, such as an application that
Setting Transaction Isolation Levels is building queries
on the fly from a search UX, and we don’t want our host to run out
including DBAPI Autocommit of memory
if for example, a hundred thousand different queries were run in the past
24 hours
and they were all cached.
Autocommit Isolation Level It is extremely difficult to measure how much memory is occupied by Python
data
structures, however using a process to measure growth in memory via top as a
Using Server Side Cursors (a.k.a. stream successive series of 250 new statements are added to the cache suggest a
results) moderate Core statement takes up about 12K while a small ORM statement takes
about
20K, including result-fetching structures which for the ORM will be much
greater.
Execution

Disabling or using an alternate dictionary to cache some (or
all) statements
The internal cache used is known as LRUCache , but this is mostly just
a dictionary. Any
Configuration dictionary may be used as a cache for any series of
statements by using the
Connection.execution_options.compiled_cache
option as an execution option.
Execution options may be set on a statement,
on an Engine or Connection , as well as
Using Logging when using the ORM Session.execute() method for SQLAlchemy-2.0
style

invocations. For example, to run a series of SQL statements and have
them cached in
a particular dictionary:
use?
Disabling or using an alternate my_cache = {}
dictionary to cache some (or all) with engine.connect().execution_options(compiled_cache=my_cach
conn.execute(table.select())
CURRENT RELEASE
The SQLAlchemy ORM uses the above technique to hold onto per-mapper caches
Home
within the unit of work “flush” process that are separate from the default
cache
Search terms:
search... configured on the Engine , as well as for some
relationship loader queries.
The cache can also be disabled with this argument by sending a value of
None :

# disable caching for this connection

with engine.connect().execution_options(compiled_cache=None) a
latest listings.
conn.execute(table.select())
ADS VIA CARBON
SQLAlchemy Core
Caching for Third Party Dialects
The caching feature requires that the dialect’s compiler produces SQL
strings that
SQL Statements and Expressions API are safe to reuse for many statement invocations, given
a particular cache key that is
keyed to that SQL string. This means
that any literal values in a statement, such as
the LIMIT/OFFSET values for
a SELECT, can not be hardcoded in the dialect’s
Column and Data Types compilation scheme, as
the compiled string will not be re-usable. SQLAlchemy
supports rendered
bound parameters using the
BindParameter.render_literal_execute()
method which can be applied to the existing
Engine Configuration Select._limit_clause and
Select._offset_clause attributes by a custom compiler,
which
are illustrated later in this section.
As there are many third party dialects, many of which may be generating literal
values
Basic Usage
from SQL statements without the benefit of the newer “literal execute”
feature,
Using Transactions SQLAlchemy as of version 1.4.5 has added an attribute to dialects
known as
Dialect.supports_statement_cache . This attribute is
checked at runtime for its
presence directly on a particular dialect’s class,
even if it’s already present on a
Arbitrary Transaction Nesting as superclass, so that even a third party
dialect that subclasses an existing cacheable
an Antipattern SQLAlchemy dialect such as
sqlalchemy.dialects.postgresql.PGDialect must still
explicitly include this
attribute for caching to be enabled. The attribute should only
Migrating from the “nesting” be enabled
once the dialect has been altered as needed and tested for reusability of
pattern compiled SQL statements with differing parameters.
Library Level (e.g. emulated) For all third party dialects that don’t support this attribute, the logging for
such a
Autocommit dialect will indicate dialect does not support caching .
Setting Transaction Isolation Levels When a dialect has been tested against caching, and in particular the SQL
compiler
including DBAPI Autocommit has been updated to not render any literal LIMIT / OFFSET within
a SQL string
directly, dialect authors can apply the attribute as follows:
from sqlalchemy.engine.default import DefaultDialect

class MyDialect(DefaultDialect):
results)
supports_statement_cache = True
Execution The flag needs to be applied to all subclasses of the dialect as well:

class MyDBAPIForMyDialect(MyDialect):

supports_statement_cache = True
Configuration

New in version 1.4.5: Added the Dialect.supports_statement_cache attribute.
Using Logging

The typical case for dialect modification follows.
use?
Example: Rendering LIMIT / OFFSET with post compile
parameters
As an example, suppose a dialect overrides the SQLCompiler.limit_clause()
method,
SQLAlchemy 1.4 Documentation which produces the “LIMIT / OFFSET” clause for a SQL statement,
like this:
CURRENT RELEASE
# pre 1.4 style code
Home
def limit_clause(self, select, **kw):
Search terms:
search... text = ""
if select._limit is not None:
text += " \n LIMIT %d" % (select._limit, )
if select._offset is not None:
Your new development text += " \n OFFSET %d" % (select._offset, )
career awaits. Check out the return text

latest listings.
ADS VIA CARBON

The above routine renders the Select._limit and
Select._offset integer values as
SQLAlchemy Core literal integers embedded in the SQL
statement. This is a common requirement for
databases that do not support using
a bound parameter within the LIMIT/OFFSET
SQL Expression Language Tutorial (1.x API) clauses of a SELECT statement.
However, rendering the integer value within the

initial compilation stage is
directly incompatible with caching as the limit and offset
integer values
of a Select object are not part of the cache key, so that many
Select
Schema Definition Language statements with different limit/offset values would not render
with the correct value.

The correction for the above code is to move the literal integer into
SQLAlchemy’s
Engine and Connection Use post-compile facility, which will render the
literal integer outside of the initial
compilation stage, but instead at
execution time before the statement is sent to the
DBAPI. This is accessed
within the compilation stage using the
Working with Engines and Connections BindParameter.render_literal_execute()
method, in conjunction with using the
Select._limit_clause and
Select._offset_clause attributes, which represent the
Basic Usage LIMIT/OFFSET
as a complete SQL expression, as follows:
Using Transactions
# 1.4 cache-compatible code

def limit_clause(self, select, **kw):
Arbitrary Transaction Nesting as text = ""
an Antipattern
limit_clause = select._limit_clause
Migrating from the “nesting” offset_clause = select._offset_clause
pattern
if select._simple_int_clause(limit_clause):
Library Level (e.g. emulated) text += " \n LIMIT %s" % (
Autocommit self.process(limit_clause.render_literal_execute()
)
Setting Transaction Isolation Levels elif limit_clause is not None:
including DBAPI Autocommit # assuming the DB doesn't support SQL expressions for
# Otherwise render here normally

raise exc.CompileError(
Autocommit Isolation Level "dialect 'mydialect' can only render simple intege
)

if select._simple_int_clause(offset_clause):
results) text += " \n OFFSET %s" % (
self.process(offset_clause.render_literal_execute(
)
Execution elif offset_clause is not None:

# assuming the DB doesn't support SQL expressions for
# Otherwise render here normally
SQL Compilation Caching raise exc.CompileError(
"dialect 'mydialect' can only render simple intege

Configuration
)

Using Logging
return text

use? The approach above will generate a compiled SELECT statement that looks like:

SELECT x FROM y
SQLAlchemy 1.4 Documentation LIMIT __[POSTCOMPILE_param_1]
CURRENT RELEASE OFFSET __[POSTCOMPILE_param_2]

Home
Where above, the __[POSTCOMPILE_param_1] and __[POSTCOMPILE_param_2]
indicators
Search terms:
search... will be populated with their corresponding integer values at
statement execution
time, after the SQL string has been retrieved from the
cache.
Your new development After changes like the above have been made as appropriate, the
career awaits. Check out the Dialect.supports_statement_cache flag should be set to True .
It is strongly
latest listings. recommended that third party dialects make use of the
dialect third party test suite
which will assert that operations like
SELECTs with LIMIT/OFFSET are correctly
ADS VIA CARBON
rendered and cached.
SQLAlchemy Core
See also
Why is my application slow after upgrading to 1.4 and/or 2.x? - in the Frequently Asked
Questions section

Using Lambdas to add significant speed gains to statement
Engine and Connection Use production
Engine Configuration Deep Alchemy

This technique is generally non-essential except in very
Basic Usage performance

intensive scenarios, and intended for experienced
Python programmers.
While fairly straightforward, it involves
Using Transactions metaprogramming concepts that are
not appropriate for novice
Nesting of Transaction Blocks Python developers. The lambda approach can be

applied to at a
later time to existing code with a minimal amount of effort.
an Antipattern
Python functions, typically expressed as lambdas, may be used to generate
SQL
Migrating from the “nesting” expressions which are cacheable based on the Python code location of
the lambda
pattern function itself as well as the closure variables within the
lambda. The rationale is to
allow caching of not only the SQL string-compiled
form of a SQL expression
construct as is SQLAlchemy’s normal behavior when
the lambda system isn’t used,
Autocommit but also the in-Python composition
of the SQL expression construct itself, which also
has some degree of
Python overhead.
including DBAPI Autocommit The lambda SQL expression feature is available as a performance enhancing
feature,
and is also optionally used in the with_loader_criteria()
ORM option in order to
provide a generic SQL fragment.

Synopsis
results) Lambda statements are constructed using the lambda_stmt() function,
which returns
an instance of StatementLambdaElement , which is
itself an executable statement
Connectionless Execution, Implicit construct. Additional modifiers and criteria
are added to the object using the Python
Execution addition operator + , or
alternatively the StatementLambdaElement.add_criteria()
method which
allows for more options.

It is assumed that the lambda_stmt() construct is being invoked
within an enclosing
function or method that expects to be used many times
within an application, so that
Configuration subsequent executions beyond the first one
can take advantage of the compiled SQL
being cached. When the lambda is
constructed inside of an enclosing function in
Python it is then subject
to also having closure variables, which are significant to the
Using Logging
whole
approach:
use? from sqlalchemy import lambda_stmt
Disabling or using an alternate def run_my_statement(connection, parameter):
dictionary to cache some (or all) stmt = lambda_stmt(lambda: select(table))
stmt += lambda s: s.where(table.c.col == parameter)
SQLAlchemy 1.4 Documentation stmt += lambda s: s.order_by(table.c.id)
CURRENT RELEASE return connection.execute(stmt)
Home
Search terms:
search... result = run_my_statement(some_connection, "some parameter
Your new development Above, the three lambda callables that are used to define the structure
of a SELECT
career awaits. Check out the statement are invoked exactly once, and the resulting SQL
string cached in the
latest listings.
compilation cache of the engine. From that point
forward, the run_my_statement()
ADS VIA CARBON function may be invoked any number
of times and the lambda callables within it will
not be called, only
used as cache keys to retrieve the already-compiled SQL.
SQLAlchemy Core
Note
SQL Statements and Expressions API It is important to note that there is already SQL caching in place
when the lambda system is not used. The lambda system only
adds an
additional layer of work reduction per SQL statement
Column and Data Types invoked by caching
the building up of the SQL construct itself and
also using a simpler
cache key.
Quick Guidelines for Lambdas
Above all, the emphasis within the lambda SQL system is ensuring that there
is never
Basic Usage a mismatch between the cache key generated for a lambda and the
SQL string it will
produce. The LamdaElement and related
objects will run and analyze the given lambda
Using Transactions
in order to calculate how
it should be cached on each run, trying to detect any
Nesting of Transaction Blocks potential problems.
Basic guidelines include:
Arbitrary Transaction Nesting as Any kind of statement is supported - while it’s expected that
select()
an Antipattern constructs are the prime use case for lambda_stmt() ,
DML statements such as
insert() and update() are
equally usable:
pattern
def upd(id_, newname):
Library Level (e.g. emulated) stmt = lambda_stmt(lambda: users.update())
stmt += lambda s: s.values(name=newname)
Autocommit
stmt += lambda s: s.where(users.c.id==id_)
Setting Transaction Isolation Levels return stmt

Understanding the DBAPI-Level conn.execute(upd(7, "foo"))


ORM use cases directly supported as well - the lambda_stmt()
can
accommodate ORM functionality completely and used directly with
results)
Session.execute() :
Execution def select_user(session, name):
stmt = lambda_stmt(lambda: select(User))

stmt += lambda s: s.where(User.name == name)

row = session.execute(stmt).first()
Configuration return row

Using Logging Bound parameters are automatically accommodated - in contrast to
SQLAlchemy’s
previous “baked query” system, the lambda SQL system
How much memory does the cache accommodates for
Python literal values which become SQL bound parameters
use? automatically.
This means that even though a given lambda runs only once, the
values that
become bound parameters are extracted from the closure of the
lambda
on every run:
>>> def my_stmt(x, y):
SQLAlchemy 1.4 Documentation ... stmt = lambda_stmt(lambda: select(func.max(x, y)))
... return stmt
CURRENT RELEASE
...
Home
>>> engine = create_engine("sqlite://", echo=True)
>>> with engine.connect() as conn:
Search terms:
search...
... print(conn.scalar(my_stmt(5, 10)))
... print(conn.scalar(my_stmt(12, 8)))
...

career awaits. Check out the SELECT max(?, ?) AS max_1
latest listings. [generated in 0.00057s] (5, 10)
ADS VIA CARBON

10
SQLAlchemy Core
SELECT max(?, ?) AS max_1

[cached since 0.002059s ago] (12, 8)
SQL Statements and Expressions API 12

Above, StatementLambdaElement extracted the values of x
and y from the closure
Column and Data Types of the lambda that is generated each time
my_stmt() is invoked; these were
Engine and Connection Use substituted into the cached SQL
construct as the values of the parameters.
Engine Configuration The lambda should ideally produce an identical SQL structure in all cases -
Avoid using conditionals or custom callables inside of lambdas that might make
it produce different SQL based on inputs; if a function might conditionally
use
Basic Usage two different SQL fragments, use two separate lambdas:
Using Transactions
# **Don't** do this:

def my_stmt(parameter, thing=False):

stmt = lambda_stmt(lambda: select(table))
an Antipattern stmt += (
lambda s: s.where(table.c.x > parameter) if thing

else s.where(table.c.y == parameter)
pattern return stmt

# **Do** do this:
Autocommit
Setting Transaction Isolation Levels def my_stmt(parameter, thing=False):
stmt = lambda_stmt(lambda: select(table))

if thing:
Understanding the DBAPI-Level stmt += lambda s: s.where(table.c.x > parameter)
else:

stmt += lambda s: s.where(table.c.y == parameter)
Using Server Side Cursors (a.k.a. stream return stmt

results)

There are a variety of failures which can occur if the lambda does not
produce a
consistent SQL construct and some are not trivially detectable
right now.
Execution
Don’t use functions inside the lambda to produce bound values - the
bound
value tracking approach requires that the actual value to be used in
the SQL
SQL Compilation Caching statement be locally present in the closure of the lambda. This is
not possible if
values are generated from other functions, and the
LambdaElement should
Configuration
normally raise an error if this is
attempted:
Using Logging >>> def my_stmt(x, y):
... def get_x():

... return x
use? ... def get_y():
... return y

...

... stmt = lambda_stmt(lambda: select(func.max(get_x()
... return stmt
SQLAlchemy 1.4 Documentation ...
>>> with engine.connect() as conn:
CURRENT RELEASE ... print(conn.scalar(my_stmt(5, 10)))
Home
| Download this Documentation ...
Traceback (most recent call last):
Search terms:
search... # ...
sqlalchemy.exc.InvalidRequestError: Can't invoke Python cal

inside of lambda expression argument at
Your new development <code object <lambda> at 0x7fed15f350e0, file "<stdin>", li

career awaits. Check out the lambda SQL constructs should not invoke functions from clos
latest listings. to produce literal values since the lambda SQL system norma
bound values without actually invoking the lambda or any fu
ADS VIA CARBON
SQLAlchemy Core
Above, the use of get_x() and get_y() , if they are necessary, should
occur
outside of the lambda and assigned to a local closure variable:
Schema Definition Language >>> def my_stmt(x, y):
... def get_x():
Column and Data Types ... return x
... def get_y():

... return y
Engine Configuration ...
... x_param, y_param = get_x(), get_y()

... stmt = lambda_stmt(lambda: select(func.max(x_param
Basic Usage ... return stmt
Using Transactions
Nesting of Transaction Blocks Avoid referring to non-SQL constructs inside of lambdas as they are not
cacheable by default - this issue refers to how the LambdaElement
creates a
cache key from other closure variables within the statement. In order
to provide
an Antipattern the best guarantee of an accurate cache key, all objects located
in the closure of
the lambda are considered to be significant, and none
will be assumed to be
appropriate for a cache key by default.
So the following example will also raise a
pattern
rather detailed error message:
Autocommit >>> class Foo:
... def __init__(self, x, y):
Setting Transaction Isolation Levels ... self.x = x
including DBAPI Autocommit ... self.y = y
...

>>> def my_stmt(foo):
Autocommit Isolation Level ... stmt = lambda_stmt(lambda: select(func.max(foo.x, f

... return stmt

...
results) >>> with engine.connect() as conn:

... print(conn.scalar(my_stmt(Foo(5, 10))))
...
Execution
Traceback (most recent call last):
Translation of Schema Names # ...
sqlalchemy.exc.InvalidRequestError: Closure variable named

SQL Compilation Caching lambda callable <code object <lambda> at 0x7fed15f35450, fi
Configuration
"<stdin>", line 2> does not refer to a cacheable SQL elemen
does not appear to be serving as a SQL literal bound value
Estimating Cache Performance default SQL expression returned by the function. This vari
Using Logging remain outside the scope of a SQL-generating lambda so that
key may be generated from the lambda's state. Evaluate thi
How much memory does the cache outside of the lambda, set track_on=[<elements>] to explici
use? closure elements to track, or set track_closure_variables=F
closure variables from being part of the cache key.
The above error indicates that LambdaElement will not assume
that the Foo object
SQLAlchemy 1.4 Documentation passed in will continue to behave the same in all
cases. It also won’t assume it
can use Foo as part of the cache key
by default; if it were to use the Foo object as
CURRENT RELEASE
part of the cache key,
if there were many different Foo objects this would fill up
Home
the cache
with duplicate information, and would also hold long-lasting
references to
all of these objects.
Search terms:
search...
The best way to resolve the above situation is to not refer to foo
inside of the
lambda, and refer to it outside instead:
career awaits. Check out the >>> def my_stmt(foo):
latest listings.
... x_param, y_param = foo.x, foo.y
ADS VIA CARBON ... stmt = lambda_stmt(lambda: select(func.max(x_param

... return stmt
SQLAlchemy Core

In some situations, if the SQL structure of the lambda is guaranteed to
never
change based on input, to pass track_closure_variables=False
which will disable
Schema Definition Language any tracking of closure variables other than those
used for bound parameters:

>>> def my_stmt(foo):
Engine and Connection Use ... stmt = lambda_stmt(
... lambda: select(func.max(foo.x, foo.y)),
... track_closure_variables=False
Working with Engines and Connections ... )
... return stmt

Basic Usage
Using Transactions There is also the option to add objects to the element to explicitly form
part of
the cache key, using the track_on parameter; using this parameter
allows
specific values to serve as the cache key and will also prevent other
closure
Arbitrary Transaction Nesting as variables from being considered. This is useful for cases where part
of the SQL
an Antipattern being constructed originates from a contextual object of some sort
that may
have many different values. In the example below, the first
segment of the
Migrating from the “nesting” SELECT statement will disable tracking of the foo variable,
whereas the second
pattern segment will explicitly track self as part of the
cache key:

>>> def my_stmt(self, foo):
Autocommit
... stmt = lambda_stmt(
Setting Transaction Isolation Levels ... lambda: select(*self.column_expressions),

... track_closure_variables=False
... )
Understanding the DBAPI-Level ... stmt = stmt.add_criteria(
Autocommit Isolation Level ... lambda: self.where_criteria,
... track_on=[self]
Using Server Side Cursors (a.k.a. stream ... )
results) ... return stmt

Using track_on means the given objects will be stored long term in the
lambda’s
Execution
internal cache and will have strong references for as long as the
cache doesn’t
Translation of Schema Names clear out those objects (an LRU scheme of 1000 entries is used
by default).

Cache Key Generation
Configuration In order to understand some of the options and behaviors which occur
with lambda
SQL constructs, an understanding of the caching system
is helpful.
Using Logging SQLAlchemy’s caching system normally generates a cache key from a given
SQL
expression construct by producing a structure that represents all the
state within the
construct:
use?
Disabling or using an alternate >>> from sqlalchemy import select, column
dictionary to cache some (or all) >>> stmt = select(column('q'))
>>> cache_key = stmt._generate_cache_key()
SQLAlchemy 1.4 Documentation >>> print(cache_key) # somewhat paraphrased
CacheKey(key=(
CURRENT RELEASE '0',
Home
| Download this Documentation <class 'sqlalchemy.sql.selectable.Select'>,
'_raw_columns',
Search terms:
search... (
'1',
Your new development <class 'sqlalchemy.sql.elements.ColumnClause'>,
career awaits. Check out the 'name',
latest listings. 'q',
ADS VIA CARBON

'type',
SQLAlchemy Core <class 'sqlalchemy.sql.sqltypes.NullType'>,
),
SQL Expression Language Tutorial (1.x API) ),

),
# a few more elements are here, and many more for a more
Schema Definition Language # complicated SELECT statement
),)

The above key is stored in the cache which is essentially a dictionary, and the
value is
Engine Configuration a construct that among other things stores the string form of the SQL
statement, in
this case the phrase “SELECT q”. We can observe that even for an
extremely short
query the cache key is pretty verbose as it has to represent
everything that may vary
Basic Usage about what’s being rendered and potentially executed.
Using Transactions The lambda construction system by contrast creates a different kind of cache
key:

>>> from sqlalchemy import lambda_stmt
Arbitrary Transaction Nesting as >>> stmt = lambda_stmt(lambda: select(column("q")))
an Antipattern >>> cache_key = stmt._generate_cache_key()
>>> print(cache_key)
Migrating from the “nesting” CacheKey(key=(
pattern <code object <lambda> at 0x7fed1617c710, file "<stdin>", lin

<class 'sqlalchemy.sql.lambdas.StatementLambdaElement'>,

),)
Autocommit

Above, we see a cache key that is vastly shorter than that of the non-lambda
statement, and additionally that production of the select(column("q"))
construct
Understanding the DBAPI-Level itself was not even necessary; the Python lambda itself contains
an attribute called
Autocommit Isolation Level __code__ which refers to a Python code object that
within the runtime of the
application is immutable and permanent.
results) When the lambda also includes closure variables, in the normal case that these
variables refer to SQL constructs such as column objects, they become
part of the
Connectionless Execution, Implicit cache key, or if they refer to literal values that will be bound
parameters, they are
Execution placed in a separate element of the cache key:

>>> def my_stmt(parameter):
SQL Compilation Caching ... col = column("q")
Configuration
... stmt = lambda_stmt(lambda: select(col))
... stmt += lambda s: s.where(col == parameter)
Estimating Cache Performance ... return stmt

Using Logging
The above StatementLambdaElement includes two lambdas, both
of which refer to the
col closure variable, so the cache key will
represent both of these segments as well
use?
as the column() object:
>>> stmt = my_stmt(5)
SQLAlchemy 1.4 Documentation >>> key = stmt._generate_cache_key()
CURRENT RELEASE >>> print(key)
Home
| Download this Documentation CacheKey(key=(
<code object <lambda> at 0x7f07323c50e0, file "<stdin>", lin

Search terms:
search... (
'0',
<class 'sqlalchemy.sql.elements.ColumnClause'>,
'name',

'q',

'type',
latest listings.
(
ADS VIA CARBON <class 'sqlalchemy.sql.sqltypes.NullType'>,
SQLAlchemy Core ),
),
SQL Expression Language Tutorial (1.x API) <code object <lambda> at 0x7f07323c5190, file "<stdin>", lin
<class 'sqlalchemy.sql.lambdas.LinkedLambdaElement'>,
SQL Statements and Expressions API (
'0',

Column and Data Types 'name',
'q',

'type',
Engine Configuration (
<class 'sqlalchemy.sql.sqltypes.NullType'>,
Working with Engines and Connections ),
),
Basic Usage
(
Using Transactions '0',

'name',
Arbitrary Transaction Nesting as 'q',
'type',
an Antipattern
(
Migrating from the “nesting” <class 'sqlalchemy.sql.sqltypes.NullType'>,
pattern ),
),
Library Level (e.g. emulated) ),)

Autocommit

The second part of the cache key has retrieved the bound parameters that will
be
used when the statement is invoked:
Autocommit Isolation Level >>> key.bindparams
[BindParameter('%(139668884281280 parameter)s', 5, type_=Integ

results)
For a series of examples of “lambda” caching with performance comparisons,
see the
“short_selects” test suite within the Performance
performance example.
Execution

Engine Disposal
The Engine refers to a connection pool, which means under normal
circumstances,
Configuration
there are open database connections present while the
Engine object is still resident
Estimating Cache Performance in memory. When an Engine
is garbage collected, its connection pool is no longer
Using Logging
referred to by
that Engine , and assuming none of its connections are still checked
out,
the pool and its connections will also be garbage collected, which has the
effect of
How much memory does the cache closing out the actual database connections as well. But otherwise,
the Engine will
use? hold onto open database connections assuming
it uses the normally default pool
implementation of QueuePool .
The Engine is intended to normally be a permanent
fixture established up-front and
SQLAlchemy 1.4 Documentation maintained throughout the lifespan of an
application. It is not intended to be created
and disposed on a
per-connection basis; it is instead a registry that maintains both a
CURRENT RELEASE
pool
of connections as well as configurational information about the database
and
Home
DBAPI in use, as well as some degree of internal caching of per-database
resources.
Search terms:
search... However, there are many cases where it is desirable that all connection resources
referred to by the Engine be completely closed out. It’s
generally not a good idea to
rely on Python garbage collection for this
to occur for these cases; instead, the
Your new development Engine can be explicitly disposed using
the Engine.dispose() method. This disposes
career awaits. Check out the of the engine’s
underlying connection pool and replaces it with a new one that’s
latest listings. empty.
Provided that the Engine
is discarded at this point and no longer used, all
ADS VIA CARBON
checked-in connections
which it refers to will also be fully closed.
SQLAlchemy Core Valid use cases for calling Engine.dispose() include:
SQL Expression Language Tutorial (1.x API) When a program wants to release any remaining checked-in connections
held
by the connection pool and expects to no longer be connected
to that database
at all for any future operations.
When a program uses multiprocessing or fork() , and an
Engine object is copied
Column and Data Types to the child process,
Engine.dispose() should be called so that the engine

creates
brand new database connections local to that fork. Database
connections
generally do not travel across process boundaries. Use the
Engine Configuration Engine.dispose.close parameter set to False in this case.
See the section Using
Connection Pools with Multiprocessing or os.fork() for more background on this
use case.
Basic Usage
Within test suites or multitenancy scenarios where many
ad-hoc, short-lived
Using Transactions Engine objects may be created and disposed.

Connections that are checked out are not discarded when the
engine is disposed or
Arbitrary Transaction Nesting as garbage collected, as these connections are still
strongly referenced elsewhere by
an Antipattern the application.
However, after Engine.dispose() is called, those
connections are no
longer associated with that Engine ; when they
are closed, they will be returned to
Migrating from the “nesting” their now-orphaned connection pool
which will ultimately be garbage collected, once
pattern all connections which refer
to it are also no longer referenced anywhere.
Since this
process is not easy to control, it is strongly recommended that
Engine.dispose() is
called only after all checked out connections
are checked in or otherwise de-
Autocommit associated from their pool.

An alternative for applications that are negatively impacted by the
Engine object’s
including DBAPI Autocommit use of connection pooling is to disable pooling
entirely. This typically incurs only a
modest performance impact upon the
use of new connections, and means that when
a connection is checked in,
it is entirely closed out and is not held in memory. See
Switching Pool Implementations
for guidelines on how to disable pooling.
See also
results)
Connectionless Execution, Implicit Connection Pooling
Execution
Using Connection Pools with Multiprocessing or os.fork()
Configuration Working with Driver SQL and Raw DBAPI

Estimating Cache Performance Connections
Using Logging The introduction on using Connection.execute() made use of the
text() construct in
order to illustrate how textual SQL statements
may be invoked. When working with
SQLAlchemy, textual SQL is actually more
of the exception rather than the norm, as
use? the Core expression language
and the ORM both abstract away the textual
Disabling or using an alternate representation of SQL. However, the
text() construct itself also provides some
abstraction of textual
SQL in that it normalizes how bound parameters are passed, as
SQLAlchemy 1.4 Documentation well as that
it supports datatyping behavior for parameters and result set rows.
CURRENT RELEASE Invoking SQL strings directly to the driver

Home
For the use case where one wants to invoke textual SQL directly passed to the
Search terms:
search... underlying driver (known as the DBAPI) without any intervention
from the text()
construct, the Connection.exec_driver_sql()
method may be used:

conn.exec_driver_sql("SET param='bar'")
latest listings.
ADS VIA CARBON

New in version 1.4: Added the Connection.exec_driver_sql() method.
SQLAlchemy Core
SQL Expression Language Tutorial (1.x API) Working with the DBAPI cursor directly
SQL Statements and Expressions API There are some cases where SQLAlchemy does not provide a genericized way
at
accessing some DBAPI functions, such as calling stored procedures as well
as
dealing with multiple result sets. In these cases, it’s just as expedient
to deal with the
Column and Data Types raw DBAPI connection directly.
Engine and Connection Use The most common way to access the raw DBAPI connection is to get it
from an
already present Connection object directly. It is
present using the
Connection.connection attribute:
Basic Usage connection = engine.connect()
dbapi_conn = connection.connection
Using Transactions
Nesting of Transaction Blocks The DBAPI connection here is actually a “proxied” in terms of the
originating
connection pool, however this is an implementation detail
that in most cases can be
ignored. As this DBAPI connection is still
contained within the scope of an owning
an Antipattern
Connection object, it is
best to make use of the Connection object for most features
Migrating from the “nesting” such
as transaction control as well as calling the Connection.close()
method; if these
operations are performed on the DBAPI connection directly,
the owning Connection
pattern
will not be aware of these changes in state.
To overcome the limitations imposed by the DBAPI connection that is
maintained by
Autocommit
an owning Connection , a DBAPI connection is also
available without the need to
Setting Transaction Isolation Levels procure a
Connection first, using the Engine.raw_connection() method
of Engine :
dbapi_conn = engine.raw_connection()
This DBAPI connection is again a “proxied” form as was the case before.
The purpose
Using Server Side Cursors (a.k.a. stream of this proxying is now apparent, as when we call the .close()
method of this
results) connection, the DBAPI connection is typically not actually
closed, but instead
released back to the
engine’s connection pool:
Execution
dbapi_conn.close()
SQL Compilation Caching While SQLAlchemy may in the future add built-in patterns for more DBAPI
use cases,
there are diminishing returns as these cases tend to be rarely
needed and they also
Configuration vary highly dependent on the type of DBAPI in use,
so in any case the direct DBAPI
Estimating Cache Performance calling pattern is always there for those
cases where it is needed.
Using Logging See also

How do I get at the raw DBAPI connection when using an Engine? - includes additional
use?
details about how
the DBAPI connection is accessed as well as the “driver”
Disabling or using an alternate connection
when using asyncio drivers.
Some recipes for DBAPI connection use follow.
Calling Stored Procedures and User Defined Functions
CURRENT RELEASE
SQLAlchemy supports calling stored procedures and user defined functions
several
Home
ways. Please note that all DBAPIs have different practices, so you must
consult your
Search terms:
search... underlying DBAPI’s documentation for specifics in relation to your
particular usage.
The following examples are hypothetical and may not work with
your underlying
DBAPI.
Your new development For stored procedures or functions with special syntactical or parameter concerns,
career awaits. Check out the DBAPI-level callproc
may potentially be used with your DBAPI. An example of this
latest listings.
pattern is:
ADS VIA CARBON
SQLAlchemy Core connection = engine.raw_connection()
try:
SQL Expression Language Tutorial (1.x API) cursor_obj = connection.cursor()
cursor_obj.callproc("my_procedure", ['x', 'y', 'z'])

results = list(cursor_obj.fetchall())
Schema Definition Language cursor_obj.close()
connection.commit()
Column and Data Types finally:
connection.close()
Note
Not all DBAPIs use callproc and overall usage details will vary. The
Basic Usage
above
example is only an illustration of how it might look to use a
Using Transactions particular DBAPI
function.
Arbitrary Transaction Nesting as Your DBAPI may not have a callproc requirement or may require a stored
procedure
an Antipattern or user defined function to be invoked with another pattern, such as
normal
SQLAlchemy connection usage. One example of this usage pattern is,
at the time of
this documentation’s writing, executing a stored procedure in
the PostgreSQL
pattern database with the psycopg2 DBAPI, which should be invoked
with normal connection

usage:
Autocommit
connection.execute("CALL my_procedure();")
This above example is hypothetical. The underlying database is not guaranteed to
Understanding the DBAPI-Level support “CALL” or “SELECT” in these situations, and the keyword may vary
dependent on the function being a stored procedure or a user defined function.
You
should consult your underlying DBAPI and database documentation in these
Using Server Side Cursors (a.k.a. stream situations to determine the correct syntax and patterns to use.
results)
Multiple Result Sets
Multiple result set support is available from a raw DBAPI cursor using the
nextset
Execution method:

connection = engine.raw_connection()

try:
Configuration cursor_obj = connection.cursor()
cursor_obj.execute("select * from table1; select * from ta

Estimating Cache Performance results_one = cursor_obj.fetchall()
Using Logging cursor_obj.nextset()
results_two = cursor_obj.fetchall()

cursor_obj.close()
use? finally:
connection.close()
SQLAlchemy 1.4 Documentation Registering New Dialects

CURRENT RELEASE The create_engine() function call locates the given dialect
using setuptools
Home
| Download this Documentation entrypoints. These entry points can be established
for third party dialects within the
setup.py script. For example,
to create a new dialect “foodialect://”, the steps are as
Search terms:
search...
follows:
1. Create a package called foodialect .

2. The package should have a module containing the dialect class,
which is
latest listings. typically a subclass of sqlalchemy.engine.default.DefaultDialect .
In this example
let’s say it’s called FooDialect and its module is accessed
via foodialect.dialect .
ADS VIA CARBON
SQLAlchemy Core 3. The entry point can be established in setup.py as follows:
SQL Expression Language Tutorial (1.x API) entry_points="""
[sqlalchemy.dialects]

foodialect = foodialect.dialect:FooDialect
Schema Definition Language """

If the dialect is providing support for a particular DBAPI on top of
an existing
SQLAlchemy-supported database, the name can be given
including a database-
Engine Configuration qualification. For example, if FooDialect
were in fact a MySQL dialect, the entry point
could be established like this:
Basic Usage entry_points="""
[sqlalchemy.dialects]
Using Transactions
mysql.foodialect = foodialect.dialect:FooDialect
Nesting of Transaction Blocks """

The above entrypoint would then be accessed as
an Antipattern
create_engine("mysql+foodialect://") .
Registering Dialects In-Process
pattern
SQLAlchemy also allows a dialect to be registered within the current process,
bypassing
the need for separate installation. Use the register() function as follows:
Autocommit
Setting Transaction Isolation Levels from sqlalchemy.dialects import registry
registry.register("mysql.foodialect", "myapp.dialect", "MyMySQ


Autocommit Isolation Level The above will respond to create_engine("mysql+foodialect://") and load the
MyMySQLDialect class from the myapp.dialect module.
results)
Connectionless Execution, Implicit Connection / Engine API

Execution
Object Name Description
Provides high-level functionality for a wrapped DB-
SQL Compilation Caching Connection
API connection.
Configuration
Estimating Cache Performance A set of hooks intended to augment the construction

CreateEnginePlugin of an
Engine object based on entrypoint names in a
Using Logging
URL.
use? Connects a Pool and
Dialect together to provide a
Engine
Disabling or using an alternate source of database connectivity and behavior.

CURRENT RELEASE Encapsulate information about an error condition in
ExceptionContext
progress.
Home
Search terms:
search... NestedTransaction Represent a ‘nested’, or SAVEPOINT transaction.
RootTransaction Represent the “root” transaction on a Connection .

latest listings.
Transaction Represent a database transaction in progress.
ADS VIA CARBON
SQLAlchemy Core TwoPhaseTransaction Represent a two-phase transaction.
SQL Statements and Expressions API class sqlalchemy.engine. Connection (engine, connection=None,
close_with_result=False, _branch_from=None, _execution_options=None,
_dispatch=None, _has_events=None, _allow_revalidate=True)
Provides high-level functionality for a wrapped DB-API connection.
This is the SQLAlchemy 1.x.x version of the Connection
class. For the 2.0 style
version, which features some API
differences, see Connection .
The Connection object is procured by calling
the Engine.connect() method of the
Basic Usage Engine
object, and provides services for execution of SQL statements as well
as
transaction control.
Using Transactions
Nesting of Transaction Blocks The Connection object is not thread-safe. While a Connection can be
shared
among threads using properly synchronized access, it is still
possible that the
underlying DBAPI connection may not support shared
access between threads.
an Antipattern Check the DBAPI documentation for details.

The Connection object represents a single DBAPI connection checked out
from the
pattern connection pool. In this state, the connection pool has no affect
upon the
connection, including its expiration or timeout state. For the
connection pool to
properly manage connections, connections should be
returned to the connection
Autocommit
pool (i.e. connection.close() ) whenever the
connection is not in use.
including DBAPI Autocommit Class signature

class sqlalchemy.engine.Connection ( sqlalchemy.engine.Connectable )

method sqlalchemy.engine.Connection. __init__ (engine, connection=None,
results)
close_with_result=False, _branch_from=None, _execution_options=None,
Connectionless Execution, Implicit _dispatch=None, _has_events=None, _allow_revalidate=True)
Execution
Construct a new Connection.
SQL Compilation Caching method sqlalchemy.engine.Connection. begin ()
Configuration Begin a transaction and return a transaction handle.

The returned object is an instance of Transaction .
This object represents the
Using Logging “scope” of the transaction,
which completes when either the
Transaction.rollback()
or Transaction.commit() method is called.
use? Tip

The Connection.begin() method is invoked when using
the Engine.begin() context
SQLAlchemy 1.4 Documentation manager method as well.
All documentation that refers to behaviors specific to the
Connection.begin() method also apply to use of the
Engine.begin() method.
CURRENT RELEASE
Home
Legacy use: nested calls to begin() on the same
Connection will return new
Search terms:
search... Transaction
objects that represent an emulated transaction within the scope of
the
enclosing transaction, that is:
Your new development trans = conn.begin() # outermost transaction
career awaits. Check out the trans2 = conn.begin() # "nested"
latest listings.
trans2.commit() # does nothing
ADS VIA CARBON trans.commit() # actually commits

SQLAlchemy Core
Calls to Transaction.commit() only have an effect
when invoked via the outermost
SQL Expression Language Tutorial (1.x API) Transaction object, though the
Transaction.rollback() method of any of the
Transaction objects will roll back the
transaction.
Schema Definition Language Tip

The above “nesting” behavior is a legacy behavior specific to
1.x style use and will
Engine and Connection Use be removed in SQLAlchemy 2.0. For

notes on 2.0 style use, see
Connection.begin() .
See also
Basic Usage Connection.begin_nested() - use a SAVEPOINT
Using Transactions Connection.begin_twophase() -

use a two phase /XID transaction

Engine.begin() - context manager available from
Engine
an Antipattern
method sqlalchemy.engine.Connection. begin_nested ()
pattern Begin a nested transaction (i.e. SAVEPOINT) and return a
transaction handle,
assuming an outer transaction is already
established.
Autocommit Nested transactions require SAVEPOINT support in the
underlying database. Any
transaction in the hierarchy may
commit and rollback , however the outermost
transaction
still controls the overall commit or rollback of the
transaction of a
including DBAPI Autocommit whole.
The legacy form of Connection.begin_nested() method has
alternate behaviors
Autocommit Isolation Level based on whether or not the
Connection.begin() method was called previously. If
Using Server Side Cursors (a.k.a. stream Connection.begin() was not called, then this method will
behave the same as the
Connection.begin() method and
return a RootTransaction object that begins and
results)
commits a
real transaction - no savepoint is invoked. If
Connection.begin() has
Connectionless Execution, Implicit been called, and a
RootTransaction is already established, then this method
Execution
returns an instance of NestedTransaction which will invoke
and manage the scope
of a SAVEPOINT.
Tip
Configuration The above mentioned behavior of

Connection.begin_nested() is a legacy behavior
specific to 1.x style use. In 2.0 style use, the
Connection.begin_nested() method
instead autobegins
the outer transaction that can be committed using
“commit-
Using Logging as-you-go” style; see
Connection.begin_nested() for migration details.

use?
Changed in version 1.4.13: The behavior of
Connection.begin_nested()
as
returning a RootTransaction if
Connection.begin() were not called has been
restored
as was the case in 1.3.x versions; in previous 1.4.x versions, an
SQLAlchemy 1.4 Documentation outer transaction would be “autobegun” but would not be committed.
CURRENT RELEASE
Home
| Download this Documentation See also
Search terms:
search... Connection.begin()
Connection.begin_twophase()

latest listings. method sqlalchemy.engine.Connection. begin_twophase (xid=None)
ADS VIA CARBON
Begin a two-phase or XA transaction and return a transaction
handle.
SQLAlchemy Core
The returned object is an instance of TwoPhaseTransaction ,
which in addition to the
SQL Expression Language Tutorial (1.x API) methods provided by
Transaction , also provides a
TwoPhaseTransaction.prepare()
method.
Schema Definition Language Parameters:
Column and Data Types xid – the two phase transaction id. If not supplied, a
random id will be
generated.
Engine Configuration See also

Connection.begin()
Basic Usage
Using Transactions

method sqlalchemy.engine.Connection. close ()
an Antipattern Close this Connection .

This results in a release of the underlying database
resources, that is, the DBAPI
pattern connection referenced
internally. The DBAPI connection is typically restored
back
to the connection-holding Pool referenced
by the Engine that produced this
Connection . Any transactional state present on
the DBAPI connection is also
Autocommit
unconditionally released via
the DBAPI connection’s rollback() method,
Setting Transaction Isolation Levels regardless
of any Transaction object that may be
outstanding with regards to this
Connection .
Understanding the DBAPI-Level After Connection.close() is called, the

Connection is permanently in a closed state,
and will allow no further operations.
Using Server Side Cursors (a.k.a. stream attribute sqlalchemy.engine.Connection. closed

results)
Return True if this connection is closed.
Execution method sqlalchemy.engine.Connection. connect (close_with_result=False)
Returns a branched version of this Connection .
Configuration Deprecated since version 1.4: The Connection.connect() method is

considered legacy as of the 1.x series of SQLAlchemy and will be removed in
2.0. (Background on SQLAlchemy 2.0 at: Migrating to SQLAlchemy 2.0)
Using Logging

The Connection.close() method on the returned
Connection can be called and this
use?
Connection will remain open.
This method provides usage symmetry with
Engine.connect() , including for usage
with context managers.
attribute sqlalchemy.engine.Connection. connection

CURRENT RELEASE The underlying DB-API connection managed by this Connection.
Home
This is a SQLAlchemy connection-pool proxied connection
which then has the
attribute
_ConnectionFairy.dbapi_connection that refers to the
actual driver
Search terms:
search...
connection.
See also
career awaits. Check out the Working with Driver SQL and Raw DBAPI Connections
latest listings.
ADS VIA CARBON
attribute sqlalchemy.engine.Connection. default_isolation_level

SQLAlchemy Core

The default isolation level assigned to this
Connection .
SQL Statements and Expressions API This is the isolation level setting that the
Connection
has when first procured via
the Engine.connect() method.
This level stays in place until the
Connection.execution_options.isolation_level is used
to change the setting on a
Column and Data Types per- Connection basis.
Engine and Connection Use Unlike Connection.get_isolation_level() ,

this attribute is set
ahead of time from
the first connection procured by the dialect,
so SQL query is not invoked when this
accessor is called.
Basic Usage New in version 0.9.9.
Using Transactions
Nesting of Transaction Blocks See also
Arbitrary Transaction Nesting as Connection.get_isolation_level()

- view current level
an Antipattern
create_engine.isolation_level
- set per Engine isolation level
- set per Connection isolation level
pattern

Autocommit method sqlalchemy.engine.Connection. detach ()

Detach the underlying DB-API connection from its connection pool.
E.g.:
Using Server Side Cursors (a.k.a. stream conn.detach()
results)
conn.execute(text("SET search_path TO schema1, schema2")
Connectionless Execution, Implicit # work with connection
Execution
# connection is fully closed (since we used "with:", can
Translation of Schema Names # also call .close())

Configuration
This Connection instance will remain usable.
When closed
(or exited from a context
Estimating Cache Performance manager context as above),
the DB-API connection will be literally closed and not
returned to its originating pool.
Using Logging
How much memory does the cache This method can be used to insulate the rest of an application
from a modified
state on a connection (such as a transaction
isolation level or similar).
use?
Disabling or using an alternate method sqlalchemy.engine.Connection. exec_driver_sql (statement,

dictionary to cache some (or all) parameters=None, execution_options=None)
Executes a SQL statement construct and returns a

CursorResult .
CURRENT RELEASE Parameters:
Home
| Download this Documentation statement – The statement str to be executed. Bound parameters
must
use the underlying DBAPI’s paramstyle, such as “qmark”,
“pyformat”,
Search terms:
search... “format”, etc.
parameters –
represent bound parameter values to be used in the

execution. The format
career awaits. Check out the is one of: a dictionary of named parameters,
a tuple of positional
latest listings. parameters, or a list containing either
dictionaries or tuples for multiple-
execute support.
ADS VIA CARBON
E.g. multiple dictionaries:

SQLAlchemy Core
conn.exec_driver_sql(

"INSERT INTO table (id, value) VALUES (%(id)s, %(va
SQL Statements and Expressions API [{"id":1, "value":"v1"}, {"id":2, "value":"v2"}]
)

Single dictionary:
Engine Configuration conn.exec_driver_sql(
"INSERT INTO table (id, value) VALUES (%(id)s, %(va

dict(id=1, value="v1")
Basic Usage )
Using Transactions
Nesting of Transaction Blocks Single tuple:

conn.exec_driver_sql(
an Antipattern "INSERT INTO table (id, value) VALUES (?, ?)",
(1, 'v1')

)
pattern
Library Level (e.g. emulated) Note

Autocommit
The Connection.exec_driver_sql() method does
not
participate in the
ConnectionEvents.before_execute()
including DBAPI Autocommit and
ConnectionEvents.after_execute() events. To
Understanding the DBAPI-Level intercept calls to Connection.exec_driver_sql() , use

ConnectionEvents.before_cursor_execute() and
ConnectionEvents.after_cursor_execute() .
results)
See also
Execution PEP 249

method sqlalchemy.engine.Connection. execute (statement, *multiparams,
Configuration **params)
Executes a SQL statement construct and returns a
CursorResult .
Using Logging
Parameters:
use? statement –
The statement to be executed. May be

one of:
a plain string (deprecated)
any ClauseElement construct that is also
a subclass of Executable , such
SQLAlchemy 1.4 Documentation as a
select() construct
CURRENT RELEASE a FunctionElement , such as that generated

by func , will be automatically
Home
| Download this Documentation wrapped in
a SELECT statement, which is then executed.
a DDLElement object
Search terms:
search...
a DefaultGenerator object
a Compiled object

career awaits. Check out the Deprecated since version 2.0: passing a string to
latest listings. Connection.execute() is
deprecated and will be removed in version
2.0. Use the
text() construct with
Connection.execute() , or the
ADS VIA CARBON
Connection.exec_driver_sql()
method to invoke a driver-level
SQL
SQLAlchemy Core string.

*multiparams/**params –
represent bound parameter
values to be used in the execution. Typically,
the format is either a collection of one or more
dictionaries passed to
Column and Data Types *multiparams:

conn.execute(
Engine Configuration table.insert(),
{"id":1, "value":"v1"},
Working with Engines and Connections {"id":2, "value":"v2"}
)
Basic Usage
Using Transactions
…or individual key/values interpreted by **params:
conn.execute(

table.insert(), id=1, value="v1"
an Antipattern )
pattern
In the case that a plain SQL string is passed, and the underlying
DBAPI
accepts positional bind parameters, a collection of tuples
or individual
Library Level (e.g. emulated) values in *multiparams may be passed:
Autocommit
conn.execute(

"INSERT INTO table (id, value) VALUES (?, ?)",
including DBAPI Autocommit (1, "v1"), (2, "v2")

Autocommit Isolation Level conn.execute(
"INSERT INTO table (id, value) VALUES (?, ?)",

1, "v1"
results)
)
Execution Note above, the usage of a question mark “?” or other
symbol is contingent
upon the “paramstyle” accepted by the DBAPI
in use, which may be any of
“qmark”, “named”, “pyformat”, “format”,
“numeric”. See pep-249 for details
SQL Compilation Caching on
paramstyle.
Configuration To execute a textual SQL statement which uses bound parameters in a

DBAPI-agnostic way, use the text() construct.
Using Logging Deprecated since version 2.0: use of tuple or scalar positional
parameters
is deprecated. All params should be dicts or sequences
of dicts.
Use exec_driver_sql() to execute a plain string with
tuple or
use?
scalar positional parameters.
method sqlalchemy.engine.Connection. execution_options (**opt)

CURRENT RELEASE Set non-SQL options for the connection which take effect
during execution.
Home
For a “future” style connection, this method returns this same
Connection object
with the new options added.
Search terms:
search...
For a legacy connection, this method returns a copy of this
Connection which
references the same underlying DBAPI
connection, but also defines the given
Your new development execution options which will
take effect for a call to
execute() . As the new
career awaits. Check out the Connection references the
same underlying resource, it’s usually a good idea to
latest listings. ensure that
the copies will be discarded immediately, which is implicit if used
as in:
ADS VIA CARBON
SQLAlchemy Core result = connection.execution_options(stream_results=True).\

execute(stmt)

Note that any key/value can be passed to
Connection.execution_options() ,
and it
Schema Definition Language will be stored in the
_execution_options dictionary of the Connection .
It
is suitable
for usage by end-user schemes to communicate with
event listeners, for example.

The keywords that are currently recognized by SQLAlchemy itself
include all
those listed under Executable.execution_options() ,
as well as others that are
Engine Configuration specific to Connection .

Parameters:
Basic Usage autocommit –
Using Transactions Available on: Connection, statement.

When True, a COMMIT will be invoked
after execution
when executed in ‘autocommit’ mode, i.e. when an explicit
transaction is not begun on the connection. Note that this
is library level,
Arbitrary Transaction Nesting as not DBAPI level autocommit. The DBAPI
connection will remain in a real
an Antipattern transaction unless the
“AUTOCOMMIT” isolation level is used.

Deprecated since version 1.4: The “autocommit” execution option is
pattern deprecated
and will be removed in SQLAlchemy 2.0. See
Library-level
(but not driver level) “Autocommit” removed from both Core and
ORM for discussion.
Autocommit

compiled_cache –
Available on: Connection.
A dictionary where Compiled objects
will be
cached when the Connection
compiles a clause
expression into a Compiled
Autocommit Isolation Level object. This dictionary will
supersede the statement cache that may be
configured on the
Engine itself. If set to None, caching
is disabled, even if
the engine has a configured cache size.
results)
Note that the ORM makes use of its own “compiled” caches for
some
Connectionless Execution, Implicit operations, including flush operations. The caching
used by the ORM
Execution internally supersedes a cache dictionary
specified here.
logging_token –
Available on: Connection ,
Engine .
Adds the specified string token surrounded by brackets in log
messages
Configuration
logged by the connection, i.e. the logging that’s enabled
either via the
Estimating Cache Performance create_engine.echo flag or via the
logging.getLogger("sqlalchemy.engine")
logger. This allows a
per-connection or per-sub-engine token to be available
Using Logging
which is
useful for debugging concurrent connection scenarios.
use? New in version 1.4.0b2.

dictionary to cache some (or all) See also
Setting Per-Connection / Sub-Engine Tokens - usage example
create_engine.logging_name - adds a name to the
name used by the Python
CURRENT RELEASE logger object itself.
Home
Search terms:
search... isolation_level –
Available on: Connection .

Set the transaction isolation level for the lifespan of this
Connection object.
Valid values include those string
values accepted by the
parameter passed to create_engine() . These
latest listings.
levels are
semi-database specific; see individual dialect documentation for
ADS VIA CARBON
valid levels.
SQLAlchemy Core The isolation level option applies the isolation level by emitting
statements
on the DBAPI connection, and necessarily affects the
original Connection
object overall, not just the copy that is
returned by the call to
SQL Statements and Expressions API Connection.execution_options()
method. The isolation level will remain at
the given setting until
the DBAPI connection itself is returned to the
Schema Definition Language connection pool, i.e.
the Connection.close() method on the original
Column and Data Types Connection is called,
where an event handler will emit
additional statements
on the DBAPI connection in order to revert the
isolation level change.
Warning
The isolation_level execution option should
not be
used when a transaction is already established, that
is,
Basic Usage the Connection.begin()
method or similar has been
called. A database cannot change the isolation level on
Using Transactions
a
transaction in progress, and different DBAPIs and/or
Nesting of Transaction Blocks SQLAlchemy dialects may implicitly roll back or
commit
the transaction, or not affect the connection at
all.
an Antipattern

Note
pattern
Library Level (e.g. emulated) The isolation_level execution option is implicitly

reset
if the Connection is invalidated, e.g. via
the
Autocommit
Connection.invalidate() method, or if a
disconnection
Setting Transaction Isolation Levels error occurs. The new connection produced after
the
including DBAPI Autocommit invalidation will not have the isolation level re-applied
to it automatically.
See also
results) create_engine.isolation_level

Connection.get_isolation_level()
- view current level
Execution
SQLite Transaction Isolation
PostgreSQL Transaction Isolation
Configuration MySQL Transaction Isolation
Estimating Cache Performance SQL Server Transaction Isolation

Using Logging
Setting Transaction Isolation Levels / DBAPI AUTOCOMMIT - for the ORM
use?
no_parameters – When True , if the final parameter
list or dictionary is
Disabling or using an alternate totally empty, will invoke the
statement on the cursor as
dictionary to cache some (or all) cursor.execute(statement) ,
not passing the parameter collection at all.
Some DBAPIs such as psycopg2 and mysql-python consider
percent signs
SQLAlchemy 1.4 Documentation as significant only when parameters are
present; this option allows code to
generate SQL
containing percent signs (and possibly other characters)
that
CURRENT RELEASE
is neutral regarding whether it’s executed by the DBAPI
or piped into a
Home
script that’s later invoked by
command line tools.
Search terms:
search... stream_results –
Available on: Connection, statement.

Indicate to the dialect that results
should be
“streamed” and not pre-buffered, if possible. This is a limitation
Your new development of many DBAPIs. The flag is currently understood within a subset
of
career awaits. Check out the dialects within the PostgreSQL and MySQL categories, and
may be
latest listings. supported by other third party dialects as well.
ADS VIA CARBON
See also
SQLAlchemy Core
Using Server Side Cursors (a.k.a. stream results)
SQL Statements and Expressions API schema_translate_map –
Schema Definition Language Available on: Connection, Engine.

A dictionary mapping schema names to
schema names, that will be
applied to the Table.schema element of each
Table
encountered when SQL or DDL expression elements
are compiled
Engine and Connection Use into strings; the resulting schema name will be
converted based on
presence in the map of the original name.
Working with Engines and Connections New in version 1.1.
Basic Usage
Using Transactions See also


an Antipattern
See also
pattern Engine.execution_options()
Library Level (e.g. emulated) Executable.execution_options()

Autocommit
Connection.get_execution_options()
Understanding the DBAPI-Level method sqlalchemy.engine.Connection. get_execution_options ()

Get the non-SQL options which will take effect during execution.
results) New in version 1.3.

Execution See also

Connection.execution_options()
Configuration
method sqlalchemy.engine.Connection. get_isolation_level ()
Using Logging Return the current isolation level assigned to this
Connection .
How much memory does the cache This will typically be the default isolation level as determined
by the dialect, unless
use? if the
feature has been used to
alter the isolation level on a
per- Connection basis.
This attribute will typically perform a live SQL operation in order
to procure the
SQLAlchemy 1.4 Documentation current isolation level, so the value returned is the
actual level on the underlying
DBAPI connection regardless of how
this state was set. Compare to the
CURRENT RELEASE
Connection.default_isolation_level accessor
which returns the dialect-level
Home
setting without performing a SQL
query.
Search terms:
search...
New in version 0.9.9.

See also
latest listings.
Connection.default_isolation_level
- view default level
ADS VIA CARBON
SQLAlchemy Core
- set per Connection isolation level
Schema Definition Language method sqlalchemy.engine.Connection. get_nested_transaction ()
Column and Data Types Return the current nested transaction in progress, if any.

New in version 1.4.
Basic Usage
method sqlalchemy.engine.Connection. get_transaction ()
Using Transactions Return the current root transaction in progress, if any.

New in version 1.4.
an Antipattern
Migrating from the “nesting” method sqlalchemy.engine.Connection. in_nested_transaction ()

pattern
Return True if a transaction is in progress.
Autocommit method sqlalchemy.engine.Connection. in_transaction ()

Return True if a transaction is in progress.
Understanding the DBAPI-Level attribute sqlalchemy.engine.Connection. info

Info dictionary associated with the underlying DBAPI connection
referred to by
Using Server Side Cursors (a.k.a. stream this Connection , allowing user-defined
data to be associated with the connection.
results)
The data here will follow along with the DBAPI connection including
after it is
Connectionless Execution, Implicit returned to the connection pool and used again
in subsequent instances of
Connection .
Execution
Translation of Schema Names method sqlalchemy.engine.Connection. invalidate (exception=None)

Invalidate the underlying DBAPI connection associated with
this Connection .
Configuration
An attempt will be made to close the underlying DBAPI connection
immediately;
however if this operation fails, the error is logged
but not raised. The connection is
Using Logging then discarded whether or not
close() succeeded.

Upon the next use (where “use” typically means using the
Connection.execute()
use? method or similar),
this Connection will attempt to
procure a new DBAPI
connection using the services of the
Pool as a source of connectivity (e.g.
a
“reconnection”).
If a transaction was in progress (e.g. the
Connection.begin() method has been
SQLAlchemy 1.4 Documentation called) when
Connection.invalidate() method is called, at the DBAPI
level all state
associated with this transaction is lost, as
the DBAPI connection is closed. The
CURRENT RELEASE
Connection
will not allow a reconnection to proceed until the
Transaction object is
Home
ended, by calling the
Transaction.rollback() method; until that point, any attempt
at
continuing to use the Connection will raise an
InvalidRequestError .
This is to
Search terms:
search...
prevent applications from accidentally
continuing an ongoing transactional
operations despite the
fact that the transaction has been lost due to an
invalidation.
career awaits. Check out the The Connection.invalidate() method,
just like auto-invalidation,
will at the
latest listings. connection pool level invoke the
PoolEvents.invalidate() event.
ADS VIA CARBON
Parameters:
SQLAlchemy Core
exception – an optional Exception instance that’s the
reason for the
SQL Expression Language Tutorial (1.x API) invalidation. is passed along to event handlers
and logging functions.

See also
More on Invalidation
attribute sqlalchemy.engine.Connection. invalidated
Working with Engines and Connections Return True if this connection was invalidated.
Basic Usage
method sqlalchemy.engine.Connection. run_callable (callable_, *args,
Using Transactions **kwargs)

Given a callable object or function, execute it, passing
a Connection as the first
Arbitrary Transaction Nesting as argument.
an Antipattern
Migrating from the “nesting” Deprecated since version 1.4: The Connection.run_callable() method is
deprecated and will be removed in a future release. Invoke the callable
pattern
function directly, passing the Connection.
Autocommit
The given *args and **kwargs are passed subsequent
to the Connection argument.
This function, along with Engine.run_callable() ,
allows a function to be run with a
Connection
or Engine object without the need to know
which one is being dealt
Understanding the DBAPI-Level with.
method sqlalchemy.engine.Connection. scalar (object_, *multiparams,
**params)
results)
Executes and returns the first column of the first row.
Execution The underlying result/cursor is closed after execution.

method sqlalchemy.engine.Connection. scalars (object_, *multiparams,
SQL Compilation Caching **params)
Configuration
Executes and returns a scalar result set, which yields scalar values
from the first
Estimating Cache Performance column of each row.
Using Logging
This method is equivalent to calling Connection.execute()
to receive a Result
How much memory does the cache object, then invoking the
Result.scalars() method to produce a
ScalarResult
use?
instance.
Disabling or using an alternate Returns:

dictionary to cache some (or all) a ScalarResult

CURRENT RELEASE
Home
method sqlalchemy.engine.Connection. schema_for_object (obj)

Search terms:
search...
Return the schema name for the given schema item taking into
account current
schema translate map.
method sqlalchemy.engine.Connection. transaction (callable_, *args,
latest listings.
**kwargs)
ADS VIA CARBON
SQLAlchemy Core Execute the given function within a transaction boundary.
SQL Expression Language Tutorial (1.x API) Deprecated since version 1.4: The Connection.transaction() method is
SQL Statements and Expressions API deprecated and will be removed in a future release. Use the Engine.begin()
context manager instead.

The function is passed this Connection
as the first argument, followed by the given
Engine and Connection Use *args and **kwargs,
e.g.:
def do_something(conn, x, y):
Working with Engines and Connections conn.execute(text("some statement"), {'x':x, 'y':y})
Basic Usage
conn.transaction(do_something, 5, 10)
Using Transactions
Nesting of Transaction Blocks The operations inside the function are all invoked within the
context of a single
Transaction .
Upon success, the transaction is committed. If an
exception is raised,
the transaction is rolled back
before propagating the exception.
an Antipattern
Note
pattern The transaction() method is superseded by
the usage of the
Python with: statement, which can
be used with
Connection.begin() :
Autocommit
Setting Transaction Isolation Levels with conn.begin():
including DBAPI Autocommit conn.execute(text("some statement"),

As well as with Engine.begin() :

results) with engine.begin() as conn:
conn.execute(text("some statement"),
Execution

See also
Engine.begin() - engine-level transactional
context
Configuration
Estimating Cache Performance Engine.transaction() - engine-level version of

Connection.transaction()
Using Logging

class sqlalchemy.engine. CreateEnginePlugin (url, kwargs)
use?
A set of hooks intended to augment the construction of an
Engine object based on
entrypoint names in a URL.
The purpose of CreateEnginePlugin is to allow third-party
systems to apply engine,
SQLAlchemy 1.4 Documentation pool and dialect level event listeners without
the need for the target application to
be modified; instead, the plugin
names can be added to the database URL. Target
CURRENT RELEASE
applications for
CreateEnginePlugin include:
Home
connection and SQL performance tools, e.g. which use events to track
number
Search terms:
search... of checkouts and/or time spent with statements
connectivity plugins such as proxies

A rudimentary CreateEnginePlugin that attaches a logger
to an Engine object might
look like:
latest listings.
ADS VIA CARBON

import logging
SQLAlchemy Core
from sqlalchemy.engine import CreateEnginePlugin
SQL Expression Language Tutorial (1.x API) from sqlalchemy import event

class LogCursorEventsPlugin(CreateEnginePlugin):
Schema Definition Language def __init__(self, url, kwargs):
# consume the parameter "log_cursor_logging_name" fro

# URL query
Engine and Connection Use logging_name = url.query.get("log_cursor_logging_name
Engine Configuration self.log = logging.getLogger(logging_name)

def update_url(self, url):
Basic Usage "update the URL to one that no longer includes our pa
return url.difference_update_query(["log_cursor_loggi
Using Transactions
Nesting of Transaction Blocks def engine_created(self, engine):
"attach an event listener after the new Engine is con

Arbitrary Transaction Nesting as event.listen(engine, "before_cursor_execute", self._l
an Antipattern

def _log_event(
pattern self,
conn,

cursor,
Autocommit statement,

parameters,
context,

executemany):

self.log.info("Plugin logged cursor event: %s", state

results) Plugins are registered using entry points in a similar way as that
of dialects:

entry_points={
Execution
'sqlalchemy.plugins': [
Translation of Schema Names 'log_cursor_plugin = myapp.plugins:LogCursorEventsPlu

]
Configuration
A plugin that uses the above names would be invoked from a database
URL as in:
Using Logging

engine = create_engine(
use?
"mysql+pymysql://scott:tiger@localhost/test?"
Disabling or using an alternate "plugin=log_cursor_plugin&log_cursor_logging_name=mylogge

)
SQLAlchemy 1.4 Documentation The plugin URL parameter supports multiple instances, so that a URL
may specify
CURRENT RELEASE multiple plugins; they are loaded in the order stated
in the URL:
Home
Search terms:
search... "mysql+pymysql://scott:tiger@localhost/test?"
"plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three")

career awaits. Check out the The plugin names may also be passed directly to create_engine()
using the
latest listings. create_engine.plugins argument:
ADS VIA CARBON
SQLAlchemy Core engine = create_engine(
"mysql+pymysql://scott:tiger@localhost/test",
SQL Expression Language Tutorial (1.x API) plugins=["myplugin"])
Schema Definition Language New in version 1.2.3: plugin names can also be specified
to create_engine()
as a list

A plugin may consume plugin-specific arguments from the
URL object as well as the
Engine Configuration kwargs dictionary, which is
the dictionary of arguments passed to the
create_engine()
call. “Consuming” these arguments includes that they must be
removed
when the plugin initializes, so that the arguments are not passed along
to
Basic Usage the Dialect constructor, where they will raise an
ArgumentError because they are not
known by the dialect.
Using Transactions
Nesting of Transaction Blocks As of version 1.4 of SQLAlchemy, arguments should continue to be consumed
from
the kwargs dictionary directly, by removing the values with a
method such as
Arbitrary Transaction Nesting as dict.pop . Arguments from the URL object
should be consumed by implementing the
an Antipattern CreateEnginePlugin.update_url() method, returning a new copy
of the URL with
plugin-specific parameters removed:
pattern
class MyPlugin(CreateEnginePlugin):
Library Level (e.g. emulated) def __init__(self, url, kwargs):
self.my_argument_one = url.query['my_argument_one']
Autocommit
self.my_argument_two = url.query['my_argument_two']
Setting Transaction Isolation Levels self.my_argument_three = kwargs.pop('my_argument_thre

Understanding the DBAPI-Level return url.difference_update_query(
Autocommit Isolation Level ["my_argument_one", "my_argument_two"]
)
results)
Connectionless Execution, Implicit Arguments like those illustrated above would be consumed from a
create_engine()
call such as:
Execution
Translation of Schema Names from sqlalchemy import create_engine

Configuration "mysql+pymysql://scott:tiger@localhost/test?"
"plugin=myplugin&my_argument_one=foo&my_argument_two=bar",

my_argument_three='bat'
Using Logging )
use?
Disabling or using an alternate Changed in version 1.4: The URL object is now immutable; a
CreateEnginePlugin that needs to alter the
URL should implement the newly
added
CreateEnginePlugin.update_url() method, which
is invoked after the
SQLAlchemy 1.4 Documentation plugin is constructed.
CURRENT RELEASE For migration, construct the plugin in the following way, checking
for the
Home
| Download this Documentation existence of the CreateEnginePlugin.update_url()
method to detect which
version is running:
Search terms:
search...
class MyPlugin(CreateEnginePlugin):
def __init__(self, url, kwargs):
Your new development if hasattr(CreateEnginePlugin, "update_url"):
career awaits. Check out the # detect the 1.4 API
latest listings. self.my_argument_one = url.query['my_argument

ADS VIA CARBON self.my_argument_two = url.query['my_argument
else:
SQLAlchemy Core
# detect the 1.3 and earlier API - mutate the
# URL directly

self.my_argument_one = url.query.pop('my_argu
SQL Statements and Expressions API self.my_argument_two = url.query.pop('my_argu

self.my_argument_three = kwargs.pop('my_argument_
Engine and Connection Use # this method is only called in the 1.4 version
return url.difference_update_query(
["my_argument_one", "my_argument_two"]
Working with Engines and Connections )
Basic Usage

The URL object is now immutable - overview of the URL change which
also
Arbitrary Transaction Nesting as includes notes regarding CreateEnginePlugin .
an Antipattern

pattern When the engine creation process completes and produces the
Engine object, it is
again passed to the plugin via the
CreateEnginePlugin.engine_created() hook. In this
hook, additional
changes can be made to the engine, most typically involving setup
Autocommit of
events (e.g. those defined in Core Events).

including DBAPI Autocommit New in version 1.1.

Autocommit Isolation Level method sqlalchemy.engine.CreateEnginePlugin. __init__ (url, kwargs)
Construct a new CreateEnginePlugin .
results)
The plugin object is instantiated individually for each call
to create_engine() . A
single Engine will be
passed to the CreateEnginePlugin.engine_created() method
Execution
corresponding to this URL.
Parameters:
url –
Configuration
the URL object. The plugin may inspect
the URL for arguments. Arguments
Estimating Cache Performance used by the
plugin should be removed, by returning an updated URL
from
the CreateEnginePlugin.update_url() method.
Using Logging
How much memory does the cache Changed in version 1.4: The URL object is now immutable, so a
use? CreateEnginePlugin that needs to alter the
URL object should
implement the
CreateEnginePlugin.update_url() method.
kwargs – The keyword arguments passed to
create_engine() .
CURRENT RELEASE
method sqlalchemy.engine.CreateEnginePlugin. engine_created (engine)
Home
Receive the Engine
object when it is fully constructed.
Search terms:
search...
The plugin may make additional changes to the engine, such as
registering engine
or connection pool events.
career awaits. Check out the method
latest listings. sqlalchemy.engine.CreateEnginePlugin. handle_dialect_kwargs (dialect_cls,
ADS VIA CARBON dialect_args)
SQLAlchemy Core
parse and modify dialect kwargs

method
SQL Statements and Expressions API sqlalchemy.engine.CreateEnginePlugin. handle_pool_kwargs (pool_cls,

pool_args)
Column and Data Types parse and modify pool kwargs

method sqlalchemy.engine.CreateEnginePlugin. update_url (url)
Update the URL .
Basic Usage A new URL should be returned. This method is

typically used to consume
configuration arguments from the
URL which must be removed, as they will not be
Using Transactions recognized by the dialect. The
URL.difference_update_query() method is available
Nesting of Transaction Blocks to remove these arguments. See the docstring at
CreateEnginePlugin for an
example.
an Antipattern
New in version 1.4.
pattern
class sqlalchemy.engine. Engine (pool, dialect, url, logging_name=None,
echo=None, query_cache_size=500, execution_options=None,
Autocommit hide_parameters=False)

Connects a Pool and
Dialect together to provide a
source of database connectivity
including DBAPI Autocommit and behavior.
This is the SQLAlchemy 1.x version of Engine . For
the 2.0 style version, which
Autocommit Isolation Level includes some API differences,
see Engine .
An Engine object is instantiated publicly using the
create_engine() function.
results)
See also
Execution Engine Configuration

Configuration
Class signature
Using Logging class sqlalchemy.engine.Engine ( sqlalchemy.engine.Connectable ,
sqlalchemy.log.Identified )
use?
Disabling or using an alternate method sqlalchemy.engine.Engine. begin (close_with_result=False)
Return a context manager delivering a Connection

with a Transaction established.
CURRENT RELEASE E.g.:
Home
Search terms:
search... conn.execute(
text("insert into table (x, y, z) values (1, 2, 3)")

)
conn.execute(text("my_special_procedure(5)"))
latest listings.
Upon successful operation, the Transaction
is committed. If an error is raised, the
ADS VIA CARBON
Transaction
is rolled back.
SQLAlchemy Core
Legacy use only: the close_with_result flag is normally False ,
and indicates that
SQL Expression Language Tutorial (1.x API) the Connection will be closed when
the operation is complete. When set to True , it
indicates the
Connection is in “single use” mode, where the
CursorResult returned
by the first call to
Connection.execute() will close the
Connection when that
Schema Definition Language CursorResult has
exhausted all result rows.
Column and Data Types See also

Engine.connect() - procure a
Connection from
an Engine .
Connection.begin() - start a Transaction
for a particular Connection .
Basic Usage
method sqlalchemy.engine.Engine. clear_compiled_cache ()
Using Transactions
Nesting of Transaction Blocks Clear the compiled cache associated with the dialect.
Arbitrary Transaction Nesting as This applies only to the built-in cache that is established
via the
an Antipattern create_engine.query_cache_size parameter.
It will not impact any dictionary caches
that were passed via the
Connection.execution_options.query_cache parameter.
pattern
New in version 1.4.
Autocommit
method sqlalchemy.engine.Engine. connect (close_with_result=False)
including DBAPI Autocommit Return a new Connection object.

The Connection object is a facade that uses a DBAPI
connection internally in order
Autocommit Isolation Level to communicate with the database. This
connection is procured from the
connection-holding Pool
referenced by this Engine . When the
Connection.close()
method of the
Connection object
is called, the underlying DBAPI connection is
results)
then returned to the
connection pool, where it may be used again in a subsequent
Connectionless Execution, Implicit call to
Engine.connect() .
Execution
method sqlalchemy.engine.Engine. dispose (close=True)

Dispose of the connection pool used by this
Engine .
Configuration A new connection pool is created immediately after the old one has been
disposed. The previous connection pool is disposed either actively, by
closing out
all currently checked-in connections in that pool, or
passively, by losing references
Using Logging to it but otherwise not closing any
connections. The latter strategy is more
appropriate for an initializer
in a forked Python process.
use? Parameters:
Disabling or using an alternate close –

if left at its default of True , has the
effect of fully closing all currently
SQLAlchemy 1.4 Documentation checked in
database connections. Connections that are still checked out
will not be closed, however they will no longer be associated
with this
CURRENT RELEASE
Engine ,
so when they are closed individually, eventually the
Pool which they
Home
are associated with will
be garbage collected and they will be closed out
fully, if
not already closed on checkin.
Search terms:
search...
If set to False , the previous connection pool is de-referenced,
and
otherwise not touched in any way.
latest listings. New in version 1.4.33: Added the Engine.dispose.close
parameter to allow
ADS VIA CARBON
the replacement of a connection pool in a child
process without interfering
with the connections used by the parent
process.
SQLAlchemy Core

See also
Engine Disposal
Using Connection Pools with Multiprocessing or os.fork()

attribute sqlalchemy.engine.Engine. driver
Working with Engines and Connections Driver name of the Dialect

in use by this Engine .
Basic Usage
attribute sqlalchemy.engine.Engine. engine
Using Transactions
The Engine instance referred to by this
Connectable .

May be self if this is already an Engine .
an Antipattern
method sqlalchemy.engine.Engine. execute (statement, *multiparams,
Migrating from the “nesting” **params)
pattern
Executes the given construct and returns a
CursorResult .
Autocommit
Deprecated since version 1.4: The Engine.execute() method is considered
Setting Transaction Isolation Levels legacy as of the 1.x series of SQLAlchemy and will be removed in 2.0. All
statement execution in SQLAlchemy 2.0 is performed by the
Connection.execute() method of Connection , or in the ORM by the
Understanding the DBAPI-Level Session.execute() method of Session . (Background on SQLAlchemy 2.0 at:
Autocommit Isolation Level Migrating to SQLAlchemy 2.0)

results) The arguments are the same as those used by
Connection.execute() .
Connectionless Execution, Implicit Here, a Connection is acquired using the

Engine.connect() method, and the
Execution statement executed
with that connection. The returned CursorResult
is flagged
such that when the CursorResult is exhausted and its
underlying cursor is closed,
the Connection
created here
will also be closed, which allows its associated DBAPI
SQL Compilation Caching connection
resource to be returned to the connection pool.
Configuration
method sqlalchemy.engine.Engine. execution_options (**opt)
Return a new Engine that will provide
Connection objects with the given execution
Using Logging
options.
The returned Engine remains related to the original
Engine in that it shares the
use?
same connection pool and
other state:
The Pool used by the new Engine
is the
same instance. The Engine.dispose()
SQLAlchemy 1.4 Documentation method will replace
the connection pool instance for the parent engine as
well
as this one.
CURRENT RELEASE
Home
| Download this Documentation Event listeners are “cascaded” - meaning, the new
Engine
inherits the events
of the parent, and new events can be associated
with the new Engine
Search terms:
search... individually.
The logging configuration and logging_name is copied from the parent

Engine .
The intent of the Engine.execution_options() method is
to implement “sharding”
latest listings.
schemes where multiple Engine
objects refer to the same connection pool, but are
ADS VIA CARBON
differentiated
by options that would be consumed by a custom event:
SQLAlchemy Core
primary_engine = create_engine("mysql://")
SQL Expression Language Tutorial (1.x API) shard1 = primary_engine.execution_options(shard_id="shard1")

shard2 = primary_engine.execution_options(shard_id="shard2")
Column and Data Types Above, the shard1 engine serves as a factory for
Connection
objects that will
contain the execution option
shard_id=shard1 , and shard2 will produce
Connection
Engine and Connection Use objects that contain the execution option shard_id=shard2 .
An event handler can consume the above execution option to perform
a schema
Working with Engines and Connections switch or other operation, given a connection. Below
we emit a MySQL use
statement to switch databases, at the same
time keeping track of which database
Basic Usage
we’ve established using the
Connection.info dictionary,
which gives us a
Using Transactions persistent
storage space that follows the DBAPI connection:

from sqlalchemy import event
Arbitrary Transaction Nesting as from sqlalchemy.engine import Engine
an Antipattern
shards = {"default": "base", shard_1: "db1", "shard_2": "db2
pattern @event.listens_for(Engine, "before_cursor_execute")
def _switch_shard(conn, cursor, stmt,
Library Level (e.g. emulated) params, context, executemany):
Autocommit shard_id = conn._execution_options.get('shard_id', "defa

current_shard = conn.info.get("current_shard", None)

including DBAPI Autocommit if current_shard != shard_id:
cursor.execute("use %s" % shards[shard_id])

conn.info["current_shard"] = shard_id

results) See also
Connectionless Execution, Implicit Connection.execution_options()

- update execution options
on a Connection object.
Execution
Engine.update_execution_options()
- update the execution
options for a given
Translation of Schema Names Engine in place.

Engine.get_execution_options()
Configuration

method sqlalchemy.engine.Engine. get_execution_options ()
Using Logging
How much memory does the cache Get the non-SQL options which will take effect during execution.
use?
See also
Engine.execution_options()
SQLAlchemy 1.4 Documentation method sqlalchemy.engine.Engine. has_table (table_name, schema=None)

CURRENT RELEASE
Home
| Download this Documentation Return True if the given backend has a table of the given name.
Search terms:
search... Deprecated since version 1.4: The Engine.has_table() method is
deprecated and will be removed in a future release. Please refer to
Inspector.has_table() .
latest listings. See also
ADS VIA CARBON

Fine Grained Reflection with Inspector - detailed schema inspection
using the
SQLAlchemy Core Inspector interface.
SQL Expression Language Tutorial (1.x API) quoted_name - used to pass quoting information along
with a schema identifier.

attribute sqlalchemy.engine.Engine. name
String name of the Dialect
in use by this Engine .
Engine Configuration method sqlalchemy.engine.Engine. raw_connection (_connection=None)
Working with Engines and Connections Return a “raw” DBAPI connection from the connection pool.
Basic Usage
The returned object is a proxied version of the DBAPI
connection object used by
Using Transactions the underlying driver in use.
The object will have all the same behavior as the real
DBAPI
connection, except that its close() method will result in the
connection
being returned to the pool, rather than being closed
for real.
This method provides direct DBAPI connection access for
special situations when
an Antipattern
the API provided by
Connection
is not needed. When a Connection object is already
Migrating from the “nesting” present, the DBAPI connection is available using
the Connection.connection
accessor.
pattern
Library Level (e.g. emulated) See also
Autocommit
Working with Driver SQL and Raw DBAPI Connections
method sqlalchemy.engine.Engine. run_callable (callable_, *args,
**kwargs)
Given a callable object or function, execute it, passing
a Connection as the first
argument.
results)
Connectionless Execution, Implicit Deprecated since version 1.4: The Engine.run_callable() method is
Execution deprecated and will be removed in a future release. Use the Engine.begin()

The given *args and **kwargs are passed subsequent
to the Connection argument.
Configuration
This function, along with Connection.run_callable() ,
allows a function to be run
with a Connection
or Engine object without the need to know
which one is being
Using Logging dealt with.

method sqlalchemy.engine.Engine. scalar (statement, *multiparams,
use?
**params)
dictionary to cache some (or all) Executes and returns the first column of the first row.
Deprecated since version 1.4: The Engine.scalar() method is considered

legacy as of the 1.x series of SQLAlchemy and will be removed in 2.0. All
CURRENT RELEASE statement execution in SQLAlchemy 2.0 is performed by the
Home
| Download this Documentation Connection.execute() method of Connection , or in the ORM by the
Session.execute() method of Session ; the Result.scalar() method can then
Search terms:
search... be used to return a scalar result. (Background on SQLAlchemy 2.0 at:
Migrating to SQLAlchemy 2.0)

career awaits. Check out the The underlying result/cursor is closed after execution.
latest listings.
ADS VIA CARBON

method sqlalchemy.engine.Engine. table_names (schema=None,
connection=None)
SQLAlchemy Core
Return a list of all table names available in the database.

Deprecated since version 1.4: The Engine.table_names() method is
Schema Definition Language deprecated and will be removed in a future release. Please refer to
Inspector.get_table_names() .

Parameters:
schema – Optional, retrieve names from a non-default schema.
Working with Engines and Connections connection – Optional, use a specified connection.
Basic Usage
Using Transactions method sqlalchemy.engine.Engine. transaction (callable_, *args, **kwargs)

Execute the given function within a transaction boundary.
an Antipattern
Deprecated since version 1.4: The Engine.transaction() method is
Migrating from the “nesting” deprecated and will be removed in a future release. Use the Engine.begin()
pattern

The function is passed a Connection newly procured
from Engine.connect() as the
Autocommit
first argument,
followed by the given *args and **kwargs.
e.g.:
Understanding the DBAPI-Level def do_something(conn, x, y):
Autocommit Isolation Level conn.execute(text("some statement"), {'x':x, 'y':y})

engine.transaction(do_something, 5, 10)
results)
Connectionless Execution, Implicit The operations inside the function are all invoked within the
context of a single
Execution Transaction .
Upon success, the transaction is committed. If an
exception is raised,
the transaction is rolled back
before propagating the exception.
Note
Configuration The transaction() method is superseded by

the usage of the
Python with: statement, which can
be used with
Engine.begin() :
Using Logging
How much memory does the cache with engine.begin() as conn:
use? conn.execute(text("some statement"),

See also
Engine.begin() - engine-level transactional
context
CURRENT RELEASE
Home
| Download this Documentation Connection.transaction()
- connection-level version of
Engine.transaction()
Search terms:
search...
method sqlalchemy.engine.Engine. update_execution_options (**opt)
Your new development Update the default execution_options dictionary

of this Engine .
latest listings. The given keys/values in **opt are added to the
default execution options that will
ADS VIA CARBON
be used for
all connections. The initial contents of this dictionary
can be sent via
the execution_options parameter
to create_engine() .
SQLAlchemy Core
See also
Connection.execution_options()
Schema Definition Language Engine.execution_options()
Engine and Connection Use class sqlalchemy.engine. ExceptionContext
Encapsulate information about an error condition in progress.
This object exists solely to be passed to the
ConnectionEvents.handle_error() event,
Basic Usage supporting an interface that
can be extended without backwards-incompatibility.
Using Transactions

an Antipattern attribute sqlalchemy.engine.ExceptionContext. chained_exception =
None
pattern The exception that was returned by the previous handler in the
exception chain, if
any.
Autocommit If present, this exception will be the one ultimately raised by
SQLAlchemy unless a
subsequent handler replaces it.
including DBAPI Autocommit May be None.

attribute sqlalchemy.engine.ExceptionContext. connection = None
Using Server Side Cursors (a.k.a. stream The Connection in use during the exception.
results)
This member is present, except in the case of a failure when
first connecting.
See also
Execution
Translation of Schema Names ExceptionContext.engine
Configuration attribute sqlalchemy.engine.ExceptionContext. cursor = None

The DBAPI cursor object.
Using Logging
May be None.
use? attribute sqlalchemy.engine.ExceptionContext. engine = None
The Engine in use during the exception.
This member should always be present, even in the case of a failure
when first
SQLAlchemy 1.4 Documentation connecting.
CURRENT RELEASE
Home
| Download this Documentation New in version 1.0.0.
Search terms:
search...
attribute sqlalchemy.engine.ExceptionContext. execution_context =
None
career awaits. Check out the The ExecutionContext corresponding to the execution
operation in progress.
latest listings.
This is present for statement execution operations, but not for
operations such as
ADS VIA CARBON
transaction begin/end. It also is not present when
the exception was raised before
SQLAlchemy Core the ExecutionContext
could be constructed.
SQL Expression Language Tutorial (1.x API) Note that the ExceptionContext.statement and
ExceptionContext.parameters
members may represent a
different value than that of the ExecutionContext ,
potentially in the case where a
ConnectionEvents.before_cursor_execute() event or
Schema Definition Language similar
modified the statement/parameters to be sent.
Column and Data Types May be None.

attribute
Engine Configuration sqlalchemy.engine.ExceptionContext. invalidate_pool_on_disconnect
= True
Basic Usage Represent whether all connections in the pool should be invalidated
when a
“disconnect” condition is in effect.
Using Transactions

Setting this flag to False within the scope of the
ConnectionEvents.handle_error()
event will have the effect such
that the full collection of connections in the pool
Arbitrary Transaction Nesting as will not be
invalidated during a disconnect; only the current connection that is the
an Antipattern subject of the error will actually be invalidated.
Migrating from the “nesting” The purpose of this flag is for custom disconnect-handling schemes where
the
pattern invalidation of other connections in the pool is to be performed
based on other
conditions, or even on a per-connection basis.
Autocommit
attribute sqlalchemy.engine.ExceptionContext. is_disconnect = None
Autocommit Isolation Level Represent whether the exception as occurred represents a “disconnect”
condition.
results) This flag will always be True or False within the scope of the
ConnectionEvents.handle_error() handler.
Execution SQLAlchemy will defer to this flag in order to determine whether or not
the
connection should be invalidated subsequently. That is, by
assigning to this flag, a
“disconnect” event which then results in
a connection and pool invalidation can be
SQL Compilation Caching invoked or prevented by
changing this flag.
Configuration
Note

The pool “pre_ping” handler enabled using the
Using Logging
create_engine.pool_pre_ping parameter does not
consult this
How much memory does the cache event before deciding if the “ping” returned false,
as opposed
use? to receiving an unhandled error. For this use case, the

legacy
recipe based on engine_connect() may be used. A future API
Disabling or using an alternate allow more
comprehensive customization of the “disconnect”
dictionary to cache some (or all) detection mechanism
across all functions.

attribute sqlalchemy.engine.ExceptionContext. original_exception =
CURRENT RELEASE None
Home
The exception object which was caught.
Search terms:
search...
This member is always present.
Your new development attribute sqlalchemy.engine.ExceptionContext. parameters = None

latest listings. Parameter collection that was emitted directly to the DBAPI.
ADS VIA CARBON

May be None.
SQLAlchemy Core
attribute sqlalchemy.engine.ExceptionContext. sqlalchemy_exception =
SQL Expression Language Tutorial (1.x API) None
The sqlalchemy.exc.StatementError which wraps the original,
and will be raised if
Schema Definition Language exception handling is not circumvented by the event.

May be None, as not all exception types are wrapped by SQLAlchemy.
For DBAPI-
Engine and Connection Use level exceptions that subclass the dbapi’s Error class, this
field will always be
present.
Working with Engines and Connections attribute sqlalchemy.engine.ExceptionContext. statement = None
Basic Usage String SQL statement that was emitted directly to the DBAPI.
Using Transactions
May be None.
class sqlalchemy.engine. NestedTransaction (connection)
an Antipattern
Represent a ‘nested’, or SAVEPOINT transaction.
The NestedTransaction object is created by calling the
pattern method of
Connection .
When using NestedTransaction , the semantics of “begin” /
“commit” / “rollback” are
Autocommit as follows:
the “begin” operation corresponds to the “BEGIN SAVEPOINT” command,
including DBAPI Autocommit where
the savepoint is given an explicit name that is part of the state
of this
Understanding the DBAPI-Level object.
Autocommit Isolation Level The NestedTransaction.commit() method corresponds to a

“RELEASE
SAVEPOINT” operation, using the savepoint identifier associated
with this
NestedTransaction .
results)
The NestedTransaction.rollback() method corresponds to a
“ROLLBACK TO
SAVEPOINT” operation, using the savepoint identifier
associated with this
Execution
NestedTransaction .
The rationale for mimicking the semantics of an outer transaction in
terms of
SQL Compilation Caching savepoints so that code may deal with a “savepoint” transaction
and an “outer”
transaction in an agnostic way.
Configuration
Estimating Cache Performance See also
Using Logging
Using SAVEPOINT - ORM version of the SAVEPOINT API.
use?
Disabling or using an alternate Class signature
dictionary to cache some (or all) class sqlalchemy.engine.NestedTransaction ( sqlalchemy.engine.Transaction )

method sqlalchemy.engine.NestedTransaction. close ()
CURRENT RELEASE
Home
inherited from the Transaction.close() method of Transaction
Search terms:
search... Close this Transaction .
If this transaction is the base transaction in a begin/commit

nesting, the

transaction will rollback(). Otherwise, the
method returns.
This is used to cancel a Transaction without affecting the scope of
an enclosing
latest listings.
transaction.
ADS VIA CARBON
SQLAlchemy Core method sqlalchemy.engine.NestedTransaction. commit ()

inherited from the Transaction.commit() method of Transaction
SQL Statements and Expressions API Commit this Transaction .

The implementation of this may vary based on the type of transaction in
use:
For a simple database transaction (e.g. RootTransaction ),
it corresponds to a
Engine and Connection Use COMMIT.
Engine Configuration For a NestedTransaction , it corresponds to a

“RELEASE SAVEPOINT”
Working with Engines and Connections operation.
Basic Usage For a TwoPhaseTransaction , DBAPI-specific methods for two

phase
transactions may be used.
Using Transactions
Nesting of Transaction Blocks method sqlalchemy.engine.NestedTransaction. rollback ()

inherited from the Transaction.rollback() method of Transaction
an Antipattern
Roll back this Transaction .
pattern The implementation of this may vary based on the type of transaction in
use:
Library Level (e.g. emulated) For a simple database transaction (e.g. RootTransaction ),
it corresponds to a
Autocommit ROLLBACK.
Setting Transaction Isolation Levels For a NestedTransaction , it corresponds to a

“ROLLBACK TO SAVEPOINT”
including DBAPI Autocommit operation.
Understanding the DBAPI-Level For a TwoPhaseTransaction , DBAPI-specific methods for two

phase
Autocommit Isolation Level transactions may be used.

class sqlalchemy.engine. RootTransaction (connection)
results)
Represent the “root” transaction on a Connection .
Execution This corresponds to the current “BEGIN/COMMIT/ROLLBACK” that’s occurring
for
the Connection . The RootTransaction
is created by calling upon the
Connection.begin() method, and
remains associated with the Connection
SQL Compilation Caching throughout its
active span. The current RootTransaction in use is
accessible via the
Connection.get_transaction method of
Connection .
Configuration
In 2.0 style use, the Connection also employs
“autobegin” behavior that will create a
new
RootTransaction whenever a connection in a
non-transactional state is used to
Using Logging
emit commands on the DBAPI connection.
The scope of the RootTransaction in 2.0
How much memory does the cache style
use can be controlled using the Connection.commit() and
Connection.rollback() methods.
use?

Class signature
class sqlalchemy.engine.RootTransaction ( sqlalchemy.engine.Transaction )
CURRENT RELEASE
Home
| Download this Documentation method sqlalchemy.engine.RootTransaction. close ()
Search terms:
search... inherited from the Transaction.close() method of Transaction
Close this Transaction .
Your new development If this transaction is the base transaction in a begin/commit

nesting, the
career awaits. Check out the transaction will rollback(). Otherwise, the
method returns.
latest listings.
an enclosing
ADS VIA CARBON
transaction.
SQLAlchemy Core
method sqlalchemy.engine.RootTransaction. commit ()
SQL Statements and Expressions API inherited from the Transaction.commit() method of Transaction
Schema Definition Language Commit this Transaction .
Column and Data Types The implementation of this may vary based on the type of transaction in
use:
Engine and Connection Use For a simple database transaction (e.g. RootTransaction ),
it corresponds to a
COMMIT.
Working with Engines and Connections For a NestedTransaction , it corresponds to a

operation.
Basic Usage
For a TwoPhaseTransaction , DBAPI-specific methods for two
phase
Using Transactions
method sqlalchemy.engine.RootTransaction. rollback ()
an Antipattern
Roll back this Transaction .
pattern
use:
Autocommit For a simple database transaction (e.g. RootTransaction ),
it corresponds to a
ROLLBACK.
including DBAPI Autocommit For a NestedTransaction , it corresponds to a
operation.
Autocommit Isolation Level For a TwoPhaseTransaction , DBAPI-specific methods for two
phase
results) class sqlalchemy.engine. Transaction (connection)
Represent a database transaction in progress.
Execution
The Transaction object is procured by
calling the Connection.begin() method of
Connection :
Configuration from sqlalchemy import create_engine
engine = create_engine("postgresql://scott:tiger@localhost/te
Estimating Cache Performance connection = engine.connect()
Using Logging trans = connection.begin()
connection.execute(text("insert into x (a, b) values (1, 2)")

How much memory does the cache trans.commit()
use?

The object provides rollback() and commit()
methods in order to control
SQLAlchemy 1.4 Documentation transaction boundaries. It
also implements a context manager interface so that
the
Python with statement can be used with the
Connection.begin() method:
CURRENT RELEASE
Home
Search terms:
search... connection.execute(text("insert into x (a, b) values (1,
The Transaction object is not threadsafe.

See also
latest listings.
ADS VIA CARBON

Connection.begin()
SQLAlchemy Core


Class signature
Engine and Connection Use class sqlalchemy.engine.Transaction ( sqlalchemy.engine.util.TransactionalContext )
Working with Engines and Connections method sqlalchemy.engine.Transaction. close ()
Basic Usage Close this Transaction .

Using Transactions
nesting, the
Nesting of Transaction Blocks transaction will rollback(). Otherwise, the
method returns.
Arbitrary Transaction Nesting as This is used to cancel a Transaction without affecting the scope of
an enclosing
an Antipattern transaction.

method sqlalchemy.engine.Transaction. commit ()
pattern
Library Level (e.g. emulated) Commit this Transaction .
Autocommit The implementation of this may vary based on the type of transaction in
use:
it corresponds to a
including DBAPI Autocommit COMMIT.
For a NestedTransaction , it corresponds to a
Autocommit Isolation Level operation.
phase
results) transactions may be used.

method sqlalchemy.engine.Transaction. rollback ()
Execution
Translation of Schema Names Roll back this Transaction .
SQL Compilation Caching The implementation of this may vary based on the type of transaction in
use:
Configuration
it corresponds to a
Estimating Cache Performance ROLLBACK.
Using Logging
How much memory does the cache operation.
use?
phase
Disabling or using an alternate transactions may be used.
class sqlalchemy.engine. TwoPhaseTransaction (connection, xid)

CURRENT RELEASE Represent a two-phase transaction.
Home
A new TwoPhaseTransaction object may be procured
using the
Connection.begin_twophase() method.
Search terms:
search...
The interface is the same as that of Transaction
with the addition of the prepare()
method.
latest listings. Class signature
ADS VIA CARBON class sqlalchemy.engine.TwoPhaseTransaction ( sqlalchemy.engine.RootTransaction )
SQLAlchemy Core
SQL Expression Language Tutorial (1.x API) method sqlalchemy.engine.TwoPhaseTransaction. close ()

inherited from the Transaction.close() method of Transaction
Close this Transaction .
nesting, the
transaction will rollback(). Otherwise, the
method returns.
an enclosing
Working with Engines and Connections transaction.
Basic Usage
method sqlalchemy.engine.TwoPhaseTransaction. commit ()
Using Transactions
Nesting of Transaction Blocks inherited from the Transaction.commit() method of Transaction
Commit this Transaction .

an Antipattern The implementation of this may vary based on the type of transaction in
use:
Migrating from the “nesting” For a simple database transaction (e.g. RootTransaction ),
it corresponds to a
pattern COMMIT.
Library Level (e.g. emulated) For a NestedTransaction , it corresponds to a

Autocommit operation.
Setting Transaction Isolation Levels For a TwoPhaseTransaction , DBAPI-specific methods for two
phase
including DBAPI Autocommit transactions may be used.

method sqlalchemy.engine.TwoPhaseTransaction. prepare ()
Using Server Side Cursors (a.k.a. stream Prepare this TwoPhaseTransaction .
results) After a PREPARE, the transaction can be committed.

Execution
method sqlalchemy.engine.TwoPhaseTransaction. rollback ()

SQL Compilation Caching Roll back this Transaction .
Configuration
use:
it corresponds to a
Using Logging
ROLLBACK.
use?
operation.
phase
dictionary to cache some (or all) transactions may be used.
SQLAlchemy 1.4 Documentation Result Set API

CURRENT RELEASE
Home
BaseCursorResult Base class for database result objects.

Search terms:
search...
An IteratorResult that works from an iterator-

ChunkedIteratorResult
Your new development producing callable.
latest listings.
A Result that is representing state from a DBAPI
ADS VIA CARBON
CursorResult
cursor.
SQLAlchemy Core
Represents a Result object in a “frozen” state
SQL Expression Language Tutorial (1.x API) FrozenResult
suitable
for caching.
Schema Definition Language A Result that gets data from a Python iterator of
IteratorResult
Row objects.

LegacyCursorResult Legacy version of CursorResult .
Working with Engines and Connections A subclass of Row that delivers 1.x SQLAlchemy
LegacyRow
behaviors
for Core.
Basic Usage
Using Transactions
A wrapper for a Result that returns dictionary
MappingResult
values
rather than Row values.

an Antipattern A Result that is merged from any number of
MergedResult
Result objects.
pattern
Result Represent a set of database results.
Autocommit
Row Represent a single result row.
A Mapping that maps column names and objects to
RowMapping
Understanding the DBAPI-Level Row values.
Using Server Side Cursors (a.k.a. stream A wrapper for a Result that returns scalar values
ScalarResult
results)

Execution class sqlalchemy.engine. BaseCursorResult (context, cursor_strategy,
cursor_description)
SQL Compilation Caching Base class for database result objects.
Configuration
attribute sqlalchemy.engine.BaseCursorResult. inserted_primary_key
Using Logging
Return the primary key for the row just inserted.
How much memory does the cache The return value is a Row object representing
a named tuple of primary key values
in the order in which the
primary key columns are configured in the source
Table .
use?

Changed in version 1.4.8: - the
CursorResult.inserted_primary_key
value is
now a named tuple via the Row class,
rather than a plain tuple.

This accessor only applies to single row insert()
constructs which did not
CURRENT RELEASE explicitly specify
Insert.returning() . Support for multirow inserts,
while not yet
Home
| Download this Documentation available for most backends, would be accessed using
the
CursorResult.inserted_primary_key_rows accessor.
Search terms:
search...
Note that primary key columns which specify a server_default clause, or
otherwise do not qualify as “autoincrement” columns (see the notes at
Column ),
and were generated using the database-side
default, will appear in this list as None
career awaits. Check out the unless the backend
supports “returning” and the insert statement executed with
latest listings. the
“implicit returning” enabled.
ADS VIA CARBON

Raises InvalidRequestError if the executed
statement is not a compiled
SQLAlchemy Core expression construct
or is not an insert() construct.
SQL Expression Language Tutorial (1.x API) attribute

sqlalchemy.engine.BaseCursorResult. inserted_primary_key_rows
Schema Definition Language Return the value of CursorResult.inserted_primary_key

as a row contained within a
list; some dialects may support a
multiple row form as well.
Engine and Connection Use Note
Engine Configuration As indicated below, in current SQLAlchemy versions this
Working with Engines and Connections accessor is only useful beyond what’s already supplied by
CursorResult.inserted_primary_key when using the
psycopg2
Basic Usage dialect. Future versions hope to
generalize this feature to
more dialects.
Using Transactions

This accessor is added to support dialects that offer the feature
that is currently
implemented by the Psycopg2 Fast Execution Helpers
feature, currently only the
an Antipattern psycopg2 dialect, which provides
for many rows to be INSERTed at once while
still retaining the
behavior of being able to return server-generated primary key
values.
pattern
When using the psycopg2 dialect, or other dialects that may support
“fast
executemany” style inserts in upcoming releases : When
invoking an
Autocommit INSERT statement while passing a list of rows as the
second argument to
Setting Transaction Isolation Levels Connection.execute() , this accessor
will then provide a list of rows, where
each row contains the primary
key value for each row that was INSERTed.
Understanding the DBAPI-Level When using all other dialects / backends that don’t yet support
this
feature: This accessor is only useful for single row INSERT
statements, and
returns the same information as that of the
Using Server Side Cursors (a.k.a. stream CursorResult.inserted_primary_key within a
single-element list. When an
results) INSERT statement is executed in

conjunction with a list of rows to be
INSERTed, the list will contain
one row per row inserted in the statement,
Connectionless Execution, Implicit however it will contain
None for any server-generated values.
Execution
Future releases of SQLAlchemy will further generalize the
“fast execution helper”
Translation of Schema Names feature of psycopg2 to suit other dialects,
thus allowing this accessor to be of
more general use.
Configuration
New in version 1.4.
Using Logging
See also
use? CursorResult.inserted_primary_key

dictionary to cache some (or all) attribute sqlalchemy.engine.BaseCursorResult. is_insert
SQLAlchemy 1.4 Documentation True if this CursorResult is the result

of a executing an expression language
compiled
insert() construct.
CURRENT RELEASE
Home
| Download this Documentation When True, this implies that the
inserted_primary_key attribute is accessible,
assuming the statement did not include
a user defined “returning” construct.
Search terms:
search...
method sqlalchemy.engine.BaseCursorResult. last_inserted_params ()
Your new development Return the collection of inserted parameters from this
execution.
latest listings. Raises InvalidRequestError if the executed
expression construct
ADS VIA CARBON
SQLAlchemy Core method sqlalchemy.engine.BaseCursorResult. last_updated_params ()
SQL Expression Language Tutorial (1.x API) Return the collection of updated parameters from this
execution.
Schema Definition Language expression construct
or is not an update() construct.

method sqlalchemy.engine.BaseCursorResult. lastrow_has_defaults ()
Return lastrow_has_defaults() from the underlying
ExecutionContext .
Working with Engines and Connections See ExecutionContext for details.
Basic Usage attribute sqlalchemy.engine.BaseCursorResult. lastrowid

Using Transactions
Return the ‘lastrowid’ accessor on the DBAPI cursor.
This is a DBAPI specific method and is only functional
for those backends which
support it, for statements
where it is appropriate. It’s behavior is not
consistent
an Antipattern across backends.

Usage of this method is normally unnecessary when
using insert() expression
pattern constructs; the
CursorResult.inserted_primary_key attribute provides a
tuple of
primary key values for a newly inserted row,
regardless of database backend.
Autocommit
method sqlalchemy.engine.BaseCursorResult. postfetch_cols ()
including DBAPI Autocommit Return postfetch_cols() from the underlying
ExecutionContext .
Understanding the DBAPI-Level See ExecutionContext for details.

Using Server Side Cursors (a.k.a. stream expression construct
or is not an insert() or update() construct.
results)
method sqlalchemy.engine.BaseCursorResult. prefetch_cols ()
Execution Return prefetch_cols() from the underlying
ExecutionContext .
Translation of Schema Names See ExecutionContext for details.

Configuration expression construct

attribute sqlalchemy.engine.BaseCursorResult. returned_defaults
Using Logging
Return the values of default columns that were fetched using
the
ValuesBase.return_defaults() feature.
use?
The value is an instance of Row , or None
if ValuesBase.return_defaults() was not
used or if the
backend does not support RETURNING.

CURRENT RELEASE
See also
Home
Search terms:
search... ValuesBase.return_defaults()

attribute
career awaits. Check out the sqlalchemy.engine.BaseCursorResult. returned_defaults_rows
latest listings.
Return a list of rows each containing the values of default
columns that were
ADS VIA CARBON
fetched using
the ValuesBase.return_defaults() feature.
SQLAlchemy Core
The return value is a list of Row objects.
SQL Statements and Expressions API New in version 1.4.
Column and Data Types attribute sqlalchemy.engine.BaseCursorResult. returns_rows

True if this CursorResult returns zero or more rows.
I.e. if it is legal to call the methods
CursorResult.fetchone() ,
Working with Engines and Connections CursorResult.fetchmany()
CursorResult.fetchall() .
Basic Usage Overall, the value of CursorResult.returns_rows should

always be synonymous with
Using Transactions whether or not the DBAPI cursor had a
.description attribute, indicating the
presence of result columns,
noting that a cursor that returns zero rows still has a
Nesting of Transaction Blocks .description if a row-returning statement was emitted.

This attribute should be True for all results that are against
SELECT statements,
an Antipattern as well as for DML statements INSERT/UPDATE/DELETE
that use RETURNING.
For INSERT/UPDATE/DELETE statements that were
not using RETURNING, the
value will usually be False, however
there are some dialect-specific exceptions to
pattern
this, such as when
using the MSSQL / pyodbc dialect a SELECT is emitted inline in
Library Level (e.g. emulated) order to retrieve an inserted primary key value.
Autocommit
attribute sqlalchemy.engine.BaseCursorResult. rowcount
including DBAPI Autocommit Return the ‘rowcount’ for this result.
Understanding the DBAPI-Level The ‘rowcount’ reports the number of rows matched
by the WHERE criterion of an
Autocommit Isolation Level UPDATE or DELETE statement.
Using Server Side Cursors (a.k.a. stream Note

results)
Notes regarding CursorResult.rowcount :
Execution This attribute returns the number of rows matched,
which is not necessarily the same as the number of
rows
that were actually modified - an UPDATE
SQL Compilation Caching statement, for example,
may have no net change
on a given row if the SET values
given are the same
Configuration
as those present in the row already.
Such a row
Estimating Cache Performance would be matched but not modified.
On backends
that feature both styles, such as MySQL,
rowcount
Using Logging
is configured by default to return the match
count
How much memory does the cache in all cases.
use?
CursorResult.rowcount
is only useful in conjunction
Disabling or using an alternate with an UPDATE or DELETE statement. Contrary to
dictionary to cache some (or all) what the Python
DBAPI says, it does not return the
number of rows available from the results of a
SQLAlchemy 1.4 Documentation SELECT statement
as DBAPIs cannot support this
functionality when rows are
unbuffered.
CURRENT RELEASE
Home
| Download this Documentation CursorResult.rowcount
may not be fully
implemented by
all dialects. In particular, most
Search terms:
search... DBAPIs do not support an
aggregate rowcount
result from an executemany call.
The
CursorResult.supports_sane_rowcount() and
Your new development CursorResult.supports_sane_multi_rowcount()
career awaits. Check out the methods
will report from the dialect if each usage
latest listings. is known to be
supported.
ADS VIA CARBON
Statements that use RETURNING may not return a
SQLAlchemy Core correct
rowcount.

See also
Schema Definition Language Getting Affected Row Count from UPDATE, DELETE - in the SQLAlchemy 1.4 / 2.0
Tutorial

method
sqlalchemy.engine.BaseCursorResult. supports_sane_multi_rowcount ()
Return supports_sane_multi_rowcount from the dialect.
Basic Usage
See CursorResult.rowcount for background.
Using Transactions
Nesting of Transaction Blocks method

sqlalchemy.engine.BaseCursorResult. supports_sane_rowcount ()
an Antipattern
Return supports_sane_rowcount from the dialect.
See CursorResult.rowcount for background.
pattern
Library Level (e.g. emulated) class sqlalchemy.engine. ChunkedIteratorResult (cursor_metadata,

Autocommit chunks, source_supports_scalars=False, raw=None, dynamic_yield_per=False)
Setting Transaction Isolation Levels An IteratorResult that works from an iterator-producing callable.
The given chunks argument is a function that is given a number of rows
to return in
Understanding the DBAPI-Level each chunk, or None for all rows. The function should
then return an un-consumed
Autocommit Isolation Level iterator of lists, each list of the requested
size.
Using Server Side Cursors (a.k.a. stream The function can be called at any time again, in which case it should
continue from
results) the same result set but adjust the chunk size as given.

New in version 1.4.
Execution
SQL Compilation Caching Class signature
Configuration
class sqlalchemy.engine.ChunkedIteratorResult ( sqlalchemy.engine.IteratorResult )

Using Logging
method sqlalchemy.engine.ChunkedIteratorResult. yield_per (num)
use? Configure the row-fetching strategy to fetch num rows at a time.
Disabling or using an alternate This impacts the underlying behavior of the result when iterating over
the result
dictionary to cache some (or all) object, or otherwise making use of methods such as
Result.fetchone() that return
one row at a time. Data
from the underlying cursor or other data source will be
SQLAlchemy 1.4 Documentation buffered up to
this many rows in memory, and the buffered collection will then be
yielded out one row at at time or as many rows are requested. Each time
the
CURRENT RELEASE
buffer clears, it will be refreshed to this many rows or as many
rows remain if
Home
fewer remain.
Search terms:
search... The Result.yield_per() method is generally used in
conjunction with the
Connection.execution_options.stream_results
execution option, which will allow
the database dialect in use to make
use of a server side cursor, if the DBAPI
Your new development supports it.
latest listings. Most DBAPIs do not use server side cursors by default, which means all
rows will
be fetched upfront from the database regardless of the
Result.yield_per()
ADS VIA CARBON
setting. However,
Result.yield_per() may still be useful in that it batches
the
SQLAlchemy Core SQLAlchemy-side processing of the raw data from the database, and
additionally
when used for ORM scenarios will batch the conversion of
database rows into
SQL Expression Language Tutorial (1.x API) ORM entity rows.
Schema Definition Language New in version 1.4.

Parameters:
num – number of rows to fetch each time the buffer is refilled.
If set to a
value below 1, fetches all rows for the next buffer.
See also
Basic Usage
Using Transactions Yield Per - in the ORM Querying Guide

Result.partitions()

an Antipattern
class sqlalchemy.engine. FrozenResult (result)
pattern Represents a Result object in a “frozen” state suitable
for caching.
Library Level (e.g. emulated) The FrozenResult object is returned from the
Result.freeze() method of any Result
Autocommit object.
Setting Transaction Isolation Levels A new iterable Result object is generated from a fixed
set of data each time the
including DBAPI Autocommit FrozenResult is invoked as
a callable:

result = connection.execute(query)
Using Server Side Cursors (a.k.a. stream frozen = result.freeze()
results)
unfrozen_result_one = frozen()

for row in unfrozen_result_one:
Execution
print(row)

unfrozen_result_two = frozen()

rows = unfrozen_result_two.all()
Configuration
# ... etc
Using Logging

New in version 1.4.
use?
Disabling or using an alternate See also
Re-Executing Statements - example usage within the
ORM to implement a result-
SQLAlchemy 1.4 Documentation set cache.
CURRENT RELEASE merge_frozen_result() - ORM function to merge

a frozen result back into a Session .
Home
Search terms:
search...
class sqlalchemy.engine. IteratorResult (cursor_metadata, iterator,
raw=None, _source_supports_scalars=False)
Your new development A Result that gets data from a Python iterator of
Row objects.
latest listings.
New in version 1.4.
ADS VIA CARBON
SQLAlchemy Core
Class signature
SQL Statements and Expressions API class sqlalchemy.engine.IteratorResult ( sqlalchemy.engine.Result )
Column and Data Types class sqlalchemy.engine. LegacyRow (parent, processors, keymap, key_style,

data)
Engine Configuration A subclass of Row that delivers 1.x SQLAlchemy behaviors

for Core.
Working with Engines and Connections The LegacyRow class is where most of the Python mapping
(i.e. dictionary-like)
Basic Usage behaviors are implemented for the row object. The mapping behavior
of Row going
forward is accessible via the _mapping
attribute.
Using Transactions
Nesting of Transaction Blocks New in version 1.4: - added LegacyRow which encapsulates most
of the

deprecated behaviors of Row .
an Antipattern

Class signature
pattern
class sqlalchemy.engine.LegacyRow ( sqlalchemy.engine.Row )
Autocommit
Setting Transaction Isolation Levels method sqlalchemy.engine.LegacyRow. has_key (key)

Return True if this LegacyRow contains the given key.
Autocommit Isolation Level Deprecated since version 1.4: The LegacyRow.has_key() method is
Using Server Side Cursors (a.k.a. stream deprecated and will be removed in a future release. To test for key
membership, use the Row._mapping attribute, i.e. ‘key in row._mapping`.
results)

Through the SQLAlchemy 1.x series, the __contains__() method of
Row (or
Execution
LegacyRow as of SQLAlchemy 1.4) also links
to Row.has_key() , in that an expression
Translation of Schema Names such as

"some_col" in row
Configuration
Estimating Cache Performance Will return True if the row contains a column named "some_col" ,
in the way that a
Using Logging Python mapping works.
How much memory does the cache However, it is planned that the 2.0 series of SQLAlchemy will reverse
this behavior
use? so that __contains__() will refer to a value being
present in the row, in the way that
a Python tuple works.
dictionary to cache some (or all) See also
RowProxy is no longer a “proxy”; is now called Row and behaves like an enhanced
SQLAlchemy 1.4 Documentation named tuple
CURRENT RELEASE
Home
method sqlalchemy.engine.LegacyRow. items ()
Search terms:
search...
Return a list of tuples, each tuple containing a key/value pair.
Your new development Deprecated since version 1.4: The LegacyRow.items() method is deprecated
career awaits. Check out the and will be removed in a future release. Use the Row._mapping attribute, i.e.,
latest listings. ‘row._mapping.items()’.
ADS VIA CARBON
SQLAlchemy Core This method is analogous to the Python dictionary .items() method,
except that it
returns a list, not an iterator.
SQL Statements and Expressions API method sqlalchemy.engine.LegacyRow. iterkeys ()
Schema Definition Language Return a an iterator against the Row.keys() method.

Deprecated since version 1.4: The LegacyRow.iterkeys() method is
deprecated and will be removed in a future release. Use the Row._mapping
Engine Configuration attribute, i.e., ‘row._mapping.keys()’.
Basic Usage
This method is analogous to the Python-2-only dictionary
.iterkeys() method.
Using Transactions
method sqlalchemy.engine.LegacyRow. itervalues ()
Return a an iterator against the Row.values() method.
an Antipattern
Deprecated since version 1.4: The LegacyRow.itervalues() method is
Migrating from the “nesting” deprecated and will be removed in a future release. Use the Row._mapping
pattern
attribute, i.e., ‘row._mapping.values()’.

Autocommit
This method is analogous to the Python-2-only dictionary
.itervalues() method.
Setting Transaction Isolation Levels method sqlalchemy.engine.LegacyRow. values ()

Return the values represented by this Row as a list.
Deprecated since version 1.4: The LegacyRow.values() method is
Using Server Side Cursors (a.k.a. stream deprecated and will be removed in a future release. Use the Row._mapping
results) attribute, i.e., ‘row._mapping.values()’.

Execution This method is analogous to the Python dictionary .values() method,
except that
it returns a list, not an iterator.
SQL Compilation Caching class sqlalchemy.engine. MergedResult (cursor_metadata, results)
Configuration
A Result that is merged from any number of
Result objects.
Returned by the Result.merge() method.
Using Logging

New in version 1.4.
use?

dictionary to cache some (or all) Class signature
class sqlalchemy.engine.MergedResult ( sqlalchemy.engine.IteratorResult )
CURRENT RELEASE
Home
| Download this Documentation class sqlalchemy.engine. Result (cursor_metadata)
Search terms:
search... Represent a set of database results.
New in version 1.4: The Result object provides a completely

updated usage
Your new development model and calling facade for SQLAlchemy Core and
SQLAlchemy ORM. In
career awaits. Check out the Core, it forms the basis of the
CursorResult object which replaces the
latest listings. previous
ResultProxy interface. When using the ORM, a higher level
object
ADS VIA CARBON
called ChunkedIteratorResult is normally used.
SQLAlchemy Core
Note
SQL Statements and Expressions API In SQLAlchemy 1.4 and above, this object is
used for ORM
results returned by Session.execute() , which can
yield instances
Schema Definition Language of ORM mapped objects either individually or within
tuple-like
Column and Data Types rows. Note that the Result object does not
deduplicate
instances or rows automatically as is the case with the
legacy
Engine and Connection Use Query object. For in-Python de-duplication of
instances or rows,
Engine Configuration use the Result.unique() modifier

method.

See also
Basic Usage
Using Transactions Fetching Rows - in the SQLAlchemy 1.4 / 2.0 Tutorial

Class signature
an Antipattern
class sqlalchemy.engine.Result ( sqlalchemy.engine._WithKeys ,
sqlalchemy.engine.ResultInternal )
pattern

method sqlalchemy.engine.Result. all ()
Autocommit
Setting Transaction Isolation Levels Return all rows in a list.

Closes the result set after invocation. Subsequent invocations
will return an
Understanding the DBAPI-Level empty list.
Using Server Side Cursors (a.k.a. stream New in version 1.4.
results)
Connectionless Execution, Implicit Returns:
Execution a list of Row objects.
SQL Compilation Caching method sqlalchemy.engine.Result. close ()
Configuration
close this Result .
The behavior of this method is implementation specific, and is
not implemented
Using Logging
by default. The method should generally end
the resources in use by the result
How much memory does the cache object and also cause any
subsequent iteration or row fetching to raise
ResourceClosedError .
use?

New in version 1.4.27: - .close() was previously not generally
available for
dictionary to cache some (or all) all Result classes, instead only
being available on the CursorResult returned
for
Core statement executions. As most other result objects, namely the
SQLAlchemy 1.4 Documentation ones used by the ORM, are proxying a CursorResult
in any case, this allows
the underlying cursor result to be closed
from the outside facade for the
CURRENT RELEASE
case when the ORM query is using
the yield_per execution option where it
Home
does not immediately
exhaust and autoclose the database cursor.
Search terms:
search...
method sqlalchemy.engine.Result. columns (*col_expressions)

Establish the columns that should be returned in each row.
latest listings. This method may be used to limit the columns returned as well
as to reorder them.
ADS VIA CARBON The given list of expressions are normally
a series of integers or string key names.
They may also be
appropriate ColumnElement objects which correspond to
a given
SQLAlchemy Core
statement construct.

E.g.:
statement = select(table.c.x, table.c.y, table.c.z)

result = connection.execute(statement)

for z, y in result.columns('z', 'y'):

# ...
Working with Engines and Connections Example of using the column objects from the statement itself:
Basic Usage
for z, y in result.columns(
Using Transactions statement.selected_columns.c.z,
statement.selected_columns.c.y
Nesting of Transaction Blocks ):
Arbitrary Transaction Nesting as # ...
an Antipattern
Migrating from the “nesting” New in version 1.4.

pattern
Library Level (e.g. emulated) Parameters:

Autocommit
*col_expressions – indicates columns to be returned. Elements
may be
Setting Transaction Isolation Levels integer row indexes, string column names, or appropriate
ColumnElement

objects corresponding to a select construct.
Understanding the DBAPI-Level Returns:

Autocommit Isolation Level this Result object with the modifications
given.

results)
method sqlalchemy.engine.Result. fetchall ()
A synonym for the Result.all() method.
Execution
Translation of Schema Names method sqlalchemy.engine.Result. fetchmany (size=None)

Fetch many rows.
Configuration
When all rows are exhausted, returns an empty list.
Using Logging This method is provided for backwards compatibility with
SQLAlchemy 1.x.x.
How much memory does the cache To fetch rows in groups, use the Result.partitions()
method.
use?
Returns:
a list of Row objects.
method sqlalchemy.engine.Result. fetchone ()

CURRENT RELEASE Fetch one row.
Home
When all rows are exhausted, returns None.
Search terms:
search... This method is provided for backwards compatibility with
SQLAlchemy 1.x.x.
To fetch the first row of a result only, use the

Result.first() method. To iterate
Your new development through all
rows, iterate the Result object directly.
latest listings. Returns:
ADS VIA CARBON a Row object if no filters are applied, or None

if no rows remain.
SQLAlchemy Core
method sqlalchemy.engine.Result. first ()
SQL Statements and Expressions API Fetch the first row or None if no row is present.
Schema Definition Language Closes the result set and discards remaining rows.
Note
This method returns one row, e.g. tuple, by default.
To return
exactly one single scalar value, that is, the first
column of the
Working with Engines and Connections first row, use the Result.scalar() method,
or combine
Result.scalars() and Result.first() .
Basic Usage
Additionally, in contrast to the behavior of the legacy ORM
Using Transactions
Query.first() method, no limit is applied to the
SQL query
Nesting of Transaction Blocks which was invoked to produce this Result ;
for a DBAPI driver
that buffers results in memory before yielding
rows, all rows
will be sent to the Python process and all but
the first row will
an Antipattern
be discarded.
See also
pattern
Library Level (e.g. emulated) ORM Query Unified with Core Select
Autocommit

Returns:
a Row object, or None
if no rows remain.
See also
results) Result.scalar()
Connectionless Execution, Implicit Result.one()
Execution

method sqlalchemy.engine.Result. freeze ()
Return a callable object that will produce copies of this
Result when invoked.
Configuration
The callable object returned is an instance of
FrozenResult .
Using Logging This is used for result set caching. The method must be called
on the result when
it has been unconsumed, and calling the method
will consume the result fully.
When the FrozenResult
is retrieved from a cache, it can be called any number of
use?
times where
it will produce a new Result object each time
against its stored set of
Disabling or using an alternate rows.
See also
Re-Executing Statements - example usage within the
CURRENT RELEASE
set cache.
Home
Search terms:
search...
method sqlalchemy.engine.Result. keys ()
inherited from the sqlalchemy.engine._WithKeys.keys method of

sqlalchemy.engine._WithKeys
latest listings. Return an iterable view which yields the string keys that would
be represented by
ADS VIA CARBON
each Row .
SQLAlchemy Core The keys can represent the labels of the columns returned by a core
statement or
the names of the orm classes returned by an orm
execution.
The view also can be tested for key containment using the Python
in operator,
which will test both for the string keys represented
in the view, as well as for
Schema Definition Language alternate keys such as column objects.

Changed in version 1.4: a key view object is returned rather than a
plain list.
method sqlalchemy.engine.Result. mappings ()
Basic Usage Apply a mappings filter to returned rows, returning an instance of

MappingResult .
Using Transactions When this filter is applied, fetching rows will return
RowMapping objects instead of
Row objects.

New in version 1.4.
an Antipattern

Returns:
pattern
a new MappingResult filtering object
referring to this Result object.
Autocommit
method sqlalchemy.engine.Result. merge (*others)
including DBAPI Autocommit Merge this Result with other compatible result
objects.

The object returned is an instance of MergedResult ,
which will be composed of
Autocommit Isolation Level iterators from the given result
objects.

The new result will use the metadata from this result object.
The subsequent
results) result objects must be against an identical
set of result / cursor metadata,
otherwise the behavior is
undefined.
Execution
method sqlalchemy.engine.Result. one ()
Return exactly one row or raise an exception.
Raises NoResultFound if the result returns no
rows, or MultipleResultsFound if
Configuration
multiple rows
would be returned.
Note
Using Logging
How much memory does the cache This method returns one row, e.g. tuple, by default.
To return
use? exactly one single scalar value, that is, the first
column of the
first row, use the Result.scalar_one() method,
or combine
Result.scalars() and Result.one() .
New in version 1.4.

CURRENT RELEASE
Home
| Download this Documentation Returns:
The first Row .

Search terms:
search...
Raises:
MultipleResultsFound , NoResultFound
latest listings. See also
ADS VIA CARBON

Result.first()
SQLAlchemy Core
Result.one_or_none()
Result.scalar_one()

method sqlalchemy.engine.Result. one_or_none ()
Engine and Connection Use Return at most one result or raise an exception.
Engine Configuration Returns None if the result has no rows.

Raises MultipleResultsFound
if multiple rows
are returned.
Basic Usage
New in version 1.4.
Using Transactions

Returns:
The first Row or None if no row is available.
an Antipattern
Raises:
MultipleResultsFound
pattern

See also
Autocommit
Result.first()
including DBAPI Autocommit Result.one()

method sqlalchemy.engine.Result. partitions (size=None)
results) Iterate through sub-lists of rows of the size given.
Connectionless Execution, Implicit Each list will be of the size given, excluding the last list to
be yielded, which may
Execution
have a small number of rows. No empty
lists will be yielded.
Translation of Schema Names The result object is automatically closed when the iterator
is fully consumed.
SQL Compilation Caching Note that the backend driver will usually buffer the entire result
ahead of time
unless the
Connection.execution_options.stream_results execution
option is used
Configuration
indicating that the driver should not pre-buffer
results, if possible. Not all drivers
Estimating Cache Performance support this option and
the option is silently ignored for those who do not.
Using Logging
When using the ORM, the Result.partitions() method
is typically more effective
How much memory does the cache from a memory perspective when it is
combined with use of the
use? Result.yield_per() method,
which instructs the ORM loading internals to only
build a certain
amount of ORM objects from a result at a time before yielding
them
Disabling or using an alternate out.
New in version 1.4.

CURRENT RELEASE
Parameters:
Home
size – indicate the maximum number of rows to be present
in each list
Search terms:
search... yielded. If None, makes use of the value set by
Result.yield_per() , if
present, otherwise uses the
Result.fetchmany() default which may be
backend
specific.
Returns:
latest listings. iterator of lists
ADS VIA CARBON
SQLAlchemy Core See also
SQL Expression Language Tutorial (1.x API) Connection.execution_options.stream_results
SQL Statements and Expressions API Yield Per - in the ORM Querying Guide
Column and Data Types method sqlalchemy.engine.Result. scalar ()

Fetch the first column of the first row, and close the result set.
Returns None if there are no rows to fetch.
No validation is performed to test if additional rows remain.
Basic Usage
Using Transactions After calling this method, the object is fully closed,
e.g. the CursorResult.close()
method will have been called.
Returns:
an Antipattern a Python scalar value , or None if no rows remain.

pattern method sqlalchemy.engine.Result. scalar_one ()

Return exactly one scalar result or raise an exception.
Autocommit
This is equivalent to calling Result.scalars() and then
Result.one() .
including DBAPI Autocommit See also
Understanding the DBAPI-Level Result.one()

Result.scalars()
results)
Connectionless Execution, Implicit method sqlalchemy.engine.Result. scalar_one_or_none ()
Execution
Return exactly one or no scalar result.
Result.one_or_none() .
See also
Configuration
Estimating Cache Performance Result.one_or_none()
Using Logging
Result.scalars()

use?
method sqlalchemy.engine.Result. scalars (index=0)
Return a ScalarResult filtering object which

will return single elements rather than
SQLAlchemy 1.4 Documentation Row objects.
CURRENT RELEASE
E.g.:
Home
Search terms:
search... >>> result = conn.execute(text("select int_id from table"))
>>> result.scalars().all()
[1, 2, 3]
latest listings. When results are fetched from the ScalarResult
filtering object, the single
column-row that would be returned by the
Result is instead returned as the
ADS VIA CARBON
column’s value.
SQLAlchemy Core
SQL Expression Language Tutorial (1.x API) New in version 1.4.

Parameters:
index – integer or row key indicating the column to be fetched
from each
row, defaults to 0 indicating the first column.
Returns:
a new ScalarResult filtering object referring
to this Result object.
Basic Usage
method sqlalchemy.engine.Result. unique (strategy=None)
Using Transactions
Apply unique filtering to the objects returned by this
Result .
Arbitrary Transaction Nesting as When this filter is applied with no arguments, the rows or objects
returned will
filtered such that each row is returned uniquely. The
algorithm used to determine
an Antipattern
this uniqueness is by default the Python
hashing identity of the whole tuple. In
Migrating from the “nesting” some cases a specialized
per-entity hashing scheme may be used, such as when
pattern using the ORM, a
scheme is applied which works against the primary key identity
of
returned objects.
Autocommit The unique filter is applied after all other filters, which means
if the columns
returned have been refined using a method such as the
Result.columns() or
Setting Transaction Isolation Levels Result.scalars()
method, the uniquing is applied to only the column or columns
including DBAPI Autocommit returned. This occurs regardless of the order in which these
methods have been
called upon the Result object.
Autocommit Isolation Level The unique filter also changes the calculus used for methods like
Result.fetchmany() and Result.partitions() .
When using Result.unique() , these
methods will continue
to yield the number of rows or objects requested, after
results) uniquing
has been applied. However, this necessarily impacts the buffering
Connectionless Execution, Implicit behavior of the underlying cursor or datasource, such that multiple
underlying
calls to cursor.fetchmany() may be necessary in order
to accumulate enough
Execution
objects in order to provide a unique collection
of the requested size.
Parameters:
strategy – a callable that will be applied to rows or objects
being iterated,
Configuration which should return an object that represents the
unique value of the row. A
Estimating Cache Performance Python set() is used to store
these identities. If not passed, a default
uniqueness strategy
is used which may have been assembled by the source
Using Logging
of this
Result object.
use?
method sqlalchemy.engine.Result. yield_per (num)
dictionary to cache some (or all) Configure the row-fetching strategy to fetch num rows at a time.
This impacts the underlying behavior of the result when iterating over
the result
SQLAlchemy 1.4 Documentation object, or otherwise making use of methods such as
one row at a time. Data
CURRENT RELEASE
buffered up to
Home
the
rows remain if
Search terms:
search...
fewer remain.
The Result.yield_per() method is generally used in

Your new development Connection.execution_options.stream_results
career awaits. Check out the the database dialect in use to make
latest listings. supports it.
ADS VIA CARBON
Most DBAPIs do not use server side cursors by default, which means all
rows will
SQLAlchemy Core be fetched upfront from the database regardless of the
Result.yield_per()
setting. However,
the
SQL Expression Language Tutorial (1.x API) SQLAlchemy-side processing of the raw data from the database, and
additionally
SQL Statements and Expressions API when used for ORM scenarios will batch the conversion of
database rows into
ORM entity rows.
Column and Data Types New in version 1.4.
Engine Configuration Parameters:
Working with Engines and Connections num – number of rows to fetch each time the buffer is refilled.
If set to a
value below 1, fetches all rows for the next buffer.
Basic Usage

Yield Per - in the ORM Querying Guide
Result.partitions()
an Antipattern

pattern class sqlalchemy.engine. ScalarResult (real_result, index)

A wrapper for a Result that returns scalar values
Autocommit
The ScalarResult object is acquired by calling the
Result.scalars() method.
including DBAPI Autocommit A special limitation of ScalarResult is that it has
no fetchone() method; since the
semantics of fetchone() are that
the None value indicates no more results, this is not
compatible
with ScalarResult since there is no way to distinguish
between None as a
Autocommit Isolation Level row value versus None as an indicator. Use
next(result) to receive values
individually.
results)
Class signature
Execution class sqlalchemy.engine.ScalarResult ( sqlalchemy.engine.FilterResult )
SQL Compilation Caching method sqlalchemy.engine.ScalarResult. all ()
Configuration
Return all scalar values in a list.
Equivalent to Result.all() except that
scalar values, rather than Row objects,
are
Using Logging
returned.
use? method sqlalchemy.engine.ScalarResult. fetchall ()
Disabling or using an alternate A synonym for the ScalarResult.all() method.

method sqlalchemy.engine.ScalarResult. fetchmany (size=None)

CURRENT RELEASE Fetch many objects.
Home
Equivalent to Result.fetchmany() except that
scalar values, rather than Row
objects,
are returned.
Search terms:
search...
method sqlalchemy.engine.ScalarResult. first ()

Fetch the first object or None if no object is present.
latest listings.
Equivalent to Result.first() except that
are
ADS VIA CARBON returned.
SQLAlchemy Core
method sqlalchemy.engine.ScalarResult. one ()
Return exactly one object or raise an exception.
Equivalent to Result.one() except that
are
returned.
method sqlalchemy.engine.ScalarResult. one_or_none ()
Engine Configuration Return at most one object or raise an exception.
Working with Engines and Connections Equivalent to Result.one_or_none() except that

objects,
are returned.
Basic Usage
Using Transactions method sqlalchemy.engine.ScalarResult. partitions (size=None)

Iterate through sub-lists of elements of the size given.
an Antipattern
Equivalent to Result.partitions() except that
objects,
are returned.
pattern method sqlalchemy.engine.ScalarResult. unique (strategy=None)

Apply unique filtering to the objects returned by this
ScalarResult .
Autocommit
See Result.unique() for usage details.
class sqlalchemy.engine. MappingResult (result)
A wrapper for a Result that returns dictionary values
Using Server Side Cursors (a.k.a. stream The MappingResult object is acquired by calling the
Result.mappings() method.
results)
Class signature
Execution class sqlalchemy.engine.MappingResult ( sqlalchemy.engine._WithKeys ,
sqlalchemy.engine.FilterResult )
Configuration method sqlalchemy.engine.MappingResult. all ()
Estimating Cache Performance Return all scalar values in a list.

Using Logging
Equivalent to Result.all() except that
mapping values, rather than Row objects,
How much memory does the cache are returned.
use?
method sqlalchemy.engine.MappingResult. columns (*col_expressions)
dictionary to cache some (or all) Establish the columns that should be returned in each row.
method sqlalchemy.engine.MappingResult. fetchall ()

CURRENT RELEASE A synonym for the MappingResult.all() method.
Home
method sqlalchemy.engine.MappingResult. fetchmany (size=None)
Search terms:
search...
Fetch many objects.
Equivalent to Result.fetchmany() except that

mapping values, rather than Row
objects,
are returned.
latest listings.
method sqlalchemy.engine.MappingResult. fetchone ()
ADS VIA CARBON
SQLAlchemy Core Fetch one object.
SQL Expression Language Tutorial (1.x API) Equivalent to Result.fetchone() except that
objects,
are returned.
Schema Definition Language method sqlalchemy.engine.MappingResult. first ()

Fetch the first object or None if no object is present.
Equivalent to Result.first() except that
Engine Configuration are returned.

method sqlalchemy.engine.MappingResult. keys ()
Basic Usage
Using Transactions inherited from the sqlalchemy.engine._WithKeys.keys method of

sqlalchemy.engine._WithKeys
Return an iterable view which yields the string keys that would
be represented by
Arbitrary Transaction Nesting as each Row .
an Antipattern
The keys can represent the labels of the columns returned by a core
statement or
Migrating from the “nesting” the names of the orm classes returned by an orm
execution.
pattern
The view also can be tested for key containment using the Python
in operator,
Library Level (e.g. emulated) which will test both for the string keys represented
Autocommit alternate keys such as column objects.

Changed in version 1.4: a key view object is returned rather than a
plain list.

Autocommit Isolation Level method sqlalchemy.engine.MappingResult. one ()
Using Server Side Cursors (a.k.a. stream Return exactly one object or raise an exception.
results)
Equivalent to Result.one() except that
Connectionless Execution, Implicit are returned.
Execution
method sqlalchemy.engine.MappingResult. one_or_none ()
SQL Compilation Caching Return at most one object or raise an exception.
Configuration Equivalent to Result.one_or_none() except that

Estimating Cache Performance objects,
are returned.
Using Logging
method sqlalchemy.engine.MappingResult. partitions (size=None)
use? Iterate through sub-lists of elements of the size given.
Disabling or using an alternate Equivalent to Result.partitions() except that

dictionary to cache some (or all) objects,
are returned.
method sqlalchemy.engine.MappingResult. unique (strategy=None)

CURRENT RELEASE Apply unique filtering to the objects returned by this
MappingResult .
Home
See Result.unique() for usage details.
Search terms:
search...
class sqlalchemy.engine. CursorResult (context, cursor_strategy,
cursor_description)

A Result that is representing state from a DBAPI cursor.
latest listings.
ADS VIA CARBON

Changed in version 1.4: The CursorResult and
LegacyCursorResult
classes
replace the previous ResultProxy interface.
These classes are based on the
SQLAlchemy Core Result calling API
which provides an updated usage model and calling facade
for
SQLAlchemy Core and SQLAlchemy ORM.

Returns database rows via the Row class, which provides
additional API features and
Schema Definition Language behaviors on top of the raw data returned by
the DBAPI. Through the use of filters
such as the Result.scalars()
method, other kinds of objects may also be returned.
Engine and Connection Use Within the scope of the 1.x series of SQLAlchemy, Core SQL results in
version 1.4
return an instance of LegacyCursorResult
which takes the place of the CursorResult
class used for the 1.3 series
and previously. This object returns rows as LegacyRow
Working with Engines and Connections objects,
which maintains Python mapping (i.e. dictionary) like behaviors upon the
object itself. Going forward, the Row._mapping attribute should
be used for dictionary
Basic Usage behaviors.
Using Transactions
See also
Selecting - introductory material for accessing
CursorResult and Row objects.
an Antipattern
Migrating from the “nesting” Class signature

pattern
class sqlalchemy.engine.CursorResult ( sqlalchemy.engine.BaseCursorResult ,
Library Level (e.g. emulated) sqlalchemy.engine.Result )
Autocommit

method sqlalchemy.engine.CursorResult. all ()
Understanding the DBAPI-Level inherited from the Result.all() method of Result

Autocommit Isolation Level Return all rows in a list.
Closes the result set after invocation. Subsequent invocations
will return an
results) empty list.
Execution New in version 1.4.
SQL Compilation Caching Returns:
Configuration a list of Row objects.

Using Logging method sqlalchemy.engine.CursorResult. close ()

Close this CursorResult .
use?
This closes out the underlying DBAPI cursor corresponding to the
statement
Disabling or using an alternate execution, if one is still present. Note that the DBAPI
cursor is automatically
dictionary to cache some (or all) released when the CursorResult
exhausts all available rows. CursorResult.close()
is
generally an optional method except in the case when discarding a
CursorResult
SQLAlchemy 1.4 Documentation that still has additional rows pending
for fetch.
CURRENT RELEASE After this method is called, it is no longer valid to call upon
the fetch methods,
Home
| Download this Documentation which will raise a ResourceClosedError
on subsequent use.
Search terms:
search... See also

latest listings. method sqlalchemy.engine.CursorResult. columns (*col_expressions)
ADS VIA CARBON
inherited from the Result.columns() method of Result

SQLAlchemy Core
Establish the columns that should be returned in each row.
This method may be used to limit the columns returned as well
as to reorder them.
SQL Statements and Expressions API The given list of expressions are normally
a series of integers or string key names.

They may also be
appropriate ColumnElement objects which correspond to
a given
statement construct.
E.g.:
Engine Configuration statement = select(table.c.x, table.c.y, table.c.z)
result = connection.execute(statement)
Basic Usage for z, y in result.columns('z', 'y'):
# ...
Using Transactions
Nesting of Transaction Blocks Example of using the column objects from the statement itself:

an Antipattern
for z, y in result.columns(
statement.selected_columns.c.z,
Migrating from the “nesting” statement.selected_columns.c.y
pattern ):
# ...
Autocommit
New in version 1.4.
Parameters:
Autocommit Isolation Level *col_expressions – indicates columns to be returned. Elements
may be
integer row indexes, string column names, or appropriate
ColumnElement
objects corresponding to a select construct.
results)
Returns:
Execution
this Result object with the modifications
given.

method sqlalchemy.engine.CursorResult. fetchall ()
Configuration
inherited from the Result.fetchall() method of Result
Estimating Cache Performance A synonym for the Result.all() method.
Using Logging
method sqlalchemy.engine.CursorResult. fetchmany (size=None)
use?
inherited from the Result.fetchmany() method of Result
Disabling or using an alternate Fetch many rows.
When all rows are exhausted, returns an empty list.
This method is provided for backwards compatibility with
SQLAlchemy 1.x.x.
CURRENT RELEASE
Home
| Download this Documentation To fetch rows in groups, use the Result.partitions()
method.
Search terms:
search... Returns:
a list of Row objects.

career awaits. Check out the method sqlalchemy.engine.CursorResult. fetchone ()
latest listings.
ADS VIA CARBON inherited from the Result.fetchone() method of Result
SQLAlchemy Core Fetch one row.
SQL Expression Language Tutorial (1.x API) When all rows are exhausted, returns None.
SQL Statements and Expressions API This method is provided for backwards compatibility with
SQLAlchemy 1.x.x.
Schema Definition Language To fetch the first row of a result only, use the
Result.first() method. To iterate
Column and Data Types through all
rows, iterate the Result object directly.
Engine and Connection Use Returns:
Engine Configuration a Row object if no filters are applied, or None

if no rows remain.
Basic Usage method sqlalchemy.engine.CursorResult. first ()
Using Transactions
inherited from the Result.first() method of Result
Fetch the first row or None if no row is present.
Closes the result set and discards remaining rows.
an Antipattern
Note
pattern This method returns one row, e.g. tuple, by default.
To return
Library Level (e.g. emulated) exactly one single scalar value, that is, the first
column of the
first row, use the Result.scalar() method,
or combine
Autocommit
Result.scalars() and Result.first() .
Additionally, in contrast to the behavior of the legacy ORM
Query.first() method, no limit is applied to the
SQL query
Understanding the DBAPI-Level which was invoked to produce this Result ;
for a DBAPI driver
Autocommit Isolation Level that buffers results in memory before yielding
rows, all rows
will be sent to the Python process and all but
the first row will
be discarded.
results)
See also
Execution ORM Query Unified with Core Select

Returns:
Configuration
a Row object, or None
if no rows remain.
Using Logging
See also

Result.scalar()
use?
Disabling or using an alternate Result.one()
method sqlalchemy.engine.CursorResult. freeze ()

CURRENT RELEASE inherited from the Result.freeze() method of Result
Home
| Download this Documentation Return a callable object that will produce copies of this
Result when invoked.
Search terms:
search... The callable object returned is an instance of
FrozenResult .
This is used for result set caching. The method must be called
on the result when
it has been unconsumed, and calling the method
will consume the result fully.
career awaits. Check out the When the FrozenResult
is retrieved from a cache, it can be called any number of
latest listings. times where
it will produce a new Result object each time
against its stored set of
rows.
ADS VIA CARBON
SQLAlchemy Core See also
SQL Expression Language Tutorial (1.x API) Re-Executing Statements - example usage within the
set cache.

attribute sqlalchemy.engine.CursorResult. inserted_primary_key
Engine and Connection Use inherited from the BaseCursorResult.inserted_primary_key attribute of BaseCursorResult
Engine Configuration Return the primary key for the row just inserted.
Working with Engines and Connections The return value is a Row object representing
a named tuple of primary key values
Basic Usage
in the order in which the
primary key columns are configured in the source
Table .
Using Transactions
Changed in version 1.4.8: - the
value is
Nesting of Transaction Blocks now a named tuple via the Row class,
rather than a plain tuple.

an Antipattern This accessor only applies to single row insert()
constructs which did not
explicitly specify
Insert.returning() . Support for multirow inserts,
while not yet
available for most backends, would be accessed using
the
pattern
CursorResult.inserted_primary_key_rows accessor.

Note that primary key columns which specify a server_default clause, or
Autocommit otherwise do not qualify as “autoincrement” columns (see the notes at
Column ),
Setting Transaction Isolation Levels and were generated using the database-side
default, will appear in this list as None
unless the backend
supports “returning” and the insert statement executed with
the
“implicit returning” enabled.
results) attribute
sqlalchemy.engine.CursorResult. inserted_primary_key_rows
Execution
inherited from the BaseCursorResult.inserted_primary_key_rows attribute of
Translation of Schema Names BaseCursorResult

Return the value of CursorResult.inserted_primary_key
as a row contained within a
list; some dialects may support a
multiple row form as well.
Configuration
Note
Using Logging As indicated below, in current SQLAlchemy versions this
accessor is only useful beyond what’s already supplied by
CursorResult.inserted_primary_key when using the
psycopg2
use?
dialect. Future versions hope to
generalize this feature to
Disabling or using an alternate more dialects.
This accessor is added to support dialects that offer the feature
that is currently
SQLAlchemy 1.4 Documentation implemented by the Psycopg2 Fast Execution Helpers
feature, currently only the
psycopg2 dialect, which provides
for many rows to be INSERTed at once while
CURRENT RELEASE
still retaining the
behavior of being able to return server-generated primary key
Home
values.
Search terms:
search... When using the psycopg2 dialect, or other dialects that may support
“fast
executemany” style inserts in upcoming releases : When
invoking an
INSERT statement while passing a list of rows as the
second argument to
Your new development Connection.execute() , this accessor
will then provide a list of rows, where
career awaits. Check out the each row contains the primary
key value for each row that was INSERTed.
latest listings.
When using all other dialects / backends that don’t yet support
this
ADS VIA CARBON
feature: This accessor is only useful for single row INSERT
statements, and
SQLAlchemy Core returns the same information as that of the
CursorResult.inserted_primary_key within a
single-element list. When an
SQL Expression Language Tutorial (1.x API) INSERT statement is executed in
conjunction with a list of rows to be
SQL Statements and Expressions API INSERTed, the list will contain
one row per row inserted in the statement,
however it will contain
None for any server-generated values.
Future releases of SQLAlchemy will further generalize the
“fast execution helper”
feature of psycopg2 to suit other dialects,
thus allowing this accessor to be of
Engine and Connection Use more general use.
New in version 1.4.
Basic Usage
See also
Using Transactions

an Antipattern attribute sqlalchemy.engine.CursorResult. is_insert

inherited from the BaseCursorResult.is_insert attribute of BaseCursorResult
pattern
True if this CursorResult is the result
of a executing an expression language
Library Level (e.g. emulated) compiled
insert() construct.
Autocommit
When True, this implies that the
inserted_primary_key attribute is accessible,
Setting Transaction Isolation Levels assuming the statement did not include
a user defined “returning” construct.
method sqlalchemy.engine.CursorResult. keys ()
inherited from the sqlalchemy.engine._WithKeys.keys method of
Using Server Side Cursors (a.k.a. stream sqlalchemy.engine._WithKeys
results) Return an iterable view which yields the string keys that would
be represented by
each Row .
Execution The keys can represent the labels of the columns returned by a core
statement or
the names of the orm classes returned by an orm
execution.
SQL Compilation Caching The view also can be tested for key containment using the Python
in operator,
which will test both for the string keys represented
Configuration alternate keys such as column objects.
Using Logging Changed in version 1.4: a key view object is returned rather than a
plain list.

use?
method sqlalchemy.engine.CursorResult. last_inserted_params ()
dictionary to cache some (or all) inherited from the BaseCursorResult.last_inserted_params() method of BaseCursorResult
Return the collection of inserted parameters from this
execution.
CURRENT RELEASE expression construct
Home
method sqlalchemy.engine.CursorResult. last_updated_params ()
Search terms:
search...
inherited from the BaseCursorResult.last_updated_params() method of BaseCursorResult
Return the collection of updated parameters from this

execution.
latest listings.
or is not an update() construct.
ADS VIA CARBON
SQLAlchemy Core method sqlalchemy.engine.CursorResult. lastrow_has_defaults ()
SQL Expression Language Tutorial (1.x API) inherited from the BaseCursorResult.lastrow_has_defaults() method of BaseCursorResult
SQL Statements and Expressions API Return lastrow_has_defaults() from the underlying
ExecutionContext .

See ExecutionContext for details.
attribute sqlalchemy.engine.CursorResult. lastrowid
Engine Configuration inherited from the BaseCursorResult.lastrowid attribute of BaseCursorResult
Working with Engines and Connections Return the ‘lastrowid’ accessor on the DBAPI cursor.
Basic Usage This is a DBAPI specific method and is only functional

for those backends which
support it, for statements
where it is appropriate. It’s behavior is not
consistent
Using Transactions
across backends.
Usage of this method is normally unnecessary when
using insert() expression
Arbitrary Transaction Nesting as constructs; the
CursorResult.inserted_primary_key attribute provides a
tuple of
an Antipattern primary key values for a newly inserted row,
regardless of database backend.

method sqlalchemy.engine.CursorResult. mappings ()
pattern
Library Level (e.g. emulated) inherited from the Result.mappings() method of Result
Autocommit Apply a mappings filter to returned rows, returning an instance of
MappingResult .

When this filter is applied, fetching rows will return
RowMapping objects instead of
including DBAPI Autocommit Row objects.

Autocommit Isolation Level New in version 1.4.

results) Returns:
Connectionless Execution, Implicit a new MappingResult filtering object

referring to this Result object.
Execution
Translation of Schema Names method sqlalchemy.engine.CursorResult. merge (*others)

Merge this Result with other compatible result
objects.
Configuration
The object returned is an instance of MergedResult ,
which will be composed of
Estimating Cache Performance iterators from the given result
objects.
Using Logging
The new result will use the metadata from this result object.
The subsequent
How much memory does the cache result objects must be against an identical
set of result / cursor metadata,
use? otherwise the behavior is
undefined.

method sqlalchemy.engine.CursorResult. one ()
inherited from the Result.one() method of Result

SQLAlchemy 1.4 Documentation Return exactly one row or raise an exception.
CURRENT RELEASE
Raises NoResultFound if the result returns no
rows, or MultipleResultsFound if
Home
multiple rows
would be returned.
Search terms:
search...
Note
This method returns one row, e.g. tuple, by default.

To return
Your new development exactly one single scalar value, that is, the first
column of the
career awaits. Check out the first row, use the Result.scalar_one() method,
or combine
latest listings.
Result.scalars() and Result.one() .
ADS VIA CARBON
SQLAlchemy Core
New in version 1.4.

Returns:
The first Row .
Raises:
MultipleResultsFound , NoResultFound
Working with Engines and Connections See also
Basic Usage
Result.first()
Using Transactions
Result.scalar_one()
an Antipattern
Migrating from the “nesting” method sqlalchemy.engine.CursorResult. one_or_none ()

pattern
inherited from the Result.one_or_none() method of Result
Return at most one result or raise an exception.
Autocommit
Returns None if the result has no rows.
Raises MultipleResultsFound
if multiple rows
are returned.

New in version 1.4.

Returns:
results)
The first Row or None if no row is available.
Raises:
Execution
MultipleResultsFound

See also
Configuration
Result.first()
Using Logging Result.one()

use? method sqlalchemy.engine.CursorResult. partitions (size=None)
dictionary to cache some (or all) inherited from the Result.partitions() method of Result
Iterate through sub-lists of rows of the size given.
Each list will be of the size given, excluding the last list to
be yielded, which may
CURRENT RELEASE have a small number of rows. No empty
lists will be yielded.
Home
The result object is automatically closed when the iterator
is fully consumed.
Search terms:
search...
Note that the backend driver will usually buffer the entire result
ahead of time
unless the
Connection.execution_options.stream_results execution
option is used
indicating that the driver should not pre-buffer
results, if possible. Not all drivers
support this option and
the option is silently ignored for those who do not.
latest listings.
When using the ORM, the Result.partitions() method
is typically more effective
ADS VIA CARBON from a memory perspective when it is
combined with use of the
Result.yield_per() method,
which instructs the ORM loading internals to only
SQLAlchemy Core
build a certain
amount of ORM objects from a result at a time before yielding
them
SQL Expression Language Tutorial (1.x API) out.

New in version 1.4.

Parameters:
size – indicate the maximum number of rows to be present
in each list
Engine Configuration yielded. If None, makes use of the value set by
Result.yield_per() , if
present, otherwise uses the
Result.fetchmany() default which may be
backend
specific.
Basic Usage
Returns:
Using Transactions
iterator of lists
Arbitrary Transaction Nesting as See also
an Antipattern
Connection.execution_options.stream_results
Yield Per - in the ORM Querying Guide
pattern

Autocommit method sqlalchemy.engine.CursorResult. postfetch_cols ()

inherited from the BaseCursorResult.postfetch_cols() method of BaseCursorResult
Return postfetch_cols() from the underlying
ExecutionContext .
Autocommit Isolation Level See ExecutionContext for details.
Using Server Side Cursors (a.k.a. stream Raises InvalidRequestError if the executed
results) expression construct

method sqlalchemy.engine.CursorResult. prefetch_cols ()
Execution
Translation of Schema Names inherited from the BaseCursorResult.prefetch_cols() method of BaseCursorResult
Return prefetch_cols() from the underlying

ExecutionContext .
Configuration See ExecutionContext for details.
Estimating Cache Performance Raises InvalidRequestError if the executed

Using Logging expression construct

attribute sqlalchemy.engine.CursorResult. returned_defaults
use?
Disabling or using an alternate inherited from the BaseCursorResult.returned_defaults attribute of BaseCursorResult
Return the values of default columns that were fetched using
the
SQLAlchemy 1.4 Documentation ValuesBase.return_defaults() feature.
CURRENT RELEASE The value is an instance of Row , or None

if ValuesBase.return_defaults() was not
Home
| Download this Documentation used or if the
backend does not support RETURNING.
Search terms:
search...
Your new development See also

latest listings.
ValuesBase.return_defaults()
ADS VIA CARBON
SQLAlchemy Core
attribute sqlalchemy.engine.CursorResult. returned_defaults_rows
inherited from the BaseCursorResult.returned_defaults_rows attribute of BaseCursorResult
Return a list of rows each containing the values of default
columns that were
fetched using
the ValuesBase.return_defaults() feature.
The return value is a list of Row objects.
Engine Configuration New in version 1.4.
Basic Usage attribute sqlalchemy.engine.CursorResult. returns_rows

Using Transactions
inherited from the BaseCursorResult.returns_rows attribute of BaseCursorResult
True if this CursorResult returns zero or more rows.
an Antipattern
I.e. if it is legal to call the methods
CursorResult.fetchone() ,
CursorResult.fetchmany()
CursorResult.fetchall() .
Overall, the value of CursorResult.returns_rows should
always be synonymous with
pattern
whether or not the DBAPI cursor had a
.description attribute, indicating the
Library Level (e.g. emulated) presence of result columns,
noting that a cursor that returns zero rows still has a
Autocommit .description if a row-returning statement was emitted.
Setting Transaction Isolation Levels This attribute should be True for all results that are against
SELECT statements,
including DBAPI Autocommit as well as for DML statements INSERT/UPDATE/DELETE
that use RETURNING.
For INSERT/UPDATE/DELETE statements that were
not using RETURNING, the
value will usually be False, however
there are some dialect-specific exceptions to
Autocommit Isolation Level this, such as when
using the MSSQL / pyodbc dialect a SELECT is emitted inline in
order to retrieve an inserted primary key value.
results)
attribute sqlalchemy.engine.CursorResult. rowcount
Execution inherited from the BaseCursorResult.rowcount attribute of BaseCursorResult

Return the ‘rowcount’ for this result.
SQL Compilation Caching The ‘rowcount’ reports the number of rows matched
by the WHERE criterion of an
UPDATE or DELETE statement.
Configuration
Note
Using Logging
Notes regarding CursorResult.rowcount :
This attribute returns the number of rows matched,
use?
which is not necessarily the same as the number of
Disabling or using an alternate rows
that were actually modified - an UPDATE
statement, for example,
may have no net change
on a given row if the SET values
given are the same
SQLAlchemy 1.4 Documentation as those present in the row already.
Such a row
would be matched but not modified.
On backends
CURRENT RELEASE
that feature both styles, such as MySQL,
rowcount
Home
is configured by default to return the match
count
in all cases.
Search terms:
search...
CursorResult.rowcount
is only useful in conjunction
with an UPDATE or DELETE statement. Contrary to
Your new development what the Python
DBAPI says, it does not return the
career awaits. Check out the number of rows available from the results of a
latest listings. SELECT statement
as DBAPIs cannot support this
ADS VIA CARBON functionality when rows are
unbuffered.
SQLAlchemy Core CursorResult.rowcount

may not be fully
implemented by
all dialects. In particular, most
SQL Expression Language Tutorial (1.x API) DBAPIs do not support an
aggregate rowcount
SQL Statements and Expressions API result from an executemany call.
The
CursorResult.supports_sane_rowcount() and
Schema Definition Language CursorResult.supports_sane_multi_rowcount()
Column and Data Types methods

will report from the dialect if each usage
is known to be
supported.
Statements that use RETURNING may not return a
correct
rowcount.
Basic Usage See also
Using Transactions
Getting Affected Row Count from UPDATE, DELETE - in the SQLAlchemy 1.4 / 2.0
Nesting of Transaction Blocks Tutorial

an Antipattern
method sqlalchemy.engine.CursorResult. scalar ()
pattern inherited from the Result.scalar() method of Result
Fetch the first column of the first row, and close the result set.
Autocommit Returns None if there are no rows to fetch.
Setting Transaction Isolation Levels No validation is performed to test if additional rows remain.
After calling this method, the object is fully closed,
e.g. the CursorResult.close()
Understanding the DBAPI-Level method will have been called.
Returns:
a Python scalar value , or None if no rows remain.
results)

Execution method sqlalchemy.engine.CursorResult. scalar_one ()

inherited from the Result.scalar_one() method of Result
SQL Compilation Caching Return exactly one scalar result or raise an exception.
Configuration
Result.one() .
See also
Using Logging
How much memory does the cache Result.one()
use?
Result.scalars()

method sqlalchemy.engine.CursorResult. scalar_one_or_none ()

CURRENT RELEASE inherited from the Result.scalar_one_or_none() method of Result
Home
| Download this Documentation Return exactly one or no scalar result.
Search terms:
search... This is equivalent to calling Result.scalars() and then
Result.one_or_none() .
See also

latest listings.
Result.scalars()
ADS VIA CARBON
SQLAlchemy Core
method sqlalchemy.engine.CursorResult. scalars (index=0)
SQL Statements and Expressions API inherited from the Result.scalars() method of Result

Return a ScalarResult filtering object which
will return single elements rather than
Row objects.
E.g.:
Engine Configuration >>> result = conn.execute(text("select int_id from table"))
>>> result.scalars().all()

[1, 2, 3]
Basic Usage
Using Transactions
When results are fetched from the ScalarResult
filtering object, the single
Nesting of Transaction Blocks column-row that would be returned by the
Result is instead returned as the
column’s value.
an Antipattern
New in version 1.4.
pattern
Parameters:
index – integer or row key indicating the column to be fetched
from each
Autocommit
row, defaults to 0 indicating the first column.
Returns:
a new ScalarResult filtering object referring

to this Result object.
Using Server Side Cursors (a.k.a. stream method

sqlalchemy.engine.CursorResult. supports_sane_multi_rowcount ()
results)
Connectionless Execution, Implicit inherited from the BaseCursorResult.supports_sane_multi_rowcount() method of

Execution BaseCursorResult
Translation of Schema Names Return supports_sane_multi_rowcount from the dialect.
SQL Compilation Caching See CursorResult.rowcount for background.
Configuration
method sqlalchemy.engine.CursorResult. supports_sane_rowcount ()
Using Logging inherited from the BaseCursorResult.supports_sane_rowcount() method of
BaseCursorResult
use? Return supports_sane_rowcount from the dialect.
Disabling or using an alternate See CursorResult.rowcount for background.

method sqlalchemy.engine.CursorResult. unique (strategy=None)

CURRENT RELEASE inherited from the Result.unique() method of Result
Home
| Download this Documentation Apply unique filtering to the objects returned by this
Result .
Search terms:
search... When this filter is applied with no arguments, the rows or objects
returned will
filtered such that each row is returned uniquely. The
algorithm used to determine
this uniqueness is by default the Python
hashing identity of the whole tuple. In
Your new development some cases a specialized
per-entity hashing scheme may be used, such as when
career awaits. Check out the using the ORM, a
scheme is applied which works against the primary key identity
latest listings. of
returned objects.
ADS VIA CARBON
The unique filter is applied after all other filters, which means
if the columns
SQLAlchemy Core returned have been refined using a method such as the
Result.columns() or
Result.scalars()
method, the uniquing is applied to only the column or columns
SQL Expression Language Tutorial (1.x API) returned. This occurs regardless of the order in which these
methods have been
SQL Statements and Expressions API called upon the Result object.
Schema Definition Language The unique filter also changes the calculus used for methods like
Result.fetchmany() and Result.partitions() .
When using Result.unique() , these
methods will continue
to yield the number of rows or objects requested, after
Engine and Connection Use uniquing
has been applied. However, this necessarily impacts the buffering
behavior of the underlying cursor or datasource, such that multiple
underlying
calls to cursor.fetchmany() may be necessary in order
to accumulate enough
Working with Engines and Connections objects in order to provide a unique collection
of the requested size.
Basic Usage Parameters:
Using Transactions strategy – a callable that will be applied to rows or objects

being iterated,
which should return an object that represents the
unique value of the row. A
Python set() is used to store
these identities. If not passed, a default
Arbitrary Transaction Nesting as uniqueness strategy
is used which may have been assembled by the source
an Antipattern of this
Result object.

pattern method sqlalchemy.engine.CursorResult. yield_per (num)

Configure the row-fetching strategy to fetch num rows at a time.
Autocommit
This impacts the underlying behavior of the result when iterating over
the result
object, or otherwise making use of methods such as
including DBAPI Autocommit one row at a time. Data
buffered up to
the
rows remain if
Using Server Side Cursors (a.k.a. stream fewer remain.
results) The Result.yield_per() method is generally used in

Connectionless Execution, Implicit Connection.execution_options.stream_results
the database dialect in use to make
Execution
supports it.
Most DBAPIs do not use server side cursors by default, which means all
rows will
SQL Compilation Caching be fetched upfront from the database regardless of the
Result.yield_per()
Configuration setting. However,
the
SQLAlchemy-side processing of the raw data from the database, and
additionally
Estimating Cache Performance when used for ORM scenarios will batch the conversion of
database rows into
Using Logging ORM entity rows.

New in version 1.4.
use?

Parameters:
num – number of rows to fetch each time the buffer is refilled.

If set to a
SQLAlchemy 1.4 Documentation value below 1, fetches all rows for the next buffer.
CURRENT RELEASE
Home
| Download this Documentation See also
Search terms:
search... Yield Per - in the ORM Querying Guide
Result.partitions()

latest listings. class sqlalchemy.engine. LegacyCursorResult (context,
ADS VIA CARBON cursor_strategy, cursor_description)
SQLAlchemy Core Legacy version of CursorResult .
SQL Expression Language Tutorial (1.x API) This class includes connection “connection autoclose” behavior for use with
“connectionless” execution, as well as delivers rows using the
LegacyRow row
implementation.
Column and Data Types New in version 1.4.
Class signature
class sqlalchemy.engine.LegacyCursorResult ( sqlalchemy.engine.CursorResult )
Basic Usage
Using Transactions
method sqlalchemy.engine.LegacyCursorResult. close ()
Arbitrary Transaction Nesting as Close this LegacyCursorResult .
an Antipattern
This method has the same behavior as that of
sqlalchemy.engine.CursorResult() ,
Migrating from the “nesting” but it also may close
the underlying Connection for the case of “connectionless”
execution.
pattern

Deprecated since version 2.0: “connectionless” execution is deprecated
Autocommit
and will
be removed in version 2.0. Version 2.0 will feature the
Result
object
Setting Transaction Isolation Levels that will no longer affect the status
of the originating connection in any
case.

After this method is called, it is no longer valid to call upon
the fetch methods,
which will raise a ResourceClosedError
on subsequent use.
See also
results)
Connectionless Execution, Implicit Working with Engines and Connections
Execution
Connectionless Execution, Implicit Execution

class sqlalchemy.engine. Row (parent, processors, keymap, key_style, data)
Configuration
Represent a single result row.
Using Logging The Row object represents a row of a database result. It is
typically associated in the
1.x series of SQLAlchemy with the
CursorResult object, however is also used by the
ORM for
tuple-like results as of SQLAlchemy 1.4.
use?
The Row object seeks to act as much like a Python named
tuple as possible. For
mapping (i.e. dictionary) behavior on a row,
such as testing for containment of keys,
dictionary to cache some (or all) refer to the Row._mapping
attribute.
See also
Selecting Rows with Core or ORM - includes examples of selecting
rows from
CURRENT RELEASE
SELECT statements.
Home
LegacyRow - Compatibility interface introduced in SQLAlchemy
1.4.
Search terms:
search...
Changed in version 1.4: Renamed RowProxy to Row . Row is no longer a

“proxy”
object in that it contains the final form of data within it,
and now acts mostly
latest listings.
like a named tuple. Mapping-like functionality is
moved to the Row._mapping
attribute, but will remain available
in SQLAlchemy 1.x series via the LegacyRow
ADS VIA CARBON
class that is used
by LegacyCursorResult .
See RowProxy is no longer a “proxy”;
SQLAlchemy Core is now called Row and behaves like an enhanced named tuple for background
on this change.

Class signature
Column and Data Types class sqlalchemy.engine.Row ( sqlalchemy.engine.BaseRow , collections.abc.Sequence )
Engine Configuration method sqlalchemy.engine.Row. _asdict ()

Return a new dict which maps field names to their corresponding
values.
Basic Usage
This method is analogous to the Python named tuple ._asdict()
method, and
Using Transactions works by applying the dict() constructor to the
Row._mapping attribute.

New in version 1.4.
an Antipattern
See also
pattern Row._mapping

Autocommit
attribute sqlalchemy.engine.Row. _fields
including DBAPI Autocommit Return a tuple of string keys as represented by this
Row .
Understanding the DBAPI-Level The keys can represent the labels of the columns returned by a core
statement or
Autocommit Isolation Level the names of the orm classes returned by an orm
execution.
Using Server Side Cursors (a.k.a. stream This attribute is analogous to the Python named tuple ._fields
attribute.
results)
Connectionless Execution, Implicit New in version 1.4.
Execution
Translation of Schema Names See also
SQL Compilation Caching Row._mapping
Configuration

attribute sqlalchemy.engine.Row. _mapping
Using Logging
Return a RowMapping for this Row .
use? This object provides a consistent Python mapping (i.e. dictionary)
interface for the
data contained within the row. The Row
by itself behaves like a named tuple,
however in the 1.4 series of
SQLAlchemy, the LegacyRow class is still used by Core
dictionary to cache some (or all) which
continues to have mapping-like behaviors against the row object
itself.
See also
Row._fields
CURRENT RELEASE
Home
Search terms:
search... New in version 1.4.
Your new development attribute sqlalchemy.engine.Row. count

latest listings.
attribute sqlalchemy.engine.Row. index
ADS VIA CARBON
SQLAlchemy Core
method sqlalchemy.engine.Row. keys ()
Return the list of keys as strings represented by this
Row .
Schema Definition Language Deprecated since version 1.4: The Row.keys() method is considered legacy
as of the 1.x series of SQLAlchemy and will be removed in 2.0. Use the
namedtuple standard accessor Row._fields , or for full mapping behavior use
Engine and Connection Use row._mapping.keys() (Background on SQLAlchemy 2.0 at: Migrating to
SQLAlchemy 2.0)

The keys can represent the labels of the columns returned by a core
statement or
Basic Usage the names of the orm classes returned by an orm
execution.
Using Transactions
This method is analogous to the Python dictionary .keys() method,
except that it
Nesting of Transaction Blocks returns a list, not an iterator.
Arbitrary Transaction Nesting as See also

an Antipattern
Row._fields
pattern Row._mapping

Autocommit class sqlalchemy.engine. RowMapping (parent, processors, keymap,
Setting Transaction Isolation Levels key_style, data)

A Mapping that maps column names and objects to Row values.
The RowMapping is available from a Row via the
Row._mapping attribute, as well as from
the iterable interface
provided by the MappingResult object returned by the
Using Server Side Cursors (a.k.a. stream Result.mappings() method.
results)
RowMapping supplies Python mapping (i.e. dictionary) access to
the contents of the
Connectionless Execution, Implicit row. This includes support for testing of
containment of specific keys (string column
Execution
names or objects), as well
as iteration of keys, values, and items:

for row in result:
SQL Compilation Caching if 'a' in row._mapping:
print("Column 'a': %s" % row._mapping['a'])
Configuration
Estimating Cache Performance print("Column b: %s" % row._mapping[table.c.b])
Using Logging
How much memory does the cache New in version 1.4: The RowMapping object replaces the
mapping-like access
use? previously provided by a database result row,
which now seeks to behave
mostly like a named tuple.
Class signature
class sqlalchemy.engine.RowMapping ( sqlalchemy.engine.BaseRow ,
CURRENT RELEASE
collections.abc.Mapping )
Home
Search terms:
search...
method sqlalchemy.engine.RowMapping. items ()
Return a view of key/value tuples for the elements in the

underlying Row .
latest listings. method sqlalchemy.engine.RowMapping. keys ()
ADS VIA CARBON

Return a view of ‘keys’ for string column names represented
by the underlying Row .
SQLAlchemy Core
method sqlalchemy.engine.RowMapping. values ()

Return a view of values for the values represented in the
underlying Row .
Column and Data Types Previous:

Next:
Connection Pooling
Engine and Connection Use © Copyright 2007-2022, the SQLAlchemy authors and contributors.
Engine Configuration flambé! the dragon and The Alchemist image designs created and generously donated by
Rotem Yaari.
Basic Usage Created using Sphinx 5.0.2.
Using Transactions

an Antipattern

pattern

Autocommit



results)

Execution
Configuration

Using Logging

use?


CURRENT RELEASE
Home
Search terms:
search...

latest listings.
ADS VIA CARBON
SQLAlchemy Core
SQLAlchemy
Column and DataSponsors
Types
Website content copyright © by SQLAlchemy authors and contributors.
SQLAlchemy and its documentation are licensed under the MIT license.
Working with
SQLAlchemy Engines and
is a trademark Connections
of Michael Bayer. mike(&)zzzcomputing.com
All rights reserved.
Website generation by
zeekofile, with
huge thanks to the Blogofile
project.
Basic Usage
Using Transactions

an Antipattern

pattern

Autocommit



results)

Execution
Configuration

Using Logging

use?


Working With Engines and Connections - SQLAlchemy 1.4 Documentation

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Working With Engines and Connections - SQLAlchemy 1.4 Documentation

Uploaded by

Copyright:

Available Formats

30/6/22, 17:10 Working with Engines and Connections — SQLAlchemy 1.

SQLAlchemy 1.4 Documentation

Column and Data Types

Engine and Connection Use

Understanding the DBAPI-Level

Connectionless Execution, Implicit

Execution result = connection.execute(text("select username from use

Schema Definition Language

Nesting of Transaction Blocks The Connection object provides a Connection.begin()

Migrating from the “nesting” with engine.connect() as connection:

pattern with connection.begin():

Library Level (e.g. emulated) connection.execute(table1.insert(), {"col1": 7, "col2"

Setting Transaction Isolation Levels

Understanding the DBAPI-Level

with engine.begin() as connection:

Using Server Side Cursors (a.k.a. stream r1 = connection.execute(table1.select())

results) connection.execute(table1.insert(), {"col1": 7, "col2": "t

Connectionless Execution, Implicit

Using Logging which invokes these methods automatically, is recommended

How much memory does the cache Nesting of Transaction Blocks

ADS VIA CARBON with connection.begin(): # open a transaction

SQL Expression Language Tutorial (1.x API)

Engine and Connection Use # open a Connection and call method_a

Engine Configuration with engine.connect() as conn:

Connectionless Execution, Implicit def method_a(connection):

SQL Compilation Caching def method_b(connection):

Configuration connection.execute(text("insert into mytable values ('bat'

with engine.begin() as conn:

How much memory does the cache method_a(conn)

Disabling or using an alternate

Engine and Connection Use

Basic Usage if not connection.in_transaction():

Using Transactions yield connection

Nesting of Transaction Blocks else:

Library Level (e.g. emulated) with transaction(connection): # open a transaction

Understanding the DBAPI-Level

Autocommit Isolation Level connection.execute(text("insert into mytable values ('

Connectionless Execution, Implicit

Translation of Schema Names

Estimating Cache Performance

How much memory does the cache def connectivity(engine):

Disabling or using an alternate @contextlib.contextmanager

dictionary to cache some (or all) def connect():

SQLAlchemy 1.4 Documentation

CURRENT RELEASE connection = engine.connect()

Your new development

ADS VIA CARBON Using the above would look like:

SQL Statements and Expressions API

Schema Definition Language method_b(connectivity)

Engine Configuration with connectivity() as connection:

connection.execute(text("insert into mytable values ('

Nesting of Transaction Blocks method_a(connectivity(engine))

Arbitrary Transaction Nesting as

Migrating from the “nesting”

including DBAPI Autocommit

Understanding the DBAPI-Level

SQL Compilation Caching

Given this requirement, SQLAlchemy implements its own “autocommit” feature

Schema Definition Language conn = engine.connect()

conn.execute(text("INSERT INTO users VALUES (1, 'john')")) #

Engine and Connection Use

Library Level (e.g. emulated)