Debian Codegraph @

docs/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin.rst

raw
1 SQLAlchemy Init Plugin
2 ----------------------
3
4 The :class:`SQLAlchemyInitPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyInitPlugin>` adds functionality to the
5 application that supports using Litestar with `SQLAlchemy <http://www.sqlalchemy.org/>`_.
6
7 The plugin:
8
9 - Makes the SQLAlchemy engine and session available via dependency injection.
10 - Manages the SQLAlchemy engine and session factory in the application's state.
11 - Configures a ``before_send`` handler that is called before sending a response.
12 - Includes relevant names in the signature namespace to aid resolving annotated types.
13
14 Dependencies
15 ============
16
17 The plugin makes the engine and session available for injection.
18
19 .. tab-set::
20
21 .. tab-item:: Async
22
23 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_dependencies.py
24 :caption: SQLAlchemy Async Dependencies
25 :language: python
26 :linenos:
27
28 .. tab-item:: Sync
29
30 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_dependencies.py
31 :caption: SQLAlchemy Sync Dependencies
32 :language: python
33 :linenos:
34
35 The above example illustrates how to access the engine and session in the handler, and like all other dependencies, they
36 can also be injected into other dependency functions.
37
38 Renaming the dependencies
39 #########################
40
41 You can change the name that the engine and session are bound to by setting the
42 :attr:`engine_dependency_key <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig.engine_dependency_key>`
43 and :attr:`session_dependency_key <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig.session_dependency_key>`
44 attributes on the plugin configuration.
45
46 Configuring the before send handler
47 ###################################
48
49 The plugin configures a ``before_send`` handler that is called before sending a response. The default handler closes the
50 session and removes it from the connection scope.
51
52 You can change the handler by setting the
53 :attr:`before_send_handler <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig.before_send_handler>`
54 attribute on the configuration object. For example, an alternate handler is available that will also commit the session
55 on success and rollback upon failure.
56
57 .. tab-set::
58
59 .. tab-item:: Async
60
61 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_before_send_handler.py
62 :caption: SQLAlchemy Async Before Send Handler
63 :language: python
64 :linenos:
65
66 .. tab-item:: Sync
67
68 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_before_send_handler.py
69 :caption: SQLAlchemy Sync Before Send Handler
70 :language: python
71 :linenos:
72
73 Configuring the plugins
74 #######################
75
76 Both the :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig>` and the
77 :class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemySyncConfig>` have an ``engine_config``
78 attribute that is used to configure the engine. The ``engine_config`` attribute is an instance of
79 :class:`EngineConfig <advanced_alchemy.extensions.litestar.EngineConfig>` and exposes all of the configuration options
80 available to the SQLAlchemy engine.
81
82 The :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig>` class and the
83 :class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemySyncConfig>` class also have a
84 ``session_config`` attribute that is used to configure the session. This is either an instance of
85 :class:`AsyncSessionConfig <advanced_alchemy.extensions.litestar.AsyncSessionConfig>` or
86 :class:`SyncSessionConfig <advanced_alchemy.extensions.litestar.SyncSessionConfig>` depending on the type of config
87 object. These classes expose all of the configuration options available to the SQLAlchemy session.
88
89 Finally, the :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig>` class and the
90 :class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemySyncConfig>` class expose configuration
91 options to control their behavior.
92
93 Consult the reference documentation for more information.
94
95 Example
96 =======
97
98 The below example is a complete demonstration of use of the init plugin. Readers who are familiar with the prior section
99 may note the additional complexity involved in managing the conversion to and from SQLAlchemy objects within the
100 handlers. Read on to see how this increased complexity is efficiently handled by the
101 :class:`SQLAlchemySerializationPlugin <advanced_alchemy.extensions.litestar.SQLAlchemySerializationPlugin>`.
102
103 .. tab-set::
104
105 .. tab-item:: Async
106
107 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_init_plugin_example.py
108 :caption: SQLAlchemy Async Init Plugin Example
109 :language: python
110 :linenos:
111
112 .. tab-item:: Sync
113
114 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_init_plugin_example.py
115 :caption: SQLAlchemy Sync Init Plugin Example
116 :language: python
117 :linenos: