Skip to content

Common Parameters

All Field types have a set of common parameters.

primary_key

primary_key: bool = False -> by default False.

Sets the primary key column on a table, foreign keys always refer to the pk of the Model.

Used in sql only.

autoincrement

autoincrement: bool = primary_key and type == int -> defaults to True if column is a primary key and of type Integer, otherwise False.

Can be only used with int/bigint fields.

If a field has autoincrement it becomes optional.

Used both in sql and pydantic (changes pk field to optional for autoincrement).

nullable

nullable: bool = False -> defaults to False for all fields except relation fields.

Automatically changed to True if user provide one of the following:

  • default value or function is provided
  • server_default value or function is provided
  • autoincrement is set on Integer primary_key field
  • [DEPRECATED]pydantic_only=True is set

Specifies if field is optional or required, used both with sql and pydantic.

By default, used for both pydantic and sqlalchemy as those are the most common settings:

  • nullable=False - means database column is not null and field is required in pydantic
  • nullable=True - means database column is null and field is optional in pydantic

If you want to set different setting for pydantic and the database see sql_nullable below.

Note

By default all ForeignKeys are also nullable, meaning the related Model is not required.

If you change the ForeignKey column to nullable=False, it becomes required.

sql_nullable

sql_nullable: bool = nullable -> defaults to the value of nullable (described above).

Specifies if field is not null or allows nulls in the database only.

Use this setting in combination with nullable only if you want to set different options on pydantic model and in the database.

A sample usage might be i.e. making field not null in the database, but allow this field to be nullable in pydantic (i.e. with server_default value). That will prevent the updates of the field to null (as with server_default set you cannot insert null values already as the default value would be used)

default

default: Any = None -> defaults to None.

A default value used if no other value is passed.

In sql invoked on an insert, used during pydantic model definition.

If the field has a default value it becomes optional.

You can pass a static value or a Callable (function etc.)

Used both in sql and pydantic.

Sample usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# note the distinction between passing a value and Callable pointer

# value
name: str = ormar.String(max_length=200, default="Name")

# note that when you call a function it's not a pointer to Callable
# a definition like this will call the function at startup and assign
# the result of the function to the default, so it will be constant value for all instances
created_date: datetime.datetime = ormar.DateTime(default=datetime.datetime.now())

# if you want to pass Callable reference (note that it cannot have arguments)
# note lack of the parenthesis -> ormar will call this function for you on each model
created_date: datetime.datetime = ormar.DateTime(default=datetime.datetime.now)

# Callable can be a function, builtin, class etc.

server default

server_default: Any = None -> defaults to None.

A default value used if no other value is passed.

In sql invoked on the server side so you can pass i.e. sql function (like now() or query/value wrapped in sqlalchemy text() clause).

If the field has a server_default value it becomes optional.

You can pass a static value or a Callable (function etc.)

Used in sql only.

Sample usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from datetime import datetime

import databases
import sqlalchemy
from sqlalchemy import func, text

import ormar

database = databases.Database("sqlite:///test.db")
metadata = sqlalchemy.MetaData()


class Product(ormar.Model):
    class Meta:
        tablename = "product"
        metadata = metadata
        database = database

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=100)
    company: str = ormar.String(max_length=200, server_default="Acme")
    sort_order: int = ormar.Integer(server_default=text("10"))
    created: datetime = ormar.DateTime(server_default=func.now())

Warning

server_default accepts str, sqlalchemy.sql.elements.ClauseElement or sqlalchemy.sql.elements.TextClause so if you want to set i.e. Integer value you need to wrap it in sqlalchemy.text() function like above

Tip

You can pass also valid sql (dialect specific) wrapped in sqlalchemy.text()

For example func.now() above could be exchanged for text('(CURRENT_TIMESTAMP)') for sqlite backend

Info

server_default is passed straight to sqlalchemy table definition so you can read more in server default sqlalchemy documentation

name

name: str = None -> defaults to None

Allows you to specify a column name alias to be used.

Useful for existing database structures that use a reserved keyword, or if you would like to use database name that is different from ormar field name.

Take for example the snippet below.

from, being a reserved word in python, will prevent you from creating a model with that column name.

Changing the model name to from_ and adding the parameter name='from' will cause ormar to use from for the database column name. 

1
2
 #... rest of Model cut for brevity
 from_: str = ormar.String(max_length=15, name='from')

Similarly, you can change the foreign key column names in database, while keeping the desired relation name in ormar:

1
2
 # ... rest of Model cut for brevity
album: Optional[Album] = ormar.ForeignKey(Album, name="album_id")

index

index: bool = False -> by default False,

Sets the index on a table's column.

Used in sql only.

unique

unique: bool = False

Sets the unique constraint on a table's column.

Used in sql only.

pydantic_only (DEPRECATED)

This parameter is deprecated and will be removed in one of next releases!

To check how to declare pydantic only fields that are not saved into database see pydantic fields section

pydantic_only: bool = False

Prevents creation of a sql column for given field.

Used for data related to given model but not to be stored in the database.

Used in pydantic only.

overwrite_pydantic_type

By default, ormar uses predefined pydantic field types that it applies on model creation (hence the type hints are optional).

If you want to, you can apply your own type, that will be completely replacing the build in one. So it's on you as a user to provide a type that is valid in the context of given ormar field type.

Warning

Note that by default you should use build in arguments that are passed to underlying pydantic field.

You can check what arguments are supported in field types section or in pydantic docs.

Danger

Setting a wrong type of pydantic field can break your model, so overwrite it only when you know what you are doing.

As it's easy to break functionality of ormar the overwrite_pydantic_type argument is not available on relation fields!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# sample overwrites
class OverwriteTest(ormar.Model):
    class Meta:
        tablename = "overwrites"
        metadata = metadata
        database = database

    id: int = ormar.Integer(primary_key=True)
    my_int: str = ormar.Integer(overwrite_pydantic_type=PositiveInt)
    constraint_dict: Json = ormar.JSON(
        overwrite_pydantic_type=Optional[Json[Dict[str, int]]])

choices

choices: Sequence = []

A set of choices allowed to be used for given field.

Used for data validation on pydantic side.

Prevents insertion of value not present in the choices list.

Used in pydantic only.