# Datomic Flare for Ruby

A Ruby gem for interacting with [Datomic](https://www.datomic.com) through [Datomic Flare](https://github.com/gbaptista/datomic-flare).

![The image features a logo with curved lines forming a ruby, suggesting distortion and movement like space-time.](https://media.githubusercontent.com/media/gbaptista/assets/refs/heads/main/ruby-datomic-flare/ruby-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

```ruby
gem '{{ gem.name }}', '~> {{ gem.version }}'
```

```ruby
require '{{ gem.name }}'

client = Flare.new(credentials: { address: 'http://localhost:3042' })
```

```ruby
client.dsl.transact_schema!(
  {
    book: {
      title: { type: :string, doc: 'The title of the book.' },
      genre: { type: :string, doc: 'The genre of the book.' }
    }
  }
)

client.dsl.assert_into!(
  :book,
  {
    title: 'The Tell-Tale Heart',
    genre: 'Horror'
  }
)

client.dsl.query(
  datalog: <<~EDN
    [:find ?e ?title ?genre
     :where [?e :book/title ?title]
            [?e :book/genre ?genre]]
  EDN
)
```

```ruby
[[4611681620380877802, 'The Tell-Tale Heart', 'Horror']]
```

{{ index }}

## Flare

### Creating a Client

```ruby
require '{{ gem.name }}'

client = Flare.new(credentials: { address: 'http://localhost:3042' })
```

### Meta

```ruby
client.meta
```

```ruby
{
  'meta' =>
    {
      'at' => '2024-09-29T13:52:52.252882446Z',
      'mode' => 'peer',
      'took' => { 'milliseconds' => 0.377446 }
    },
  'data' =>
  {
    'mode' => 'peer',
    'datomic-flare' => '1.0.0',
    'org.clojure/clojure' => '1.12.0',
    'com.datomic/peer' => '1.0.7187',
    'com.datomic/client-pro' => '1.0.81'
  }
}
```

{{ dsl }}

{{ api }}

## Development

```bash
bundle
rubocop -A

```

### Publish to RubyGems

```bash
gem build {{ gem.name }}.gemspec

gem signin

gem push {{ gem.name }}-{{ gem.version }}.gem

```

### Setup for Tests and Documentation

Tests run against real Datomic databases, and documentation (README) is generated by interacting with real Datomic databases.

To accomplish that, we need to have [Datomic](https://github.com/gbaptista/datomic-pro-docker) and [Flare](https://github.com/gbaptista/datomic-flare) running.

**TL;DR:**

```bash
git clone https://github.com/gbaptista/datomic-pro-docker.git

cd datomic-pro-docker

cp compose/flare-dev.yml docker-compose.yml

docker compose up -d datomic-storage

docker compose run datomic-tools psql \
  -f bin/sql/postgres-table.sql \
  -h datomic-storage \
  -U datomic-user \
  -d my-datomic-storage

docker compose up -d datomic-transactor

docker compose run datomic-tools clojure -M -e "$(cat <<'CLOJURE'
  (require '[datomic.api :as d])
  
  (d/create-database "datomic:sql://my-datomic-database?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")

  (d/create-database "datomic:sql://my-datomic-database-test?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")

  (d/create-database "datomic:sql://my-datomic-database-test-green?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")

  (System/exit 0)
CLOJURE
)"

docker compose up -d datomic-peer-server

docker compose up -d datomic-flare-peer datomic-flare-client

```

```bash
curl -s http://localhost:3042/meta \
  -X GET \
  -H "Content-Type: application/json"  \
| jq

```

```json
{
  "data": {
    "mode": "peer"
  }
}

```

```bash
curl -s http://localhost:3043/meta \
  -X GET \
  -H "Content-Type: application/json"  \
| jq

```

```json
{
  "data": {
    "mode": "client"
  }
}

```

You are ready to run tests and generate documentation.

**Detailed instructions:**

Clone the [datomic-pro-docker](https://github.com/gbaptista/datomic-pro-docker) repository and copy the Docker Compose template:

```bash
git clone https://github.com/gbaptista/datomic-pro-docker.git

cd datomic-pro-docker

cp compose/flare-dev.yml docker-compose.yml

```

Start PostgreSQL as Datomic's storage service:

```bash
docker compose up -d datomic-storage

docker compose logs -f datomic-storage

```

Create the table for Datomic databases:

```bash
docker compose run datomic-tools psql \
  -f bin/sql/postgres-table.sql \
  -h datomic-storage \
  -U datomic-user \
  -d my-datomic-storage

```

You will be prompted for a password, which is `unsafe`.

Start the Datomic Transactor:

```bash
docker compose up -d datomic-transactor

docker compose logs -f datomic-transactor

```

Create the following databases:

- `my-datomic-database`
- `my-datomic-database-test`
- `my-datomic-database-test-green`

```bash
docker compose run datomic-tools clojure -M -e "$(cat <<'CLOJURE'
  (require '[datomic.api :as d])
  
  (d/create-database "datomic:sql://my-datomic-database?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")

  (d/create-database "datomic:sql://my-datomic-database-test?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")

  (d/create-database "datomic:sql://my-datomic-database-test-green?jdbc:postgresql://datomic-storage:5432/my-datomic-storage?user=datomic-user&password=unsafe")

  (System/exit 0)
CLOJURE
)"

```

Start the Peer Server:

```bash
docker compose up -d datomic-peer-server

docker compose logs -f datomic-peer-server

```

Start 2 instances of Flare, one in Peer Mode and another in Client Mode:

```bash
docker compose up -d datomic-flare-peer datomic-flare-client

docker compose logs -f datomic-flare-peer
docker compose logs -f datomic-flare-client

```

You should be able to request both:

Datomic Flare in Peer Mode:
```bash
curl -s http://localhost:3042/meta \
  -X GET \
  -H "Content-Type: application/json"  \
| jq

```

```json
{
  "data": {
    "mode": "peer"
  }
}

```

Datomic Flare in Client Mode:
```bash
curl -s http://localhost:3043/meta \
  -X GET \
  -H "Content-Type: application/json"  \
| jq

```

```json
{
  "data": {
    "mode": "client"
  }
}

```

You are ready to run tests and generate documentation.

### Running Tests

Tests run against real Datomic databases, so complete the [Setup for Tests and Documentation](#setup-for-tests-and-documentation) first.

```bash
cp .env.example .env

bundle exec rspec

```

### Updating the README

Documentation (README) is generated by interacting with real Datomic databases, so complete the [Setup for Tests and Documentation](#setup-for-tests-and-documentation) first.

Update the `docs/templates/*.md` files, and then:

```sh
cp .env.example .env

bundle exec ruby ports/cli.rb docs:generate

```

Trick for automatically updating the `README.md` when `docs/templates/*.md` files change:

```sh
sudo pacman -S inotify-tools # Arch / Manjaro
sudo apt-get install inotify-tools # Debian / Ubuntu / Raspberry Pi OS
sudo dnf install inotify-tools # Fedora / CentOS / RHEL

while inotifywait -e modify docs/templates/*; \
  do bundle exec ruby ports/cli.rb docs:generate; \
  done

```

Trick for Markdown Live Preview:
```sh
pip install -U markdown_live_preview

mlp README.md -p 8042 --no-follow

```