database-specific object implementations including
ExecutionContext, Compiled, DefaultGenerator, and TypeEngine.
- All Dialects implement the following attributes:
+ .. note:: Third party dialects should not subclass :class:`.Dialect`
+ directly. Instead, subclass :class:`.default.DefaultDialect` or
+ descendant class.
- name
+ All dialects include the following attributes. There are many other
+ attributes that may be supported as well:
+
+ ``name``
identifying name for the dialect from a DBAPI-neutral point of view
(i.e. 'sqlite')
- driver
+ ``driver``
identifying name for the dialect's DBAPI
- positional
+ ``positional``
True if the paramstyle for this Dialect is positional.
- paramstyle
+ ``paramstyle``
the paramstyle to be used (some DB-APIs support multiple
paramstyles).
- convert_unicode
- True if Unicode conversion should be applied to all ``str``
- types.
-
- encoding
+ ``encoding``
type of encoding to use for unicode, usually defaults to
'utf-8'.
- statement_compiler
+ ``statement_compiler``
a :class:`.Compiled` class used to compile SQL statements
- ddl_compiler
+ ``ddl_compiler``
a :class:`.Compiled` class used to compile DDL statements
- server_version_info
+ ``server_version_info``
a tuple containing a version number for the DB backend in use.
This value is only available for supporting dialects, and is
typically populated during the initial connection to the database.
- default_schema_name
+ ``default_schema_name``
the name of the default schema. This value is only available for
supporting dialects, and is typically populated during the
initial connection to the database.
- execution_ctx_cls
+ ``execution_ctx_cls``
a :class:`.ExecutionContext` class used to handle statement execution
- execute_sequence_format
+ ``execute_sequence_format``
either the 'tuple' or 'list' type, depending on what cursor.execute()
accepts for the second argument (they vary).
- preparer
+ ``preparer``
a :class:`~sqlalchemy.sql.compiler.IdentifierPreparer` class used to
quote identifiers.
- supports_alter
- ``True`` if the database supports ``ALTER TABLE``.
+ ``supports_alter``
+ ``True`` if the database supports ``ALTER TABLE`` - used only for
+ generating foreign key constraints in certain circumstances
- max_identifier_length
+ ``max_identifier_length``
The maximum length of identifier names.
- supports_unicode_statements
- Indicate whether the DB-API can receive SQL statements as Python
- unicode strings
-
- supports_unicode_binds
- Indicate whether the DB-API can receive string bind parameters
- as Python unicode strings
-
- supports_sane_rowcount
+ ``supports_sane_rowcount``
Indicate whether the dialect properly implements rowcount for
``UPDATE`` and ``DELETE`` statements.
- supports_sane_multi_rowcount
+ ``supports_sane_multi_rowcount``
Indicate whether the dialect properly implements rowcount for
``UPDATE`` and ``DELETE`` statements when executed via
executemany.
- preexecute_autoincrement_sequences
+ ``preexecute_autoincrement_sequences``
True if 'implicit' primary key functions must be executed separately
in order to get their value. This is currently oriented towards
PostgreSQL.
- implicit_returning
+ ``implicit_returning``
use RETURNING or equivalent during INSERT execution in order to load
newly generated primary keys and other column defaults in one execution,
which are then available via inserted_primary_key.
the "implicit" functionality is not used and inserted_primary_key
will not be available.
- dbapi_type_map
- A mapping of DB-API type objects present in this Dialect's
- DB-API implementation mapped to TypeEngine implementations used
- by the dialect.
-
- This is used to apply types to result sets based on the DB-API
- types present in cursor.description; it only takes effect for
- result sets against textual statements where no explicit
- typemap was present.
-
- colspecs
+ ``colspecs``
A dictionary of TypeEngine classes from sqlalchemy.types mapped
to subclasses that are specific to the dialect class. This
dictionary is class-level only and is not accessed from the
dialect instance itself.
- supports_default_values
+ ``supports_default_values``
Indicates if the construct ``INSERT INTO tablename DEFAULT
VALUES`` is supported
- supports_sequences
+ ``supports_sequences``
Indicates if the dialect supports CREATE SEQUENCE or similar.
- sequences_optional
+ ``sequences_optional``
If True, indicates if the "optional" flag on the Sequence() construct
should signal to not generate a CREATE SEQUENCE. Applies only to
dialects that support sequences. Currently used only to allow PostgreSQL
SERIAL to be used on a column that specifies Sequence() for usage on
other backends.
- supports_native_enum
+ ``supports_native_enum``
Indicates if the dialect supports a native ENUM construct.
This will prevent types.Enum from generating a CHECK
constraint when that type is used.
- supports_native_boolean
+ ``supports_native_boolean``
Indicates if the dialect supports a native boolean construct.
This will prevent types.Boolean from generating a CHECK
constraint when that type is used.
- dbapi_exception_translation_map
+ ``dbapi_exception_translation_map``
A dictionary of names that will contain as values the names of
pep-249 exceptions ("IntegrityError", "OperationalError", etc)
keyed to alternate class names, to support the case where a
def create_connect_args(self, url):
"""Build DB-API compatible connection arguments.
- Given a :class:`~sqlalchemy.engine.url.URL` object, returns a tuple
- consisting of a `*args`/`**kwargs` suitable to send directly
- to the dbapi's connect function.
+ Given a :class:`.URL` object, returns a tuple
+ consisting of a ``(*args, **kwargs)`` suitable to send directly
+ to the dbapi's connect function. The arguments are sent to the
+ :meth:`.Dialect.connect` method which then runs the DBAPI-level
+ ``connect()`` function.
+
+ The method typically makes use of the
+ :meth:`.URL.translate_connect_args`
+ method in order to generate a dictionary of options.
+
+ The default implementation is::
+
+ def create_connect_args(self, url):
+ opts = url.translate_connect_args()
+ opts.update(url.query)
+ return [[], opts]
+
+ :param url: a :class:`.URL` object
+
+ :return: a tuple of ``(*args, **kwargs)`` which will be passed to the
+ :meth:`.Dialect.connect` method.
+
+ .. seealso::
+
+ :meth:`.URL.translate_connect_args`
"""
raise NotImplementedError()
- def connect(self):
+ def connect(self, *cargs, **cparams):
+ r"""Establish a connection using this dialect's DBAPI.
+
+ The default implementation of this method is::
+
+ def connect(self, *cargs, **cparams):
+ return self.dbapi.connect(*cargs, **cparams)
+
+ The ``*cargs, **cparams`` parameters are generated directly
+ from this dialect's :meth:`.Dialect.create_connect_args` method.
+
+ This method may be used for dialects that need to perform programmatic
+ per-connection steps when a new connection is procured from the
+ DBAPI.
+
+
+ :param \*cargs: positional parameters returned from the
+ :meth:`.Dialect.create_connect_args` method
+
+ :param \*\*cparams: keyword parameters returned from the
+ :meth:`.Dialect.create_connect_args` method.
+
+ :return: a DBAPI connection, typically from the :pep:`249` module
+ level ``.connect()`` function.
+
+ .. seealso::
+
+ :meth:`.Dialect.create_connect_args`
+
+ :meth:`.Dialect.on_connect`
+
+ """
+
+ def on_connect(self):
"""return a callable which sets up a newly created DBAPI connection.
- The callable accepts a single argument "conn" which is the
- DBAPI connection itself. It has no return value.
+ The callable should accept a single argument "conn" which is the
+ DBAPI connection itself. The inner callable has no
+ return value.
+
+ E.g.::
+
+ class MyDialect(default.DefaultDialect):
+ # ...
+
+ def on_connect(self):
+ def do_on_connect(connection):
+ connection.execute("SET SPECIAL FLAGS etc")
+
+ return do_on_connect
This is used to set dialect-wide per-connection options such as
- isolation modes, unicode modes, etc.
+ isolation modes, Unicode modes, etc.
- If a callable is returned, it will be assembled into a pool listener
- that receives the direct DBAPI connection, with all wrappers removed.
+ The "do_on_connect" callable is invoked by using the
+ :meth:`.PoolEvents.first_connect` and :meth:`.PoolEvents.connect` event
+ hooks, then unwrapping the DBAPI connection and passing it into the
+ callable. The reason it is invoked for both events is so that any
+ dialect-level initialization that occurs upon first connection, which
+ also makes use of the :meth:`.PoolEvents.first_connect` method, will
+ proceed after this hook has been called. This currently means the
+ hook is in fact called twice for the very first connection in which a
+ dialect creates; and once per connection afterwards.
+
+ If None is returned, no event listener is generated.
+
+ :return: a callable that accepts a single DBAPI connection as an
+ argument, or None.
+
+ .. seealso::
- If None is returned, no listener will be generated.
+ :meth:`.Dialect.connect` - allows the DBAPI ``connect()`` sequence
+ itself to be controlled.
"""
return None
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
