DEV Community: Elliot Jackson

Let's Build a Proof of Concept Dynamic Image Generator with Elixir & Phoenix

Elliot Jackson — Sat, 23 Jan 2021 17:23:08 +0000

The problem

GIFs are great but sometimes it could be nice to have a little bit of dynamism on a site without having a GIF changing in a loop and distracting the user or just without adding the file size of a GIF to the page load.

The solution

What we're going to build is a small Phoenix web app that has a single endpoint, /quote.png, that will return an image of a random quote and attribution from an array of user defined quotes. Demo:

The how

The first question is how we'll get the list of quotes and attributions from the user. In a "real" app this would probably be backed by a database and a nice UI for adding quotes. Remember that this is only a proof of concept though so we'll go with the simplest method I could think of: putting them in the query string.

The syntax for an array in a query string is key[]=value&key[]=value2 so if we create an array of quotes and an array of attributions we'll end up with something like this (q for quotes and a for attributions to help keep a long URL a bit shorter):

/quote.png?q[]=It%27s%20awesome&a[]=Mum&q[]=Pretty%20fun&a[]=Bob&q[]=Great%20stuff&a[]=Alice&q[]=Average%20at%20best&a[]=Theo

Now we know how the data is going to be passed into our endpoint, let's start doing something with it!

💡 First you'll need to install Phoenix. The project maintains a very good installation page so I won't repeat its contents. You can skip the node.js and Postgres sections if you don't already have them installed, we won't be needing them.

Once you have Phoenix installed, create a new project and install the dependencies when prompted. We won't need a DB or Webpack so we can skip those with flags.

mix phx.new image_gen_poc --no-ecto --no-webpack

Open the project in your editor of choice and let's get to it!

We'll start be defining the endpoint. Go to image_gen_poc/lib/image_gen_poc_web/router.ex and update line 19 to the following:

get "/quote.png", PageController, :index

We can see above that the new /quote.png endpoint is handled by the index function in the PageController so that's where we'll go next.

First things first we need to extract our quotes and attributions from the URL which can be done very easily with Elixir's pattern matching:

# image_gen_poc/lib/image_gen_poc_web/controllers/page_controller.ex

defmodule ImageGenPocWeb.PageController do
  use ImageGenPocWeb, :controller

  def index(conn, %{"q" => quotes, "a" => attributions}) do

    # ...

  end
end

The array of quotes (q) is assigned to quotes and the array of attributions (a) is assigned to attributions. Before we go any further let's make sure this is all working so far. We'll require Logger then update our index function as follows:

defmodule ImageGenPocWeb.PageController do
  use ImageGenPocWeb, :controller
  require Logger

  def index(conn, %{"q" => quotes, "a" => attributions}) do
    Logger.info(quotes)
    Logger.info(attributions)

    render(conn, "index.html")
  end
end

cd into your project directory and start the server with mix phx.server. Now go to your browser and paste the following URL:

http://localhost:4000/quote.png?q[]=It%27s%20awesome&a[]=Mum&q[]=Pretty%20fun&a[]=Bob&q[]=Great%20stuff&a[]=Alice&q[]=Average%20at%20best&a[]=Theo

Coming back to your terminal you should see something like this:

[info] GET /quote.png
[debug] Processing with ImageGenPocWeb.PageController.index/2
  Parameters: %{"a" => ["Mum", "Bob", "Alice", "Theo"], "q" => ["It's awesome", "Pretty fun", "Great stuff", "Average at best"]}
  Pipelines: [:browser]
[info] It's awesomePretty funGreat stuffAverage at best
[info] MumBobAliceTheo
[info] Sent 200 in 1ms

It's working, great!

Next we need to get a quote and its matching attribution.

def index(conn, %{"q" => quotes, "a" => attributions}) do
  random_index = Enum.random(0..(length(quotes) - 1))
  quote = Enum.at(quotes, random_index)
  attribution = Enum.at(attributions, random_index)

  Logger.info(quote)
  Logger.info(attribution)

  render(conn, "index.html")
