Concepts

In joplin you declare 3 main components (databases, migrators, seeds) and combine them into environments. All these components have names and are defines in 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..."}
           }

:migrators

Migrators are named strings which value signifies a path on the local filesystem. This path will be scanned for files representing the migrators. You add a migrator 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 to rollback 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 signifies 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 in an environment must defined the relevant sections described above.

You can migrate/seed and 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}]}