Debian Codegraph @

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

raw
1 SQLAlchemy Plugin
2 -----------------
3
4 The :class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyPlugin>` provides complete support for
5 working with `SQLAlchemy <https://www.sqlalchemy.org/>`_ in Litestar applications.
6
7 .. note::
8
9 This plugin is only compatible with SQLAlchemy 2.0+.
10
11 The :class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyPlugin>` combines the functionality of
12 :class:`SQLAlchemyInitPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyInitPlugin>` and
13 :class:`SQLAlchemySerializationPlugin <advanced_alchemy.extensions.litestar.SQLAlchemySerializationPlugin>`, each of
14 which are examined in detail in the following sections. As such, this section describes a complete example of using the
15 :class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyPlugin>` with a Litestar application and a
16 SQLite database.
17
18 Or, skip ahead to :doc:`/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin` or
19 :doc:`/usage/databases/sqlalchemy/plugins/sqlalchemy_serialization_plugin` to learn more about the individual plugins.
20
21 .. tip::
22
23 You can install SQLAlchemy alongside Litestar by running ``pip install 'litestar[sqlalchemy]'``.
24
25 Example
26 =======
27
28 .. tab-set::
29
30 .. tab-item:: Async
31
32 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_plugin_example.py
33 :caption: SQLAlchemy Async Plugin Example
34 :language: python
35 :linenos:
36
37 .. tab-item:: Sync
38
39 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_plugin_example.py
40 :caption: SQLAlchemy Sync Plugin Example
41 :language: python
42 :linenos:
43
44 Defining the Database Models
45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46
47 We start by defining our base model class, and a ``TodoItem`` class which extends the base model. The ``TodoItem`` class
48 represents a todo item in our SQLite database.
49
50 .. tab-set::
51
52 .. tab-item:: Async
53
54 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_plugin_example.py
55 :caption: SQLAlchemy Async Plugin Example
56 :language: python
57 :lines: 6,16-25
58
59 .. tab-item:: Sync
60
61 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_plugin_example.py
62 :caption: SQLAlchemy Sync Plugin Example
63 :language: python
64 :lines: 6,16-25
65
66 Setting Up an API Endpoint
67 ~~~~~~~~~~~~~~~~~~~~~~~~~~
68
69 Next, we set up an API endpoint at the root (``"/"``) that allows adding a ``TodoItem`` to the SQLite database.
70
71 .. tab-set::
72
73 .. tab-item:: Async
74
75 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_plugin_example.py
76 :caption: SQLAlchemy Async Plugin Example
77 :language: python
78 :lines: 3-5,8-9,11-15,26-32
79
80 .. tab-item:: Sync
81
82 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_plugin_example.py
83 :caption: SQLAlchemy Sync Plugin Example
84 :language: python
85 :lines: 3-5,8-9,11-15,26-32
86
87 Initializing the Database
88 ~~~~~~~~~~~~~~~~~~~~~~~~~
89
90 We create a function ``init_db`` that we'll use to initialize the database when the app starts up.
91
92 .. important::
93
94 In this example we drop the database before creating it. This is done for the sake of repeatability, and should not
95 be done in production.
96
97 .. tab-set::
98
99 .. tab-item:: Async
100
101 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_plugin_example.py
102 :caption: SQLAlchemy Async Plugin Example
103 :language: python
104 :lines: 10,32-36
105
106 .. tab-item:: Sync
107
108 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_plugin_example.py
109 :caption: SQLAlchemy Sync Plugin Example
110 :language: python
111 :lines: 10,32-34
112
113 Setting Up the Plugin and the App
114 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115
116 Finally, we set up the SQLAlchemy Plugin and the Litestar app.
117
118 .. tab-set::
119
120 .. tab-item:: Async
121
122 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_plugin_example.py
123 :caption: SQLAlchemy Async Plugin Example
124 :language: python
125 :lines: 8,32-36
126
127 .. tab-item:: Sync
128
129 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_plugin_example.py
130 :caption: SQLAlchemy Sync Plugin Example
131 :language: python
132 :lines: 10,32-34
133
134 This configures the app with the plugin, sets up a route handler for adding items, and specifies that the ``init_db``
135 function should be run when the app starts up.
136
137 Running the App
138 ~~~~~~~~~~~~~~~
139
140 Run the app with the following command:
141
142 .. code-block:: bash
143
144 $ litestar run
145
146 You can now add a todo item by sending a POST request to ``http://localhost:8000`` with a JSON body containing the
147 ``"title"`` of the todo item.
148
149 .. code-block:: bash
150
151 $ curl -X POST -H "Content-Type: application/json" -d '{"title": "Your Todo Title", "done": false}' http://localhost:8000/