end

If we were only dealing with one list we could have just used Enum.random/1 directly on it but as we need to get a value from the same random index in 2 sperate lists we're just using it to generate an index. We can then use Enum.at/2 to get a value from the same random index in 2 different lists.

Going back to your browser and refreshing the page should now output something like this in your terminal:

[info] GET /quote.png
[debug] Processing with ImageGenPocWeb.PageController.index/2
  Parameters: %{"a" => ["Mum", "Bob", "Alice", "Theo"], "q" => ["It's awesome", "Pretty fun", "Great stuff", "Average at best"]}
  Pipelines: [:browser]
[info] Great stuff
[info] Alice
[info] Sent 200 in 3ms

The quote and attribution match so the next job is to generate the image! We're going to hand the work involved in this off to ImageMagick via System.cmd/2. Installing ImageMagick on macOS is just a case of brew install imagemagick, for other OSs check out their downloads page.

System.cmd/2 returns a tuple containing the collected result of the command and the exit status code (0 means the command was successful) which we'll pattern match.

def index(conn, %{"q" => quotes, "a" => attributions}) do
  random_index = Enum.random(0..(length(quotes) - 1))
  quote = Enum.at(quotes, random_index)
  attribution = Enum.at(attributions, random_index)

  {output, 0} =
    System.cmd("convert", [
      "-background",
      "#333333",
      "-fill",
      "white",
      "-font",
      "Helvetica",
      "-pointsize",
      "56",
      "label:#{quote}", # [1]
      "-fill",
      "grey",
      "-font",
      "Helvetica-Oblique",
      "-pointsize",
      "32",
      "label:- #{attribution}", #[2]
      "-append",
      "-background",
      "#333333",
      "-gravity",
      "center",
      "-extent",
      "800x400",
      "png:-" # [3]
    ])

  render(conn, "index.html")
end

There's a lot of ImageMagick config going on there and we're going to ignore most of it as this isn't really an ImageMagick tutorial. I've numbered the lines that are of interest to us:

The first label is passed the value of quote, the quote will be escaped automatically so we don't have to worry about it containing spaces or anything.
Similarly, the value of attribution is passed to the second label.
png:- tells ImageMagick to output the generated image data as a PNG to STDOUT. This is what's collected in output.

We now have the image data in output, all that's left to do is return it to the client. Replace render/2 with the following:

def index(conn, %{"q" => quotes, "a" => attributions}) do

  # ...

  conn
  |> put_resp_content_type("image/png")
  |> send_resp(200, output)
end

put_resp_content_type/2 assigns the appropriate Content-Type header for the PNG we'll be returning, then we send the response back with a status code of 200 and the image data.

If you now go back to your browser and refresh it you should see a quotation image like the one at the start of this article generated. Keep refreshing and it should change randomly!

Thanks for reading! You'll find the source code here if you need it and if you have any questions, feel free to ask below 💬

How to Write Custom Validations for Ecto Changesets

Elliot Jackson — Sun, 10 Jan 2021 10:52:36 +0000

Written for Phoenix 1.5.7 & Ecto 3.5.5

Ecto changesets provide common validation options but we can also write our own. Before we get into writing our own though, we need to understand how (most of) the default validators work. Let's have a look at the definition of validate_inclusion for example:

def validate_inclusion(changeset, field, data, opts \\ []) do
  validate_change changeset, field, {:inclusion, data}, fn _, value ->
    if value in data,
      do: [],
      else: [{field, {message(opts, "is invalid"), [validation: :inclusion, enum: data]}}]
  end
end

We can see that the actual logic is wrapped inside validate_change/4. validate_change/3 and validate_change/4 both take a changeset, a field, and a validator function (validate_change/4 takes metadata as its 3rd paramater). validate_change will then check for the presence of the field in the changeset and if it exists and the change value is not nil then it will run the validator. The validator must return either an empty list if the validation passed or a list of errors which will be appended to the :errors field of the changeset and valid? will be set to false.

