codekingpro/portable-devtools
115k
1# engine/create.py
2# Copyright (C) 2005-2026 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
7
8from __future__ import annotations
9
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
21
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
33
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
46
47
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: ...
86
87
88@overload
89def create_engine(url: Union[str, URL], **kwargs: Any) -> Engine: ...
90
91
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.
118
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::
122
123 engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
124
125 .. note::
126
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.
130
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::
135
136 engine = create_engine(
137 "mysql+mysqldb://scott:tiger@hostname/dbname",
138 pool_recycle=3600,
139 echo=True,
140 )
141
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`.
148
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.
156
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.
165
166 .. seealso::
167
168 :doc:`/core/engines`
169
170 :doc:`/dialects/index`
171
172 :ref:`connections_toplevel`
173
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`.
178
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.
184
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.
189
190 .. seealso::
191
192 :meth:`_events.DialectEvents.do_connect` - event hook that allows
193 full control over DBAPI connection mechanics.
194
195 :ref:`custom_dbapi_args`
196
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.
204
205 .. seealso::
206
207 :ref:`dbengine_logging` - further detail on how to configure
208 logging.
209
210
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.
218
219 .. seealso::
220
221 :ref:`dbengine_logging` - further detail on how to configure
222 logging.
223
224
225 :param empty_in_strategy: No longer used; SQLAlchemy now uses
226 "empty set" behavior for IN in all cases.
227
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.
231
232 .. versionadded:: 1.4
233
234 .. seealso::
235
236 :ref:`change_4737`
237
238 :param execution_options: Dictionary execution options which will
239 be applied to all connections. See
240 :meth:`~sqlalchemy.engine.Connection.execution_options`
241
242 :param future: Use the 2.0 style :class:`_engine.Engine` and
243 :class:`_engine.Connection` API.
244
245 As of SQLAlchemy 2.0, this parameter is present for backwards
246 compatibility only and must remain at its default value of ``True``.
247
248 The :paramref:`_sa.create_engine.future` parameter will be
249 deprecated in a subsequent 2.x release and eventually removed.
250
251 .. versionadded:: 1.4
252
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.
256
257 .. seealso::
258
259 :ref:`migration_20_toplevel`
260
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.
264
265 .. versionadded:: 1.3.8
266
267 .. seealso::
268
269 :ref:`dbengine_logging` - further detail on how to configure
270 logging.
271
272 :param implicit_returning=True: Legacy parameter that may only be set
273 to True. In SQLAlchemy 2.0, this parameter does nothing. In order to
274 disable "implicit returning" for statements invoked by the ORM,
275 configure this on a per-table basis using the
276 :paramref:`.Table.implicit_returning` parameter.
277
278
279 :param insertmanyvalues_page_size: number of rows to format into an
280 INSERT statement when the statement uses "insertmanyvalues" mode, which is
281 a paged form of bulk insert that is used for many backends when using
282 :term:`executemany` execution typically in conjunction with RETURNING.
283 Defaults to 1000, but may also be subject to dialect-specific limiting
284 factors which may override this value on a per-statement basis.
285
286 .. versionadded:: 2.0
287
288 .. seealso::
289
290 :ref:`engine_insertmanyvalues`
291
292 :ref:`engine_insertmanyvalues_page_size`
293
294 :paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size`
295
296 :param isolation_level: optional string name of an isolation level
297 which will be set on all new connections unconditionally.
298 Isolation levels are typically some subset of the string names
299 ``"SERIALIZABLE"``, ``"REPEATABLE READ"``,
300 ``"READ COMMITTED"``, ``"READ UNCOMMITTED"`` and ``"AUTOCOMMIT"``
301 based on backend.
302
303 The :paramref:`_sa.create_engine.isolation_level` parameter is
304 in contrast to the
305 :paramref:`.Connection.execution_options.isolation_level`
306 execution option, which may be set on an individual
307 :class:`.Connection`, as well as the same parameter passed to
308 :meth:`.Engine.execution_options`, where it may be used to create
309 multiple engines with different isolation levels that share a common
310 connection pool and dialect.
311
312 .. versionchanged:: 2.0 The
313 :paramref:`_sa.create_engine.isolation_level`
314 parameter has been generalized to work on all dialects which support
315 the concept of isolation level, and is provided as a more succinct,
316 up front configuration switch in contrast to the execution option
317 which is more of an ad-hoc programmatic option.
318
319 .. seealso::
320
321 :ref:`dbapi_autocommit`
322
323 :param json_deserializer: for dialects that support the
324 :class:`_types.JSON`
325 datatype, this is a Python callable that will convert a JSON string
326 to a Python object. By default, the Python ``json.loads`` function is
327 used.
328
329 .. versionchanged:: 1.3.7 The SQLite dialect renamed this from
330 ``_json_deserializer``.
331
332 :param json_serializer: for dialects that support the :class:`_types.JSON`
333 datatype, this is a Python callable that will render a given object
334 as JSON. By default, the Python ``json.dumps`` function is used.
335
336 .. versionchanged:: 1.3.7 The SQLite dialect renamed this from
337 ``_json_serializer``.
338
339
340 :param label_length=None: optional integer value which limits
341 the size of dynamically generated column labels to that many
342 characters. If less than 6, labels are generated as
343 "_(counter)". If ``None``, the value of
344 ``dialect.max_identifier_length``, which may be affected via the
345 :paramref:`_sa.create_engine.max_identifier_length` parameter,
346 is used instead. The value of
347 :paramref:`_sa.create_engine.label_length`
348 may not be larger than that of
349 :paramref:`_sa.create_engine.max_identfier_length`.
350
351 .. seealso::
352
353 :paramref:`_sa.create_engine.max_identifier_length`
354
355 :param logging_name: String identifier which will be used within
356 the "name" field of logging records generated within the
357 "sqlalchemy.engine" logger. Defaults to a hexstring of the
358 object's id.
359
360 .. seealso::
361
362 :ref:`dbengine_logging` - further detail on how to configure
363 logging.
364
365 :paramref:`_engine.Connection.execution_options.logging_token`
366
367 :param max_identifier_length: integer; override the max_identifier_length
368 determined by the dialect. if ``None`` or zero, has no effect. This
369 is the database's configured maximum number of characters that may be
370 used in a SQL identifier such as a table name, column name, or label
371 name. All dialects determine this value automatically, however in the
372 case of a new database version for which this value has changed but
373 SQLAlchemy's dialect has not been adjusted, the value may be passed
374 here.
375
376 .. versionadded:: 1.3.9
377
378 .. seealso::
379
380 :paramref:`_sa.create_engine.label_length`
381
382 :param max_overflow=10: the number of connections to allow in
383 connection pool "overflow", that is connections that can be
384 opened above and beyond the pool_size setting, which defaults
385 to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`.
386
387 :param module=None: reference to a Python module object (the module
388 itself, not its string name). Specifies an alternate DBAPI module to
389 be used by the engine's dialect. Each sub-dialect references a
390 specific DBAPI which will be imported before first connect. This
391 parameter causes the import to be bypassed, and the given module to
392 be used instead. Can be used for testing of DBAPIs as well as to
393 inject "mock" DBAPI implementations into the :class:`_engine.Engine`.
394
395 :param paramstyle=None: The `paramstyle <https://legacy.python.org/dev/peps/pep-0249/#paramstyle>`_
396 to use when rendering bound parameters. This style defaults to the
397 one recommended by the DBAPI itself, which is retrieved from the
398 ``.paramstyle`` attribute of the DBAPI. However, most DBAPIs accept
399 more than one paramstyle, and in particular it may be desirable
400 to change a "named" paramstyle into a "positional" one, or vice versa.
401 When this attribute is passed, it should be one of the values
402 ``"qmark"``, ``"numeric"``, ``"named"``, ``"format"`` or
403 ``"pyformat"``, and should correspond to a parameter style known
404 to be supported by the DBAPI in use.
405
406 :param pool=None: an already-constructed instance of
407 :class:`~sqlalchemy.pool.Pool`, such as a
408 :class:`~sqlalchemy.pool.QueuePool` instance. If non-None, this
409 pool will be used directly as the underlying connection pool
410 for the engine, bypassing whatever connection parameters are
411 present in the URL argument. For information on constructing
412 connection pools manually, see :ref:`pooling_toplevel`.
413
414 :param poolclass=None: a :class:`~sqlalchemy.pool.Pool`
415 subclass, which will be used to create a connection pool
416 instance using the connection parameters given in the URL. Note
417 this differs from ``pool`` in that you don't actually
418 instantiate the pool in this case, you just indicate what type
419 of pool to be used.
420
421 :param pool_logging_name: String identifier which will be used within
422 the "name" field of logging records generated within the
423 "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
424 id.
425
426 .. seealso::
427
428 :ref:`dbengine_logging` - further detail on how to configure
429 logging.
430
431 :param pool_pre_ping: boolean, if True will enable the connection pool
432 "pre-ping" feature that tests connections for liveness upon
433 each checkout.
434
435 .. versionadded:: 1.2
436
437 .. seealso::
438
439 :ref:`pool_disconnects_pessimistic`
440
441 :param pool_size=5: the number of connections to keep open
442 inside the connection pool. This used with
443 :class:`~sqlalchemy.pool.QueuePool` as
444 well as :class:`~sqlalchemy.pool.SingletonThreadPool`. With
445 :class:`~sqlalchemy.pool.QueuePool`, a ``pool_size`` setting
446 of 0 indicates no limit; to disable pooling, set ``poolclass`` to
447 :class:`~sqlalchemy.pool.NullPool` instead.
448
449 :param pool_recycle=-1: this setting causes the pool to recycle
450 connections after the given number of seconds has passed. It
451 defaults to -1, or no timeout. For example, setting to 3600
452 means connections will be recycled after one hour. Note that
453 MySQL in particular will disconnect automatically if no
454 activity is detected on a connection for eight hours (although
455 this is configurable with the MySQLDB connection itself and the
456 server configuration as well).
457
458 .. seealso::
459
460 :ref:`pool_setting_recycle`
461
462 :param pool_reset_on_return='rollback': set the
463 :paramref:`_pool.Pool.reset_on_return` parameter of the underlying
464 :class:`_pool.Pool` object, which can be set to the values
465 ``"rollback"``, ``"commit"``, or ``None``.
466
467 .. seealso::
468
469 :ref:`pool_reset_on_return`
470
471 :ref:`dbapi_autocommit_skip_rollback` - a more modern approach
472 to using connections with no transactional instructions
473
474 :param pool_timeout=30: number of seconds to wait before giving
475 up on getting a connection from the pool. This is only used
476 with :class:`~sqlalchemy.pool.QueuePool`. This can be a float but is
477 subject to the limitations of Python time functions which may not be
478 reliable in the tens of milliseconds.
479
480 .. note: don't use 30.0 above, it seems to break with the :param tag
481
482 :param pool_use_lifo=False: use LIFO (last-in-first-out) when retrieving
483 connections from :class:`.QueuePool` instead of FIFO
484 (first-in-first-out). Using LIFO, a server-side timeout scheme can
485 reduce the number of connections used during non- peak periods of
486 use. When planning for server-side timeouts, ensure that a recycle or
487 pre-ping strategy is in use to gracefully handle stale connections.
488
489 .. versionadded:: 1.3
490
491 .. seealso::
492
493 :ref:`pool_use_lifo`
494
495 :ref:`pool_disconnects`
496
497 :param plugins: string list of plugin names to load. See
498 :class:`.CreateEnginePlugin` for background.
499
500 .. versionadded:: 1.2.3
501
502 :param query_cache_size: size of the cache used to cache the SQL string
503 form of queries. Set to zero to disable caching.
504
505 The cache is pruned of its least recently used items when its size reaches
506 N * 1.5. Defaults to 500, meaning the cache will always store at least
507 500 SQL statements when filled, and will grow up to 750 items at which
508 point it is pruned back down to 500 by removing the 250 least recently
509 used items.
510
511 Caching is accomplished on a per-statement basis by generating a
512 cache key that represents the statement's structure, then generating
513 string SQL for the current dialect only if that key is not present
514 in the cache. All statements support caching, however some features
515 such as an INSERT with a large set of parameters will intentionally
516 bypass the cache. SQL logging will indicate statistics for each
517 statement whether or not it were pull from the cache.
518
519 .. note:: some ORM functions related to unit-of-work persistence as well
520 as some attribute loading strategies will make use of individual
521 per-mapper caches outside of the main cache.
522
523
524 .. seealso::
525
526 :ref:`sql_caching`
527
528 .. versionadded:: 1.4
529
530 :param skip_autocommit_rollback: When True, the dialect will
531 unconditionally skip all calls to the DBAPI ``connection.rollback()``
532 method if the DBAPI connection is confirmed to be in "autocommit" mode.
533 The availability of this feature is dialect specific; if not available,
534 a ``NotImplementedError`` is raised by the dialect when rollback occurs.
535
536 .. seealso::
537
538 :ref:`dbapi_autocommit_skip_rollback`
539
540 .. versionadded:: 2.0.43
541
542 :param use_insertmanyvalues: True by default, use the "insertmanyvalues"
543 execution style for INSERT..RETURNING statements by default.
544
545 .. versionadded:: 2.0
546
547 .. seealso::
548
549 :ref:`engine_insertmanyvalues`
550
551 """ # noqa
552
553 if "strategy" in kwargs:
554 strat = kwargs.pop("strategy")
555 if strat == "mock":
556 # this case is deprecated
557 return create_mock_engine(url, **kwargs) # type: ignore
558 else:
559 raise exc.ArgumentError("unknown strategy: %r" % strat)
560
561 kwargs.pop("empty_in_strategy", None)
562
563 # create url.URL object
564 u = _url.make_url(url)
565
566 u, plugins, kwargs = u._instantiate_plugins(kwargs)
567
568 entrypoint = u._get_entrypoint()
569 _is_async = kwargs.pop("_is_async", False)
570 if _is_async:
571 dialect_cls = entrypoint.get_async_dialect_cls(u)
572 else:
573 dialect_cls = entrypoint.get_dialect_cls(u)
574
575 if kwargs.pop("_coerce_config", False):
576
577 def pop_kwarg(key: str, default: Optional[Any] = None) -> Any:
578 value = kwargs.pop(key, default)
579 if key in dialect_cls.engine_config_types:
580 value = dialect_cls.engine_config_types[key](value)
581 return value
582
583 else:
584 pop_kwarg = kwargs.pop # type: ignore
585
586 dialect_args = {}
587 # consume dialect arguments from kwargs
588 for k in util.get_cls_kwargs(dialect_cls):
589 if k in kwargs:
590 dialect_args[k] = pop_kwarg(k)
591
592 dbapi = kwargs.pop("module", None)
593 if dbapi is None:
594 dbapi_args = {}
595
596 if "import_dbapi" in dialect_cls.__dict__:
597 dbapi_meth = dialect_cls.import_dbapi
598
599 elif hasattr(dialect_cls, "dbapi") and inspect.ismethod(
600 dialect_cls.dbapi
601 ):
602 util.warn_deprecated(
603 "The dbapi() classmethod on dialect classes has been "
604 "renamed to import_dbapi(). Implement an import_dbapi() "
605 f"classmethod directly on class {dialect_cls} to remove this "
606 "warning; the old .dbapi() classmethod may be maintained for "
607 "backwards compatibility.",
608 "2.0",
609 )
610 dbapi_meth = dialect_cls.dbapi
611 else:
612 dbapi_meth = dialect_cls.import_dbapi
613
614 for k in util.get_func_kwargs(dbapi_meth):
615 if k in kwargs:
616 dbapi_args[k] = pop_kwarg(k)
617 dbapi = dbapi_meth(**dbapi_args)
618
619 dialect_args["dbapi"] = dbapi
620
621 dialect_args.setdefault("compiler_linting", compiler.NO_LINTING)
622 enable_from_linting = kwargs.pop("enable_from_linting", True)
623 if enable_from_linting:
624 dialect_args["compiler_linting"] ^= compiler.COLLECT_CARTESIAN_PRODUCTS
625
626 for plugin in plugins:
627 plugin.handle_dialect_kwargs(dialect_cls, dialect_args)
628
629 # create dialect
630 dialect = dialect_cls(**dialect_args)
631
632 # assemble connection arguments
633 (cargs_tup, _cparams) = dialect.create_connect_args(u)
634 cparams = util.immutabledict(_cparams).union(pop_kwarg("connect_args", {}))
635
636 if "async_fallback" in cparams and util.asbool(cparams["async_fallback"]):
637 util.warn_deprecated(
638 "The async_fallback dialect argument is deprecated and will be "
639 "removed in SQLAlchemy 2.1.",
640 "2.0",
641 )
642
643 # look for existing pool or create
644 pool = pop_kwarg("pool", None)
645 if pool is None:
646
647 def connect(
648 connection_record: Optional[ConnectionPoolEntry] = None,
649 ) -> DBAPIConnection:
650 if dialect._has_events:
651 mutable_cargs = list(cargs_tup)
652 mutable_cparams = dict(cparams)
653 for fn in dialect.dispatch.do_connect:
654 connection = cast(
655 DBAPIConnection,
656 fn(
657 dialect,
658 connection_record,
659 mutable_cargs,
660 mutable_cparams,
661 ),
662 )
663 if connection is not None:
664 return connection
665 return dialect.connect(*mutable_cargs, **mutable_cparams)
666 else:
667 return dialect.connect(*cargs_tup, **cparams)
668
669 creator = pop_kwarg("creator", connect)
670
671 poolclass = pop_kwarg("poolclass", None)
672 if poolclass is None:
673 poolclass = dialect.get_dialect_pool_class(u)
674 pool_args = {"dialect": dialect}
675
676 # consume pool arguments from kwargs, translating a few of
677 # the arguments
678 for k in util.get_cls_kwargs(poolclass):
679 tk = _pool_translate_kwargs.get(k, k)
680 if tk in kwargs:
681 pool_args[k] = pop_kwarg(tk)
682
683 for plugin in plugins:
684 plugin.handle_pool_kwargs(poolclass, pool_args)
685
686 pool = poolclass(creator, **pool_args)
687 else:
688 pool._dialect = dialect
689
690 if (
691 hasattr(pool, "_is_asyncio")
692 and pool._is_asyncio is not dialect.is_async
693 ):
694 raise exc.ArgumentError(
695 f"Pool class {pool.__class__.__name__} cannot be "
696 f"used with {'non-' if not dialect.is_async else ''}"
697 "asyncio engine",
698 code="pcls",
699 )
700
701 # create engine.
702 if not pop_kwarg("future", True):
703 raise exc.ArgumentError(
704 "The 'future' parameter passed to "
705 "create_engine() may only be set to True."
706 )
707
708 engineclass = base.Engine
709
710 engine_args = {}
711 for k in util.get_cls_kwargs(engineclass):
712 if k in kwargs:
713 engine_args[k] = pop_kwarg(k)
714
715 # internal flags used by the test suite for instrumenting / proxying
716 # engines with mocks etc.
717 _initialize = kwargs.pop("_initialize", True)
718
719 # all kwargs should be consumed
720 if kwargs:
721 raise TypeError(
722 "Invalid argument(s) %s sent to create_engine(), "
723 "using configuration %s/%s/%s. Please check that the "
724 "keyword arguments are appropriate for this combination "
725 "of components."
726 % (
727 ",".join("'%s'" % k for k in kwargs),
728 dialect.__class__.__name__,
729 pool.__class__.__name__,
730 engineclass.__name__,
731 )
732 )
733
734 engine = engineclass(pool, dialect, u, **engine_args)
735
736 if _initialize:
737 do_on_connect = dialect.on_connect_url(u)
738 if do_on_connect:
739
740 def on_connect(
741 dbapi_connection: DBAPIConnection,
742 connection_record: ConnectionPoolEntry,
743 ) -> None:
744 assert do_on_connect is not None
745 do_on_connect(dbapi_connection)
746
747 event.listen(pool, "connect", on_connect)
748
749 builtin_on_connect = dialect._builtin_onconnect()
750 if builtin_on_connect:
751 event.listen(pool, "connect", builtin_on_connect)
752
753 def first_connect(
754 dbapi_connection: DBAPIConnection,
755 connection_record: ConnectionPoolEntry,
756 ) -> None:
757 c = base.Connection(
758 engine,
759 connection=_AdhocProxiedConnection(
760 dbapi_connection, connection_record
761 ),
762 _has_events=False,
763 # reconnecting will be a reentrant condition, so if the
764 # connection goes away, Connection is then closed
765 _allow_revalidate=False,
766 # dont trigger the autobegin sequence
767 # within the up front dialect checks
768 _allow_autobegin=False,
769 )
770 c._execution_options = util.EMPTY_DICT
771
772 try:
773 dialect.initialize(c)
774 finally:
775 # note that "invalidated" and "closed" are mutually
776 # exclusive in 1.4 Connection.
777 if not c.invalidated and not c.closed:
778 # transaction is rolled back otherwise, tested by
779 # test/dialect/postgresql/test_dialect.py
780 # ::MiscBackendTest::test_initial_transaction_state
781 dialect.do_rollback(c.connection)
782
783 # previously, the "first_connect" event was used here, which was then
784 # scaled back if the "on_connect" handler were present. now,
785 # since "on_connect" is virtually always present, just use
786 # "connect" event with once_unless_exception in all cases so that
787 # the connection event flow is consistent in all cases.
788 event.listen(
789 pool, "connect", first_connect, _once_unless_exception=True
790 )
791
792 dialect_cls.engine_created(engine)
793 if entrypoint is not dialect_cls:
794 entrypoint.engine_created(engine)
795
796 for plugin in plugins:
797 plugin.engine_created(engine)
798
799 return engine
800
801
802def engine_from_config(
803 configuration: Dict[str, Any], prefix: str = "sqlalchemy.", **kwargs: Any
804) -> Engine:
805 """Create a new Engine instance using a configuration dictionary.
806
807 The dictionary is typically produced from a config file.
808
809 The keys of interest to ``engine_from_config()`` should be prefixed, e.g.
810 ``sqlalchemy.url``, ``sqlalchemy.echo``, etc. The 'prefix' argument
811 indicates the prefix to be searched for. Each matching key (after the
812 prefix is stripped) is treated as though it were the corresponding keyword
813 argument to a :func:`_sa.create_engine` call.
814
815 The only required key is (assuming the default prefix) ``sqlalchemy.url``,
816 which provides the :ref:`database URL <database_urls>`.
817
818 A select set of keyword arguments will be "coerced" to their
819 expected type based on string values. The set of arguments
820 is extensible per-dialect using the ``engine_config_types`` accessor.
821
822 :param configuration: A dictionary (typically produced from a config file,
823 but this is not a requirement). Items whose keys start with the value
824 of 'prefix' will have that prefix stripped, and will then be passed to
825 :func:`_sa.create_engine`.
826
827 :param prefix: Prefix to match and then strip from keys
828 in 'configuration'.
829
830 :param kwargs: Each keyword argument to ``engine_from_config()`` itself
831 overrides the corresponding item taken from the 'configuration'
832 dictionary. Keyword arguments should *not* be prefixed.
833
834 """
835
836 options = {
837 key[len(prefix) :]: configuration[key]
838 for key in configuration
839 if key.startswith(prefix)
840 }
841 options["_coerce_config"] = True
842 options.update(kwargs)
843 url = options.pop("url")
844 return create_engine(url, **options)
845
846
847@overload
848def create_pool_from_url(
849 url: Union[str, URL],
850 *,
851 poolclass: Optional[Type[Pool]] = ...,
852 logging_name: str = ...,
853 pre_ping: bool = ...,
854 size: int = ...,
855 recycle: int = ...,
856 reset_on_return: Optional[_ResetStyleArgType] = ...,
857 timeout: float = ...,
858 use_lifo: bool = ...,
859 **kwargs: Any,
860) -> Pool: ...
861
862
863@overload
864def create_pool_from_url(url: Union[str, URL], **kwargs: Any) -> Pool: ...
865
866
867def create_pool_from_url(url: Union[str, URL], **kwargs: Any) -> Pool:
868 """Create a pool instance from the given url.
869
870 If ``poolclass`` is not provided the pool class used
871 is selected using the dialect specified in the URL.
872
873 The arguments passed to :func:`_sa.create_pool_from_url` are
874 identical to the pool argument passed to the :func:`_sa.create_engine`
875 function.
876
877 .. versionadded:: 2.0.10
878 """
879
880 for key in _pool_translate_kwargs:
881 if key in kwargs:
882 kwargs[_pool_translate_kwargs[key]] = kwargs.pop(key)
883
884 engine = create_engine(url, **kwargs, _initialize=False)
885 return engine.pool
886
887
888_pool_translate_kwargs = immutabledict(
889 {
890 "logging_name": "pool_logging_name",
891 "echo": "echo_pool",
892 "timeout": "pool_timeout",
893 "recycle": "pool_recycle",
894 "events": "pool_events", # deprecated
895 "reset_on_return": "pool_reset_on_return",
896 "pre_ping": "pool_pre_ping",
897 "use_lifo": "pool_use_lifo",
898 }
899)
900