[DONT MERGE] [#240] Improve cli ux and add cli example / docs

.gitignore

@@ -16,5 +16,5 @@ migratus.iml
 .lsp/.cache
 .portal
 .cpcache
-.calva/output-window/
+.calva
 .clj-kondo/

CHANGES.md

@@ -1,3 +1,8 @@
+### Unreleased
+* Improved CLI interface
+* Improved CLI documentation
+* Added example project
+
 ### 1.5.6
 * [Fix spec problem for next.jdbc.sql/insert! and next.jdbc.sql/delete! ](https://github.com/yogthos/migratus/pull/262)
 

README.md

@@ -130,6 +130,11 @@ The environment variable associated with the `database.table` key will replace `
 
 ### Setup
 
+Migratus can be used as a library in your project or as a CLI tool.
+There is also an option (from a third party) to run a migratus as native binary - for PostgreSQL only.
+
+#### Using Migratus as a library in your project
+
 - Add Migratus as a dependency to your `project.clj`
 ```clojure
 :dependencies [[migratus <VERSION>]]
@@ -214,6 +219,14 @@ It is possible to pass a `java.sql.Connection` or `javax.sql.DataSource` in plac
 (def config {:db {:datasource (hk/make-datasource datasource-options)}})
 ```
 
+#### Using migratus as a command line (cli) tool
+
+Migratus exposes a CLI interface via `migratus.cli` namespace.
+It uses [tools.cli](https://github.com/clojure/tools.cli) for argument parsing.
+
+
+
+
 #### Running as native image (Postgres only)
 
 [PGMig](https://github.com/leafclick/pgmig) is a standalone tool built with migratus that's compiled as a standalone GraalVM native image executable.
@@ -391,7 +404,7 @@ This is intended for use with http://2ndquadrant.com/en/resources/pglogical/ and
    | `migratus.core/rollback`                  | Run `down` for the last migration that was run.                                                                                                    |
    | `migratus.core/rollback-until-just-after` | Run `down` all migrations after `migration-id`. This only considers completed migrations, and will not migrate up.                                 |
    | `migratus.core/up`                        | Run `up` for the specified migration ids. Will skip any migration that is already up.                                                              |
-   | `migratus.core/down`                      | Run `down` for the specified migration ids. Will skip any migration that is already down. 
+   | `migratus.core/down`                      | Run `down` for the specified migration ids. Will skip any migration that is already down.
    | `migratus.core/reset`                 | Reset the database by down-ing all migrations successfully applied, then up-ing all migratinos.
    | `migratus.core/pending-list`              | Returns a list of pending migrations.                                                                                                              |
    | `migratus.core/migrate-until-just-before` | Run `up` for for any pending migrations which precede the given migration id (good for testing migrations).                                        |

deps.edn

@@ -21,6 +21,10 @@
                   hikari-cp/hikari-cp {:mvn/version "2.13.0"}
                   org.clojure/tools.trace {:mvn/version "0.7.11"}
                   org.postgresql/postgresql {:mvn/version "42.2.5"}}}
+           :migratus {:jvm-opts [;; print clojure errors to standard out instead of file
+                                 "-Dclojure.main.report=stderr"]
+                      :extra-deps {org.postgresql/postgresql {:mvn/version "42.2.5"}}
+                      :main-opts ["-m" "migratus.cli"]}
            :test-runner {:extra-paths ["test"]
                          :extra-deps
                          {lambdaisland/kaocha           {:mvn/version "1.66.1034"}

examples/postgres/README.md

@@ -0,0 +1,103 @@
+# Example using migratus with Postgres
+
+This is an example project that uses migratus to apply migrations to a PostgreSQL database.
+
+TODO: Add instructions on how to use migratus via code.
+
+## Using migratus via cli
+
+### Setup your database
+
+If you have an existing database, skip this step.
+This guide uses docker for PostgreSQL setup, but you can setup PostgreSQL any way you like.
+
+Bellow is a short guide on how to manage a PostgreSQL db as a container for the purpose of the guide.
+
+For more information on PostgreSQL see [postgres image](https://hub.docker.com/_/postgres/)
+
+```shell
+# Run a postgresql instance as a container named migratus-pg.
+# We ask PostgreSQL to create a database named migratus_example_db
+docker run --name migratus-pg --detach -p 5432:5432 \
+    -e POSTGRES_PASSWORD=migrate-me \
+    -e POSTGRES_DB=migratus_example_db \
+    -v migratus_data:/var/lib/postgresql/data \
+    postgres:latest
+
+# If all is well, we should see the container running
+docker ps
+
+> CONTAINER ID   IMAGE             COMMAND                  CREATED          STATUS          PORTS                                       NAMES
+> c37a91d27631   postgres:latest   "docker-entrypoint.s…"   23 seconds ago   Up 23 seconds   0.0.0.0:5432->5432/tcp, :::5432->5432/tcp   migratus-pg
+
+# View the data volume for postgres
+docker volume ls
+
+# And we can view the logs (in another terminal perhaps ?!)
+docker logs -f migratus-pg
+
+# You can stop and start the container
+docker container stop migratus-pg
+docker container start migratus-pg
+
+# We can remove the container once you are done, or if you want to reset everything
+docker container rm --force --volumes migratus-pg
+```
+
+### Setup migratus cli
+
+We use migratus cli via `deps.edn` aliases.
+See the `deps.edn` file in this project for details.
+
+The file should look like this
+```clojure
+{:paths ["resources"]
+ :deps {io.github.yogthos/migratus  {:mvn/version "RELEASE"}
+        org.postgresql/postgresql {:mvn/version "42.6.0"}}
+ :aliases
+ {:migratus {:jvm-opts ["-Dclojure.main.report=stderr"]
+             :main-opts ["-m" "migratus.cli"]}}}
+```
+
+If you have such a configuration, we can use `clojure` or `clj` tool to drive the CLI.
+Since Migratus is a clojure library, we need to run it via clojure like this `clojure -M:migratus --help`
+
+There is also a bash script `migratus.sh` that does the same: `./migratus.sh --help`
+
+#### Calling migratus via babashka task
+
+We can use [babashka](https://babashka.org/) tasks to drive migratus.
+This is usefull for creating developer and ops tooling.
+
+Developers can easily create migrations from cli.
+Operations people can query the migration status on the server.
+
+Bellow is a sample `bb.edn` file that calls the migratus alias in `deps.edn`, that we created earlier.
+
+bb.edn
+```clojure
+;; example on how to call migrations via babashka
+{:tasks {:requires ([clojure.string :as str])
+         migrate
+         {:doc "Run migration tasks. Specify MIGRATUS_DB_SPEC to choose db."
+          :task (clojure {:dir "."
+                          :extra-env {"MIGRATUS_STORE" "database"
+                                      "MIGRATUS_MIGRATION_DIR" "resources/migrations"}}
+                         (str/join " " (list* "-M:migratus" *command-line-args*)))}}}
+
+```
+
+Commands with migratus
+
+```shell
+
+cd examples/postgres
+# We export the configuration as env variable, but we can use cli or file as well
+export MIGRATUS_CONFIG='{:store :database :db {:jdbcUrl "jdbc:postgresql://localhost:5432/migratus_example_db?user=postgres&password=migrate-me"}}'
+
+
+clojure -M:migratus status
+# via bb
+bb migratus status
+
+```

examples/postgres/bb.edn

@@ -0,0 +1,8 @@
+;; example on how to call migrations via babashka
+{:tasks {:requires ([clojure.string :as str])
+         migrate
+         {:doc "Run migration tasks. Specify MIGRATUS_DB_SPEC to choose db."
+          :task (clojure {:dir "."
+                          :extra-env {"MIGRATUS_STORE" "database"
+                                      "MIGRATUS_MIGRATION_DIR" "resources/migrations"}}
+                         (str/join " " (list* "-M:migratus" *command-line-args*)))}}}

examples/postgres/deps.edn

@@ -0,0 +1,10 @@
+{;; migration sql files will be on "resources"
+ :paths ["src" "resources"]
+ ;; we need migratus and postgresql jdbc driver on the classpath
+ :deps {io.github.yogthos/migratus  {:local/root "../.."}
+        org.postgresql/postgresql {:mvn/version "42.6.0"}}
+ :aliases
+ {:migratus {:jvm-opts [;; print clojure errors to standard out instead of fli
+                        "-Dclojure.main.report=stderr"]
+             ;; Run migratus.cli -main fn
+             :main-opts ["-m" "migratus.cli"]}}}

examples/postgres/migratus.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+# Run migratus passing all args to it
+clojure -J-Dclojure.main.report=stderr -M:migratus "$@"

examples/postgres/src/migratus/examples/postgres.clj

@@ -0,0 +1,12 @@
+(ns migratus.examples.postgres
+  (:require [migratus.cli :as cli]))
+
+
+
+(comment
+
+  (apply cli/-main ["list"])
+
+
+
+  )