With that in mind, let's write our own validation. Below we have a basic module with a schema and a changeset function for our tutorials table:

defmodule MyApp.Tutorials.Tutorial do
  use Ecto.Schema
  import Ecto.Changeset

  schema "tutorials" do
    field :name, :string
    field :is_useful, :boolean

    timestamps()
  end

  @doc false
  def changeset(tutorial, attrs) do
    tutorial
    |> cast(attrs, [:name, :is_useful])
    |> validate_required([:name, :is_useful])
  end
end

To add a custom validation, we'll write a function that takes the Changeset as its first parameter and then the field atom:

defmodule MyApp.Tutorials.Tutorial do

  # ...

  def validate_is_useful(changeset, field) when is_atom(field) do
    validate_change(changeset, field, fn field, value ->
      case value do
        true ->
          []

        false ->
          [{field, "tutorials should be useful"}]
      end
    end)
  end
end

All we need to do now is update our changeset function to include the new validation:

defmodule MyApp.Tutorials.Tutorial do

  # ...

  @doc false
  def changeset(tutorial, attrs) do
    tutorial
    |> cast(attrs, [:name, :is_useful])
    |> validate_required([:name, :is_useful])
    |> validate_is_useful(:is_useful)
  end

  # ...

end

You could also write a custom validation by simply getting the field value you want from the changeset using get_field/3, and that does have its palce, but by leveraging validate_change when the field you're validating exists and has a value your validator will be run but if you're generating a changeset with no changes, for example to pass to a form in Phoenix, then the validator won't run and raise an error when the field who's value you're trying to get doesn't exist.

That's all there is to it really! For further reading, check out the Ecto.Changeset docs, they're very good. If you have any questions, don't hesitate to ask 💬

SQLite and iOS: Advanced GRDB

Elliot Jackson — Fri, 20 Dec 2019 16:06:54 +0000

In part 1: "Getting started with GRDB", we covered how to setup a local SQLite database for your iOS app, how to write migrations, how to adopt GRDB's protocols within a struct that can then be saved to the database, and lastly we went over some basic querying.

In part 2, we'll have a look at how to observe and react to changes in the database, how to define relationships between tables, and how to save a custom types.

Defining associations

To show you how associations work in GRDB, we'll create a tasks table and setup a "has many" relationship between the project and task tables. Tasks, in turn, will have a "belongs to" relationship with projects.

DatabaseManager.swift

class DatabaseManager {

    static var migrator: DatabaseMigrator {
        var migrator = DatabaseMigrator()

        migrator.eraseDatabaseOnSchemaChange = true

        migrator.registerMigration("createProject") { db in
            try db.create(table: "project") { t in
                t.autoIncrementedPrimaryKey("id")
                t.column("name", .text).notNull()
                t.column("description", .text)
                t.column("due", .date)
                t.column("isDraft", .boolean).notNull().defaults(to: true)
            }
        }

        migrator.registerMigration("createTask") { db in
            try db.create(table: "task") { t in
                t.autoIncrementedPrimaryKey("id")
                t.column("projectId", .integer).notNull().indexed().references("project", onDelete: .cascade)
                t.column("name", .text).notNull()
                t.column("isDone", .boolean).notNull().defaults(to: false)
            }
        }

        return migrator
    }

}

We went through what most of the above does in part 1; the interesting bit is line 21, where we create a column named projectId. The column is defined as an integer (because the primary key of the project table is an integer), then constrained to be notNull because we want SQLite to guarantee that all tasks have a project. indexed tells SQLite that we want the column to be indexed, which'll increase performance once we start querying for tasks that belong to a project (and thus matching against the value of this column). Lastly, references creates a foreign key constraint which tells SQLite that for each row in the tasks table, there exists a project it belongs to. onDelete: .cascade upholds that constraint by automatically deleting all tasks that belong a project when that project is deleted from the database.

