Skip to content

Upgrading to 4.0

This guide shows you how to upgrade an existing Vapor 3.x project to 4.x. This guide attempts to cover all of Vapor's official packages as well as some commonly used providers. If you notice anything missing, Vapor's team chat is a great place to ask for help. Issues and pull requests are also appreciated.

Dependencies

To use Vapor 4, you will need Xcode 11.4 and macOS 10.15 or greater.

The Install section of the docs goes over installing dependencies.

Package.swift

The first step to upgrading to Vapor 4 is to update your package's dependencies. Below is an example of an upgraded Package.swift file. You can also check out the updated template Package.swift.

-// swift-tools-version:4.0
+// swift-tools-version:5.2
 import PackageDescription

 let package = Package(
     name: "api",
+    platforms: [
+        .macOS(.v10_15),
+    ],
     dependencies: [
-        .package(url: "https://github.com/vapor/fluent-postgresql.git", from: "1.0.0"),
+        .package(url: "https://github.com/vapor/fluent.git", from: "4.0.0"),
+        .package(url: "https://github.com/vapor/fluent-postgres-driver.git", from: "2.0.0"),
-        .package(url: "https://github.com/vapor/jwt.git", from: "3.0.0"),
+        .package(url: "https://github.com/vapor/jwt.git", from: "4.0.0"),
-        .package(url: "https://github.com/vapor/vapor.git", from: "3.0.0"),
+        .package(url: "https://github.com/vapor/vapor.git", from: "4.3.0"),
     ],
     targets: [
         .target(name: "App", dependencies: [
-            "FluentPostgreSQL", 
+            .product(name: "Fluent", package: "fluent"),
+            .product(name: "FluentPostgresDriver", package: "fluent-postgres-driver"),
-            "Vapor", 
+            .product(name: "Vapor", package: "vapor"),
-            "JWT", 
+            .product(name: "JWT", package: "jwt"),
         ]),
-        .target(name: "Run", dependencies: ["App"]),
-        .testTarget(name: "AppTests", dependencies: ["App"])
+        .target(name: "Run", dependencies: [
+            .target(name: "App"),
+        ]),
+        .testTarget(name: "AppTests", dependencies: [
+            .target(name: "App"),
+        ])
     ]
 )

All packages that have been upgraded for Vapor 4 will have their major version number incremented by one.

Warning

The -rc pre-release identifier is used since some packages of Vapor 4 has not been officially released yet.

Old Packages

Some Vapor 3 packages have been deprecated, such as:

  • vapor/auth: Now included in Vapor.
  • vapor/core: Absorbed into several modules.
  • vapor/crypto: Replaced by SwiftCrypto (Now included in Vapor).
  • vapor/multipart: Now included in Vapor.
  • vapor/url-encoded-form: Now included in Vapor.
  • vapor-community/vapor-ext: Now included in Vapor.
  • vapor-community/pagination: Now part of Fluent.
  • IBM-Swift/LoggerAPI: Replaced by SwiftLog.

Fluent Dependency

vapor/fluent must now be added as a separate dependency to your dependencies list and targets. All database-specific packages have been suffixed with -driver to make the requirement on vapor/fluent clear.

- .package(url: "https://github.com/vapor/fluent-postgresql.git", from: "1.0.0"),
+ .package(url: "https://github.com/vapor/fluent.git", from: "4.0.0"),
+ .package(url: "https://github.com/vapor/fluent-postgres-driver.git", from: "2.0.0"),

Platforms

Vapor's package manifests now explicitly support macOS 10.15 and greater. This means your package will also need to specify platform support.

+ platforms: [
+     .macOS(.v10_15),
+ ],

Vapor may add additional supported platforms in the future. Your package may support any subset of these platforms as long as the version number is equal or greater to Vapor's minimum version requirements.

Xcode

Vapor 4 utilizes Xcode 11's native SPM support. This means you will no longer need to generate .xcodeproj files. Opening your project's folder in Xcode will automatically recognize SPM and pull in dependencies.

You can open your project natively in Xcode using vapor xcode or open Package.swift.

