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