Now that the required migrations have been done, create a Task struct for the newly created table (go back and reference part 1 if you're unsure how to do so). Once you've done that, we can move on to updating our Project struct.

Models/Project.swift

extension Project: TableRecord, EncodableRecord {

    static let tasks = hasMany(Task.self)

    private enum Columns {
        static let id = Column(CodingKeys.id)
        static let name = Column(CodingKeys.name)
        static let description = Column(CodingKeys.description)
        static let due = Column(CodingKeys.due)
        static let isDraft = Column(CodingKeys.isDraft)
    }

    var tasks: QueryInterfaceRequest<Task> {
        return request(for: Project.tasks)
    }


    static func drafts() -> QueryInterfaceRequest<Project> {
        return Project.filter(Columns.isDraft == true)
    }

}

In the above snippet, the extension that housed our queries in part 1 has been updated. First, on line 1, TableRecord and EncodableRecord have been adopted, which gives us access to GRDB's belongsTo function. On line 3, that function is then used to tell GRDB of the foreign key.

Lines 13 through 15 provide us with a nice way to query all the tasks that belong to a project simply by doing:

let tasks = try project.tasks.fetchAll(db)

Similarly, we can update the Task struct to provide us with a way to fetch the project it belongs to:

Models/Project.swift

extension Task: TableRecord, EncodableRecord {

    static let project = belongsTo(Project.self)

    var project: QueryInterfaceRequest<Project> {
        return request(for: Task.project)
    }

}

To then fetch the parent project, all that's needed is:

let project = try task.project.fetchOne(db)

Note that filters can still be applied when querying a hasMany relationship. The following, for example, is valid:

let doneTasks = try project
    .tasks
    .filter(Column("isDone") == true)
    .fetchAll(db)

Observing and reacting to changes

GRDB leverages SQLite's data change notifications to provide us with an efficient ValueObservation tool that will, in turn, call either the onChange or onError callback it is passed.

For this example, we'll implement an observer into a simple TaskListViewController whose view we want to update as and when the tasks that belong to a certain project update.

To start, import GRDB and define an optional TransactionObserver property in your controller; this is where our observer will be kept in memory. TransactionObserver is the type returned when start is called on a ValueObservation.

TaskListViewController.swift

class TaskListViewController: UIViewController {

    private var tasksObserver: TransactionObserver?

}

tasksObserver now needs a value. We'll break its configuration out into its own function; remember to call configureTasksObserver in viewDidLoad, or wherever you're handling view setup.

TaskListViewController.swift

class TaskListViewController: UIViewController {

    private func configureTasksObserver() {
        let project: Project = ...

        let observation = ValueObservation.tracking { db in
            try project.tasks.fetchAll(db)
        }

        tasksObserver = observation.start(
            in: dbQueue,
            onError: onTasksObserverError(_:),
            onChange: onTasksObserverChange(_:)
        )
    }

}

When start is first called on a ValueObservation type, the query in its definition will run once before any changes are made. This is nice because it means we don't have to duplicate the query elsewhere in our setup code to fetch the data required for the first initialization of the controller.

You can see that 2 callbacks are passed into start on lines 12 and 13. We still need to define those:

TaskListViewController.swift

class TaskListViewController: UIViewController {

    private func onTasksObserverChange(_ tasks: [Task]) {
        // Update your UI, etc...
    }

    private func onTasksObserverError(_ error: Error) {
        // Update your UI, etc...
    }

}

The only thing left to do is clean-up when the controller closes:

TaskListViewController.swift

class TaskListViewController: UIViewController {

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        tasksObserver = nil
    }

}

That's all there is to it; GRDB does a great job of making observation straightforward.

Tip: A frequest use case for database observation is keeping the data in a UICollectionView up to date. The DeepDiff package makes a great accompaniment to what we've just covered if that's what you're implementing.

Reading and writing custom data types

GRDB supports strings, integers, dates, booleans, and enums (that adopt DatabaseValueConvertible) out of the box. For this example, we'll contrive a requirement that projects can have a user-defined accent colour and banner image that must be modelled into a ProjectBrand struct.

DatabaseManager.swift

class DatabaseManager {

    static var migrator: DatabaseMigrator {
        var migrator = DatabaseMigrator()

        migrator.eraseDatabaseOnSchemaChange = true

        migrator.registerMigration("createProject") { db in
            try db.create(table: "project") { t in
                t.autoIncrementedPrimaryKey("id")
                t.column("name", .text).notNull()
                t.column("description", .text)
                t.column("due", .date)
                t.column("isDraft", .boolean).notNull().defaults(to: true)
                t.column("accentColor", .text)
                t.column("bannerImage", .text)
            }
        }

        return migrator
    }

}

You can see on lines 15 and 16 that the two new fields still have to adhere to the basic types when they're in the database, and that they are stored in their own columns.

GRDB will come into play post-read, transforming the two fields into one ProjectBrand, and pre-write, splitting the ProjectBrand back down to two fields in preparation for SQLite. Let's implement that.

Models/Project.swift

struct Project {
    var id: Int64?
    var name: String
    var description: String?
    var due: Date?
    var isDraft: Bool
    var brand: ProjectBrand
}

struct ProjectBrand {
    var accentColor: String?
    var bannerImage: String?
}

extension Project: TableRecord, FetchableRecord, MutablePersistableRecord {

    enum Columns: String, ColumnExpression {
        case id, name, description, due, isDraft, accentColor, bannerImage
    }

    init(row: Row) {
        id = row[Columns.id]
        name = row[Columns.name]
        description = row[Columns.description]
        due = row[Columns.due]
        isDraft = row[Columns.isDraft]
        brand = ProjectBrand(
            accentColor: row[Columns.accentColor],
            bannerImage: row[Columns.bannerImage]
        )

        super.init(row: row)
    }

    func encode(to container: inout PersistenceContainer) {
        container[Columns.id] = id
        container[Columns.name] = name
        container[Columns.description] = description
        container[Columns.due] = due
        container[Columns.isDraft] = isDraft
        container[Columns.accentColor] = brand.accentColor
        container[Columns.bannerImage] = brand.bannerImage
    }

    mutating func didInsert(with rowID: Int64, for column: String?) {
        id = rowID
    }

}

You'll see on line 7 that instead of accentColor and bannerImage keys in the Project struct, we have a brand key of type ProjectBrand. Your struct should represent your data as you want to use it in your app, now how it is structured in the database.

The two main differences when compared to the Project struct we wrote in part 1 are the init and encode functions. The former is responsible for modelling a database row into a Project when the database is read; you can see that lines 27 through 30 transform the accentColor and bannerImage rows into a ProjectBrand. The latter is responsible for splitting the Project back down into database rows — lines 41 and 42 break down the ProjectBrand.

With all that in place, here's an example of what a Project could look like in your app:

try dbQueue.write { db in
    var projectBrand = ProjectBrand(
      accentColor: "#005eff",
      bannerImage: nil
    )

    var project = Project(
        name: "Advanced GRDB",
        description: "A blog post",
        due: Date().addingTimeInterval(24 * 60 * 60),
        isDraft: true,
        brand: projectBrand
    )

    try! project.insert(db)
}

You can see that we can now call insert directly on a Project type even though it has a key that uses a custom data type. As we're writing to the database in this case, the afore-defined encode function will run as part of the write process and breakdown the ProjectBrand. Similarly, we could read a Project and the ProjectBrand would be pre-assembled for us by the init function.

try dbQueue.read { db in
  let project = try Project.fetchOne(db, key: 1)
  print(project)

  // => Project(id: nil, name: "Advanced GRDB", description: Optional("A blog post"), due: Optional(2019-12-11 14:16:15 +0000), isDraft: true, brand: ProjectBrand(accentColor: "#005eff", bannerImage: nil))
}

Wrapping up

