

# Adding Fluent to your Project

Fluent (vapor/fluent) is a type-safe, fast, and easy-to-use ORM built for Swift. It takes advantage of Swift's strong type system to provide an elegant API for your database.

## Database

In addition to adding Fluent to your project, you must also add a Fluent compatible database. Fluent does not include any databases by default. All official databases have a getting started guide similar to this one.

database | library | driver | guide
--- | --- | --- | ---
PostgreSQL | vapor/postgres | vapor/fluent-postgres | PostgreSQL → Package
MySQL | vapor/mysql | vapor/fluent-mysql | MySQL → Package
SQLite | vapor/sqlite | vapor/fluent-sqlite | SQLite → Package
MongoDB | mongokitten/mongokitten | vapor/fluent-mongokitten | README.md

Tip

Any database can be made to work with Fluent by conforming to its Database protocol. For a list of all compatible database types, search GitHub for the fluent-driver topic.

## Fluent

After you have added your database driver, simply add the Fluent package to your Package manifest.

    // swift-tools-version:4.0
    import PackageDescription

    let package = Package(
        name: "Project",
        dependencies: [
            ...
            .package(url: "https://github.com/vapor/fluent.git", .upToNextMajor(from: "3.0.0")),
        ],
        targets: [
          .target(name: "Project", dependencies: ["Fluent", ... ])
        ]
    )

If this is your first time adding a dependency, you should read our introduction to Package.swift.

Note

Use `import Fluent` to access Fluent's APIs.

Once you have Fluent added to your project, you are ready to configure your database(s).

## Configuring Fluent

Fluent integrates seamlessly into your Vapor project using services. In this section we will add the Fluent service provider to your application and configure your databases.

Warning

This section assumes you have added both Fluent and a Fluent database to your package.

## Service Provider

The first step to using Fluent, is registering it with your Vapor application.

    import Fluent

    ...

    try services.instance(FluentProvider())

Register the `FluentProvider` in the configure section of your application.

Question

Learn more about how service providers work in Getting Started: Application and Concepts: Services.

## Config

Once the service provider has been added, we can configure one or more databases to be used with Fluent.

### Identifier

Each database you use with Fluent must have a unique identifier. The easiest way to keep track of this identifier is to add it as static extension to `DatabaseIdentifier`.

    import Fluent
    import FluentMySQL
    import FluentSQLite

    extension DatabaseIdentifier {
        static var foo: DatabaseIdentifier<SQLiteDatabase> {
            return .init("foo")
        }

        static var bar: DatabaseIdentifier<MySQLDatabase> {
            return .init("bar")
        }
    }

Now we can use the identifier anywhere in our project:

    req.database(.foo) { ... }

The configure section of your project is a good place to put this extension.

### Databases

Now that we have created a unique identifier for our database, we can register it to our application using `DatabaseConfig`. A good place to do this is in the configure section of your project.

You can add databases to the `DatabaseConfig` using either a type (`.self`) or an instance.

#### Type

If you register a database type (like `SQLiteDatabase.self`), Fluent will ask the application to create an instance of your database at boot.

    import Fluent
    import FluentSQLite

    ...

    var databaseConfig = DatabaseConfig()

    databaseConfig.add(database: SQLiteDatabase.self, as: .foo)

    services.instance(databaseConfig)

#### Instance

You can also register a pre-initialized database. This is especially useful if you'd like to configure two instances of the same database type.

    import Fluent
    import FluentMySQL

    ...

    var databaseConfig = DatabaseConfig()

    let mysql = MySQLDatabase(...)
    databaseConfig.add(database: mysql, as: .bar)

    services.instance(databaseConfig)

### Migrations

If your database uses schemas (most SQL databases do, whereas NoSQL databases don't), you will also want to configure your migrations using `MigrationConfig`.

    import Fluent

    ...

    var migrationConfig = MigrationConfig()

    migrationConfig.add(migration: User.self, database: .foo)

    services.instance(migrationConfig)

You can read more about migrations in Fluent: Migrations.

## Done

You should now be able to compile and run your application. The next step is to create your models.