Version 0.3

Integration of Http4s and ldbc

This guide explains how to build a web application by combining Http4s and ldbc.

Introduction

Http4s is a pure functional HTTP server and client library for Scala. By combining it with ldbc, you can build web applications with type-safe database access.

Adding Dependencies

First, you need to add the following dependencies to your build.sbt:

libraryDependencies ++= Seq(
  "org.http4s"    %% "http4s-dsl"          % "0.23.30",
  "org.http4s"    %% "http4s-ember-server" % "0.23.30",
  "org.http4s"    %% "http4s-circe"        % "0.23.30",
  "io.circe"      %% "circe-generic"       % "0.14.10"
)

Basic Usage

1. Table Definition

First, create models and table definitions corresponding to your database tables:

// Model definition
case class City(
  id:          Int,
  name:        String,
  countryCode: String,
  district:    String,
  population:  Int
)

// JSON encoder definition
object City:
  given Encoder[City] = Encoder.derived[City]

// Table definition
class CityTable extends Table[City]("city"):
  // Set column naming convention (optional)
  given Naming = Naming.PASCAL

  // Column definitions
  def id:          Column[Int]    = int("ID").unsigned.autoIncrement.primaryKey
  def name:        Column[String] = char(35)
  def countryCode: Column[String] = char(3).unique
  def district:    Column[String] = char(20)
  def population:  Column[Int]    = int()

  // Mapping definition
  override def * : Column[City] = 
    (id *: name *: countryCode *: district *: population).to[City]

val cityTable = TableQuery[CityTable]

2. Database Connection Configuration

Configure the database connection:

private def provider =
  ConnectionProvider
    .default[IO]("127.0.0.1", 13306, "ldbc", "password", "world")
    .setSSL(SSL.Trusted)

Main options available in connection configuration:

3. HTTP Route Definition

Define Http4s routes and incorporate ldbc queries:

private def routes(conn: Connection[IO]): HttpRoutes[IO] = HttpRoutes.of[IO] {
  case GET -> Root / "cities" =>
    for
      cities <- cityTable.selectAll.query.to[List].readOnly(conn)
      result <- Ok(cities.asJson)
    yield result
}

4. Server Startup

Finally, start the Http4s server:

object Main extends ResourceApp.Forever:
  override def run(args: List[String]): Resource[IO, Unit] =
    for
      conn <- provider.createConnection()
      _ <- EmberServerBuilder
             .default[IO]
             .withHttpApp(routes(conn).orNotFound)
             .build
    yield ()

Advanced Examples

Adding Custom Queries

Example of implementing searches with specific conditions or complex queries:

private def routes(conn: Connection[IO]): HttpRoutes[IO] = HttpRoutes.of[IO] {
  case GET -> Root / "cities" / "search" / name =>
    for
      cities <- cityTable.filter(_.name === name).query.to[List].readOnly(conn)
      result <- Ok(cities.asJson)
    yield result
      
  case GET -> Root / "cities" / "population" / IntVar(minPopulation) =>
    for
      cities <- cityTable.filter(_.population >= minPopulation).query.to[List].readOnly(conn)
      result <- Ok(cities.asJson)
    yield result
}

Error Handling

Example of properly handling database errors:

private def handleDatabaseError[A](action: IO[A]): IO[Response[IO]] =
  action.attempt.flatMap {
    case Right(value) => Ok(value.asJson)
    case Left(error) => 
      InternalServerError(s"Database error: ${error.getMessage}")
  }

private def routes(conn: Connection[IO]): HttpRoutes[IO] = HttpRoutes.of[IO] {
  case GET -> Root / "cities" =>
    handleDatabaseError {
      cityTable.selectAll.query.to[List].readOnly(conn)
    }
}

Summary

Combining Http4s and ldbc offers the following advantages:

In actual application development, you can combine these basic patterns to implement more complex functionality.