scalamolecule / molecule   0.12.1

Molecule is a Scala library to query SQL and NoSQL databases with the words of your domain.

Compose an immutable "molecule" data structure:

Person.name.age.Address.street

instead of building queries

SELECT
  Person.name,
  Person.age,
  Address.street
FROM Person
  INNER JOIN Address 
    ON Person.address = Address.id;

[:find ?name ?age ?street
 :where [?a :Person/name ?name]
        [?a :Person/age ?age]
        [?a :Ns/address ?b]
        [?b :Address/street ?street]]

and get typed data matching the molecule from the database:

val persons: List[(String, Int, String)] =
  Person.name.age.Address.street.query.get

Data can also be fetched asynchronously in a Future or ZIO.

• Support for PostgreSQL, SQlite, MySQL, MariaDB, H2 and Datomic databases. More can easily be added
• Molecules for any database behave identically. Each db pass the same SPI compliance test suite (+1500 tests).
• Targets Scala 3.3, 2.13 and 2.12 on JVM and JS platforms
• Synchronous, Asynchronous (Future), ZIO and cats.effect.IO APIs
• All Scala primitive types and collection types available as molecule attributes (!)
• Typed methods to compose even complex molecules:
  • Filter/aggregation functions
  • Validation
  • Nested and optional relationships
  • Sorting
  • Pagination (offset/cursor)
  • Subscriptions
• Molecules on ScalaJS side transparently operates server database with no JSON marshalling/wiring setup
• Fast transparent binary serialization between Client and Server with Boopickle (no manual setup)
• No macros
• No complex type class implicits
• Maximum type inference in IDE to easily choose available attributes/expressions/relationships

1. Define a model of your domain data with Molecule's meta DSL

object MyDomain extends DataModel(5) { 

  trait Person {
    val name     = oneString
    val age      = oneInt
    val birthday = oneLocalDate 
    val address  = one[Address]
  }

  trait Address {
    val street = oneString
    val zip    = oneString
    val city   = oneString
  }
}

2. Run sbt compile -Dmolecule=true once to generate molecule-enabling boilerplate code and db schemas.
3. Compose fluent molecules with your domain terms to save and read data from your database.

Molecules using any Database/API combination return the same data, just in different wrappings:

Synchronous API, Datomic

import molecule.datalog.datomic.sync._

val persons: List[(String, Int, String)] =
  Person.name.age.Address.street.query.get

Synchronous API, PostgreSQL

import molecule.sql.postgres.sync._

val persons: List[(String, Int, String)] =
  Person.name.age.Address.street.query.get

Asynchronous API

import molecule.sql.postgres.async._

val persons: Future[List[(String, Int, String)]] =
  Person.name.age.Address.street.query.get

ZIO API

import molecule.sql.postgres.zio._

val persons: ZIO[Conn, MoleculeError, List[(String, Int, String)]] =
  Person.name.age.Address.street.query.get

IO API

import molecule.sql.postgres.io._

val persons: cats.effect.IO[List[(String, Int, String)]] =
  Person.name.age.Address.street.query.get

Save one entity

Person
  .name("Bob")
  .age(42)
  .Address
  .street("Baker st")
  .save.transact

Insert multiple entities

Person.name.age.Address.street.insert(
  ("Bob", 42, "Baker st"),
  ("Liz", 38, "Bond road")
).transact

Update

Person(bobId).age(43).update.transact

Delete

Person(bobId).delete.transact

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

git clone https://github.com/scalamolecule/molecule-samples.git

Add the following to your build files:

project/build.properties:

sbt.version = 1.10.2

project/plugins.sbt:

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

build.sbt:

lazy val yourProject = project.in(file("app"))
  .enablePlugins(MoleculePlugin)
  .settings(
    libraryDependencies ++= Seq(
      // One or more of:
      "org.scalamolecule" %%% "molecule-sql-postgres" % "0.12.1",
      "org.scalamolecule" %%% "molecule-sql-sqlite" % "0.12.1",
      "org.scalamolecule" %%% "molecule-sql-mysql" % "0.12.1",
      "org.scalamolecule" %%% "molecule-sql-mariadb" % "0.12.1",
      "org.scalamolecule" %%% "molecule-sql-h2" % "0.12.1",
      "org.scalamolecule" %%% "molecule-datalog-datomic" % "0.12.1",
    ),
    moleculeSchemas := Seq("app/dataModel") // paths to directories with Data Model definition files
  )

The coreTests module in this repo has several data model definitions and +1500 tests that show all details of how molecule can be used. This forms the Service Provider Interface that each database implementation needs to comply to in order to offer all functionality of Molecule.

sbt sqlPostgresJVM/test
sbt sqlSQliteJVM/test
sbt sqlMysqlJVM/test
sbt sqlMariadbJVM/test
sbt sqlH2JVM/test
sbt datalogDatomicJVM/test

sbt sqlPostgresJVM/run

sbt sqlPostgresJS/test

git clone https://github.com/scalamolecule/sbt-molecule.git
cd ..
git clone https://github.com/scalamolecule/molecule.git

cd sbt-molecule
git pull
cd ../molecule
git pull

cd molecule
sbt ++2.12.20 "project baseJVM" publishLocal  # Used by sbt-molecule
cd ../sbt-molecule
sbt publishLocal                              # Make the plugin available
cd ../molecule
sbt compile -Dmolecule=true                   # Generate boilerplate code

Marc Grue

Molecule is licensed under the Apache License 2.0