I hope this 2 part series — the first series I've ever published on elliotekj.com — has helped you get to grips with SQLite on iOS, and shown you its power and ease of use when paired with GRDB.

If you have any questions, feel free to ask.

Thanks for reading.

SQLite and iOS: Getting started with GRDB

Elliot Jackson — Wed, 11 Dec 2019 13:00:38 +0000

Designed to provide local data storage for individual applications and devices, SQLite is a small, fast, highly reliable SQL database engine that I have a lot of love for.

GRDB is a fantastic SQLite toolkit maintained by Gwendal Roué that does all the hard work for us: it provides, amongst other features, a query interface so we don't have to write raw SQL (though you can still do that if you need to), migrations, database observation, and encryption. It's what I use in my own projects, and it's what we'll be using in this article.

This article will cover setting up a local SQLite database for your iOS app, writing migrations, writing a struct to the database without any manual value mapping, and querying data pre-modelled into a struct. There will be a follow-up article that'll cover some of GRDB's more advanced features.

Part 1: How to setup GRDB in your app

This section will cover installing GRDB, creating the database file, connecting to it, and writing a migration.

Installation

First things first, you need to add GRDB to your project. Carthage isn't supported, but CocoaPods and the Swift Package Manager are.

Podfile

pod 'GRDB.swift'

Package.swift

let package = Package(
    dependencies: [
        .package(url: "https://github.com/groue/GRDB.swift.git", ...)
    ]
)

Creating the database file and connecting to it

Now that GRDB is installed, we can get down to business. Create a file named DatabaseManager.swift, AppDatabase.swift, or something similar. This is where your migrations will live alongside the setup function.

DatabaseManager.swift

import GRDB

var dbQueue: DatabaseQueue!

class DatabaseManager {

    static func setup(for application: UIApplication) throws {
        let databaseURL = try FileManager.default
            .url(for: .applicationDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
            .appendingPathComponent("db.sqlite")

        dbQueue = try DatabaseQueue(path: databaseURL.path)
        dbQueue.setupMemoryManagement(in: application)
    }

}

Right at the top on line 3 you'll see the global dbQueue variable. The connection to the database gets closed when the DatabaseQueue gets deallocated, so for most use cases you'll want it kept in memory throughout the lifetime of your app.

You'll notice that we never explicitly create the db.sqlite file, we just compose its path. That's because the DatabaseQueue initializer on line 12 will automatically create the database file for us if it can't find an existing one.

setupMemoryManagement on line 13 tells GRDB to automatically run dbQueue.releaseMemory() both when your app enters the background and if your app receives memory warnings; releaseMemory will then free up as much of the memory GRDB is using as possible.

All that's left to do is call the setup method in your AppDelegate:

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    try! DatabaseManager.setup(for: application)
    return true
}

Adding migrations

We now have a database and a connection to it, but before we can insert data, we still need to define a table and its columns.

GRDB's DatabaseMigrator is responsible for registering and applying migrations. If you're unfamiliar with the concept, migrations provide an easy way to evolve the structure of a database over time. They are guaranteed to be applied in order, and only once.

For example, say you added a new feature to version 2 of your app that required a new column in one of your tables (or even a new table entirely). GRDB will check when the DatabaseMigrator is run and see that there's a new migration that has yet to be applied to the database. It will then run that migration, ignoring all the other ones that have already been run, and the database structure in version 2 of your app will now match your updated model(s).

DatabaseManager.swift

class DatabaseManager {

    static var migrator: DatabaseMigrator {
        var migrator = DatabaseMigrator()

        migrator.registerMigration("createProject") { db in
            try db.create(table: "project") { t in
                t.autoIncrementedPrimaryKey("id")
                t.column("name", .text).notNull()
                t.column("description", .text)
                t.column("due", .date)
            }
        }

        return migrator
    }

}

Most of the above is fairly self-explanatory, but we'll run through it quickly just in case.

You can see that line 6 marks the start of a new migration. It's important to remember that once the first version of your app has been released, you can't go back and make changes to old migrations because those changes won't be applied on user's devices. Any changes must be applied in a new migration.

