The SQL Graph in Clojure

Utilizes Tinkerpop3 graph over SQL database using sqlg.

Warning

Origin’s library uses J17 for releases (at least for 3.0.x versions), so independently on this Clojure library build you will be forced to use that version too.

Installation

Add this dependency to your project.clj:

[ai.z7/sqlg-clj "0.1.0"]

This library supports multiple versions of the SQLG library. To specify which version you want to use, activate the appropriate profile:

For SQLG 3.1.1 (latest):

lein with-profile +lib-3.1.1 <command>

For SQLG 3.0.4:

lein with-profile +lib-3.0.4 <command>

For SQLG 3.0.1:

lein with-profile +lib-3.0.1 <command>

For SQLG 2.1.6 (legacy):

lein with-profile +lib-2.1.6 <command>

For development with logging enabled:

lein with-profile +dev,+logging,+lib-3.1.1 <command>

Supported DBs

1. PostgreSQL

2. MySQL

3. MariaDB

4. HSQLDB

5. H2

6. MSSQL

Caution

The low-level driver is well tested only with PostgreSQL + C3P0. You are warned.

Config

Basic config is represented by sample.properties

sample.graph.db.type = postgresql
sample.graph.db.host = localhost
sample.graph.db.port = 5432
sample.graph.db.name = sample
sample.graph.db.user = username
sample.graph.db.pass = password

In order to get it prepared use

user=> (require '[sqlg-clj.config :as c])
user=> (def config (-> "sample" c/load-config :sample :graph :db c/db-config))

Same result may be done using EDN config, i.e. directly from your app:

user=> (def config (c/db-config {:port 5432 :pass "password" :user "username" :type "postgresql" :host "localhost" :name "sample"}))

When the config is ready it may be easily read back

user=>(c/config->clj config)
{"jdbc.url" "jdbc:postgresql://localhost:5432/sample", "jdbc.username" "username", "jdbc.password" "password"}

Starting

Open SqlgGraph directly

(def G (c/graph config))

or indirectly

(def G (c/open-graph config))

The last method opens a new TinkerGraph with default configuration or open a new Graph instance with the specified configuration. The configuration may be a path to a file or a Map of configuration options. When gets prepared BaseConfiguration or Configuration object as an argument - returns SqlgGraph.

Using

user=> (require '[sqlg-clj.core :refer :all])
user=> (-> ^Graph G traversal V (has-label "label"))
#object[org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.DefaultGraphTraversal 0x3fffba3f "[GraphStep(vertex,[]), HasStep([~label.eq(label)])]"]

Transactions

In order to store or to unroll the changes were made by some iteration between calls, use

user=> (require '[sqlg-clj.util :as u])
user=> (u/commit! G)
;; or
user=> (u/rollback! G)

respectively.

Examples

create, find, process

user=> (require '[sqlg-clj.util :as u])
user=> (require '[sqlg-clj.data :as d])
user=> (require '[sqlg-clj.core :refer :all])

user=> (-> G (d/add-V :test {:aa 11 :bb 22}))
#object[org.umlg.sqlg.structure.SqlgVertex 0x2e5e87e9 "v[public.test:::14]"]
user=> (-> G (d/add-V :test {:aa 33 :cc 44}))
#object[org.umlg.sqlg.structure.SqlgVertex 0x6ec0ead1 "v[public.test:::15]"]
user=> (u/commit! G)
nil

user=> (def vxs (-> G traversal V (has-label :test) (has :aa) u/into-vec!))
#'user/vxs

user=> (map #(value % :aa) vxs)
(11 33)
user=> (map #(value % :bb) vxs)
(22 nil)
user=> (map #(value % :cc) vxs)
(nil 44)

dealing with java native structures

(select->clj ^Graph G traversal V (has-label "my-label") (has "id" #uuid "1622c1fe-41d7-4536-8138-ccfba8385678"))
;; this returns lazy sequence of keywordized hashmaps

More info

Please, read original documentation here and here

Development

Checking for Dependency Updates

This project uses the lein-ancient plugin to check for outdated dependencies. You can run:

lein ancient check

To automatically upgrade all outdated dependencies:

lein ancient upgrade :interactive

Project Structure

The project follows standard Clojure conventions:

• src-clj/ - Source code

• resources/ - Configuration files

• project.clj - Core project definition (kept clean for publishing)

• profiles.clj - Development profiles and version overrides

Building

# Compile
lein compile

# Start a REPL
lein repl

# Create a JAR
lein jar

# Deploy to repositories
lein deploy

Testing

The library includes tests that demonstrate core functionality with examples from this README. Tests are designed to work with a PostgreSQL database.

Setup test database:

./test/setup_test_db.sh

Run tests with a specific SQLG version:

# Latest version
lein with-profile +dev,+logging,+lib-3.1.1 test

# Legacy version
lein with-profile +dev,+logging,+lib-2.1.6 test

Run tests with all supported SQLG versions:

./test/run_all_version_tests.sh

Test environment variables:

# Configure test database connection
export SQLG_TEST_HOST=localhost
export SQLG_TEST_PORT=5432
export SQLG_TEST_DB=sqlgtest
export SQLG_TEST_USER=postgres
export SQLG_TEST_PASS=postgres

License

©2022-2025 Fern Flower Lab

Distributed under the MIT Licence.