vapor-docs/2.0/docs/fluent/model.md

Model

Models are the Swift representations of the data in your database. As such, they are central to most of Fluent's APIs.

This guide is an overview of the protocol requirements and methods associated with models.

!!! seealso Check out the getting started guide for an introductory overview on using models.

CRUD

Models have several basic methods for creating, reading, updating, and deleting.

Save

Persists the entity into the data store and sets the id property.

let pet = Pet(name: "Spud", age: 2)
try pet.save()

Find

Finds the model with the supplied identifier or returns nil.

guard let pet = try Pets.find(42) else {
    throw Abort.notFound
}
print(pet.name)

Delete

Deletes the entity from the data store if the entity has previously been fetched or saved.

try pet.delete()

All

Returns all entities for this model.

for pet in try Pets.all() {
    print(pet.name)
}

Count

Returns a count of all entities for this model.

let count = try Pets.count()

Chunk

Returns chunked arrays of a supplied size for all of the entities for this model.

This is a great way to parse through all models of a large data set.

try Pets.chunk(20) { pets in
    //
}

Query

Creates a Query instance for this Model.

let query = try Pet.makeQuery()

To learn more about crafting complex queries, see the query section.

Convenience

Assert Exists

The identifier property of a model is optional since models may not have been saved yet.

You can get the identifier or throw an error if the model has not been saved yet by calling assertExists().

let id = try pet.assertExists()
print(id) // not optional

Life Cycle

The following life-cycle methods can be implemented on your model to hook into internal operations.

/// Called before the entity will be created.
/// Throwing will cancel the creation.
func willCreate() throws

/// Called after the entity has been created.
func didCreate()

/// Called before the entity will be updated.
/// Throwing will cancel the update.
func willUpdate() throws

/// Called after the entity has been updated.
func didUpdate()

/// Called before the entity will be deleted.
/// Throwing will cancel the deletion.
func willDelete() throws

/// Called after the entity has been deleted.
func didDelete()

!!! note Throwing in a willFoo() method will cancel the operation.

Here's an example of implementing the didDelete method.

final class Pet: Model {
    ... 

    func didDelete() {
        print("Deleted \(name)")
    }
}

Entity

Entity is the base Fluent protocol that Model conforms to. It is responsible for providing all information the database or query may need when saving, fetching, or deleting your models.

Name

The singular relational name of this model. Also used for internal storage. Example: Pet = "pet".

This value should usually not be overriden.

final class Pet: Model {
    static let name = "pet"
}

Entity

The plural relational name of this model. Used as the collection or table name.

Example: Pet = "pets".

This value should be overriden if the table name for your model is non-standard.

final class Pet: Model {
    static let entity = "pets"
}

ID Type

The type of identifier used for both the local and foreign id keys.

Example: uuid, integer, etc.

This value should be overriden if a particular model in your database uses a different ID type.

final class Pet: Model {
    static let idType = .uuid
}

This can also be overridden at the database level using config.

Config/fluent.json

{
    "idType": "uuid"
}

Or programatically.

drop.database?.idType = .uuid

Key Naming Convention

The naming convetion to use for foreign id keys, table names, etc.

Example: snake_case vs. camelCase.

This value should be overridden if a particular model in your database uses a different key naming convention.

final class Pet: Model {
    static let keyNamingConvention = .snake_case
}

This can also be overridden at the database level using config.

Config/fluent.json

{
    "keyNamingConvention": "snake_case"
}

Or programatically.

drop.database?.keyNamingConvention = .snake_case

ID Key

The name of the column that corresponds to this entity's identifying key.

The default is 'database.driver.idKey', and then "id"

final class Pet: Model {
    static let idKey = "id"
}

Foreign ID Key

The name of the column that points to this entity's id when referenced from other tables or collections.

Example: "foo_id".

final class Pet: Model {
    static let foreignIdKey = "pet_id"
}