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

* BREAKING? Enhanced Store protocol with close alias for disconnect
* BREAKING? connect now returns the store (this)
* create (migration) fn now resolves absolute file path for migration
* Enhanced docs for Store protocol
* CLI can load config from file
* CLI can load config from env
* CLI can load config from cli args
* CLI merges configs in this order: file, env, args
* Added some tests for CLI parsing
* Added status command, to display migration status:
  - connection info - so we know which server we are connecting to
  - migrations directory - so we know where we get migrations from
  - the latest applied migration
  - the list of not-applied migrations
  - any migrations applied and not present ?!

.gitignore

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

CHANGES.md

@@ -1,3 +1,12 @@
+### Unreleased
+* Improved CLI interface
+* Improved CLI documentation
+* Added example project
+
+### 1.5.3
+* [Improved CLI options](https://github.com/yogthos/migratus/pull/251)
+* More improvements in CLI
+
 ### 1.5.2
 * [CLI options](https://github.com/yogthos/migratus/pull/244)
 * [logging improvements](https://github.com/yogthos/migratus/pull/245)

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>]]
@@ -209,6 +214,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.
@@ -386,7 +399,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).                                        |

examples/postgres/README.md

@@ -0,0 +1,77 @@
+# 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`
+
+
+Commands with migratus
+
+```shell
+
+# 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"}}'
+
+./migratus.sh status
+
+```

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 cli
+                        "-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"])
+
+
+
+  )