Models

Models are the easiest way to interact with your tables. A model is a way for you to interact with a Python class in a simple and elegant way and have all the hard overhead stuff handled for you under the hood. A model can be used to query the data in the table or even create new records, fetch related records between tables and many other features.

Creating A Model

The first step in using models is actually creating them. You can scaffold out a model by using the command:

$ python craft model Post

This will create a post model like so:

from masoniteorm.models import Model

class Post(Model):
    """Post Model"""
    pass

From here you can do as basic or advanced queries as you want. You may need to configure your model based on your needs, though.

From here you can start querying your records:

user = User.first()
users = User.all()
active_users = User.where('active', 1).first()

We'll talk more about setting up your model below

Conventions And Configuration

Masonite ORM makes a few assumptions in order to have the easiest interface for your models.

The first is table names. Table names are assumed to be the plural of your model name. If you have a User model then the users table is assumed and if you have a model like Company then the companies table is assumed. You can realize that Masonite ORM is smart enough to know that the plural of Company is not Companys so don't worry about Masonite not being able to pick up your table name.

Table Name

If your table name is something other than the plural of your models you can change it using the __table__ attribute:

class Clients:
  __table__ = "users"

Primary Keys

The next thing Masonite assumes is the primary key. Masonite ORM assumes that the primary key name is id. You can change the primary key name easily:

class Clients:
  __primary_key__ = "user_id"

Connections

The next thing Masonite assumes is that you are using the default connection you setup in your configuration settings. You can also change thing on the model:

class Clients:
  __connection__ = "staging"

Mass Assignment

By default, Masonite ORM protects against mass assignment to help prevent users from changing values on your tables you didn't want.

This is used in the create and update methods. You can set the columns you want to be mass assignable easily:

class Clients:
  __fillable__ = ['email', "active", "password"]

Timestamps

Masonite also assumed you have created_at and updated_at columns on your table. You can easily disable this behavior:

class Clients:
  __timestamps__ = False

Timezones

Models use UTC as the default timezone. You can change the timezones on your models using the __timezone__ attribute:

class User(Model):
    __timezone__ = "Europe/Paris"

Querying

Almost all of a models querying methods are passed off to the query builder. If you would like to see all the methods available for the query builder, see the QueryBuilder documentation here.

• sub queries

Single results

A query result will either have 1 or more records. If your model result has a single record then the result will be the model instance. You can then access attributes on that model instance. Here's an example:

from app.models import User

user = User.first()
user.name #== 'Joe'
user.email #== 'joe@masoniteproject.com'

You can also get a record by its primary key:

from app.models import User

user = User.find(1)
user.name #== 'Joe'
user.email #== 'joe@masoniteproject.com'

Collections

If your model result returns several results then it will be wrapped in a collection instance which you can use to iterate over:

from app.models import User

users = User.where('active', 1).get()
for users in user:
  user.name #== 'Joe'
  user.active #== '1'
  user.email #== 'joe@masoniteproject.com'

If you want to find a collection of records based on the models primary key you can pass a list to the find method:

users = User.find([1,2,3])
for users in user:
  user.name #== 'Joe'
  user.active #== '1'
  user.email #== 'joe@masoniteproject.com'

The collection class also has some handy methods you can use to interact with your data:

user_emails = User.where('active', 1).get().pluck('email') #== Collection of email addresses

If you would like to see more methods available like pluck be sure to read the Collections documentation.

Deleting

You may also quickly delete records:

from app.models import User

users = User.delete(1)

This will delete the record based on the primary key value of 1.

You can also delete based on a query:

from app.models import User

users = User.where('active', 0).delete()

Sub Queries

You may also use subqueries to do more advanced queries using lambda expressions:

from app.models import User

users = User.where(lambda q: q.where('active', 1).where_null('deleted_at'))
# == SELECT * FROM `users` WHERE (`active` = '1' AND `deleted_at` IS NULL)

Relationships

Another great feature when using models is to be able to relate several models together (like how tables can relate to eachother).

Belongs To

A belongs to relationship is a one-to-one relationship between 2 table records.

You can add a one-to-one relationship easily:

from masoniteorm.relationships import belongs_to
class User:

  @belongs_to
  def company(self):
    from app.models import Company
    return Company