Once you've updated Package.swift, you may need to close Xcode and clear the following folders from the root directory:

  • Package.resolved
  • .build
  • .swiftpm
  • *.xcodeproj

Once your updated packages have resolved successfully you should see compiler errors--probably quite a few. Don't worry! We'll show you how to fix them.

Run

The first order of business is to update your Run module's main.swift file to the new format.

import App
import Vapor

var env = try Environment.detect()
try LoggingSystem.bootstrap(from: &env)
let app = Application(env)
defer { app.shutdown() }
try configure(app)
try app.run()

The main.swift file's contents replace the App module's app.swift, so you can delete that file.

App

Let's take a look at how to update the basic App module structure.

configure.swift

The configure method should be changed to accept an instance of Application.

- public func configure(_ config: inout Config, _ env: inout Environment, _ services: inout Services) throws
+ public func configure(_ app: Application) throws

Below is an example of an updated configure method.

import Fluent
import FluentSQLiteDriver
import Vapor

// Called before your application initializes.
public func configure(_ app: Application) throws {
    // Serves files from `Public/` directory
    // app.middleware.use(FileMiddleware(publicDirectory: app.directory.publicDirectory))
    // Configure SQLite database
    app.databases.use(.sqlite(.file("db.sqlite")), as: .sqlite)

    // Configure migrations
    app.migrations.add(CreateTodo())

    try routes(app)
}

Syntax changes for configuring things like routing, middleware, fluent, and more are mentioned below.

boot.swift

boot's contents can be placed in the configure method since it now accepts the application instance.

routes.swift

The routes method should be changed to accept an instance of Application.

- public func routes(_ router: Router, _ container: Container) throws
+ public func routes(_ app: Application) throws

More information on changes to routing syntax are mentioned below.

Services

Vapor 4's services APIs have been simplified to make it easier for you to discover and use services. Services are now exposed as methods and properties on Application and Request which allows the compiler to help you use them.

To understand this better, let's take a look at a few examples.

// Change the server's default port to 8281
- services.register { container -> NIOServerConfig in
-     return .default(port: 8281)
- }
+ app.http.server.configuration.port = 8281

Instead of registering a NIOServerConfig to services, server configuration is now exposed as simple properties on Application that can be overridden.

// Register cors middleware
let corsConfiguration = CORSMiddleware.Configuration(
    allowedOrigin: .all,
    allowedMethods: [.POST, .GET, .PATCH, .PUT, .DELETE, .OPTIONS]
)
let corsMiddleware = CORSMiddleware(configuration: corsConfiguration)
- var middlewares = MiddlewareConfig() // Create _empty_ middleware config
- middlewares.use(corsMiddleware)
- services.register(middlewares)
+ app.middleware.use(corsMiddleware)

Instead of creating and registering a MiddlewareConfig to services, middleware are now exposed as a property on Application that can be added to.

// Make a request in a route handler.
- try req.make(Client.self).get("https://vapor.codes")
+ req.client.get("https://vapor.codes")

Like Application, Request also exposes services as simple properties and methods. Request-specific services should always be used when inside a route closure.

This new service pattern replaces the Container, Service, and Config types from Vapor 3.

Providers

Providers are no longer required to configure third party packages. Each package instead extends Application and Request with new properties and methods for configuration.

Take a look at how Leaf is configured in Vapor 4.

// Use Leaf for view rendering. 
- try services.register(LeafProvider())
- config.prefer(LeafRenderer.self, for: ViewRenderer.self)
+ app.views.use(.leaf)

To configure Leaf, use the app.leaf property.

// Disable Leaf view caching.
- services.register { container -> LeafConfig in
-     return LeafConfig(tags: ..., viewsDir: ..., shouldCache: false)
- }
+ app.leaf.cache.isEnabled = false

Environment

The current environment (production, development, etc) can be accessed via app.environment.

Custom Services

Custom services conforming to the Service protocol and registered to the container in Vapor 3 can be now be expressed as extensions to either Application or Request.

struct MyAPI {
    let client: Client
    func foo() { ... }
}
- extension MyAPI: Service { }
- services.register { container -> MyAPI in
-     return try MyAPI(client: container.make())
- }
+ extension Request {
+     var myAPI: MyAPI { 
+         .init(client: self.client)
+     }
+ }

This service can then be accessed using the extension instead of make.

- try req.make(MyAPI.self).foo()
+ req.myAPI.foo()

Custom Providers

Most custom services can be implemented using extensions as shown in the previous section. However, some advanced providers may need to hook into the application lifecycle or use stored properties.

Application's new Lifecycle helper can be used to register lifecycle handlers.

struct PrintHello: LifecycleHandler {
    func willBoot(_ app: Application) throws {
        print("Hello!")
    }
}

app.lifecycle.use(PrintHello())

To store values on Application, you case use the new Storage helper.

struct MyNumber: StorageKey {
    typealias Value = Int
}
app.storage[MyNumber.self] = 5
print(app.storage[MyNumber.self]) // 5

Accessing app.storage can be wrapped in a settable computed property to create a concise API.

extension Application {
    var myNumber: Int? {
        get { self.storage[MyNumber.self] }
        set { self.storage[MyNumber.self] = newValue }
    }
}

app.myNumber = 42
print(app.myNumber) // 42

NIO

Vapor 4 now exposes SwiftNIO's async APIs directly and does not attempt to overload methods like map and flatMap or alias types like EventLoopFuture. Vapor 3 provided overloads and aliases for backward compatibility with early beta versions that were released before SwiftNIO existed. These have been removed to reduce confusion with other SwiftNIO compatible packages and better follow SwiftNIO's best practice recommendations.

Async naming changes

The most obvious change is that the Future typealias for EventLoopFuture has been removed. This can be fixed fairly easily with a find and replace.

Furthermore, NIO does not support the to: labels that Vapor 3 added. Given Swift 5.2's improved type inference, to: is less necessary now anyway.

- futureA.map(to: String.self) { ... }
+ futureA.map { ... }

Methods prefixed with new, like newPromise have been changed to make to better suit Swift style.

- let promise = eventLoop.newPromise(String.self)
+ let promise = eventLoop.makePromise(of: String.self)

catchMap is no longer available, but NIO's methods like mapError and flatMapErrorThrowing will work instead.

Vapor 3's global flatMap method for combining multiple futures is no longer available. This can be replaced by using NIO's and method to combine many futures together.