Line 7 creates a new table named project, then lines 8 and 9 specify the name, type, and characteristics of 2 columns. autoIncrementedPrimaryKey is the best way to define a primary key that's numeric, as it automatically prevents reuse of the value over the lifetime of the database.

Once your first migration(s) are in place, don't forget to update your setup method to run the migrations.

DatabaseManager.swift

class DatabaseManager {

    static func setup(for application: UIApplication) throws {
        // Existing setup code…
        try migrator.migrate(dbQueue)
    }

}

Should you need to make alterations to your tables in future versions of your app, you can do so quite straightforwardly by registering a new migration.

DatabaseManager.swift

static var migrator: DatabaseMigrator {
    var migrator = DatabaseMigrator()

    // `createProject` migration…

    migrator.registerMigration("v2") { db in
        try db.alter(table: "project") { t in
            t.add(column: "isDraft", .boolean).notNull().defaults(to: true)
        }

        try db.rename(table: "project", to: "collection")
    }

    return migrator
}

💡 Tip from the GRDB docs

Database table names should be singular and camel-cased (e.g. country, postalAddress). Names that follow another convention are totally OK, but you will need to perform extra configuration when using Associations.

In the early days of an app's development, its database schema changes frequently. To avoid a pileup of migrations before v1 is even out the door, you can tell GRDB to automatically reset the database if it detects a change to an existing migration.

DatabaseManager.swift

static var migrator: DatabaseMigrator {
    // Migrations…

    #if DEBUG
    migrator.eraseDatabaseOnSchemaChange = true
    #endif

    return migrator
}

Part 2: Reading from and writing to your database

We'll ignore line 11 in the "alterations snippet" in Part 1, meaning that we now have a project table that has id, name, description, due, and isDraft columns that need modelling into a struct. That's what we'll be doing in Part 2, along with some simple reading and writing.

Structuring your data

Create a new group in your project and name it Models. Within that group, create a Project.swift file and add the following struct.

Models/Project.swift

struct Project {
    var id: Int64?
    var name: String
    var description: String?
    var due: Date?
    var isDraft: Bool
}

GRDB recommends using an Int64 for auto-incrementing ids, so that's what we'll do. You'll notice that it's written as an optional — that's because an instance of the struct can exist before it's been written to the database for the first time and thus before it's been assigned its database id.

name isn't optional because we added the notNull constraint to it during the migration. The inverse is why description and due are both optional.

isDraft was specified during the "v2" migration. It too was assigned the notNull constraint, but importantly, it was also assigned a default value. After the first release of your app, you can't create a non-nullable column without a default value because any records created prior will not have assigned a value to the inexistent column.

Adopting GRDB's protocols

Next, import GRDB if you haven't already, then add the following below the Project struct:

Models/Project.swift

extension Project: Codable, FetchableRecord, MutablePersistableRecord { }

Adopting FetchableRecord tells GRDB that a Project can be initialized from a database row, and adopting MutablePersistableRecord tells GRDB that a Project can be inserted into, updated in, and deleted from the database. Codable is simply shorthand for Decodable & Encodable.

As we're working with such a simple model, we could stop here and reading and writing of the database would work just fine. There's one improvement we can make to writing though before we move onto reading.

Let's say we have the following:

do {
    try dbQueue.write { db in
        var project = Project(
            name: "Getting started with GRDB",
            description: "A blog post",
            due: Date().addingTimeInterval(24 * 60 * 60)
        )

        try! project.insert(db)

        print(project)
    }
} catch {
    print("\(error)")
}

At the moment it'll run just fine and the Project will be written to the database. However, print on line 11 will return something like this:

Project(id: nil, name: "Getting started with GRDB", description: Optional("A blog post"), due: Optional(2019-12-11 14:16:15 +0000), isDraft: true)