It will be assumed here that the primary key of the relationship here between users and companies is id -> id. You can change the relating columns if that is not the case:

from masoniteorm.relationships import belongs_to
class User:

  @belongs_to('company_id', 'id')
  def company(self):
    from app.models import Company
    return Company

The first argument is always the column name on the current models table and the second argument is the related field on the other table.

Has Many

Another relationship is a one-to-many relationship where a record relates to many records in another table:

from masoniteorm.relationships import has_many
class User:

  @has_many('company_id', 'id')
  def posts(self):
    from app.models import Post
    return Post

The first argument is always the column name on the current models table and the second argument is the related field on the other table.

Using Relationships

You can easily use relationships to get those related records. Here is an example on how to get the company record:

user = User.first()
user.company #== <app.models.Company>
user.company.name #== Masonite X Inc.

for post in user.posts:
    post.title

Eager Loading

You can eager load any related records. Eager loading is when you preload model results instead of calling the database each time.

Let's take the example of fetching a users phone:

users = User.all()
for user in users:
    user.phone

This will result in the query:

SELECT * FROM users
SELECT * FROM phones where user_id = 1
SELECT * FROM phones where user_id = 2
SELECT * FROM phones where user_id = 3
SELECT * FROM phones where user_id = 4
...

This will result in a lot of database calls. Now let's take a look at the same example but with eager loading:

users = User.with_('phone').get()
for user in users:
    user.phone

This would now result in this query:

SELECT * FROM users
SELECT * FROM phones where user_id IN (1, 2, 3, 4)

This resulted in only 2 queries. Any subsquent calls will pull in the result from the eager loaded result set.

Nested Eager Loading

You may also eager load multiple relationships. Let's take another more advanced example:

Let's say you would like to get a users phone as well as the contacts. The code would look like this:

users = User.all()
for user in users:
    for contacts in user.phone:
        contact.name

This would result in the query:

SELECT * FROM users
SELECT * FROM phones where user_id = 1
SELECT * from contacts where phone_id = 30
SELECT * FROM phones where user_id = 2
SELECT * from contacts where phone_id = 31
SELECT * FROM phones where user_id = 3
SELECT * from contacts where phone_id = 32
SELECT * FROM phones where user_id = 4
SELECT * from contacts where phone_id = 33
...

You can see how this can get pretty large as we are looping through hundreds of users.

We can use nested eager loading to solve this by specifying the chain of relationships using . notation:

users = User.with_('phone.contacts').all()
for user in users:
    for contacts in user.phone:
        contact.name

This would now result in the query:

SELECT * FROM users
SELECT * FROM phones where user_id IN (1,2,3,4)
SELECT * from contacts where phone_id IN (30, 31, 32, 33)

You can see how this would result in 3 queries no matter how many users you had.

Scopes

Scopes are a way to take common queries you may be doing and be able to condense them into a method where you can then chain onto them. Let's say you are doing a query like getting the active user a lot:

user = User.where('active', 1).get()

We can take this query and add it as a scope:

from masoniteorm.scopes import scope
class User(Model):

  @scope
  def active(self, query):
    return query.where('active', 1)

Now we can simply call the active method:

user = User.active().get()

You may also pass in arguments:

from masoniteorm.scopes import scope
class User(Model):

  @scope
  def active(self, query, active_or_inactive):
    return query.where('active', active_or_inactive)

then pass an argument to it:

user = User.active(1).get()
user = User.active(0).get()

Soft Deleting

Masonite ORM also comes with a global scope to enable soft deleting for your models.

Simply inherit the SoftDeletes scope:

from masoniteorm.scopes import SoftDeletesMixin

class User(Model, SoftDeletesMixin):
  # ..

Now whenever you delete a record, instead of deleting it it will update the deleted_at record from the table to the current timestamp:

User.delete(1)
# == UPDATE `users` SET `deleted_at` = '2020-01-01 10:00:00' WHERE `id` = 1

When you fetch records it will also only fetch undeleted records:

User.all() #== SELECT * FROM `users` WHERE `deleted_at` IS NULL

You can disable this behavior as well:

User.with_trashed().all() #== SELECT * FROM `users`

You can also get only the deleted records:

User.only_trashed().all() #== SELECT * FROM `users` WHERE `deleted_at` IS NOT NULL

You can also restore records:

User.where('admin', 1).restore() #== UPDATE `users` SET `deleted_at` = NULL WHERE `admin` = '1'

Lastly, you can override this behavior and force the delete query:

User.where('admin', 1).force_delete() #== DELETE FROM `users` WHERE `admin` = '1'

There is also a soft_deletes() helper that you can use in migrations to add this field quickly.

# user migrations
with self.schema.create("users") as table:
  # ...
  table.soft_deletes()

Updating

You can also update or create records as well:

User.update_or_create({"username": "Joe"}, {
    'active': 1
})

If there is a record with the username or "Joe" it will update that record and else it will create the record.

Note that when the record is created, the two dictionaries will be merged together. So if this code was to create a record it would create a record with both the username of Joe and active of 1.

Changing Primary Key to use UUID

Masonite ORM also comes with another global scope to enable using UUID as primary keys for your models.

Simply inherit the UUIDPrimaryKeyMixin scope:

from masoniteorm.scopes import UUIDPrimaryKeyMixin

class User(Model, UUIDPrimaryKeyMixin):
  # ..

You can also define a UUID column with the correct primary constraint in a migration file

with self.schema.create("users") as table:
    table.uuid('id')
    table.primary('id')

Your model is now set to use UUID4 as a primary key. It will be automatically generated at creation.

You can change UUID version standard you want to use:

import uuid
from masoniteorm.scopes import UUIDPrimaryKeyMixin

class User(Model, UUIDPrimaryKeyMixin):
  __uuid_version__ = 3
  # the two following parameters are only needed for UUID 3 and 5
  __uuid_namespace__ = uuid.NAMESPACE_DNS
  __uuid_name__ = "domain.com

Casting

Not all data may be in the format you need it it. If you find yourself casting attributes to different values, like casting active to an int then you can set it right on the model:

class User(Model):
  __casts__ = {"active": "int"}

Now whenever you get the active attribute on the model it will be an int.

Other valid values are:

• int

• bool

• json

Dates

Masonite uses pendulum for dates. Whenever dates are used it will return an instance of pendulum.

If you would like to change this behavior you can override 2 methods: get_new_date() and get_new_datetime_string():

The get_new_date() method accepts 1 parameter which is an instance of datetime.datetime. You can use this to parse and return whichever dates you would like.

class User(Model):

    def get_new_date(self, datetime=None):
        # return new instance from datetime instance.

If the datetime parameter is None then you should return the current date.

The get_new_datetime_string() method takes the same datetime parameter but this time should return a string to be used in a table.

class User(Model):

    def get_new_datetime_string(self, datetime=None):
        return self.get_new_date(datetime).to_datetime_string()

Events

Models emit various events in different stages of its life cycle. Available events are:

• booting

• booted

• creating

• created

• deleting

• deleted

• hydrating

• hydrated

• saving

• saved

• updating

• updated

Observers

You can listen to various events through observers. Observers are simple classes that contain methods equal to the event you would like to listen to.

For example, if you want to listen to when users are created you will create a UserObserver class that contains the created method.

You can scaffold an obsever by running:

python craft observer User --model User

If you do not specify a model option, it will be assumed the model name is the same as the observer name

Once the observer is created you can add your logic to the event methods:

class UserObserver:
    def created(self, user):
        pass

    def creating(self, user):
        pass

    #..

The model object receieved in each event method will be the model at that point in time.

You may then set the observer to a specific model. This could be done in a service provider:

from app.models import User
from app.observers.UserObserver import UserObserver
from masonite.providers import Provider

class ModelProvider(Provider):

    def boot(self):
        User.observe(UserObserver())
        #..

Related Records

There's many times you need to take several related records and assign them all the same attribute based on another record.

For example you may have articles you want to switch the authors of.

For this you can use the associate and save_many methods. Let's say you had a User model that had a articles method that related to the Articles model.

user = User.find(1)
articles = Articles.where('user_id', 2).get()

user.save_many('articles', articles)

This will take all articles where user_id is 2 and assign them the related record between users and article (user_id).

You may do the same for a one-to-one relationship:

user = User.find(1)
phone = Phone.find(30)

user.associate('phone', phone)