scalamolecule / molecule   0.3.0

Apache License 2.0 Website GitHub

Molecule translates custom Scala code to database queries for multiple databases.

Scala versions: 3.x 2.13 2.12 2.11
Scala.js versions: 1.x 0.6

Molecule is a library to write type-inferred Scala code that translates to queries for various databases.

An sbt-molecule plugin generates boilerplate code from your domain data model definition so that you can write intuitive type-inferred queries with the words of your domain.

  • Uniformly works with databases from various query languages:
  • Targets Scala 3.3, 2.13 and 2.12 on JVM and JS platforms
  • Single SPI of 1300+ tests adhered to by each database implementation
  • No macros
  • No complex type class implicits
  • Maximum type inference
  • Synchronous/Asynchronous/ZIO APIs
  • Nested data structures
  • Validation
  • Pagination (offset/cursor)
  • Sorting
  • Subscriptions and more...

Documentation at still documents the old macro-based version of molecule but will be updated to the new version. Most concepts overlap.


Same molecule query in all APIs returns the same data in different type wrappings:

Synchronous API, Datomic

import molecule.datalog.datomic.sync._
val persons: List[(String, Int, String)] =

Synchronous API, H2

import molecule.sql.jdbc.sync._
val persons: List[(String, Int, String)] =

Asynchronous API

import molecule.datalog.datomic.async._
val persons: Future[List[(String, Int, String)]] =


import molecule.datalog.datomic.zio._
val persons: ZIO[Conn, MoleculeError, List[(String, Int, String)]] =

Save one entity"Bob").age(42).Adress.street("Baker st").save.transact

Insert multiple entities
  ("Bob", 42, "Baker st"),
  ("Liz", 38, "Bond road")





Get started

Please clone molecule-samples and use one of the template projects to get started.

git clone

Basic sbt setup

Add the following to your build files:




addSbtPlugin("org.scalamolecule" % "sbt-molecule" % "1.3.0")


lazy val yourProject ="app"))
    libraryDependencies ++= Seq(
      // One or more of:
      "org.scalamolecule" %%% "molecule-datalog-datomic" % "0.3.0",
      "org.scalamolecule" %%% "molecule-sql-h2" % "0.3.0",
      "org.scalamolecule" %%% "molecule-sql-postgres" % "0.3.0",
    moleculeSchemas := Seq("app") // paths to your data model definitions...


The coreTests module in this repo has sevel data model definitions and more than 1300 tests that you can get inspiration from.

Run jvm tests

Run the same test suite on jvm targeting both Datomic and JDBC-compliant databases:

sbt datalogDatomicJVM/test
sbt sqlH2JVM/test
sbt sqlPostgresJVM/test

Run js tests

To run tests from the client side with Scala.js, first run a jvm server (Akka Http) in one process:

sbt datalogDatomicJVM/run

Then in another process/terminal window:

sbt datalogDatomicJS/test

(Scalajs tests don't work with Scala 3.x yet)

Publish locally

To be completely up-to-date, you can pull the latest changes from Github and publish molecule locally (for Scala 2.13):

git pull
sbt publishLocal

Or target other Scala versions:

sbt ++3.3.1 publishLocal
sbt ++2.12.18 publishLocal


Marc Grue


Molecule is licensed under the Apache License 2.0