cats instance for values typed with the DBIOEffect[E, *] alias, for any effect E. This covers DBIO (which is DBIOEffect[Effect.All, *]) and the results of the standard combinators. It lives here because the implicit scope of an alias is that of its expansion, DBIOAction[R, NoStream, E]. See DBIOBase.

cats Semigroup for DBIOEffect[E, A] (including DBIO[A]) when A has a Semigroup. When A has a Monoid, the Monoid instance below is more specific and is chosen.

Suspend the construction of an action until it is run. The by-name argument is not evaluated when defer is called but each time the resulting action is run, and the action it produces is then run in its place, with the same result, streaming and effect types. An exception thrown while evaluating the argument fails the resulting action instead of propagating to the caller.

// A new timestamp is computed for each run instead of once when the action is built
val logRun: DBIO[Int] = DBIO.defer(runLog += java.time.Instant.now())

This is equivalent to DBIO.unit.flatMap(_ => a) and corresponds to cats.Defer.defer and cats.effect.IO.defer. To lift a lazily computed value rather than an action, use DBIO.defer(DBIO.successful(v)).

Lift a scala.concurrent.Future into a DBIOAction.

This overload is provided for interop with Play / Akka / Pekko code that produces Future values. The Future is wrapped in cats.effect.IO.fromFuture so that it is executed on the CE3 compute pool and its cancellation semantics are respected.

def callExternalService(): Future[String] = ???
val action: DBIO[String] = DBIO.from(callExternalService())

For lifting a CE3 effect use DBIO.from[F[_], R](fa: F[R]) directly.

Warning — do not call db.run inside the lifted Future. See the DBIO.from[F[_], R] overload for a full explanation of why nested db.run calls can cause a deadlock.

Lift any F[R] effect (e.g. cats.effect.IO[R]) into a DBIOAction.

The effect is executed on the CE3 compute pool, outside of any JDBC blocking context. Use this to interleave effectful computations (logging, UUID generation, etc.) within a DBIO action chain without needing a separate flatMap over F.

val action: DBIO[String] = for {
  id <- DBIO.from(IO(java.util.UUID.randomUUID().toString))
  _  <- users += User(id, "Alice")
} yield id

Warning — do not call db.run inside the lifted effect. db.run acquires a connection-pool permit for the full duration of the outer action. Calling db.run again from within DBIO.from attempts to acquire a second permit from the same bounded pool. If all permits are already held by outer actions, every inner db.run will block forever, deadlocking the application. Compose database work as a single DBIO chain instead:

// Wrong — nested db.run can deadlock:
DBIO.from(db.run(otherAction))

// Correct — compose as DBIO:
otherAction.flatMap(result => nextAction(result))

Alias for from.

Warning — do not call db.run inside the lifted effect. See DBIO.from[F[_], R] for a full explanation of why nested db.run calls can cause a deadlock.

A no-op DBIOAction. A cached value of DBIOAction.successful(()) to avoid allocations.