As you can see, the project's id is still nil even though the write succeeded. To get the id, you'd need to go back in and read from the database, which is far from ideal. Fortunately, we can tell GRDB to mutate the variable insert was called on once the insertion has completed.

Go back to your model and add the following to the extension:

Models/Project.swift

extension Project: Codable, FetchableRecord, MutablePersistableRecord {

    mutating func didInsert(with rowID: Int64, for column: String?) {
        id = rowID
    }

}

Now, if you were to run the write snippet above, print would return the id without having to go back for an extra read:

Project(id: Optional(1), name: "Getting started with GRDB", description: Optional("A blog post"), due: Optional(2019-12-11 14:16:15 +0000), isDraft: true)

Querying the database

We've already seen an example of a write, but let's break it down quickly.

do {
    try dbQueue.write { db in
        var project = Project(
            name: "Getting started with GRDB",
            description: "A blog post",
            due: Date().addingTimeInterval(24 * 60 * 60)
        )

        try! project.insert(db)
    }
} catch {
    print("\(error)")
}

On line 2 you can see that write is called on the global dbQueue connection we made earlier. write synchronously executes the database updates; one of the nice things about it is that concurrent reads are guaranteed not to return any partial updates.

Line 9 is where the SQL INSERT is actually performed.

Time to do some reading. Go back to Project.swift and add another extension — this one will house our queries.

A simple query to, for example, only return Projects that are drafts would look like this:

Models/Project.swift

extension Project {

    static func drafts() -> QueryInterfaceRequest<Project> {
        return Project.filter(Column("isDraft") == true)
    }

}

Not bad, but the readability could be improved and the room for developer error could be lessened. Let's map the columns to an enum.

Models/Project.swift

extension Project {

    private enum Columns {
        static let id = Column(CodingKeys.id)
        static let name = Column(CodingKeys.name)
        static let description = Column(CodingKeys.description)
        static let due = Column(CodingKeys.due)
        static let isDraft = Column(CodingKeys.isDraft)
    }

    static func drafts() -> QueryInterfaceRequest<Project> {
        return Project.filter(Columns.isDraft == true)
    }

}

Much better. Here are some examples of how that query can now be used:

do {
    try dbQueue.read { db in
        let drafts = try Project.drafts().fetchAll(db)
        let oneDraft = try Project.drafts().fetchOne(db)
        let tenDrafts = try Project.drafts().limit(10).fetchAll(db)
        let draftsCount = try Project.drafts().fetchCount(db)
    }
} catch {
    print("\(error)")
}

You might want to order the results:

Models/Project.swift

extension Project {

    static func dueDrafts() -> QueryInterfaceRequest<Project> {
        return Project
            .filter(Columns.isDraft == true)
            .order(Columns.due)
    }

}

Or have multiple filters:

Models/Project.swift

extension Project {

    static func draftsDueSoon() -> QueryInterfaceRequest<Project> {
        return Project
            .filter(Columns.isDraft == true)
            .filter(Columns.due < Date().addingTimeInterval(24 * 60 * 60))
            .order(Columns.due)
    }

}

Or get a specific draft:

Models/Project.swift

extension Project {

    static func draft(withId id: Int64) -> QueryInterfaceRequest<Project> {
        return Project.filter(Columns.id == id)
    }

}

do {
    try dbQueue.read { db in
        let draft = try Project.draft(withId: 12).fetchOne(db)
    }
} catch {
    print("\(error)")
}

As it's specifically matching against the row id, the above could also be written as:

do {
    try dbQueue.read { db in
        let draft = try Project.fetchOne(db, key: 12)
    }
} catch {
    print("\(error)")
}

As you can see, GRDB's query interface makes database requests very approachable, even if you have no experience writing SQL.

Until next time

GRDB is packed with features — far too many to go through in a single post and many of which don't belong in a "getting started" guide. I'll write about my favourite ones (including reacting to database changes and saving custom types) in a follow-up post next week, but even then, there'll still be things I won't have covered. Fortunately, GRDB has excellent documentation. I'd encourage you to check out.