-
-
Notifications
You must be signed in to change notification settings - Fork 782
📝 Add tutorial and advanced page for EncryptedType
#1574
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
📝 Docs preview for commit beb184f at: https://22b95713.sqlmodel.pages.dev
Modified Pages
williambdean
commented
Oct 6, 2025
I am seeing in the sqlalchemy-utils docs that EncryptionType is deprecating in favor StringEncryptedType. Maybe good to swap out. https://sqlalchemy-utils.readthedocs.io/en/latest/data_types.html#encryptedtype
EncryptedType (追記ここまで)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ravishan16, thank you for your interest and efforts!
The example is interesting, but I think this should be a section of docs about sa_column property (the code example boils down to just using sa_column to specify SQLAlchemy type for the field).
I also don't think we should add 2 sections about this. I think it should be in Advanced section only.
What do you think?
...ueness tutorials; remove deprecated encrypted-type page; update nav and run notes
f4ae1b4 to
00b594f
Compare
...t with sa_column; tidy examples and messages
@ravishan16, thank you for your interest and efforts!
The example is interesting, but I think this should be a section of docs about
sa_columnproperty (the code example boils down to just usingsa_columnto specify SQLAlchemy type for the field).I also don't think we should add 2 sections about this. I think it should be in Advanced section only.
What do you think?
Thanks @YuriiMotov for the thoughtful feedback, completely agree. I’ve reworked this into a single Advanced page focused on sa_column. The encryption piece is now just one example of passing a fully configured SQLAlchemy Column, rather than a standalone "encrypted type" doc.
Summary of changes:
• Consolidated content into a single Advanced doc: sa-column.md
• Replaced the deprecated EncryptedType with sqlalchemy_utils.StringEncryptedType (with a short note explaining why) as suggested by @williambdean
• Added a second small example to show versatility: enforcing uniqueness via sa_column and a composite UniqueConstraint
• Ensured examples are runnable and consistent
• Removed the old encrypted-type page and updated navigation accordingly
If you’d prefer to keep just one example (e.g., only the encrypted field) or adjust the tone/titles, I’m happy to trim or tweak as needed or you can change it as needed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ravishan16, thank you!
It's already very helpful! But I think we should try to make the style more consistent with other sections. Please, take a look at my comments below.
As for enforcing uniqueness use case - I don't see any advantage of using Column here. I would remove this part to not overload docs with. We can later add more use-cases.
Also, I think we should create a sub-group inside Advanced section like Advanced Column Configuration (let's think about the name, this is just a suggestion) where we will place all things related to customization with sa_column, sa_column_args, sa_type, sa_column_kwargs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It would be nice to explain this in a bit more details, make it a bit more entertaining and step-by-step.
Something like (very raw draft):
Remember we have
secret_namefields for every Hero?
What if the DB leakage happens and all data becomes public? Everyone will know secret names of our heroes.. 😱
Let's try to mitigate such security risks by introducing data encryption for sensitive data.
All we need is to useStringEncryptedTypeDB type forsecret_name
An then add a part of code example (only related lines with most important lines highlighted) like this
{* ./docs_src/advanced/sa_column/tutorial001.py ln[1:28] hl[4:8,11:12,20:26] *}
Then describe in short what is happening in select_heroes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should use standardized text for installation part (see how it's done for fastapi-related section) and move it to the beginning (inside ## Use case: encrypted field with a custom type)
## Use case: encrypted field with a custom type
### Install `sqlalchemy-utils` and `cryptography` packeges
The first step is to install `sqlalchemy-utils` and `cryptography` packeges.
Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install them, for example with:
<div class="termy">
```console
$ pip install sqlmodel sqlalchemy-utils cryptography
---> 100%
```
</div>
Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com>
Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com>
Closes #447
This pull request adds documentation for using EncryptedType with SQLModel. It includes: