

# 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.

## Timestamps

To add timestamps to your model, simply conform it to `Timestampable`.

    extension User: Timestampable { }

You can access the updated at and created at times on any model instance.

    user.updatedAt // Date?
    user.createdAt // Date?

When filtering or sorting on the timestamp data, you can use the timestamp keys from the class.

    let newUsers = try User
        .makeQuery()
        .filter(User.createdAtKey, .greaterThan, ...)
        .all()

You can also override the timestamp keys if you have custom needs.

    extension User: Timestampable {
        static var updatedAtKey: String { return "custom_updated_at" }
        static var createdAtKey: String { return "custom_created_at" }
    }

### Migration

`Timestampable` models will automatically have created at and updated at keys added during database create calls.

Should you need to manually add `Timestampable` to an existing model, you can use the `date()` method in a migration.

    database.modify(User.self) { builder in
        builder.date(User.createdAtKey)
        builder.date(User.updatedAtKey)
    }

## Soft Delete

Soft delete is a way of "deleting" a model from all fetch and update queries to Fluent but not actually deleting the model from the database. Soft deleted models can also be restored.

To make your model soft deletable, simply conform it to `SoftDeletable`.

    extension User: SoftDeletable { }

Once your model is soft deletable, all calls to `delete()` will set the deleted at flag instead of actually deleting the model.

To restore a model, call `.restore()`. To actually delete a model from the database, call `.forceDelete()`.

You can also override the soft delete key if you have custom needs.

    extension User: SoftDeletable {
        static var deletedAtKey: String { return "custom_deleted_at" }
    }

### Including Deleted

When a model is soft deleted, it will not be affected by any queries made with the Fluent query builder.

To include soft deleted models, for instance if you want to restore them, use the `.withSoftDeleted()` method on the query builder.

    let allUsers = try User.makeQuery().withSoftDeleted().all()

### Lifecycle

You can hook into the soft delete events of a model.

    extension User: SoftDeletable {
        func willSoftDelete() throws { ... }
        func didSoftDelete() { ... }
        func willForceDelete() throws { ... }
        func didForceDelete() { ... }
        func willRestore() throws { ... }
        func didRestore() { ... }
    }

!!! note: Throwing during a `will` hook will prevent the action from happening.

### Migration

`SoftDeletable` models will automatically have a deleted at key added during database create calls.

Should you need to manually add `SoftDeletable` to an existing model, you can use the `date()` method in a migration.

    database.modify(User.self) { builder in
        builder.date(User.deletedAtKey, optional: true)
    }

## 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: IdentifierType = .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"
    }