Merge remote-tracking branch 'origin/main' into ami/pydantic-jsonb

Author: amanmibra

docs/advanced/index.md

@@ -1,10 +1,16 @@
 # Advanced User Guide
 
-The **Advanced User Guide** is gradually growing, you can already read about some advanced topics.
+The **Advanced User Guide** covers advanced topics and features of SQLModel.
 
-At some point it will include:
+Current topics include:
 
-* How to use `async` and `await` with the async session.
-* How to run migrations.
-* How to combine **SQLModel** models with SQLAlchemy.
+* [Working with Decimal Fields](decimal.md) - How to handle decimal numbers in SQLModel
+* [Working with UUID Fields](uuid.md) - How to use UUID fields in your models
+* [Storing Pydantic Models in JSONB Columns](pydantic-jsonb.md) - How to store and work with Pydantic models in JSONB columns
+
+Coming soon:
+
+* How to use `async` and `await` with the async session
+* How to run migrations
+* How to combine **SQLModel** models with SQLAlchemy
 * ...and more. 🤓

docs/advanced/pydantic-jsonb.md

@@ -0,0 +1,74 @@
+# Storing Pydantic Models in JSONB Columns
+
+You can store Pydantic models (and lists or dicts of them) in JSON or JSONB database columns using the `PydanticJSONB` utility.
+
+This is especially useful when:
+
+- You want to persist flexible, nested data structures in your models.
+- You prefer to avoid separate relational tables for structured fields like metadata, config, or address.
+- You want automatic serialization and deserialization using Pydantic.
+
+## Usage
+
+You can use it with SQLModel like this:
+
+```python
+from typing import Optional
+from pydantic import BaseModel
+from sqlmodel import SQLModel, Field, Column
+from sqlmodel.sql.sqltypes import PydanticJSONB
+
+class Address(BaseModel):
+    street: str
+    city: str
+
+class User(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str
+    address: Address = Field(sa_column=Column(PydanticJSONB(Address)))
+```
+
+This will store the `address` field as a `JSONB` column in PostgreSQL and automatically serialize/deserialize to and from the `Address` Pydantic model.
+
+If you're using a list or dict of models, `PydanticJSONB` supports that too:
+
+```python
+Field(sa_column=Column(PydanticJSONB(List[SomeModel])))
+Field(sa_column=Column(PydanticJSONB(Dict[str, SomeModel])))
+```
+
+## Requirements
+
+* PostgreSQL (for full `JSONB` support).
+* Pydantic v2.
+* SQLAlchemy 2.x.
+
+## Limitations
+
+### Nested Model Updates
+
+Currently, updating attributes inside a nested Pydantic model doesn't automatically trigger a database update. This is similar to how plain dictionaries work in SQLAlchemy. For example:
+
+```python
+# This won't trigger a database update
+row = select(...)  # some MyTable row
+row.data.x = 1
+db.add(row)  # no effect, change isn't detected
+```
+
+To update nested model attributes, you need to reassign the entire model:
+
+```python
+# Workaround: Create a new instance and reassign
+updated = ExtraData(**row.data.model_dump())
+updated.x = 1
+row.data = updated
+db.add(row)
+```
+
+This limitation will be addressed in a future update using `MutableDict` to enable change tracking for nested fields. The `MutableDict` implementation will emit change events when the contents of the dictionary are altered, including when values are added or removed.
+
+## Notes
+
+* Falls back to `JSON` if `JSONB` is not available.
+* Only tested with PostgreSQL at the moment.

docs/databases.md

@@ -68,7 +68,7 @@ There are many databases of many types.
 
 A database could be a single file called `heroes.db`, managed with code in a very efficient way. An example would be SQLite, more about that in a bit.
 
-![database as a single file](img/databases/single-file.svg)
+![database as a single file](img/databases/single-file.drawio.svg)
 
 ### A server database
 
@@ -80,11 +80,11 @@ In this case, your code would talk to this server application instead of reading
 
 The database could be located in a different server/machine:
 
-![database in an external server](img/databases/external-server.svg)
+![database in an external server](img/databases/external-server.drawio.svg)
 
 Or the database could be located in the same server/machine:
 
-![database in the same server](img/databases/same-server.svg)
+![database in the same server](img/databases/same-server.drawio.svg)
 
 The most important aspect of these types of databases is that **your code doesn't read or modify** the files containing the data directly.
 
@@ -98,7 +98,7 @@ In some cases, the database could even be a group of server applications running
 
 In this case, your code would talk to one or more of these server applications running on different machines.
 
-![distributed database in multiple servers](img/databases/multiple-servers.svg)
+![distributed database in multiple servers](img/databases/multiple-servers.drawio.svg)
 
 Most of the databases that work as server applications also support multiple servers in one way or another.
 
@@ -257,7 +257,7 @@ For example, the table for the teams has the ID `1` for the team `Preventers` an
 
 As these **primary key** IDs can uniquely identify each row on the table for teams, we can now go to the table for heroes and refer to those IDs in the table for teams.
 
-![table relationships](img/databases/relationships.svg)
+![table relationships](img/databases/relationships.drawio.svg)
 
 So, in the table for heroes, we use the `team_id` column to define a relationship to the *foreign* table for teams. Each value in the `team_id` column on the table with heroes will be the same value as the `id` column of one row in the table with teams.
 

docs/db-to-code.md

@@ -279,7 +279,7 @@ For example this **Relation** or table:
 
 * **Mapper**: this comes from Math, when there's something that can convert from some set of things to another, that's called a "**mapping function**". That's where the **Mapper** comes from.
 
-![Squares to Triangles Mapper](img/db-to-code/mapper.svg)
+![Squares to Triangles Mapper](img/db-to-code/mapper.drawio.svg)
 
 We could also write a **mapping function** in Python that converts from the *set of lowercase letters* to the *set of uppercase letters*, like this: