CrossClj

0.1.1 docs

SourceDocs



RECENT

    alchemist

    Clojars

    Feb 10, 2014


    OWNER
    Dylan Bijnagte
    SmartThings
    Minneapolis, MN
    Dylan.Bijnagte@smartthings.com

    Readme

    Index of all namespaces


    The README below is fetched from the published project artifact. Some relative links may be broken.

    alchemist

    A Clojure library to manage database migrations for Datomic

    Transmutations are versioned transactions that are committed to the database in order. As Alchemist commits the transaction it is annotated with :alchemist/version, :alchemist/description, and :alchemist/hash attributes. When Alchemist is run again it will not re-commit the transactions below the current state.

    Example Usage

    Create properly named edn files into the transmutations directory: MyProject resources/ transmutations/ v1_0_0__initial_commit.edn v1_1_0__more_schema.edn containing transaction data:

    [{:db/id #db/id[:db.part/db]
      :db/ident :sample/attribute
      :db/valueType :db.type/string
      :db/cardinality :db.cardinality/one
      :db.install/_attribute :db.part/db}
      
      {:db/id #db/id[:db.part/db]
      :db/ident :sample/attribute2
      :db/valueType :db.type/string
      :db/cardinality :db.cardinality/one
      :db.install/_attribute :db.part/db}
      ]
    

    and run with the defaults:

    (require '[alchemist])
    
    (alchemist/transmute "datomic:mem://testdb")
    

    alchemist schema

    alchemist keeps track of which transmutations have already run by annotating the transactions

    {:alchemist/version "1.0.0"
     :alchemist/description "initial_commit"
     :alchemist/hash 236679938}
    

    and will not transact them a second time so feel free to run at app start-up every time.

    transmutation

    trans·mu·ta·tion

    transmyo͞oˈtāSHn

    noun

    1. the action of changing or the state of being changed into another form
    2. a function, wrapped in a map, that produces a Datomic transaction vector
    {:alchemist/version "1.0.0a"
     :alchemist/description "initial_schema"
     :dynamic? true
     :transaction-fn my-transaction-producing-function}
    

    :alchemist/version A string containing “.” separated elements. Each element will be compared independently from left to right. Versions will be transacted in ascending order.

    :alchemist/description A description that will be annotated on the transaction.

    :dynamic? If true then the transaction vector’s hash will not be compared during verification. If false and the transaction vector’s hash changes between runs then verification will fail.

    Note: the #db/id reader macro produces variable results so the :db/id keys will be replaced with relative values prior to getting the hash so that the numbers are consistent.

    :transaction-fn If alchemist produces the transmutation through classpath scanning the function will read the file lazily. Any function that produces transaction edn is valid.

    Configuration

    {:create? true
     :verify? true
     :update? true
     :scan? true
     :parent-directories ["transmutations"]
     :cp-excludes [#".*/?jre/\S*.jar"
                   #".*/?clojure\S*.jar"
                   #".*/?datomic\S*.jar"
                   #".*/?bin"]}
    

    :create? boolean, allows for creation of a database if it is not found at the provided uri

    :verify? boolean, will cause an exception to be thrown if the transmutations up to the current version of the database do not match those found in database

    :update? boolean, allows previously not run transmutations to be committed

    :scan? boolean, enables classpath scanning to discover transmutation files

    :parent-directories a vector of parent directory names to scan for transmutations

    :cp-excludes a vector of regexes to filter the classpath prior to scanning

    (require '[alchemist :as a])
    
    (a/transmute "datomic:mem://testdb"
                 (merge a/default-config 
                        {:create? false
                         :parent-directories ["transmutations" "sample_data"]}))
    

    Classpath Scanning

    File Naming Rules * start with the letter “v” (case doesn’t matter) * followed by dot “.” or under-bar "_“ separated version segments (under-bars will be translated into dots at runtime) * followed by a double under-bar ”__“ * followed by a description string * ending with a ”.edn“ or ”.clj" extension

    License

    Copyright © 2013 Dylan Bijnagte

    Distributed under the Eclipse Public License, the same as Clojure.