By defining an ormar Model you get corresponding Pydantic model as well as Sqlalchemy table for free.
They are being managed in the background and you do not have to create them on your own.
Model Class
To build an ormar model you simply need to inherit a ormar.Model class.
Note that if you need a normal pydantic field in your model (used to store value on model or pass around some value) you can define a
field with parameter pydantic_only=True.
Fields created like this are added to the pydantic model fields -> so are subject to validation according to Field type,
also appear in dict() and json() result.
The difference is that those fields are not saved in the database. So they won't be included in underlying sqlalchemy columns,
or table variables (check Internals section below to see how you can access those if you need).
Subsequently pydantic_only fields won't be included in migrations or any database operation (like save, update etc.)
Fields like those can be passed around into payload in fastapi request and will be returned in fastapi response
(of course only if you set their value somewhere in your code as the value is not fetched from the db.
If you pass a value in fastapirequest and return the same instance that fastapi constructs for you in request_model
you should get back exactly same value in response.).
Warning
pydantic_only=True fields are always Optional and it cannot be changed (otherwise db load validation would fail)
Tip
pydantic_only=True fields are a good solution if you need to pass additional information from outside of your API
(i.e. frontend). They are not stored in db but you can access them in your APIRoute code and they also have pydantic validation.
If you combine pydantic_only=True field with default parameter and do not pass actual value in request you will always get default value.
Since it can be a function you can set default=datetime.datetime.now and get current timestamp each time you call an endpoint etc.
Note
Note that both pydantic_only and property_field decorated field can be included/excluded in both dict() and fastapi
response with include/exclude and response_model_include/response_model_exclude accordingly.
# <==related of code removed for clarity==>classUser(ormar.Model):classMeta:tablename:str="users2"metadata=metadatadatabase=databaseid:int=ormar.Integer(primary_key=True)email:str=ormar.String(max_length=255,nullable=False)password:str=ormar.String(max_length=255)first_name:str=ormar.String(max_length=255)last_name:str=ormar.String(max_length=255)category:str=ormar.String(max_length=255,nullable=True)timestamp:datetime.datetime=ormar.DateTime(pydantic_only=True,default=datetime.datetime.now)# <==related of code removed for clarity==>app=FastAPI()@app.post("/users/")asyncdefcreate_user(user:User):returnawaituser.save()# <==related of code removed for clarity==>deftest_excluding_fields_in_endpoints():client=TestClient(app)withclientasclient:timestamp=datetime.datetime.now()user={"email":"test@domain.com","password":"^*^%A*DA*IAAA","first_name":"John","last_name":"Doe","timestamp":str(timestamp),}response=client.post("/users/",json=user)assertlist(response.json().keys())==["id","email","first_name","last_name","category","timestamp",]# returned is the same timestampassertresponse.json().get("timestamp")==str(timestamp).replace(" ","T")# <==related of code removed for clarity==>
Property fields
Sometimes it's desirable to do some kind of calculation on the model instance. One of the most common examples can be concatenating
two or more fields. Imagine you have first_name and last_name fields on your model, but would like to have full_name in the result
of the fastapi query.
You can create a new pydantic model with a method that accepts only self (so like default python @property)
and populate it in your code.
But it's so common that ormar has you covered. You can "materialize" a property_field on you Model.
Warning
property_field fields are always Optional and it cannot be changed (otherwise db load validation would fail)
The decorated function has to accept only one parameter, and that parameter have to be self.
If you try to decorate a function with more parameters ormar will raise ModelDefinitionError.
Sample:
1 2 3 4 5 6 7 8 910
# will raise ModelDefinitionError@property_fielddefprefixed_name(self,prefix="prefix_"):return'custom_prefix__'+self.name# will raise ModelDefinitionError # (calling first param something else than 'self' is a bad practice anyway)@property_fielddefprefixed_name(instance):return'custom_prefix__'+self.name
Note that property_field decorated methods do not go through verification (but that might change in future) and are only available
in the response from fastapi and dict() and json() methods. You cannot pass a value for this field in the request
(or rather you can but it will be discarded by ormar so really no point but no Exception will be raised).
Note
Note that both pydantic_only and property_field decorated field can be included/excluded in both dict() and fastapi
response with include/exclude and response_model_include/response_model_exclude accordingly.
Tip
Note that @property_field decorator is designed to replace the python @property decorator, you do not have to combine them.
In theory you can cause ormar have a failsafe mechanism, but note that i.e. mypy will complain about re-decorating a property.
12345
# valid and working but unnecessary and mypy will complain@property_field@propertydefprefixed_name(self):return'custom_prefix__'+self.name
# <==related of code removed for clarity==>defgen_pass():# note: NOT production ready choices=string.ascii_letters+string.digits+"!@#$%^&*()"return"".join(random.choice(choices)for_inrange(20))classRandomModel(ormar.Model):classMeta:tablename:str="random_users"metadata=metadatadatabase=databaseinclude_props_in_dict=Trueid:int=ormar.Integer(primary_key=True)password:str=ormar.String(max_length=255,default=gen_pass)first_name:str=ormar.String(max_length=255,default="John")last_name:str=ormar.String(max_length=255)created_date:datetime.datetime=ormar.DateTime(server_default=sqlalchemy.func.now())@property_fielddeffull_name(self)->str:return" ".join([self.first_name,self.last_name])# <==related of code removed for clarity==>app=FastAPI()# explicitly exclude property_field in this endpoint@app.post("/random/",response_model=RandomModel,response_model_exclude={"full_name"})asyncdefcreate_user(user:RandomModel):returnawaituser.save()# <==related of code removed for clarity==>deftest_excluding_property_field_in_endpoints2():client=TestClient(app)withclientasclient:RandomModel.Meta.include_props_in_dict=Trueuser3={"last_name":"Test"}response=client.post("/random3/",json=user3)assertlist(response.json().keys())==["id","password","first_name","last_name","created_date",]# despite being decorated with property_field if you explictly exclude it it will be goneassertresponse.json().get("full_name")isNone# <==related of code removed for clarity==>
Fields names vs Column names
By default names of the fields will be used for both the underlying pydantic model and sqlalchemy table.
If for whatever reason you prefer to change the name in the database but keep the name in the model you can do this
with specifying name parameter during Field declaration
If you want to customize the queries run by ormar you can define your own queryset class (that extends the ormar QuerySet) in your model class, default one is simply the QuerySet
You can provide a new class in Meta configuration of your class as queryset_class parameter.
importormarfromormar.queryset.querysetimportQuerySetfromfastapiimportHTTPExceptionclassMyQuerySetClass(QuerySet):asyncdeffirst_or_404(self,*args,**kwargs):entity=awaitself.get_or_none(*args,**kwargs)ifentityisNone:# in fastapi or starletteraiseHTTPException(404)classBook(ormar.Model):classMeta(ormar.ModelMeta):metadata=metadatadatabase=databasetablename="book"queryset_class=MyQuerySetClassid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=32)# when book not found, raise `404` in your view.book=awaitBook.objects.first_or_404(name="123")
Type Hints & Legacy
Before version 0.4.0 ormar supported only one way of defining Fields on a Model using python type hints as pydantic.
Even if you use type hints ormar does not use them to construct pydantic fields!
Type hints are there only to support static checkers and linting,
ormar construct annotations used by pydantic from own fields.
Dependencies
Since ormar depends on databases and sqlalchemy-core for database connection
and table creation you need to assign each Model with two special parameters.
fromtypingimportOptionalimportdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///test.db",force_rollback=True)metadata=sqlalchemy.MetaData()# note that you do not have to subclass ModelMeta,# it's useful for type hints and code completionclassMainMeta(ormar.ModelMeta):metadata=metadatadatabase=databaseclassArtist(ormar.Model):classMeta(MainMeta):# note that tablename is optional# if not provided ormar will user class.__name__.lower()+'s'# -> artists in this examplepassid:int=ormar.Integer(primary_key=True)first_name:str=ormar.String(max_length=100)last_name:str=ormar.String(max_length=100)born_year:int=ormar.Integer(name="year")classAlbum(ormar.Model):classMeta(MainMeta):passid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)artist:Optional[Artist]=ormar.ForeignKey(Artist)
Warning
You need to subclass your MainMeta class in each Model class as those classes store configuration variables
that otherwise would be overwritten by each Model.
Table Names
By default table name is created from Model class name as lowercase name plus 's'.
You can overwrite this parameter by providing Meta class tablename argument.
1 2 3 4 5 6 7 8 91011121314151617181920
importdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classCourse(ormar.Model):classMeta:# if you omit this parameter it will be created automatically# as class.__name__.lower()+'s' -> "courses" in this exampletablename="my_courses"database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)
Constraints
On a model level you can also set model-wise constraints on sql columns.
Right now only IndexColumns and UniqueColumns constraints are supported.
Note
Note that both constraints should be used only if you want to set a name on constraint or want to set the index on multiple columns, otherwise index and unique properties on ormar fields are preferred.
Tip
To read more about columns constraints like primary_key, unique, ForeignKey etc. visit fields.
UniqueColumns
You can set this parameter by providing Meta class constraints argument.
1 2 3 4 5 6 7 8 9101112131415161718192021
importdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classCourse(ormar.Model):classMeta:database=databasemetadata=metadata# define your constraints in Meta class of the model# it's a list that can contain multiple constraints# hera a combination of name and column will have to be unique in dbconstraints=[ormar.UniqueColumns("name","completed")]id:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)
Note
Note that constraints are meant for combination of columns that should be unique.
To set one column as unique use unique common parameter.
Of course you can set many columns as unique with this param but each of them will be checked separately.
IndexColumns
You can set this parameter by providing Meta class constraints argument.
1 2 3 4 5 6 7 8 9101112131415161718192021
importdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classCourse(ormar.Model):classMeta:database=databasemetadata=metadata# define your constraints in Meta class of the model# it's a list that can contain multiple constraints# hera a combination of name and column will have a compound index in the dbconstraints=[ormar.IndexColumns("name","completed")]id:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)
Note
Note that constraints are meant for combination of columns that should be in the index.
To set one column index use unique common parameter.
Of course, you can set many columns as indexes with this param but each of them will be a separate index.
Pydantic configuration
As each ormar.Model is also a pydantic model, you might want to tweak the settings of the pydantic configuration.
The way to do this in pydantic is to adjust the settings on the Config class provided to your model, and it works exactly the same for ormar models.
So in order to set your own preferences you need to provide not only the Meta class but also the Config class to your model.
Note
To read more about available settings visit the pydantic config page.
Note that if you do not provide your own configuration, ormar will do it for you.
The default config provided is as follows:
By default ormar forbids you to pass extra fields to Model.
If you try to do so the ModelError will be raised.
Since the extra fields cannot be saved in the database the default to disallow such fields seems a feasible option.
On the contrary in pydantic the default option is to ignore such extra fields, therefore ormar provides an Meta.extra setting to behave in the same way.
To ignore extra fields passed to ormar set this setting to Extra.ignore instead of default Extra.forbid.
Note that ormar does not allow accepting extra fields, you can only ignore them or forbid them (raise exception if present)
1 2 3 4 5 6 7 8 9101112
fromormarimportExtraclassChild(ormar.Model):classMeta(ormar.ModelMeta):tablename="children"metadata=metadatadatabase=databaseextra=Extra.ignore# set extra setting to prevent exceptions on extra fields presenceid:int=ormar.Integer(name="child_id",primary_key=True)first_name:str=ormar.String(name="fname",max_length=100)last_name:str=ormar.String(name="lname",max_length=100)
To set the same setting on all model check the best practices and BaseMeta concept.
Model sort order
When querying the database with given model by default the Model is ordered by the primary_key
column ascending. If you wish to change the default behaviour you can do it by providing orders_by
parameter to model Meta class.
Sample default ordering:
1 2 3 4 5 6 7 8 9101112131415
database=databases.Database(DATABASE_URL)metadata=sqlalchemy.MetaData()classBaseMeta(ormar.ModelMeta):metadata=metadatadatabase=database# default sort by column id ascendingclassAuthor(ormar.Model):classMeta(BaseMeta):tablename="authors"id:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)
Modified
1 2 3 4 5 6 7 8 910111213141516
database=databases.Database(DATABASE_URL)metadata=sqlalchemy.MetaData()classBaseMeta(ormar.ModelMeta):metadata=metadatadatabase=database# now default sort by name descendingclassAuthor(ormar.Model):classMeta(BaseMeta):tablename="authors"orders_by=["-name"]id:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)
Model Initialization
There are two ways to create and persist the Model instance in the database.
Tip
Use ipython to try this from the console, since it supports await.
If you plan to modify the instance in the later execution of your program you can initiate your Model as a normal class and later await a save() call.
1 2 3 4 5 6 7 8 91011121314151617181920212223
importdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classCourse(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)course=Course(name="Painting for dummies",completed=False)awaitcourse.save()awaitCourse.objects.create(name="Painting for dummies",completed=False)
If you want to initiate your Model and at the same time save in in the database use a QuerySet's method create().
For creating multiple objects at once a bulk_create() QuerySet's method is available.
Each model has a QuerySet initialised as objects parameter
1 2 3 4 5 6 7 8 91011121314151617181920212223
importdatabasesimportsqlalchemyimportormardatabase=databases.Database("sqlite:///db.sqlite")metadata=sqlalchemy.MetaData()classCourse(ormar.Model):classMeta:database=databasemetadata=metadataid:int=ormar.Integer(primary_key=True)name:str=ormar.String(max_length=100)completed:bool=ormar.Boolean(default=False)course=Course(name="Painting for dummies",completed=False)awaitcourse.save()awaitCourse.objects.create(name="Painting for dummies",completed=False)
Info
To read more about QuerySets (including bulk operations) and available methods visit queries
Model save status
Each model instance is a separate python object and they do not know anything about each other.
12345678
track1=awaitTrack.objects.get(name='The Bird')track2=awaitTrack.objects.get(name='The Bird')asserttrack1==track2# Truetrack1.name='The Bird2'awaittrack1.save()asserttrack1.name==track2.name# False# track2 does not update and knows nothing about track1
The objects itself have a saved status, which is set as following:
Model is saved after save/update/load/upsert method on model
Model is saved after create/get/first/all/get_or_create/update_or_create method
Model is saved when passed to bulk_update and bulk_create
Model is saved after adding/removingManyToMany related objects (through model instance auto saved/deleted)
Model is not saved after change of any own field (including pk as Model.pk alias)
Model is not saved after adding/removing ForeignKey related object (fk column not saved)
Model is not saved after instantiation with __init__ (w/o QuerySet.create or before calling save)
You can check if model is saved with ModelInstance.saved property