case_sensitive=True – if False, result column names
will match in a case-insensitive fashion, that is,
row['SomeColumn'].
connect_args – a dictionary of options which will be
passed directly to the DBAPI’s connect() method as
additional keyword arguments. See the example
at Custom DBAPI connect() arguments.
convert_unicode=False –
if set to True, causes
all String datatypes to act as though the
String.convert_unicode flag has been set to True,
regardless of a setting of False on an individual String
type. This has the effect of causing all String -based
columns to accommodate Python Unicode objects directly as though the
datatype were the Unicode type.
Deprecated since version 1.3: The create_engine.convert_unicode parameter
is deprecated and will be removed in a future release.
All modern DBAPIs now support Python Unicode directly and this
parameter is unnecessary.
creator – a callable which returns a DBAPI connection.
This creation function will be passed to the underlying
connection pool and will be used to create all new database
connections. Usage of this function causes connection
parameters specified in the URL argument to be bypassed.
echo=False –
if True, the Engine will log all statements
as well as a repr() of their parameter lists to the default log
handler, which defaults to sys.stdout for output. If set to the
string "debug", result rows will be printed to the standard output
as well. The echo attribute of Engine can be modified at any
time to turn logging on and off; direct control of logging is also
available using the standard Python logging module.
echo_pool=False –
if True, the connection pool will log
informational output such as when connections are invalidated
as well as when connections are recycled to the default log handler,
which defaults to sys.stdout for output. If set to the string
"debug", the logging will include pool checkouts and checkins.
Direct control of logging is also available using the standard Python
logging module.
empty_in_strategy –
The SQL compilation strategy to use when
rendering an IN or NOT IN expression for ColumnOperators.in_()
where the right-hand side
is an empty set. This is a string value that may be one of
static, dynamic, or dynamic_warn. The static
strategy is the default, and an IN comparison to an empty set
will generate a simple false expression “1 != 1”. The dynamic
strategy behaves like that of SQLAlchemy 1.1 and earlier, emitting
a false expression of the form “expr != expr”, which has the effect
of evaluting to NULL in the case of a null expression.
dynamic_warn is the same as dynamic, however also emits a
warning when an empty set is encountered; this because the “dynamic”
comparison is typically poorly performing on most databases.
New in version 1.2: Added the empty_in_strategy setting and
additionally defaulted the behavior for empty-set IN comparisons
to a static boolean expression.
encoding –
Defaults to utf-8. This is the string
encoding used by SQLAlchemy for string encode/decode
operations which occur within SQLAlchemy, outside of
the DBAPI. Most modern DBAPIs feature some degree of
direct support for Python unicode objects,
what you see in Python 2 as a string of the form
u'some string'. For those scenarios where the
DBAPI is detected as not supporting a Python unicode
object, this encoding is used to determine the
source/destination encoding. It is not used
for those cases where the DBAPI handles unicode
directly.
To properly configure a system to accommodate Python
unicode objects, the DBAPI should be
configured to handle unicode to the greatest
degree as is appropriate - see
the notes on unicode pertaining to the specific
target database in use at Dialects.
Areas where string encoding may need to be accommodated
outside of the DBAPI include zero or more of:
the values passed to bound parameters, corresponding to
the Unicode type or the String type
when convert_unicode is True;
the values returned in result set columns corresponding
to the Unicode type or the String
type when convert_unicode is True;
the string SQL statement passed to the DBAPI’s
cursor.execute() method;
the string names of the keys in the bound parameter
dictionary passed to the DBAPI’s cursor.execute()
as well as cursor.setinputsizes() methods;
the string column names retrieved from the DBAPI’s
cursor.description attribute.
When using Python 3, the DBAPI is required to support
all of the above values as Python unicode objects,
which in Python 3 are just known as str. In Python 2,
the DBAPI does not specify unicode behavior at all,
so SQLAlchemy must make decisions for each of the above
values on a per-DBAPI basis - implementations are
completely inconsistent in their behavior.
execution_options – Dictionary execution options which will
be applied to all connections. See
execution_options()
implicit_returning=True – When True, a RETURNING-
compatible construct, if available, will be used to
fetch newly generated primary key values when a single row
INSERT statement is emitted with no existing returning()
clause. This applies to those backends which support RETURNING
or a compatible construct, including PostgreSQL, Firebird, Oracle,
Microsoft SQL Server. Set this to False to disable
the automatic usage of RETURNING.
isolation_level –
this string parameter is interpreted by various
dialects in order to affect the transaction isolation level of the
database connection. The parameter essentially accepts some subset of
these string arguments: "SERIALIZABLE", "REPEATABLE_READ",
"READ_COMMITTED", "READ_UNCOMMITTED" and "AUTOCOMMIT".
Behavior here varies per backend, and
individual dialects should be consulted directly.
Note that the isolation level can also be set on a
per-Connection basis as well, using the
Connection.execution_options.isolation_level
feature.
label_length=None – optional integer value which limits
the size of dynamically generated column labels to that many
characters. If less than 6, labels are generated as
“_(counter)”. If None, the value of
dialect.max_identifier_length is used instead.
listeners – A list of one or more
PoolListener objects which will
receive connection pool events.
logging_name – String identifier which will be used within
the “name” field of logging records generated within the
“sqlalchemy.engine” logger. Defaults to a hexstring of the
object’s id.
max_overflow=10 – the number of connections to allow in
connection pool “overflow”, that is connections that can be
opened above and beyond the pool_size setting, which defaults
to five. this is only used with QueuePool.
module=None – reference to a Python module object (the module
itself, not its string name). Specifies an alternate DBAPI module to
be used by the engine’s dialect. Each sub-dialect references a
specific DBAPI which will be imported before first connect. This
parameter causes the import to be bypassed, and the given module to
be used instead. Can be used for testing of DBAPIs as well as to
inject “mock” DBAPI implementations into the Engine.
paramstyle=None – The paramstyle
to use when rendering bound parameters. This style defaults to the
one recommended by the DBAPI itself, which is retrieved from the
.paramstyle attribute of the DBAPI. However, most DBAPIs accept
more than one paramstyle, and in particular it may be desirable
to change a “named” paramstyle into a “positional” one, or vice versa.
When this attribute is passed, it should be one of the values
"qmark", "numeric", "named", "format" or
"pyformat", and should correspond to a parameter style known
to be supported by the DBAPI in use.
pool=None – an already-constructed instance of
Pool, such as a
QueuePool instance. If non-None, this
pool will be used directly as the underlying connection pool
for the engine, bypassing whatever connection parameters are
present in the URL argument. For information on constructing
connection pools manually, see Connection Pooling.
poolclass=None – a Pool
subclass, which will be used to create a connection pool
instance using the connection parameters given in the URL. Note
this differs from pool in that you don’t actually
instantiate the pool in this case, you just indicate what type
of pool to be used.
pool_logging_name – String identifier which will be used within
the “name” field of logging records generated within the
“sqlalchemy.pool” logger. Defaults to a hexstring of the object’s
id.
pool_pre_ping –
boolean, if True will enable the connection pool
“pre-ping” feature that tests connections for liveness upon
each checkout.
pool_size=5 – the number of connections to keep open
inside the connection pool. This used with
QueuePool as
well as SingletonThreadPool. With
QueuePool, a pool_size setting
of 0 indicates no limit; to disable pooling, set poolclass to
NullPool instead.
pool_recycle=-1 –
this setting causes the pool to recycle
connections after the given number of seconds has passed. It
defaults to -1, or no timeout. For example, setting to 3600
means connections will be recycled after one hour. Note that
MySQL in particular will disconnect automatically if no
activity is detected on a connection for eight hours (although
this is configurable with the MySQLDB connection itself and the
server configuration as well).
pool_reset_on_return='rollback' –
set the
Pool.reset_on_return parameter of the underlying
Pool object, which can be set to the values
"rollback", "commit", or None.
pool_timeout=30 – number of seconds to wait before giving
up on getting a connection from the pool. This is only used
with QueuePool.
pool_use_lifo=False –
use LIFO (last-in-first-out) when retrieving
connections from QueuePool instead of FIFO
(first-in-first-out). Using LIFO, a server-side timeout scheme can
reduce the number of connections used during non- peak periods of
use. When planning for server-side timeouts, ensure that a recycle or
pre-ping strategy is in use to gracefully handle stale connections.
plugins –
string list of plugin names to load. See
CreateEnginePlugin for background.
strategy='plain' –
selects alternate engine implementations.
Currently available are:
executor=None – a function taking arguments
(sql, *multiparams, **params), to which the mock strategy will
dispatch all statement execution. Used only by strategy='mock'.