diff --git a/packages/mallard/src/k16/mallard/api.clj b/packages/mallard/src/k16/mallard/api.clj index cd71ff2..4271a5c 100644 --- a/packages/mallard/src/k16/mallard/api.clj +++ b/packages/mallard/src/k16/mallard/api.clj @@ -6,44 +6,44 @@ (set! *warn-on-reflection* true) (defn run-up! - "Execute all unapplied migrations" + "Execute all unapplied operations" [props] (executor/execute! (assoc props :direction :up))) (defn run-down! - "Rollback all applied migrations" + "Rollback all applied operations" [props] (executor/execute! (assoc props :direction :down))) (defn run-next! - "Run the next unapplied migration" + "Run the next unapplied operation" [props] (executor/execute! (merge props {:direction :up :limit 1}))) (defn undo! - "Rollback the last applied migration" + "Rollback the last applied operation" [props] (executor/execute! (merge props {:direction :down :limit 1}))) (defn redo! - "Reapply the last applied migration. This will roll it back first" + "Reapply the last applied operation. This will roll it back first" [props] (undo! props) (run-next! props)) (defn run - "A run function to be used in a Deps.edn project to execute migrations using the file loader. + "A run function to be used in a Deps.edn project to execute operations using the file loader. :init-store! - Should be given a symbol that resolves to a datastore init function. - :migrations-dir - should be a resource path to a directory containing migration files that will - be loaded using the file loader. + :load-dir - should be a resource path to a directory containing operation files that will + be loaded using the file loader. :action - should be given an action to perform. One of #{:up :down :next :undo :redo}" [{create-ctx-fn :create-ctx! create-store-fn :create-store! shutdown-fn :shutdown! - migrations-dir :migrations-dir + load-dir :load-dir action :action}] (let [create-store! (requiring-resolve create-store-fn) @@ -52,7 +52,7 @@ (create-ctx)) store (create-store! context) props {:context context - :migrations (loaders.fs/load-migrations! migrations-dir) + :operations (loaders.fs/load! load-dir) :store store}] (case action diff --git a/packages/mallard/src/k16/mallard/dev.clj b/packages/mallard/src/k16/mallard/dev.clj index 882c1a7..3e4611e 100644 --- a/packages/mallard/src/k16/mallard/dev.clj +++ b/packages/mallard/src/k16/mallard/dev.clj @@ -17,17 +17,17 @@ [:or [:map - [:migrations executor/?Operations]] + [:operations executor/?Operations]] [:map - [:migrations-dir :string]]]]) + [:load-dir :string]]]]) -(def run-migrations-component! +(def run! {:gx/start {:gx/processor (fn [{:keys [props]}] - (let [{:keys [store context migrations migrations-dir]} props] + (let [{:keys [store context operations load-dir]} props] (api/run-up! {:store store :context context - :migrations (or migrations - (loaders.fs/load-migrations! migrations-dir))}))) + :operations (or operations + (loaders.fs/load! load-dir))}))) :gx/props-schema ?Props}}) diff --git a/packages/mallard/src/k16/mallard/executor.clj b/packages/mallard/src/k16/mallard/executor.clj index 6161eb8..2a0e060 100644 --- a/packages/mallard/src/k16/mallard/executor.clj +++ b/packages/mallard/src/k16/mallard/executor.clj @@ -26,18 +26,18 @@ [:map [:context {:optional true} [:maybe :any]] [:store datastore.api/?DataStore] - [:migrations ?Operations] + [:operations ?Operations] [:limit {:optional true} [:int {:min 1}]] [:direction [:enum :up :down]]]) (defn- index-by [key-fn col] (->> col - (map (fn [migration] - [(key-fn migration) migration])) + (map (fn [item] + [(key-fn item) item])) (into {}))) (defn- project-op-log - "Reduces over the op-log to project the concrete sequence of currently applied migrations ids. + "Reduces over the op-log to project the concrete sequence of currently applied operation ids. The op-log contains a sequence of `:up` and `:down` operations which can be reduced down to a sequence of only `:up` operation ids @@ -59,7 +59,7 @@ :down (if (= (:id op) (last operations)) (pop operations) (throw (ex-info (str "Error reprocessing op-log. A :down operation did not " - "follow an :up migration of the same id") + "follow an :up operation of the same id") {:last-op (last operations) :current-op (:id op)}))))) [] @@ -104,8 +104,8 @@ (defn- find-unapplied "Return an ordered set of operations based on the current op-log state and desired `:direction`. - - If the direction is `:up` this will return the remaining set of *unapplied* migrations. - - If the direction is `:down` this will return the *applied* migrations in reverse order." + - If the direction is `:up` this will return the remaining set of *unapplied* operations. + - If the direction is `:down` this will return the *applied* operations in reverse order." [op-log operations direction] (let [{:keys [applied unapplied]} (derive-active-state op-log operations)] (case direction @@ -113,11 +113,11 @@ :down (reverse applied)))) (defn- execute-one! - "Execute a single migration and return an ?OpLogEntry to be appended to the op-log." + "Execute a single operation and return an ?OpLogEntry to be appended to the op-log." [context operation direction] (let [{:keys [id run-up! run-down!]} operation ts (t/now)] - (log/info (str "Executing migration " id " [" direction "]")) + (log/info (str "Executing operation " id " [" direction "]")) (case direction :up (run-up! context) @@ -131,16 +131,16 @@ :finished_at (t/now)})) (defn execute! - "Execute the given migrations and return the new log of operations. This will handle locking - and will mutate the datastore with the changing op-log as migrations are applied." - [{:keys [context store migrations direction limit] :as props}] + "Execute the given operations and append to the op-log which is then returned. This will handle locking + and will mutate the datastore with the changing op-log as operations are applied." + [{:keys [context store operations direction limit] :as props}] (when-not (m/validate ?ExecuteProps props) (throw (ex-info "Invalid arguments provided" {:errors (me/humanize (m/explain ?ExecuteProps props))}))) (let [state (datastore.api/load-state store) op-log (atom (or (:log state) [])) - unapplied (cond-> (find-unapplied (:log state) migrations direction) + unapplied (cond-> (find-unapplied (:log state) operations direction) limit ((partial take limit))) lock (datastore.api/acquire-lock! store)] diff --git a/packages/mallard/src/k16/mallard/loaders/fs.clj b/packages/mallard/src/k16/mallard/loaders/fs.clj index 37483e3..bcf1191 100644 --- a/packages/mallard/src/k16/mallard/loaders/fs.clj +++ b/packages/mallard/src/k16/mallard/loaders/fs.clj @@ -13,7 +13,7 @@ (re-find #"^\(ns\s+([^\s);]+)") second)) -(defn resolve-migration-files [dir] +(defn resolve-operation-files [dir] (->> (or (io/resource dir) (io/file dir)) io/file @@ -24,17 +24,17 @@ sort vec)) -(defmacro load-migrations! - "Given a file or resource directory path attempt to load all files found within as migrations. +(defmacro load! + "Given a file or resource directory path attempt to load all files found within as operations. - This is implemented as a macro to allow preloading migrations during native-image compilation. This - also allows loading of migrations when they are bundled as resources within a jar as the full resource + This is implemented as a macro to allow preloading operations during native-image compilation. This + also allows loading of operations when they are bundled as resources within a jar as the full resource paths are known up front." [dir] - (let [namespaces (try (resolve-migration-files dir) + (let [namespaces (try (resolve-operation-files dir) (catch Exception _))] `(let [namespaces# (or ~namespaces - (resolve-migration-files ~dir))] + (resolve-operation-files ~dir))] (doseq [namespace# namespaces#] (require (symbol namespace#))) diff --git a/packages/mallard/src/k16/mallard/loaders/ns.clj b/packages/mallard/src/k16/mallard/loaders/ns.clj index d98d1a0..87e60dd 100644 --- a/packages/mallard/src/k16/mallard/loaders/ns.clj +++ b/packages/mallard/src/k16/mallard/loaders/ns.clj @@ -4,8 +4,8 @@ (set! *warn-on-reflection* true) -(defn load-migrations! - "Dynamically require all given namespaces as migration files." +(defn load! + "Dynamically require all given namespaces as operation files." [namespaces] (->> namespaces (map (fn [ns'] diff --git a/packages/mallard/test/k16/mallard/executor_test.clj b/packages/mallard/test/k16/mallard/executor_test.clj index 605fef4..e9ad369 100644 --- a/packages/mallard/test/k16/mallard/executor_test.clj +++ b/packages/mallard/test/k16/mallard/executor_test.clj @@ -33,11 +33,11 @@ (is (= ExceptionInfo (type ex))) (is (= "Invalid arguments provided" (ex-message ex))) (is (= {:errors {:direction ["missing required key"], - :migrations ["missing required key"], + :operations ["missing required key"], :store ["missing required key"]}} (ex-data ex)))) - (let [ex (try (executor/execute! {:migrations :wrong + (let [ex (try (executor/execute! {:operations :wrong :direction :left :store "incorrect store" :limit 0}) @@ -46,7 +46,7 @@ (is (= ExceptionInfo (type ex))) (is (= "Invalid arguments provided" (ex-message ex))) (is (= {:errors {:direction ["should be either :up or :down"], - :migrations ["should be a sequence of operations"], + :operations ["should be a sequence of operations"], :store ["should Implement DataStore protocol"], :limit ["should be at least 1"]}} (ex-data ex)))))) @@ -68,16 +68,16 @@ (executor/execute! {:store store :context context :direction :up - :migrations migs}) + :operations migs}) (executor/execute! {:store store :context context :direction :down - :migrations migs})))) + :operations migs})))) (deftest single-execution-test (let [store (stores.memory/create-memory-datastore) op-log (executor/execute! {:store store - :migrations migrations + :operations migrations :direction :up :limit 1})] @@ -93,7 +93,7 @@ (deftest multi-execution-test (let [store (stores.memory/create-memory-datastore) op-log (executor/execute! {:store store - :migrations migrations + :operations migrations :direction :up})] (is (= 3 (count op-log))) @@ -109,7 +109,7 @@ (testing "Undoing the last migration" (let [op-log (executor/execute! {:store store - :migrations migrations + :operations migrations :direction :down :limit 1})] @@ -132,7 +132,7 @@ (testing "Rerunning the last migration" (let [op-log (executor/execute! {:store store - :migrations migrations + :operations migrations :direction :up :limit 1})] @@ -155,7 +155,7 @@ :finished_at (t/now)}]}) (let [op-log (executor/execute! {:store store - :migrations migrations + :operations migrations :direction :up :limit 1})] @@ -174,7 +174,7 @@ :finished_at (t/now)}]}) (let [ex (try (executor/execute! {:store store - :migrations [] + :operations [] :direction :down :limit 1}) (catch Exception e e))] diff --git a/packages/mallard/test/k16/mallard/loaders/fs_test.clj b/packages/mallard/test/k16/mallard/loaders/fs_test.clj index b11c3f0..283be2e 100644 --- a/packages/mallard/test/k16/mallard/loaders/fs_test.clj +++ b/packages/mallard/test/k16/mallard/loaders/fs_test.clj @@ -6,7 +6,7 @@ (deftest fs-loader-test (testing "It should load migrations from disk in the correct order" - (let [migrations (loaders.fs/load-migrations! "fixtures/migrations")] + (let [migrations (loaders.fs/load! "fixtures/migrations")] (is (match? [{:id "1-migration" :run-up! (requiring-resolve 'fixtures.migrations.1-migration/run-up!) :run-down! (requiring-resolve 'fixtures.migrations.1-migration/run-down!)}