Connettersi con un transactor

Doobie è un layer JDBC funzionale puro per Scala. Un Transactor[F] fa da ponte tra i programmi puri di Doobie e una connessione reale al database.

Un Transactor sa come acquisire una Connection JDBC, eseguire il programma all’interno di una transazione e rilasciare le risorse in sicurezza.

È parametrizzato da un tipo di effetto F[_], come cats.effect.IO.

Le query Doobie sono valori di tipo ConnectionIO[A]. Descrivono un calcolo che richiede una connessione JDBC, ma non lo eseguono ancora.

Si costruiscono questi programmi in modo puro, poi li si passa a un Transactor per eseguirli. Il database non viene toccato finché non si avvia l’esecuzione.

Il Transactor più semplice è Transactor.fromDriverManager. Apre una connessione completamente nuova per ogni transazione usando il DriverManager di JDBC.

Richiede il nome della classe del driver, l’URL JDBC, il nome utente e la password. È adatto a test e script, ma non dispone di connection pooling.

Per eseguire un ConnectionIO si chiama .transact(xa). Si ottiene così un F[A], in questo caso un IO[A].

Il Transactor racchiude il programma in una transazione: esegue il commit in caso di successo e il rollback in caso di errore, rilasciando comunque la connessione.

In produzione è consigliabile usare un pool di connessioni. Doobie include HikariTransactor, basato su HikariCP.

Viene creato come una Resource, così il pool viene arrestato correttamente. È inoltre necessario passare un execution context per le operazioni JDBC bloccanti.

Un Transactor con pooling gestisce uno stato di lunga durata: connessioni aperte e thread in background. Resource[F, A] garantisce che acquisizione e rilascio siano sempre associati, anche in caso di errori o cancellazione.

In genere si costruisce il Transactor una sola volta all’avvio e lo si riutilizza per tutta la vita dell’applicazione.

HikariCP ha bisogno di un ExecutionContext per attendere le connessioni del pool. Doobie fornisce ExecutionContexts.fixedThreadPool a questo scopo, anch’esso come Resource.

Mantenere questo pool separato da quello per i calcoli impedisce che l’acquisizione bloccante delle connessioni esaurisca le risorse destinate al lavoro legato alla CPU.

Se dispone già di un javax.sql.DataSource configurato (ad esempio un’istanza Hikari ottimizzata), lo avvolga direttamente con Transactor.fromDataSource.

È una soluzione comune quando un framework gestisce il pool e si desidera soltanto utilizzarlo con Doobie.

Un semplice controllo di salute consiste nell’eseguire select 1 tramite il Transactor. Se la query restituisce un risultato, driver, URL e credenziali funzionano correttamente.

È un buon primo passo prima di collegare query reali.

Un Transactor è costruito a partire da interpreti e da una Strategy. La Strategy controlla ciò che accade intorno a ogni transazione: before, after, oops (in caso di errore) e always.

La strategia predefinita disattiva l’auto-commit, esegue il commit dopo il successo, il rollback in caso di errore e chiude sempre la connessione.

Doobie può registrare ogni statement, i relativi argomenti e i tempi di esecuzione. Le versioni moderne associano un LogHandler[F] a ogni query anziché a ogni Transactor.

È prezioso per individuare query lente e verificare il binding dei parametri in produzione.

Un Transactor[F] collega i programmi puri ConnectionIO a un database reale. fromDriverManager è adatto ai test; HikariTransactor e fromDataSource sono adatti alla produzione grazie al pooling.

Costruisca i Transactor con pooling come Resource, esegua i programmi con .transact(xa) e lasci che la Strategy predefinita gestisca commit, rollback e pulizia.