datomic-flare 1.0.0

data/docs/CURL.md

@@ -0,0 +1,781 @@
+# Datomic Flare
+
+A web server that offers an HTTP/JSON API for interacting with [Datomic](https://www.datomic.com) databases.
+
+![The image features a logo with curved lines forming a tesseract, suggesting distortion and movement like space-time.](https://media.githubusercontent.com/media/gbaptista/assets/refs/heads/main/datomic-flare/datomic-flare-canvas.png)
+
+_This is not an official Datomic project or documentation and it is not affiliated with Datomic in any way._
+
+## TL;DR and Quick Start
+
+Ensure you have [Java](https://clojure.org/guides/install_clojure#java) and [Clojure](https://clojure.org/guides/install_clojure) installed.
+
+```bash
+cp .env.example .env
+
+```
+
+```bash
+clj -M:run
+
+```
+
+```text
+[main] INFO flare.components.server - Starting server on http://0.0.0.0:3042 as peer
+
+```
+
+Ensure you have [curl](https://github.com/curl/curl), [bb](https://github.com/babashka/babashka), and [jq](https://github.com/jqlang/jq) installed.
+
+Transact a Schema:
+
+
+```bash
+echo '
+[{:db/ident       :book/title
+  :db/valueType   :db.type/string
+  :db/cardinality :db.cardinality/one
+  :db/doc         "The title of the book."}
+
+ {:db/ident       :book/genre
+  :db/valueType   :db.type/string
+  :db/cardinality :db.cardinality/one
+  :db/doc         "The genre of the book."}]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+Assert Facts:
+
+
+```bash
+echo '
+[{:db/id      -1
+  :book/title "The Tell-Tale Heart"
+  :book/genre "Horror"}]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+Read the Data by Querying:
+
+
+```bash
+echo '
+[:find ?e ?title ?genre
+ :where [?e :book/title ?title]
+        [?e :book/genre ?genre]]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/q \
+  -X GET \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "inputs": [
+    {
+      "database": {
+        "latest": true
+      }
+    }
+  ],
+  "query": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": [
+    [
+      4611681620380877802,
+      "The Tell-Tale Heart",
+      "Horror"
+    ]
+  ]
+}
+```
+
+
+- [TL;DR and Quick Start](#tldr-and-quick-start)
+- [Running](#running)
+- [Quick Start](#quick-start)
+  - [CURL](#curl)
+  - [Ruby](#ruby)
+  - [JavaScript](#javascript)
+  - [Python](#python)
+- [Usage](#usage)
+  - [Meta](#meta)
+  - [Creating a Database](#creating-a-database)
+  - [Deleting a Database](#deleting-a-database)
+  - [Listing Databases](#listing-databases)
+  - [Transacting Schema](#transacting-schema)
+  - [Asserting Facts](#asserting-facts)
+  - [Reading Data by Entity](#reading-data-by-entity)
+  - [Reading Data by Querying](#reading-data-by-querying)
+  - [Accumulating Facts](#accumulating-facts)
+  - [Retracting Facts](#retracting-facts)
+- [About](#about)
+  - [Characteristics](#characteristics)
+  - [Trade-offs](#trade-offs)
+- [Development](#development)
+
+## Running
+
+The server can operate in _Client Mode_, using `com.datomic/client-pro` to connect to a Datomic Peer Server, or in _Peer Mode_, embedding `com.datomic/peer` to establish a _Peer_ directly within the server.
+
+Copy the `.env.example` file and fill it with the appropriate information.
+
+```bash
+cp .env.example .env
+
+```
+
+If you want _Client Mode_:
+```bash
+FLARE_PORT=3042
+FLARE_BIND=0.0.0.0
+
+FLARE_MODE=client
+
+FLARE_CLIENT_ENDPOINT=localhost:8998
+FLARE_CLIENT_SECRET=unsafe-secret
+FLARE_CLIENT_ACCESS_KEY=unsafe-key
+FLARE_CLIENT_DATABASE_NAME=my-datomic-database
+
+```
+
+If you want _Peer Mode_:
+```bash
+FLARE_PORT=3042
+FLARE_BIND=0.0.0.0
+
+FLARE_MODE=peer
+
+FLARE_PEER_CONNECTION_URI="datomic:sql://my-datomic-database?jdbc:postgresql://localhost:5432/my-datomic-storage?user=datomic-user&password=unsafe"
+
+```
+
+Ensure you have [Java](https://clojure.org/guides/install_clojure#java) and [Clojure](https://clojure.org/guides/install_clojure) installed.
+
+Run the server:
+
+```bash
+clj -M:run
+
+```
+
+```text
+[main] INFO flare.components.server - Starting server on http://0.0.0.0:3042 as peer
+
+```
+
+You should be able to start firing requests to the server:
+
+
+```bash
+curl -s http://localhost:3042/meta \
+  -X GET \
+  -H "Content-Type: application/json"  \
+| jq
+```
+
+```json
+{
+  "data": {
+    "datomic-flare": "1.0.0",
+    "org.clojure/clojure": "1.12.0",
+    "com.datomic/peer": "1.0.7187",
+    "com.datomic/client-pro": "1.0.81"
+  }
+}
+```
+
+## Quick Start
+
+### CURL
+TODO
+
+### Ruby
+TODO
+
+### JavaScript
+TODO
+
+### Python
+TODO
+
+## Usage
+
+Ensure you have [curl](https://github.com/curl/curl), [bb](https://github.com/babashka/babashka), and [jq](https://github.com/jqlang/jq) installed.
+
+### Meta
+
+
+```bash
+curl -s http://localhost:3042/meta \
+  -X GET \
+  -H "Content-Type: application/json"  \
+| jq
+```
+
+```json
+{
+  "data": {
+    "datomic-flare": "1.0.0",
+    "org.clojure/clojure": "1.12.0",
+    "com.datomic/peer": "1.0.7187",
+    "com.datomic/client-pro": "1.0.81"
+  }
+}
+```
+
+### Creating a Database
+
+
+```bash
+curl -s http://localhost:3042/datomic/create-database \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d '
+{
+  "name": "moonlight"
+}
+' \
+| jq
+```
+
+```json
+{
+  "data": true
+}
+```
+
+### Deleting a Database
+
+
+```bash
+curl -s http://localhost:3042/datomic/delete-database \
+  -X DELETE \
+  -H "Content-Type: application/json" \
+  -d '
+{
+  "name": "moonlight"
+}
+' \
+| jq
+```
+
+```json
+{
+  "data": true
+}
+```
+
+### Listing Databases
+
+Flare on Peer Mode:
+```bash
+curl -s http://localhost:3042/datomic/get-database-names \
+  -X GET \
+  -H "Content-Type: application/json"  \
+| jq
+
+```
+
+Flare on Client Mode
+```bash
+curl -s http://localhost:3042/datomic/list-databases \
+  -X GET \
+  -H "Content-Type: application/json"  \
+| jq
+
+```
+
+```json
+{
+  "data": [
+    "my-datomic-database"
+  ]
+}
+
+```
+
+### Transacting Schema
+
+
+```bash
+echo '
+[{:db/ident       :book/title
+  :db/valueType   :db.type/string
+  :db/cardinality :db.cardinality/one
+  :db/doc         "The title of the book."}
+
+ {:db/ident       :book/genre
+  :db/valueType   :db.type/string
+  :db/cardinality :db.cardinality/one
+  :db/doc         "The genre of the book."}
+
+ {:db/ident       :book/published_at_year
+  :db/valueType   :db.type/long
+  :db/cardinality :db.cardinality/one
+  :db/doc         "The year the book was first published."}]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": {
+    "db-before": "datomic.db.Db@1cf55f93",
+    "db-after": "datomic.db.Db@1bdd0be0",
+    "tx-data": [
+      [1003, 50, "Sun Sep 22 08:58:31 BRT 2024", 1003, true],
+      [74, 10, "published_at_year", 1003, true],
+      [74, 40, 22, 1003, true],
+      [74, 41, 35, 1003, true],
+      [74, 62, "The year the book was first published.", 1003, true],
+      [0, 13, 74, 1003, true]
+    ],
+    "tempids": {
+      "-9223300668110593560": 72,
+      "-9223300668110593559": 73,
+      "-9223300668110593558": 74
+    }
+  }
+}
+```
+
+### Asserting Facts
+
+
+```bash
+echo '
+[{:db/id      -1
+  :book/title "Pride and Prejudice"
+  :book/genre "Romance"
+  :book/published_at_year 1813}]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": {
+    "db-before": "datomic.db.Db@39bb3c53",
+    "db-after": "datomic.db.Db@d8d15290",
+    "tx-data": [
+      [1004, 50, "Sun Sep 22 08:58:31 BRT 2024", 1004, true],
+      [1005, 72, "Pride and Prejudice", 1004, true],
+      [1005, 73, "Romance", 1004, true],
+      [1005, 74, 1813, 1004, true]
+    ],
+    "tempids": {
+      "-1": 4611681620380877805
+    }
+  }
+}
+```
+
+
+
+```bash
+echo '
+[{:db/id      -1
+  :book/title "Near to the Wild Heart"
+  :book/genre "Novel"
+  :book/published_at_year 1943}
+ {:db/id      -2
+  :book/title "A Study in Scarlet"
+  :book/genre "Detective"
+  :book/published_at_year 1887}
+ {:db/id      -3
+  :book/title "The Tell-Tale Heart"
+  :book/genre "Horror"
+  :book/published_at_year 1843}]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": {
+    "db-before": "datomic.db.Db@d8d15290",
+    "db-after": "datomic.db.Db@19234447",
+    "tx-data": [
+      [1006, 50, "Sun Sep 22 08:58:31 BRT 2024", 1006, true],
+      [1007, 72, "Near to the Wild Heart", 1006, true],
+      [1007, 73, "Novel", 1006, true],
+      [1007, 74, 1943, 1006, true],
+      [1008, 72, "A Study in Scarlet", 1006, true],
+      [1008, 73, "Detective", 1006, true],
+      [1008, 74, 1887, 1006, true],
+      [1009, 72, "The Tell-Tale Heart", 1006, true],
+      [1009, 73, "Horror", 1006, true],
+      [1009, 74, 1843, 1006, true]
+    ],
+    "tempids": {
+      "-1": 4611681620380877807,
+      "-2": 4611681620380877808,
+      "-3": 4611681620380877809
+    }
+  }
+}
+```
+
+### Reading Data by Entity
+
+
+```bash
+curl -s http://localhost:3042/datomic/entity \
+  -X GET \
+  -H "Content-Type: application/json" \
+  -d '
+{
+  "database": {
+    "latest": true
+  },
+  "id": 4611681620380877807
+}
+' \
+| jq
+```
+
+```json
+{
+  "data": {
+    ":book/title": "Near to the Wild Heart",
+    ":book/genre": "Novel",
+    ":book/published_at_year": 1943,
+    ":db/id": 4611681620380877807
+  }
+}
+```
+
+### Reading Data by Querying
+
+
+```bash
+echo '
+[:find ?e ?title ?genre ?year
+ :where [?e :book/title ?title]
+        [?e :book/genre ?genre]
+        [?e :book/published_at_year ?year]]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/q \
+  -X GET \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "inputs": [
+    {
+      "database": {
+        "latest": true
+      }
+    }
+  ],
+  "query": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": [
+    [
+      4611681620380877808,
+      "A Study in Scarlet",
+      "Detective",
+      1887
+    ],
+    [
+      4611681620380877807,
+      "Near to the Wild Heart",
+      "Novel",
+      1943
+    ],
+    [
+      4611681620380877809,
+      "The Tell-Tale Heart",
+      "Horror",
+      1843
+    ],
+    [
+      4611681620380877805,
+      "Pride and Prejudice",
+      "Romance",
+      1813
+    ]
+  ]
+}
+```
+
+
+```bash
+echo '
+[:find ?e ?title ?genre ?year
+ :in $ ?title
+ :where [?e :book/title ?title]
+        [?e :book/genre ?genre]
+        [?e :book/published_at_year ?year]]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/q \
+  -X GET \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "inputs": [
+    {
+      "database": {
+        "latest": true
+      }
+    },
+    "The Tell-Tale Heart"
+  ],
+  "query": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": [
+    [
+      4611681620380877809,
+      "The Tell-Tale Heart",
+      "Horror",
+      1843
+    ]
+  ]
+}
+```
+
+### Accumulating Facts
+
+
+```bash
+echo '
+[{:db/id 4611681620380877806 :book/genre "Gothic"}]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": {
+    "db-before": "datomic.db.Db@19234447",
+    "db-after": "datomic.db.Db@6f78a7c",
+    "tx-data": [
+      [1010, 50, "Sun Sep 22 08:58:31 BRT 2024", 1010, true],
+      [1006, 73, "Gothic", 1010, true]
+    ],
+    "tempids": {
+    }
+  }
+}
+```
+
+### Retracting Facts
+
+Retract the value of an attribute:
+
+
+```bash
+echo '
+[[:db/retract 4611681620380877806 :book/genre "Gothic"]]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": {
+    "db-before": "datomic.db.Db@6f78a7c",
+    "db-after": "datomic.db.Db@89bedc15",
+    "tx-data": [
+      [1011, 50, "Sun Sep 22 08:58:31 BRT 2024", 1011, true],
+      [1006, 73, "Gothic", 1011, false]
+    ],
+    "tempids": {
+    }
+  }
+}
+```
+
+Retract an attribute:
+
+
+```bash
+echo '
+[[:db/retract 4611681620380877804 :book/genre]]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": {
+    "db-before": "datomic.db.Db@89bedc15",
+    "db-after": "datomic.db.Db@4fa1fea2",
+    "tx-data": [
+      [1012, 50, "Sun Sep 22 08:58:31 BRT 2024", 1012, true]
+    ],
+    "tempids": {
+    }
+  }
+}
+```
+
+Retract an entity:
+
+
+```bash
+echo '
+[[:db/retractEntity 4611681620380877805]]
+' \
+| bb -e '(pr-str (edn/read-string (slurp *in*)))' \
+| curl -s http://localhost:3042/datomic/transact \
+  -X POST \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<JSON \
+| jq
+{
+  "data": $(cat)
+}
+JSON
+```
+
+```json
+{
+  "data": {
+    "db-before": "datomic.db.Db@4fa1fea2",
+    "db-after": "datomic.db.Db@74650f2d",
+    "tx-data": [
+      [1013, 50, "Sun Sep 22 08:58:31 BRT 2024", 1013, true],
+      [1005, 72, "Pride and Prejudice", 1013, false],
+      [1005, 73, "Romance", 1013, false],
+      [1005, 74, 1813, 1013, false]
+    ],
+    "tempids": {
+    }
+  }
+}
+```
+
+## About
+
+### Characteristics
+
+- Languages that play well with HTTP and JSON can interact with Datomic right away.
+
+- Plug and play into any of the many flavors of Datomic's flexible infrastructure architecture.
+
+- Minimal and transparent layer, not a DSL or framework, just straightforward access to Datomic.
+
+- Despite JSON, both queries and transactions are done in EDN, enabling, e.g., powerful Datalog queries.
+
+### Trade-offs
+
+- Languages have different data types, so EDN -> JSON -> [Your Language] and vice-versa: something will be lost in translation and expressiveness.
+
+- An extra layer in the architecture adds a new hop to requests, potentially increasing latency.
+
+- Being one step away from Clojure reduces our power to leverage its types, data structures, immutability, and other desired properties.
+
+- Some tricks that would be easy to do in Clojure + Datomic become more cumbersome: transaction functions, advanced Datalog datasources, lazy loading, etc.
+
+## Development
+
+```bash
+clj -M:repl
+
+```
+
+```bash
+clj -M:format
+clj -M:lint
+
+```
+
+```bash
+cljfmt fix deps.edn src/
+clj-kondo --lint deps.edn src/
+
+```