Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# engine/create.py
2# Copyright (C) 2005-2025 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
8from __future__ import annotations
10import inspect
11import typing
12from typing import Any
13from typing import Callable
14from typing import cast
15from typing import Dict
16from typing import List
17from typing import Optional
18from typing import overload
19from typing import Type
20from typing import Union
22from . import base
23from . import url as _url
24from .interfaces import DBAPIConnection
25from .mock import create_mock_engine
26from .. import event
27from .. import exc
28from .. import util
29from ..pool import _AdhocProxiedConnection
30from ..pool import ConnectionPoolEntry
31from ..sql import compiler
32from ..util import immutabledict
34if typing.TYPE_CHECKING:
35 from .base import Engine
36 from .interfaces import _ExecuteOptions
37 from .interfaces import _ParamStyle
38 from .interfaces import IsolationLevel
39 from .url import URL
40 from ..log import _EchoFlagType
41 from ..pool import _CreatorFnType
42 from ..pool import _CreatorWRecFnType
43 from ..pool import _ResetStyleArgType
44 from ..pool import Pool
45 from ..util.typing import Literal
48@overload
49def create_engine(
50 url: Union[str, URL],
51 *,
52 connect_args: Dict[Any, Any] = ...,
53 convert_unicode: bool = ...,
54 creator: Union[_CreatorFnType, _CreatorWRecFnType] = ...,
55 echo: _EchoFlagType = ...,
56 echo_pool: _EchoFlagType = ...,
57 enable_from_linting: bool = ...,
58 execution_options: _ExecuteOptions = ...,
59 future: Literal[True],
60 hide_parameters: bool = ...,
61 implicit_returning: Literal[True] = ...,
62 insertmanyvalues_page_size: int = ...,
63 isolation_level: IsolationLevel = ...,
64 json_deserializer: Callable[..., Any] = ...,
65 json_serializer: Callable[..., Any] = ...,
66 label_length: Optional[int] = ...,
67 logging_name: str = ...,
68 max_identifier_length: Optional[int] = ...,
69 max_overflow: int = ...,
70 module: Optional[Any] = ...,
71 paramstyle: Optional[_ParamStyle] = ...,
72 pool: Optional[Pool] = ...,
73 poolclass: Optional[Type[Pool]] = ...,
74 pool_logging_name: str = ...,
75 pool_pre_ping: bool = ...,
76 pool_size: int = ...,
77 pool_recycle: int = ...,
78 pool_reset_on_return: Optional[_ResetStyleArgType] = ...,
79 pool_timeout: float = ...,
80 pool_use_lifo: bool = ...,
81 plugins: List[str] = ...,
82 query_cache_size: int = ...,
83 use_insertmanyvalues: bool = ...,
84 **kwargs: Any,
85) -> Engine: ...
88@overload
89def create_engine(url: Union[str, URL], **kwargs: Any) -> Engine: ...
92@util.deprecated_params(
93 strategy=(
94 "1.4",
95 "The :paramref:`_sa.create_engine.strategy` keyword is deprecated, "
96 "and the only argument accepted is 'mock'; please use "
97 ":func:`.create_mock_engine` going forward. For general "
98 "customization of create_engine which may have been accomplished "
99 "using strategies, see :class:`.CreateEnginePlugin`.",
100 ),
101 empty_in_strategy=(
102 "1.4",
103 "The :paramref:`_sa.create_engine.empty_in_strategy` keyword is "
104 "deprecated, and no longer has any effect. All IN expressions "
105 "are now rendered using "
106 'the "expanding parameter" strategy which renders a set of bound'
107 'expressions, or an "empty set" SELECT, at statement execution'
108 "time.",
109 ),
110 implicit_returning=(
111 "2.0",
112 "The :paramref:`_sa.create_engine.implicit_returning` parameter "
113 "is deprecated and will be removed in a future release. ",
114 ),
115)
116def create_engine(url: Union[str, _url.URL], **kwargs: Any) -> Engine:
117 """Create a new :class:`_engine.Engine` instance.
119 The standard calling form is to send the :ref:`URL <database_urls>` as the
120 first positional argument, usually a string
121 that indicates database dialect and connection arguments::
123 engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
125 .. note::
127 Please review :ref:`database_urls` for general guidelines in composing
128 URL strings. In particular, special characters, such as those often
129 part of passwords, must be URL encoded to be properly parsed.
131 Additional keyword arguments may then follow it which
132 establish various options on the resulting :class:`_engine.Engine`
133 and its underlying :class:`.Dialect` and :class:`_pool.Pool`
134 constructs::
136 engine = create_engine(
137 "mysql+mysqldb://scott:tiger@hostname/dbname",
138 pool_recycle=3600,
139 echo=True,
140 )
142 The string form of the URL is
143 ``dialect[+driver]://user:password@host/dbname[?key=value..]``, where
144 ``dialect`` is a database name such as ``mysql``, ``oracle``,
145 ``postgresql``, etc., and ``driver`` the name of a DBAPI, such as
146 ``psycopg2``, ``pyodbc``, ``cx_oracle``, etc. Alternatively,
147 the URL can be an instance of :class:`~sqlalchemy.engine.url.URL`.
149 ``**kwargs`` takes a wide variety of options which are routed
150 towards their appropriate components. Arguments may be specific to
151 the :class:`_engine.Engine`, the underlying :class:`.Dialect`,
152 as well as the
153 :class:`_pool.Pool`. Specific dialects also accept keyword arguments that
154 are unique to that dialect. Here, we describe the parameters
155 that are common to most :func:`_sa.create_engine()` usage.
157 Once established, the newly resulting :class:`_engine.Engine` will
158 request a connection from the underlying :class:`_pool.Pool` once
159 :meth:`_engine.Engine.connect` is called, or a method which depends on it
160 such as :meth:`_engine.Engine.execute` is invoked. The
161 :class:`_pool.Pool` in turn
162 will establish the first actual DBAPI connection when this request
163 is received. The :func:`_sa.create_engine` call itself does **not**
164 establish any actual DBAPI connections directly.
166 .. seealso::
168 :doc:`/core/engines`
170 :doc:`/dialects/index`
172 :ref:`connections_toplevel`
174 :param connect_args: a dictionary of options which will be
175 passed directly to the DBAPI's ``connect()`` method as
176 additional keyword arguments. See the example
177 at :ref:`custom_dbapi_args`.
179 :param creator: a callable which returns a DBAPI connection.
180 This creation function will be passed to the underlying
181 connection pool and will be used to create all new database
182 connections. Usage of this function causes connection
183 parameters specified in the URL argument to be bypassed.
185 This hook is not as flexible as the newer
186 :meth:`_events.DialectEvents.do_connect` hook which allows complete
187 control over how a connection is made to the database, given the full
188 set of URL arguments and state beforehand.
190 .. seealso::
192 :meth:`_events.DialectEvents.do_connect` - event hook that allows
193 full control over DBAPI connection mechanics.
195 :ref:`custom_dbapi_args`
197 :param echo=False: if True, the Engine will log all statements
198 as well as a ``repr()`` of their parameter lists to the default log
199 handler, which defaults to ``sys.stdout`` for output. If set to the
200 string ``"debug"``, result rows will be printed to the standard output
201 as well. The ``echo`` attribute of ``Engine`` can be modified at any
202 time to turn logging on and off; direct control of logging is also
203 available using the standard Python ``logging`` module.
205 .. seealso::
207 :ref:`dbengine_logging` - further detail on how to configure
208 logging.
211 :param echo_pool=False: if True, the connection pool will log
212 informational output such as when connections are invalidated
213 as well as when connections are recycled to the default log handler,
214 which defaults to ``sys.stdout`` for output. If set to the string
215 ``"debug"``, the logging will include pool checkouts and checkins.
216 Direct control of logging is also available using the standard Python
217 ``logging`` module.
219 .. seealso::
221 :ref:`dbengine_logging` - further detail on how to configure
222 logging.
225 :param empty_in_strategy: No longer used; SQLAlchemy now uses
226 "empty set" behavior for IN in all cases.
228 :param enable_from_linting: defaults to True. Will emit a warning
229 if a given SELECT statement is found to have un-linked FROM elements
230 which would cause a cartesian product.
232 .. versionadded:: 1.4
234 .. seealso::
236 :ref:`change_4737`
238 :param execution_options: Dictionary execution options which will
239 be applied to all connections. See
240 :meth:`~sqlalchemy.engine.Connection.execution_options`
242 :param future: Use the 2.0 style :class:`_engine.Engine` and
243 :class:`_engine.Connection` API.
245 As of SQLAlchemy 2.0, this parameter is present for backwards
246 compatibility only and must remain at its default value of ``True``.
248 The :paramref:`_sa.create_engine.future` parameter will be
249 deprecated in a subsequent 2.x release and eventually removed.
251 .. versionadded:: 1.4
253 .. versionchanged:: 2.0 All :class:`_engine.Engine` objects are
254 "future" style engines and there is no longer a ``future=False``
255 mode of operation.
257 .. seealso::
259 :ref:`migration_20_toplevel`
261 :param hide_parameters: Boolean, when set to True, SQL statement parameters
262 will not be displayed in INFO logging nor will they be formatted into
263 the string representation of :class:`.StatementError` objects.
265 .. seealso::
267 :ref:`dbengine_logging` - further detail on how to configure
268 logging.
270 :param implicit_returning=True: Legacy parameter that may only be set
271 to True. In SQLAlchemy 2.0, this parameter does nothing. In order to
272 disable "implicit returning" for statements invoked by the ORM,
273 configure this on a per-table basis using the
274 :paramref:`.Table.implicit_returning` parameter.
277 :param insertmanyvalues_page_size: number of rows to format into an
278 INSERT statement when the statement uses "insertmanyvalues" mode, which is
279 a paged form of bulk insert that is used for many backends when using
280 :term:`executemany` execution typically in conjunction with RETURNING.
281 Defaults to 1000, but may also be subject to dialect-specific limiting
282 factors which may override this value on a per-statement basis.
284 .. versionadded:: 2.0
286 .. seealso::
288 :ref:`engine_insertmanyvalues`
290 :ref:`engine_insertmanyvalues_page_size`
292 :paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size`
294 :param isolation_level: optional string name of an isolation level
295 which will be set on all new connections unconditionally.
296 Isolation levels are typically some subset of the string names
297 ``"SERIALIZABLE"``, ``"REPEATABLE READ"``,
298 ``"READ COMMITTED"``, ``"READ UNCOMMITTED"`` and ``"AUTOCOMMIT"``
299 based on backend.
301 The :paramref:`_sa.create_engine.isolation_level` parameter is
302 in contrast to the
303 :paramref:`.Connection.execution_options.isolation_level`
304 execution option, which may be set on an individual
305 :class:`.Connection`, as well as the same parameter passed to
306 :meth:`.Engine.execution_options`, where it may be used to create
307 multiple engines with different isolation levels that share a common
308 connection pool and dialect.
310 .. versionchanged:: 2.0 The
311 :paramref:`_sa.create_engine.isolation_level`
312 parameter has been generalized to work on all dialects which support
313 the concept of isolation level, and is provided as a more succinct,
314 up front configuration switch in contrast to the execution option
315 which is more of an ad-hoc programmatic option.
317 .. seealso::
319 :ref:`dbapi_autocommit`
321 :param json_deserializer: for dialects that support the
322 :class:`_types.JSON`
323 datatype, this is a Python callable that will convert a JSON string
324 to a Python object. By default, the Python ``json.loads`` function is
325 used.
327 :param json_serializer: for dialects that support the :class:`_types.JSON`
328 datatype, this is a Python callable that will render a given object
329 as JSON. By default, the Python ``json.dumps`` function is used.
331 :param label_length=None: optional integer value which limits
332 the size of dynamically generated column labels to that many
333 characters. If less than 6, labels are generated as
334 "_(counter)". If ``None``, the value of
335 ``dialect.max_identifier_length``, which may be affected via the
336 :paramref:`_sa.create_engine.max_identifier_length` parameter,
337 is used instead. The value of
338 :paramref:`_sa.create_engine.label_length`
339 may not be larger than that of
340 :paramref:`_sa.create_engine.max_identfier_length`.
342 .. seealso::
344 :paramref:`_sa.create_engine.max_identifier_length`
346 :param logging_name: String identifier which will be used within
347 the "name" field of logging records generated within the
348 "sqlalchemy.engine" logger. Defaults to a hexstring of the
349 object's id.
351 .. seealso::
353 :ref:`dbengine_logging` - further detail on how to configure
354 logging.
356 :paramref:`_engine.Connection.execution_options.logging_token`
358 :param max_identifier_length: integer; override the max_identifier_length
359 determined by the dialect. if ``None`` or zero, has no effect. This
360 is the database's configured maximum number of characters that may be
361 used in a SQL identifier such as a table name, column name, or label
362 name. All dialects determine this value automatically, however in the
363 case of a new database version for which this value has changed but
364 SQLAlchemy's dialect has not been adjusted, the value may be passed
365 here.
367 .. seealso::
369 :paramref:`_sa.create_engine.label_length`
371 :param max_overflow=10: the number of connections to allow in
372 connection pool "overflow", that is connections that can be
373 opened above and beyond the pool_size setting, which defaults
374 to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`.
376 :param module=None: reference to a Python module object (the module
377 itself, not its string name). Specifies an alternate DBAPI module to
378 be used by the engine's dialect. Each sub-dialect references a
379 specific DBAPI which will be imported before first connect. This
380 parameter causes the import to be bypassed, and the given module to
381 be used instead. Can be used for testing of DBAPIs as well as to
382 inject "mock" DBAPI implementations into the :class:`_engine.Engine`.
384 :param paramstyle=None: The `paramstyle <https://legacy.python.org/dev/peps/pep-0249/#paramstyle>`_
385 to use when rendering bound parameters. This style defaults to the
386 one recommended by the DBAPI itself, which is retrieved from the
387 ``.paramstyle`` attribute of the DBAPI. However, most DBAPIs accept
388 more than one paramstyle, and in particular it may be desirable
389 to change a "named" paramstyle into a "positional" one, or vice versa.
390 When this attribute is passed, it should be one of the values
391 ``"qmark"``, ``"numeric"``, ``"named"``, ``"format"`` or
392 ``"pyformat"``, and should correspond to a parameter style known
393 to be supported by the DBAPI in use.
395 :param pool=None: an already-constructed instance of
396 :class:`~sqlalchemy.pool.Pool`, such as a
397 :class:`~sqlalchemy.pool.QueuePool` instance. If non-None, this
398 pool will be used directly as the underlying connection pool
399 for the engine, bypassing whatever connection parameters are
400 present in the URL argument. For information on constructing
401 connection pools manually, see :ref:`pooling_toplevel`.
403 :param poolclass=None: a :class:`~sqlalchemy.pool.Pool`
404 subclass, which will be used to create a connection pool
405 instance using the connection parameters given in the URL. Note
406 this differs from ``pool`` in that you don't actually
407 instantiate the pool in this case, you just indicate what type
408 of pool to be used.
410 :param pool_logging_name: String identifier which will be used within
411 the "name" field of logging records generated within the
412 "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
413 id.
415 .. seealso::
417 :ref:`dbengine_logging` - further detail on how to configure
418 logging.
420 :param pool_pre_ping: boolean, if True will enable the connection pool
421 "pre-ping" feature that tests connections for liveness upon
422 each checkout.
424 .. seealso::
426 :ref:`pool_disconnects_pessimistic`
428 :param pool_size=5: the number of connections to keep open
429 inside the connection pool. This used with
430 :class:`~sqlalchemy.pool.QueuePool` as
431 well as :class:`~sqlalchemy.pool.SingletonThreadPool`. With
432 :class:`~sqlalchemy.pool.QueuePool`, a ``pool_size`` setting
433 of 0 indicates no limit; to disable pooling, set ``poolclass`` to
434 :class:`~sqlalchemy.pool.NullPool` instead.
436 :param pool_recycle=-1: this setting causes the pool to recycle
437 connections after the given number of seconds has passed. It
438 defaults to -1, or no timeout. For example, setting to 3600
439 means connections will be recycled after one hour. Note that
440 MySQL in particular will disconnect automatically if no
441 activity is detected on a connection for eight hours (although
442 this is configurable with the MySQLDB connection itself and the
443 server configuration as well).
445 .. seealso::
447 :ref:`pool_setting_recycle`
449 :param pool_reset_on_return='rollback': set the
450 :paramref:`_pool.Pool.reset_on_return` parameter of the underlying
451 :class:`_pool.Pool` object, which can be set to the values
452 ``"rollback"``, ``"commit"``, or ``None``.
454 .. seealso::
456 :ref:`pool_reset_on_return`
458 :ref:`dbapi_autocommit_skip_rollback` - a more modern approach
459 to using connections with no transactional instructions
461 :param pool_timeout=30: number of seconds to wait before giving
462 up on getting a connection from the pool. This is only used
463 with :class:`~sqlalchemy.pool.QueuePool`. This can be a float but is
464 subject to the limitations of Python time functions which may not be
465 reliable in the tens of milliseconds.
467 .. note: don't use 30.0 above, it seems to break with the :param tag
469 :param pool_use_lifo=False: use LIFO (last-in-first-out) when retrieving
470 connections from :class:`.QueuePool` instead of FIFO
471 (first-in-first-out). Using LIFO, a server-side timeout scheme can
472 reduce the number of connections used during non- peak periods of
473 use. When planning for server-side timeouts, ensure that a recycle or
474 pre-ping strategy is in use to gracefully handle stale connections.
476 .. seealso::
478 :ref:`pool_use_lifo`
480 :ref:`pool_disconnects`
482 :param plugins: string list of plugin names to load. See
483 :class:`.CreateEnginePlugin` for background.
485 :param query_cache_size: size of the cache used to cache the SQL string
486 form of queries. Set to zero to disable caching.
488 The cache is pruned of its least recently used items when its size reaches
489 N * 1.5. Defaults to 500, meaning the cache will always store at least
490 500 SQL statements when filled, and will grow up to 750 items at which
491 point it is pruned back down to 500 by removing the 250 least recently
492 used items.
494 Caching is accomplished on a per-statement basis by generating a
495 cache key that represents the statement's structure, then generating
496 string SQL for the current dialect only if that key is not present
497 in the cache. All statements support caching, however some features
498 such as an INSERT with a large set of parameters will intentionally
499 bypass the cache. SQL logging will indicate statistics for each
500 statement whether or not it were pull from the cache.
502 .. note:: some ORM functions related to unit-of-work persistence as well
503 as some attribute loading strategies will make use of individual
504 per-mapper caches outside of the main cache.
507 .. seealso::
509 :ref:`sql_caching`
511 .. versionadded:: 1.4
513 :param skip_autocommit_rollback: When True, the dialect will
514 unconditionally skip all calls to the DBAPI ``connection.rollback()``
515 method if the DBAPI connection is confirmed to be in "autocommit" mode.
516 The availability of this feature is dialect specific; if not available,
517 a ``NotImplementedError`` is raised by the dialect when rollback occurs.
519 .. seealso::
521 :ref:`dbapi_autocommit_skip_rollback`
523 .. versionadded:: 2.0.43
525 :param use_insertmanyvalues: True by default, use the "insertmanyvalues"
526 execution style for INSERT..RETURNING statements by default.
528 .. versionadded:: 2.0
530 .. seealso::
532 :ref:`engine_insertmanyvalues`
534 """ # noqa
536 if "strategy" in kwargs:
537 strat = kwargs.pop("strategy")
538 if strat == "mock":
539 # this case is deprecated
540 return create_mock_engine(url, **kwargs) # type: ignore
541 else:
542 raise exc.ArgumentError("unknown strategy: %r" % strat)
544 kwargs.pop("empty_in_strategy", None)
546 # create url.URL object
547 u = _url.make_url(url)
549 u, plugins, kwargs = u._instantiate_plugins(kwargs)
551 entrypoint = u._get_entrypoint()
552 _is_async = kwargs.pop("_is_async", False)
553 if _is_async:
554 dialect_cls = entrypoint.get_async_dialect_cls(u)
555 else:
556 dialect_cls = entrypoint.get_dialect_cls(u)
558 if kwargs.pop("_coerce_config", False):
560 def pop_kwarg(key: str, default: Optional[Any] = None) -> Any:
561 value = kwargs.pop(key, default)
562 if key in dialect_cls.engine_config_types:
563 value = dialect_cls.engine_config_types[key](value)
564 return value
566 else:
567 pop_kwarg = kwargs.pop # type: ignore
569 dialect_args = {}
570 # consume dialect arguments from kwargs
571 for k in util.get_cls_kwargs(dialect_cls):
572 if k in kwargs:
573 dialect_args[k] = pop_kwarg(k)
575 dbapi = kwargs.pop("module", None)
576 if dbapi is None:
577 dbapi_args = {}
579 if "import_dbapi" in dialect_cls.__dict__:
580 dbapi_meth = dialect_cls.import_dbapi
582 elif hasattr(dialect_cls, "dbapi") and inspect.ismethod(
583 dialect_cls.dbapi
584 ):
585 util.warn_deprecated(
586 "The dbapi() classmethod on dialect classes has been "
587 "renamed to import_dbapi(). Implement an import_dbapi() "
588 f"classmethod directly on class {dialect_cls} to remove this "
589 "warning; the old .dbapi() classmethod may be maintained for "
590 "backwards compatibility.",
591 "2.0",
592 )
593 dbapi_meth = dialect_cls.dbapi
594 else:
595 dbapi_meth = dialect_cls.import_dbapi
597 for k in util.get_func_kwargs(dbapi_meth):
598 if k in kwargs:
599 dbapi_args[k] = pop_kwarg(k)
600 dbapi = dbapi_meth(**dbapi_args)
602 dialect_args["dbapi"] = dbapi
604 dialect_args.setdefault("compiler_linting", compiler.NO_LINTING)
605 enable_from_linting = kwargs.pop("enable_from_linting", True)
606 if enable_from_linting:
607 dialect_args["compiler_linting"] ^= compiler.COLLECT_CARTESIAN_PRODUCTS
609 for plugin in plugins:
610 plugin.handle_dialect_kwargs(dialect_cls, dialect_args)
612 # create dialect
613 dialect = dialect_cls(**dialect_args)
615 # assemble connection arguments
616 (cargs_tup, cparams) = dialect.create_connect_args(u)
617 cparams.update(pop_kwarg("connect_args", {}))
618 cargs = list(cargs_tup) # allow mutability
620 # look for existing pool or create
621 pool = pop_kwarg("pool", None)
622 if pool is None:
624 def connect(
625 connection_record: Optional[ConnectionPoolEntry] = None,
626 ) -> DBAPIConnection:
627 if dialect._has_events:
628 for fn in dialect.dispatch.do_connect:
629 connection = cast(
630 DBAPIConnection,
631 fn(dialect, connection_record, cargs, cparams),
632 )
633 if connection is not None:
634 return connection
636 return dialect.connect(*cargs, **cparams)
638 creator = pop_kwarg("creator", connect)
640 poolclass = pop_kwarg("poolclass", None)
641 if poolclass is None:
642 poolclass = dialect.get_dialect_pool_class(u)
643 pool_args = {"dialect": dialect}
645 # consume pool arguments from kwargs, translating a few of
646 # the arguments
647 for k in util.get_cls_kwargs(poolclass):
648 tk = _pool_translate_kwargs.get(k, k)
649 if tk in kwargs:
650 pool_args[k] = pop_kwarg(tk)
652 for plugin in plugins:
653 plugin.handle_pool_kwargs(poolclass, pool_args)
655 pool = poolclass(creator, **pool_args)
656 else:
657 pool._dialect = dialect
659 if (
660 hasattr(pool, "_is_asyncio")
661 and pool._is_asyncio is not dialect.is_async
662 ):
663 raise exc.ArgumentError(
664 f"Pool class {pool.__class__.__name__} cannot be "
665 f"used with {'non-' if not dialect.is_async else ''}"
666 "asyncio engine",
667 code="pcls",
668 )
670 # create engine.
671 if not pop_kwarg("future", True):
672 raise exc.ArgumentError(
673 "The 'future' parameter passed to "
674 "create_engine() may only be set to True."
675 )
677 engineclass = base.Engine
679 engine_args = {}
680 for k in util.get_cls_kwargs(engineclass):
681 if k in kwargs:
682 engine_args[k] = pop_kwarg(k)
684 # internal flags used by the test suite for instrumenting / proxying
685 # engines with mocks etc.
686 _initialize = kwargs.pop("_initialize", True)
688 # all kwargs should be consumed
689 if kwargs:
690 raise TypeError(
691 "Invalid argument(s) %s sent to create_engine(), "
692 "using configuration %s/%s/%s. Please check that the "
693 "keyword arguments are appropriate for this combination "
694 "of components."
695 % (
696 ",".join("'%s'" % k for k in kwargs),
697 dialect.__class__.__name__,
698 pool.__class__.__name__,
699 engineclass.__name__,
700 )
701 )
703 engine = engineclass(pool, dialect, u, **engine_args)
705 if _initialize:
706 do_on_connect = dialect.on_connect_url(u)
707 if do_on_connect:
709 def on_connect(
710 dbapi_connection: DBAPIConnection,
711 connection_record: ConnectionPoolEntry,
712 ) -> None:
713 assert do_on_connect is not None
714 do_on_connect(dbapi_connection)
716 event.listen(pool, "connect", on_connect)
718 builtin_on_connect = dialect._builtin_onconnect()
719 if builtin_on_connect:
720 event.listen(pool, "connect", builtin_on_connect)
722 def first_connect(
723 dbapi_connection: DBAPIConnection,
724 connection_record: ConnectionPoolEntry,
725 ) -> None:
726 c = base.Connection(
727 engine,
728 connection=_AdhocProxiedConnection(
729 dbapi_connection, connection_record
730 ),
731 _has_events=False,
732 # reconnecting will be a reentrant condition, so if the
733 # connection goes away, Connection is then closed
734 _allow_revalidate=False,
735 # dont trigger the autobegin sequence
736 # within the up front dialect checks
737 _allow_autobegin=False,
738 )
739 c._execution_options = util.EMPTY_DICT
741 try:
742 dialect.initialize(c)
743 finally:
744 # note that "invalidated" and "closed" are mutually
745 # exclusive in 1.4 Connection.
746 if not c.invalidated and not c.closed:
747 # transaction is rolled back otherwise, tested by
748 # test/dialect/postgresql/test_dialect.py
749 # ::MiscBackendTest::test_initial_transaction_state
750 dialect.do_rollback(c.connection)
752 # previously, the "first_connect" event was used here, which was then
753 # scaled back if the "on_connect" handler were present. now,
754 # since "on_connect" is virtually always present, just use
755 # "connect" event with once_unless_exception in all cases so that
756 # the connection event flow is consistent in all cases.
757 event.listen(
758 pool, "connect", first_connect, _once_unless_exception=True
759 )
761 dialect_cls.engine_created(engine)
762 if entrypoint is not dialect_cls:
763 entrypoint.engine_created(engine)
765 for plugin in plugins:
766 plugin.engine_created(engine)
768 return engine
771def engine_from_config(
772 configuration: Dict[str, Any], prefix: str = "sqlalchemy.", **kwargs: Any
773) -> Engine:
774 """Create a new Engine instance using a configuration dictionary.
776 The dictionary is typically produced from a config file.
778 The keys of interest to ``engine_from_config()`` should be prefixed, e.g.
779 ``sqlalchemy.url``, ``sqlalchemy.echo``, etc. The 'prefix' argument
780 indicates the prefix to be searched for. Each matching key (after the
781 prefix is stripped) is treated as though it were the corresponding keyword
782 argument to a :func:`_sa.create_engine` call.
784 The only required key is (assuming the default prefix) ``sqlalchemy.url``,
785 which provides the :ref:`database URL <database_urls>`.
787 A select set of keyword arguments will be "coerced" to their
788 expected type based on string values. The set of arguments
789 is extensible per-dialect using the ``engine_config_types`` accessor.
791 :param configuration: A dictionary (typically produced from a config file,
792 but this is not a requirement). Items whose keys start with the value
793 of 'prefix' will have that prefix stripped, and will then be passed to
794 :func:`_sa.create_engine`.
796 :param prefix: Prefix to match and then strip from keys
797 in 'configuration'.
799 :param kwargs: Each keyword argument to ``engine_from_config()`` itself
800 overrides the corresponding item taken from the 'configuration'
801 dictionary. Keyword arguments should *not* be prefixed.
803 """
805 options = {
806 key[len(prefix) :]: configuration[key]
807 for key in configuration
808 if key.startswith(prefix)
809 }
810 options["_coerce_config"] = True
811 options.update(kwargs)
812 url = options.pop("url")
813 return create_engine(url, **options)
816@overload
817def create_pool_from_url(
818 url: Union[str, URL],
819 *,
820 poolclass: Optional[Type[Pool]] = ...,
821 logging_name: str = ...,
822 pre_ping: bool = ...,
823 size: int = ...,
824 recycle: int = ...,
825 reset_on_return: Optional[_ResetStyleArgType] = ...,
826 timeout: float = ...,
827 use_lifo: bool = ...,
828 **kwargs: Any,
829) -> Pool: ...
832@overload
833def create_pool_from_url(url: Union[str, URL], **kwargs: Any) -> Pool: ...
836def create_pool_from_url(url: Union[str, URL], **kwargs: Any) -> Pool:
837 """Create a pool instance from the given url.
839 If ``poolclass`` is not provided the pool class used
840 is selected using the dialect specified in the URL.
842 The arguments passed to :func:`_sa.create_pool_from_url` are
843 identical to the pool argument passed to the :func:`_sa.create_engine`
844 function.
846 .. versionadded:: 2.0.10
847 """
849 for key in _pool_translate_kwargs:
850 if key in kwargs:
851 kwargs[_pool_translate_kwargs[key]] = kwargs.pop(key)
853 engine = create_engine(url, **kwargs, _initialize=False)
854 return engine.pool
857_pool_translate_kwargs = immutabledict(
858 {
859 "logging_name": "pool_logging_name",
860 "echo": "echo_pool",
861 "timeout": "pool_timeout",
862 "recycle": "pool_recycle",
863 "events": "pool_events", # deprecated
864 "reset_on_return": "pool_reset_on_return",
865 "pre_ping": "pool_pre_ping",
866 "use_lifo": "pool_use_lifo",
867 }
868)