Skip to content

Commit da055eb

Browse files
tiangolotiangolo
committed
📝 Add README.md
1 parent 0f01b75 commit da055eb

File tree

1 file changed

+215
-0
lines changed

1 file changed

+215
-0
lines changed

‎README.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
<p align="center">
2+
<a href="https://sqlmodel.tiangolo.com"><img src="https://sqlmodel.tiangolo.com/img/logo-margin/logo-margin-vector.svg" alt="SQLModel"></a>
3+
</p>
4+
<p align="center">
5+
<em>SQLModel, SQL databases in Python, designed for simplicity, compatibility, and robustness.</em>
6+
</p>
7+
<p align="center">
8+
<a href="https://github.com/tiangolo/sqlmodel/actions?query=workflow%3ATest" target="_blank">
9+
<img src="https://github.com/tiangolo/sqlmodel/workflows/Test/badge.svg" alt="Test">
10+
</a>
11+
<a href="https://github.com/tiangolo/sqlmodel/actions?query=workflow%3APublish" target="_blank">
12+
<img src="https://github.com/tiangolo/sqlmodel/workflows/Publish/badge.svg" alt="Publish">
13+
</a>
14+
<a href="https://codecov.io/gh/tiangolo/sqlmodel" target="_blank">
15+
<img src="https://img.shields.io/codecov/c/github/tiangolo/sqlmodel?color=%2334D058" alt="Coverage">
16+
</a>
17+
<a href="https://pypi.org/project/sqlmodel" target="_blank">
18+
<img src="https://img.shields.io/pypi/v/sqlmodel?color=%2334D058&label=pypi%20package" alt="Package version">
19+
</a>
20+
</p>
21+
22+
---
23+
24+
**Documentation**: <a href="https://sqlmodel.tiangolo.com" target="_blank">https://sqlmodel.tiangolo.com</a>
25+
26+
**Source Code**: <a href="https://github.com/tiangolo/sqlmodel" target="_blank">https://github.com/tiangolo/sqlmodel</a>
27+
28+
---
29+
30+
SQLModel is a library for interacting with <abbr title='Also called "Relational databases"'>SQL databases</abbr> from Python code, with Python objects. It is designed to be intuitive, easy to use, highly compatible, and robust.
31+
32+
**SQLModel** is based on Python type annotations, and powered by <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> and <a href="https://sqlalchemy.org/" class="external-link" target="_blank">SQLAlchemy</a>.
33+
34+
The key features are:
35+
36+
* **Intuitive to write**: Great editor support. <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.
37+
* **Easy to use**: It has sensible defaults and does a lot of work underneath to simplify the code you write.
38+
* **Compatible**: It is designed to be compatible with **FastAPI**, Pydantic, and SQLAlchemy.
39+
* **Extensible**: You have all the power of SQLAlchemy and Pydantic underneath.
40+
* **Short**: Minimize code duplication. A single type annotation does a lot of work. No need to duplicate models in SQLAlchemy and Pydantic.
41+
42+
## SQL Databases in FastAPI
43+
44+
<a href="https://fastapi.tiangolo.com" target="_blank"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" style="width: 20%;"></a>
45+
46+
**SQLModel** is designed to simplify interacting with SQL databases in <a href="https://fastapi.tiangolo.com" class="external-link" target="_blank">FastAPI</a> applications, it was created by the same <a href="https://tiangolo.com/" class="external-link" target="_blank">author</a>. 😁
47+
48+
It combines SQLAlchemy and Pydantic and tries to simplify the code you write as much as possible, allowing you to reduce the **code duplication to a minimum**, but while getting the **best developer experience** possible.
49+
50+
**SQLModel** is, in fact, a thin layer on top of **Pydantic** and **SQLAlchemy**, carefully designed to be compatible with both.
51+
52+
## Requirements
53+
54+
A recent and currently supported version of Python (right now, <a href="https://www.python.org/downloads/" class="external-link" target="_blank">Python supports versions 3.6 and above</a>).
55+
56+
As **SQLModel** is based on **Pydantic** and **SQLAlchemy**, it requires them. They will be automatically installed when you install SQLModel.
57+
58+
## Installation
59+
60+
<div class="termy">
61+
62+
```console
63+
$ pip install sqlmodel
64+
---> 100%
65+
Successfully installed sqlmodel
66+
```
67+
68+
</div>
69+
70+
## Example
71+
72+
For an introduction to databases, SQL, and everything else, see the <a href="https://sqlmodel.tiangolo.com" target="_blank">SQLModel documentation</a>.
73+
74+
Here's a quick example. ✨
75+
76+
### A SQL Table
77+
78+
Imagine you have a SQL table called `hero` with:
79+
80+
* `id`
81+
* `name`
82+
* `secret_name`
83+
* `age`
84+
85+
And you want it to have this data:
86+
87+
| id | name | secret_name | age |
88+
-----|------|-------------|------|
89+
| 1 | Deadpond | Dive Wilson | null |
90+
| 2 | Spider-Boy | Pedro Parqueador | null |
91+
| 3 | Rusty-Man | Tommy Sharp | 48 |
92+
93+
### Create a SQLModel Model
94+
95+
Then you could create a **SQLModel** model like this:
96+
97+
```Python
98+
from typing import Optional
99+
100+
from sqlmodel import Field, SQLModel
101+
102+
103+
class Hero(SQLModel, table=True):
104+
id: Optional[int] = Field(default=None, primary_key=True)
105+
name: str
106+
secret_name: str
107+
age: Optional[int] = None
108+
```
109+
110+
That class `Hero` is a **SQLModel** model, the equivalent of a SQL table in Python code.
111+
112+
And each of those class attributes is equivalent to each **table column**.
113+
114+
### Create Rows
115+
116+
Then you could **create each row** of the table as an **instance** of the model:
117+
118+
```Python
119+
hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
120+
hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
121+
hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)
122+
```
123+
124+
This way, you can use conventional Python code with **classes** and **instances** that represent **tables** and **rows**, and that way communicate with the **SQL database**.
125+
126+
### Editor Support
127+
128+
Everything is designed for you to get the best developer experience possible, with the best editor support.
129+
130+
Including **autocompletion**:
131+
132+
<img class="shadow" src="https://sqlmodel.tiangolo.com/img/index/autocompletion01.png">
133+
134+
And **inline errors**:
135+
136+
<img class="shadow" src="https://sqlmodel.tiangolo.com/img/index/inline-errors01.png">
137+
138+
### Write to the Database
139+
140+
You can learn a lot more about **SQLModel** by quickly following the **tutorial**, but if you need a taste right now of how to put all that together and save to the database, you can do this:
141+
142+
```Python hl_lines="18 21 23-27"
143+
from typing import Optional
144+
145+
from sqlmodel import Field, Session, SQLModel, create_engine
146+
147+
148+
class Hero(SQLModel, table=True):
149+
id: Optional[int] = Field(default=None, primary_key=True)
150+
name: str
151+
secret_name: str
152+
age: Optional[int] = None
153+
154+
155+
hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
156+
hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
157+
hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)
158+
159+
160+
engine = create_engine("sqlite:///database.db")
161+
162+
163+
SQLModel.metadata.create_all(engine)
164+
165+
with Session(engine) as session:
166+
session.add(hero_1)
167+
session.add(hero_2)
168+
session.add(hero_3)
169+
session.commit()
170+
```
171+
172+
That will save a **SQLite** database with the 3 heroes.
173+
174+
### Select from the Database
175+
176+
Then you could write queries to select from that same database, for example with:
177+
178+
```Python hl_lines="15-18"
179+
from typing import Optional
180+
181+
from sqlmodel import Field, Session, SQLModel, create_engine, select
182+
183+
184+
class Hero(SQLModel, table=True):
185+
id: Optional[int] = Field(default=None, primary_key=True)
186+
name: str
187+
secret_name: str
188+
age: Optional[int] = None
189+
190+
191+
engine = create_engine("sqlite:///database.db")
192+
193+
with Session(engine) as session:
194+
statement = select(Hero).where(Hero.name == "Spider-Boy")
195+
hero = session.exec(statement).first()
196+
print(hero)
197+
```
198+
199+
### Editor Support Everywhere
200+
201+
**SQLModel** was carefully designed to give you the best developer experience and editor support, **even after selecting data** from the database:
202+
203+
<img class="shadow" src="https://sqlmodel.tiangolo.com/img/index/autocompletion02.png">
204+
205+
## SQLAlchemy and Pydantic
206+
207+
That class `Hero` is a **SQLModel** model.
208+
209+
But at the same time, ✨ it is a **SQLAlchemy** model ✨. So, you can combine it and use it with other SQLAlchemy models, or you could easily migrate applications with SQLAlchemy to **SQLModel**.
210+
211+
And at the same time, ✨ it is also a **Pydantic** model ✨. You can use inheritance with it to define all your **data models** while avoiding code duplication. That makes it very easy to use with **FastAPI**.
212+
213+
## License
214+
215+
This project is licensed under the terms of the MIT license.

0 commit comments

Comments
 (0)