Concepts

In Joplin you declare 3 main components (databases, migrators, seeds) and combine them into environments. All these components have names and are defined in clojure maps.

:databases

A database is defined by a map containing a type and various configuration settings relevant for that type. Typically these settings will be connection and credential information.

Example

:databases { :sql-dev     {:type :jdbc, :url "jdbc:h2:mem:test"}
             :datomic-uat {:type :dt, :url "datomic://bla..."}
           }

Connection URIs are the same as in JDBC, for example, for PostgreSQL:

{:type :jdbc :url "jdbc:postgresql://localhost/test?user=elephant&password=secret&ssl=true"}

and MySQL:

{:type :jdbc :url "jdbc:mysql://localhost/test?user=dolphin&password=secret"}

:migrators

Migrators are named strings which value signifies a path on the local filesystem or classpath or a resource path in jar on the classpath. This path will be scanned for files containing the migrators. You add a migrator by creating a file (with the right name and structure) in this folder. Please note that Joplin provides functions for creating scaffolds of these files.

The rules for the migrator files can vary depending on database type.

Joplin keeps track of which migrators have been applied to the database. Thus the migration operation is idempotent. This allows rollback of migrations.

Example

:migrators {:sql-mig "joplin/migrators/sql"
            :es-mig "joplin/migrators/es"}

The joplin.{jdbc/elasticsearch/zookeeper/cassandra/datomic}.database namespace contains helpers for creating tables, attributes, indices etc for the different database types. See the example project for details.

:seeds

A seed is a named string which value is a clojure function (a var name) which seeds a given database. Joplin guarantees that seeds are only run when all migrations has been applied so you can safely make assumptions about the schema in this function.

Joplin does not keep track of which seed functions have been run, thus running them many times might result in duplicate data in the database.

Example

:seeds {:sql-seed "seeds.sql/run"
        :es-seed "seeds.es/run"
        :zk-seed "seeds.zk/run"}

The joplin.{jdbc/elasticsearch/zookeeper/cassandra/datomic}.database namespace contains helpers for creating and remove data etc for the different database types. See the example project for details.

:environments

Environments is a named collection of db/migrators/seed tuples. A environment can thus contain multiple databases. The database, migrator, seed used in an environment must defined the relevant sections described above.

You can migrate/seed an entire environment or individual database inside that environment.

Example

:environments {:dev [{:db :sql-dev, :migrator :sql-mig, :seed :sql-seed}
                     {:db :es-dev, :migrator :es-mig, :seed :es-seed}
                     {:db :zk-dev, :seed :zk-seed}]
               :prod [{:db :sql-prod, :migrator :sql-mig, :seed :sql-seed}
                     {:db :es-prod, :migrator :es-mig}
                     {:db :zk-prod}]}