- flatMap(futureA, futureB) { a, b in 
+ futureA.and(futureB).flatMap { (a, b) in
    // Do something with a and b.
}

ByteBuffer

Many methods and properties that previously used Data now use NIO's ByteBuffer. This type is a more powerful and performant byte storage type. You can read more about its API in SwiftNIO's ByteBuffer docs.

To convert a ByteBuffer back to Data, use:

Data(buffer.readableBytesView)

Throwing map / flatMap

The most difficult change is that map and flatMap can no longer throw. map has a throwing version named (somewhat confusingly) flatMapThrowing. flatMap however has no throwing counterpart. This may require you to restructure some asynchronous code.

Maps that do not throw should continue to work fine.

// Non-throwing map.
futureA.map { a in
    return b
}

Maps that do throw must be renamed to flatMapThrowing.

- futureA.map { a in
+ futureA.flatMapThrowing { a in
    if ... {
        throw SomeError()
    } else {
        return b
    }
}

Flat-maps that do not throw should continue to work fine.

// Non-throwing flatMap.
futureA.flatMap { a in
    return futureB
}

Instead of throwing an error inside a flat-map, return a future error. If the error originates from another throwing method, the error can be caught in a do / catch and returned as a future.

// Returning a caught error as a future.
futureA.flatMap { a in
    do {
        try doSomething()
        return futureB
    } catch {
        return eventLoop.makeFailedFuture(error)
    }
}

Throwing method calls can also be refactored into a flatMapThrowing and chained using tuples.

// Refactored throwing method into flatMapThrowing with tuple-chaining.
futureA.flatMapThrowing { a in
    try (a, doSomeThing())
}.flatMap { (a, result) in
    // result is the value of doSomething.
    return futureB
}

Routing

Routes are now registered directly to Application.

app.get("hello") { req in
    return "Hello, world"
}

This means you no longer need to register a router to services. Simply pass the application to your routes method and start adding routes. All of the methods available on RoutesBuilder are available on Application.

Synchronous Content

Decoding request content is now synchronous.

let payload = try req.content.decode(MyPayload.self)
print(payload) // MyPayload

This behavior can be overridden by register routes using the .stream body collection strategy.

app.on(.POST, "streaming", body: .stream) { req in
    // Request body is now asynchronous.
    req.body.collect().map { buffer in
        HTTPStatus.ok
    }
}

Comma-separated paths

Paths must now be comma separated and not contain / for consistency.

- router.get("v1/users/", "posts", "/comments") { req in 
+ app.get("v1", "users", "posts", "comments") { req in
    // Handle request.
}

Route parameters

The Parameter protocol has been removed in favor of explicitly named parameters. This prevents issues with duplicate parameters and un-ordered fetching of parameters in middleware and route handlers.

- router.get("planets", String.parameter) { req in 
-     let id = req.parameters.next(String.self)
+ app.get("planets", ":id") { req in
+     let id = req.parameters.get("id")
      return "Planet id: \(id)"
  }

Route parameter usage with models is mentioned in the Fluent section.

Middleware

MiddlewareConfig has been renamed to MiddlewareConfiguration and is now a property on Application. You can add middleware to your app using app.middleware.

let corsMiddleware = CORSMiddleware(configuration: ...)
- var middleware = MiddlewareConfig()
- middleware.use(corsMiddleware)
+ app.middleware.use(corsMiddleware)
- services.register(middlewares)

Middleware can no longer be registered by type name. Initialize the middleware first before registering.

- middleware.use(ErrorMiddleware.self)
+ app.middleware.use(ErrorMiddleware.default(environment: app.environment))

To remove all default middleware, set app.middleware to an empty config using:

app.middleware = .init()

Fluent

Fluent's API is now database agnostic. You can import just Fluent.

- import FluentMySQL
+ import Fluent

Models

All models now use the Model protocol and must be classes.

- struct Planet: MySQLModel {
+ final class Planet: Model {

All fields are declared using @Field or @OptionalField property wrappers.

+ @Field(key: "name")
var name: String

+ @OptionalField(key: "age")
var age: Int?

A model's ID must be defined using the @ID property wrapper.

+ @ID(key: .id)
var id: UUID?

Models using an identifier with a custom key or type must use @ID(custom:).

All models must have their table or collection name defined statically.

final class Planet: Model {
+   static let schema = "Planet"    
}

All models must now have an empty initializer. Since all properties use property wrappers, this can be empty.

final class Planet: Model {
+   init() { }
}

Model's save, update, and create no longer return the model instance.

- model.save(on: ...)
+ model.save(on: ...).map { model }

Models can no longer be used as route path components. Use find and req.parameters.get instead.

- try req.parameters.next(ServerSize.self)
+ ServerSize.find(req.parameters.get("size"), on: req.db)
+     .unwrap(or: Abort(.notFound))

Model.ID has been renamed to Model.IDValue.

Model timestamps are now declared using the @Timestamp property wrapper.

- static var createdAtKey: TimestampKey? = \.createdAt
+ @Timestamp(key: "createdAt", on: .create)
var createdAt: Date?

Relations

Relations are now defined using property wrappers.

Parent relations use the @Parent property wrapper and contain the field property internally. The key passed to @Parent should be the name of the field storing the identifier in the database.

- var serverID: Int
- var server: Parent<App, Server> { 
-    parent(\.serverID) 
- }
+ @Parent(key: "serverID") 
+ var server: Server

Children relations use the @Children property wrapper with a key path to the related @Parent.

- var apps: Children<Server, App> { 
-     children(\.serverID) 
- }
+ @Children(for: \.$server) 
+ var apps: [App]

Siblings relations use the @Siblings property wrapper with key paths to the pivot model.

- var users: Siblings<Company, User, Permission> {
-     siblings()
- }
+ @Siblings(through: Permission.self, from: \.$user, to: \.$company) 
+ var companies: [Company]

Pivots are now normal models that conform to Model with two @Parent relations and zero or more additional fields.

Query

The database context is now accessed via req.db in route handlers.

- Planet.query(on: req)
+ Planet.query(on: req.db)

DatabaseConnectable has been renamed to Database.

Key paths to fields are now prefixed with $ to specify the property wrapper instead of the field value.

- filter(\.foo == ...) 
+ filter(\.$foo == ...)

Migrations

Models no longer support reflection-based auto migrations. All migrations must be written manually.

- extension Planet: Migration { }
+ struct CreatePlanet: Migration {
+     ...
+}

Migrations are now stringly typed and decoupled from models and use the Migration protocol.

- struct CreateGalaxy: <#Database#>Migration {
+ struct CreateGalaxy: Migration {

The prepare and revert methods are no longer static.

- static func prepare(on conn: <#Database#>Connection) -> Future<Void> {
+ func prepare(on database: Database) -> EventLoopFuture<Void> 

Creating a schema builder is done via an instance method on Database.

- <#Database#>Database.create(Galaxy.self, on: conn) { builder in
-    // Use builder.
- }
+ var builder = database.schema("Galaxy")
+ // Use builder.

The create, update, and delete methods are now called on the schema builder similar to how query builder works.

Fields definitions are now stringly typed and follow the pattern:

field(<name>, <type>, <constraints>)

See the example below.

- builder.field(for: \.name)
+ builder.field("name", .string, .required)

Schema building can now be chained like query builder.

database.schema("Galaxy")
    .id()
    .field("name", .string, .required)
    .create()

Fluent Configuration

DatabasesConfig has been replaced by app.databases.

try app.databases.use(.postgres(url: "postgres://..."), as: .psql)

MigrationsConfig has been replaced by app.migrations.

app.migrations.use(CreatePlanet(), on: .psql)

Repositories

As the way services work in Vapor 4 has changed, that also means that the way to do database repositories has changed. You still need a protocol such as UserRepository but instead of making a final class conform to that protocol, you should make a struct instead.

- final class DatabaseUserRepository: UserRepository {
+ struct DatabaseUserRepository: UserRepository {
      let database: Database
      func all() -> EventLoopFuture<[User]> {
          return User.query(on: database).all()
      }
  }

You should also remove conformance from ServiceType as this no longer exists in Vapor 4.

- extension DatabaseUserRepository {
-     static let serviceSupports: [Any.Type] = [Athlete.self]
-     static func makeService(for worker: Container) throws -> Self {
-         return .init()
-     }
- }

Instead you should create a UserRepositoryFactory:

struct UserRepositoryFactory {
    var make: ((Request) -> UserRepository)?
    mutating func use(_ make: @escaping ((Request) -> UserRepository)) {
        self.make = make
    }
}

This factory is responsible for returning a UserRepository for a Request.

Next step is to add an extension to Application to specify your factory:

extension Application {
    private struct UserRepositoryKey: StorageKey { 
        typealias Value = UserRepositoryFactory 
    }

    var users: UserRepositoryFactory {
        get {
            self.storage[UserRepositoryKey.self] ?? .init()
        }
        set {
            self.storage[UserRepositoryKey.self] = newValue
        }
    }
}

To use the actual repository inside of a Request add this extension to Request:

extension Request {
    var users: UserRepository {
        self.application.users.make!(self)
    }
}

Last step is to specify the factory inside configure.swift

app.users.use { req in
    DatabaseUserRepository(database: req.db)
}

You can now access your repository in your route handlers with: req.users.all() and easily replace the factory inside tests. If you want to use a mocked repository inside tests, first create a TestUserRepository

final class TestUserRepository: UserRepository {
    var users: [User]
    let eventLoop: EventLoop

    init(users: [User] = [], eventLoop: EventLoop) {
        self.users = users
        self.eventLoop = eventLoop
    }

    func all() -> EventLoopFuture<[User]> {
        eventLoop.makeSuccededFuture(self.users)
    }
}

You can now use this mocked repository inside your tests as follows:

final class MyTests: XCTestCase {
    func test() throws {
        let users: [User] = []
        app.users.use { TestUserRepository(users: users, eventLoop: $0.eventLoop) }
        ...
    }
}