datahike-browser-tests 1.0.0

package/src/datahike/config.cljc

@@ -0,0 +1,294 @@
+(ns ^:no-doc datahike.config
+  (:require [clojure.edn :as edn]
+            [clojure.walk :refer [postwalk]]
+            [clojure.string :as str]
+            [clojure.spec.alpha :as s]
+            [environ.core :refer [env]]
+            [datahike.tools :as dt]
+            [datahike.store :as ds]
+            [datahike.index :as di]
+            [taoensso.timbre :as log])
+  (:import #?(:clj [java.net URI]
+              :cljs [goog.Uri])))
+
+;; global
+(def ^:dynamic *schema-meta-cache-size* (env :schema-meta-cache-size 1024))
+(def ^:dynamic *schema-write-cache-max-db-count* (env :schema-write-cache-size 1024))
+
+;; per database
+(def ^:dynamic *default-index* :datahike.index/persistent-set)
+(def ^:dynamic *default-schema-flexibility* :write)
+(def ^:dynamic *default-keep-history?* true)
+(def ^:dynamic *default-attribute-refs?* false)
+(def ^:dynamic *default-search-cache-size* 10000)
+(def ^:dynamic *default-store-cache-size* 1000)
+(def ^:dynamic *default-crypto-hash?* false)
+(def ^:dynamic *default-store* :memory)                           ;; store-less = in-memory?
+(def ^:dynamic *default-db-name* nil)                         ;; when nil creates random name
+(def ^:dynamic *default-db-branch* :db)                         ;; when nil creates random name
+
+(s/def ::index #{:datahike.index/hitchhiker-tree :datahike.index/persistent-set})
+(s/def ::keep-history? boolean?)
+(s/def ::schema-flexibility #{:read :write})
+(s/def ::attribute-refs? boolean?)
+(s/def ::search-cache-size nat-int?)
+(s/def ::store-cache-size pos-int?)
+(s/def ::crypto-hash? boolean?)
+(s/def ::writer map?)
+(s/def ::branch keyword?)
+(s/def ::entity (s/or :map associative? :vec vector?))
+(s/def ::initial-tx (s/nilable (s/or :data (s/coll-of ::entity) :path string?
+                                     :was-added? boolean?)))
+(s/def ::name string?)
+
+(s/def ::index-config map?)
+
+(s/def ::store map?)
+
+(s/def :datahike/config (s/keys :opt-un [:datahike/store
+                                         ::index
+                                         ::index-config
+                                         ::keep-history?
+                                         ::schema-flexibility
+                                         ::attribute-refs?
+                                         ::search-cache-size
+                                         ::store-cache-size
+                                         ::crypto-hash?
+                                         ::initial-tx
+                                         ::name
+                                         ::branch
+                                         ::writer]))
+
+(s/def :deprecated/schema-on-read boolean?)
+(s/def :deprecated/temporal-index boolean?)
+(s/def :deprecated/config (s/keys :req-un [:datahike/store]
+                                  :opt-un [:deprecated/temporal-index :deprecated/schema-on-read]))
+
+(def self-writer {:backend :self})
+
+(defn from-deprecated
+  [{:keys [backend username password path host port id] :as _backend-cfg}
+   & {:keys [schema-on-read temporal-index index initial-tx]
+      :as _index-cfg
+      :or {schema-on-read false
+           index *default-index*
+           temporal-index true}}]
+  {:store (merge {:backend backend}
+                 (case backend
+                   :memory {:id (or id
+                                    (when (or host path)
+                                      #?(:clj (java.util.UUID/nameUUIDFromBytes (.getBytes (str (or host path)) "UTF-8"))
+                                         :cljs (uuid (str (or host path))))))}
+                   :pg {:username username
+                        :password password
+                        :path path
+                        :host host
+                        :port port
+                        :id (or id #?(:clj (java.util.UUID/randomUUID) :cljs (random-uuid)))}
+                   :level {:path path
+                           :id (or id
+                                   (when path
+                                     #?(:clj (java.util.UUID/nameUUIDFromBytes (.getBytes path "UTF-8"))
+                                        :cljs (uuid path))))}
+                   :file {:path path
+                          :id (or id
+                                  (when path
+                                    #?(:clj (java.util.UUID/nameUUIDFromBytes (.getBytes path "UTF-8"))
+                                       :cljs (uuid path))))}))
+   :index index
+   :index-config (di/default-index-config index)
+   :keep-history? temporal-index
+   :attribute-refs? *default-attribute-refs?*
+   :initial-tx initial-tx
+   :schema-flexibility (if (true? schema-on-read) :read :write)
+   :branch *default-db-branch*
+   :writer self-writer
+   :crypto-hash? *default-crypto-hash?*
+   :search-cache-size *default-search-cache-size*
+   :store-cache-size *default-store-cache-size*})
+
+(defn int-from-env
+  [key default]
+  (try
+    (#?(:clj Integer/parseInt :cljs js/parseInt) (get env key (str default)))
+    (catch #?(:clj Exception :cljs js/Error) _ default)))
+
+(defn bool-from-env
+  [key default]
+  (try
+    #?(:clj  (Boolean/parseBoolean (get env key default))
+       :cljs (= "true" (get env key default)))
+    (catch #?(:clj Exception :cljs js/Error) _ default)))
+
+(defn map-from-env [key default]
+  (try
+    (edn/read-string (get env key (str default)))
+    (catch #?(:clj Exception :cljs js/Error) _ default)))
+
+(defn validate-config-attribute [attribute value config]
+  (when-not (s/valid? attribute value)
+    (throw (ex-info (str "Bad value " value " at " (name attribute)
+                         ", value does not match configuration definition. Must be conform to: "
+                         (s/describe attribute)) config))))
+
+(defn validate-config [{:keys [attribute-refs? schema-flexibility] :as config}]
+  (when-not (s/valid? :datahike/config config)
+    (throw (ex-info "Invalid Datahike configuration." (s/explain-data :datahike/config config))))
+  (when (and attribute-refs? (= :read schema-flexibility))
+    (throw (ex-info "Attribute references cannot be used with schema-flexibility ':read'." config))))
+
+(defn storeless-config []
+  {:store nil
+   :keep-history? false
+   :schema-flexibility :read
+   :attribute-refs? false
+   :index *default-index*
+   :search-cache-size *default-search-cache-size*
+   :store-cache-size *default-store-cache-size*
+   :crypto-hash? *default-crypto-hash?*
+   :branch *default-db-branch*
+   :writer self-writer
+   :index-config (di/default-index-config *default-index*)})
+
+(defn remove-nils
+  "Thanks to https://stackoverflow.com/a/34221816"
+  [m]
+  (let [f (fn [x]
+            (if (map? x)
+              (let [kvs (filter (comp not nil? second) x)]
+                (if (empty? kvs) nil (into {} kvs)))
+              x))]
+    (postwalk f m)))
+
+(defn- validate-store-backend
+  "Validate that the store backend is compatible with Datahike's sync query engine.
+   Throws an informative error for async-only backends like IndexedDB."
+  [store-config]
+  (when (= :indexeddb (:backend store-config))
+    (throw (ex-info
+            (str "The :indexeddb backend cannot be used directly.\n\n"
+                 "Datahike's query engine requires synchronous reads, but "
+                 "IndexedDB is async-only.\n\n"
+                 "Use a TieredStore with memory frontend instead:\n\n"
+                 "{:store {:backend :tiered\n"
+                 "         :id <your-uuid>\n"
+                 "         :frontend-config {:backend :memory :id <your-uuid>}\n"
+                 "         :backend-config {:backend :indexeddb :id <your-uuid>}}}\n\n"
+                 "See: https://github.com/replikativ/datahike/blob/main/doc/cljs-support.md")
+            {:type :async-only-backend
+             :backend :indexeddb
+             :config store-config}))))
+
+(defn load-config
+  "Load and validate configuration with defaults from the store."
+  ([]
+   (load-config nil nil))
+  ([config-as-arg]
+   (load-config config-as-arg nil))
+  ([config-as-arg opts]
+   (let [config-as-arg (if (s/valid? :datahike/config-depr config-as-arg)
+                         (apply from-deprecated config-as-arg (first opts))
+                         config-as-arg)
+         ;; Store config now provided by user - konserve validates :id requirement
+         raw-store-config (merge
+                           {:backend (keyword (:datahike-store-backend env *default-store*))}
+                           (:store config-as-arg))
+         ;; Normalize :mem to :memory for backward compatibility
+         store-config (if (= (:backend raw-store-config) :mem)
+                        (do
+                          (log/warn "DEPRECATION: :mem backend is deprecated, use :memory instead. Support for :mem will be removed in a future version.")
+                          (assoc raw-store-config :backend :memory))
+                        raw-store-config)
+         _ (validate-store-backend store-config)
+         index (if (:datahike-index env)
+                 (keyword "datahike.index" (:datahike-index env))
+                 *default-index*)
+         config {:store store-config
+                 :initial-tx (:datahike-initial-tx env)
+                 :keep-history? (bool-from-env :datahike-keep-history *default-keep-history?*)
+                 :attribute-refs? (bool-from-env :datahike-attribute-refs *default-attribute-refs?*)
+                 :schema-flexibility (keyword (:datahike-schema-flexibility env *default-schema-flexibility*))
+                 :index index
+                 :branch *default-db-branch*
+                 :crypto-hash? *default-crypto-hash?*
+                 :writer self-writer
+                 :search-cache-size (int-from-env :datahike-search-cache-size *default-search-cache-size*)
+                 :store-cache-size (int-from-env :datahike-store-cache-size *default-store-cache-size*)
+                 :index-config (if-let [index-config (map-from-env :datahike-index-config nil)]
+                                 index-config
+                                 (di/default-index-config index))}
+         merged-config ((comp remove-nils dt/deep-merge) config config-as-arg)
+         {:keys [schema-flexibility initial-tx store attribute-refs?]} merged-config]
+     ;; konserve now handles store config validation at runtime
+     (when-not (s/valid? :datahike/config merged-config)
+       (throw (ex-info "Invalid Datahike configuration." (s/explain-data :datahike/config merged-config))))
+     (when (and attribute-refs? (= :read schema-flexibility))
+       (throw (ex-info "Attribute references cannot be used with schema-flexibility ':read'." config)))
+     (if (string? initial-tx)
+       #?(:clj (update merged-config :initial-tx (fn [path] (-> path slurp read-string)))
+          :cljs (throw (ex-info ":initial-tx from path is not supported in cljs at this time" merged-config)))
+       merged-config))))
+
+;; deprecation begin
+(s/def ::backend-depr keyword?)
+(s/def ::username-depr string?)
+(s/def ::password-depr string?)
+(s/def ::path-depr string?)
+(s/def ::host-depr string?)
+(s/def ::port-depr int?)
+(s/def ::uri-depr string?)
+
+(s/def :datahike/config-depr (s/keys :req-un [::backend]
+                                     :opt-un [::username ::password ::path ::host ::port]))
+
+(defn uri->config [uri]
+  (log/warn "DEPRECATION WARNING: URI string format for Datahike configuration is deprecated and may be removed in a future version. Please migrate to the map-based configuration format. See documentation for details.")
+  (let [base-uri (#?(:clj URI. :cljs goog.Uri.) uri)
+        _ (when-not (= (.getScheme base-uri) "datahike")
+            (throw (ex-info "URI scheme is not datahike conform." {:uri uri})))
+        sub-uri #?(:clj (URI. (.getSchemeSpecificPart base-uri))
+                   :cljs (goog.Uri. (.getScheme base-uri)))
+        backend-raw (keyword (.getScheme sub-uri))
+        ;; Normalize :mem to :memory for backward compatibility
+        backend (if (= backend-raw :mem) :memory backend-raw)
+        [username password] (when-let [user-info (.getUserInfo sub-uri)]
+                              (str/split user-info #":"))
+        credentials (when-not (and (nil? username) (nil? password))
+                      {:username username
+                       :password password})
+        port (.getPort sub-uri)
+        path (.getPath sub-uri)
+        host (.getHost sub-uri)
+        ;; Parse query parameters to extract id if present
+        query-string #?(:clj (.getQuery sub-uri)
+                        :cljs (when-let [qd (.getQueryData sub-uri)]
+                                (when (.containsKey qd "id")
+                                  (str "id=" (.get qd "id")))))
+        parsed-id (when query-string
+                    (when-let [[_ id-str] (re-find #"id=([0-9a-fA-F-]+)" query-string)]
+                      #?(:clj (try (java.util.UUID/fromString id-str)
+                                   (catch Exception e
+                                     (throw (ex-info "Invalid UUID format in ?id= query parameter"
+                                                     {:uri uri :id-str id-str :error (.getMessage e)}))))
+                         :cljs (try (uuid id-str)
+                                    (catch js/Error e
+                                      (throw (ex-info "Invalid UUID format in ?id= query parameter"
+                                                      {:uri uri :id-str id-str :error (.-message e)})))))))
+        config (merge
+                {:backend backend
+                 :uri uri}
+                credentials
+                (when host
+                  {:host host})
+                (when-not (empty? path)
+                  {:path path})
+                (when (<= 0 port)
+                  {:port port})
+                (when parsed-id
+                  {:id parsed-id}))]
+    config))
+
+(defn validate-config-depr [config]
+  (when-not (s/valid? :datahike/config-depr config)
+    (throw (ex-info "Invalid datahike configuration." config))))
+;; deprecation end

package/src/datahike/connections.cljc

@@ -0,0 +1,16 @@
+(ns ^:no-doc datahike.connections)
+
+(def ^:dynamic *connections* (atom {}))
+
+(defn get-connection [conn-id]
+  (when-let [conn (get-in @*connections* [conn-id :conn])]
+    (swap! *connections* update-in [conn-id :count] inc)
+    conn))
+
+(defn add-connection! [conn-id conn]
+  (swap! *connections* assoc conn-id {:conn conn :count 1}))
+
+(defn delete-connection! [conn-id]
+  (when-let [conn (get-connection conn-id)]
+    (reset! conn :released)
+    (swap! *connections* dissoc conn-id)))

package/src/datahike/connector.cljc

@@ -0,0 +1,265 @@
+(ns ^:no-doc datahike.connector
+  (:require [datahike.connections :refer [get-connection add-connection! delete-connection!
+                                          *connections*]]
+            [datahike.readers]
+            [datahike.store :as ds]
+            [datahike.writing :as dsi]
+            [datahike.config :as dc]
+            [datahike.tools :as dt #?(:clj :refer :cljs :refer-macros) [meta-data]]
+            [datahike.writer :as w]
+            [konserve.core :as k]
+            [konserve.store :as ks]
+            [taoensso.timbre :as log]
+            [clojure.spec.alpha :as s]
+            [clojure.data :refer [diff]]
+            [konserve.utils :refer [#?(:clj async+sync) *default-sync-translation*]
+             #?@(:cljs [:refer-macros [async+sync]])]
+            [superv.async :refer [go-try- <?-]]
+            [clojure.core.async :refer [go] :as async])
+  #?(:clj (:import [clojure.lang IDeref IAtom IMeta ILookup IRef])))
+
+;; connection
+
+(declare deref-conn)
+
+(deftype Connection [wrapped-atom]
+  IDeref
+  (#?(:clj deref :cljs -deref) [conn] (deref-conn conn))
+  ;; These interfaces should not be used from the outside, they are here to keep
+  ;; the internal interfaces lean and working.
+  ILookup
+  (#?(:clj valAt :cljs -lookup) [c k] (if (= k :wrapped-atom) wrapped-atom nil))
+  IMeta
+  (#?(:clj meta :cljs -meta) [_] (meta wrapped-atom))
+  #?@(:cljs
+      [IAtom
+       ISwap
+       (-swap! [_ f] (swap! wrapped-atom f))
+       (-swap! [_ f arg] (swap! wrapped-atom f arg))
+       (-swap! [_ f arg1 arg2] (swap! wrapped-atom f arg1 arg2))
+       (-swap! [_ f arg1 arg2 args] (apply swap! wrapped-atom f arg1 arg2 args))
+       IReset
+       (-reset! [_ newval] (reset! wrapped-atom newval))
+       IWatchable ;; TODO This is unofficially supported, it triggers watches on each update, not on commits. For proper listeners use the API.
+       (-add-watch [_ key f] (add-watch wrapped-atom key f))
+       (-remove-watch [_ key] (remove-watch wrapped-atom key))
+       (-notify-watches [_ old new] (-notify-watches wrapped-atom old new))])
+  #?@(:clj
+      [IAtom
+       (swap [_ f] (swap! wrapped-atom f))
+       (swap [_ f arg] (swap! wrapped-atom f arg))
+       (swap [_ f arg1 arg2] (swap! wrapped-atom f arg1 arg2))
+       (swap [_ f arg1 arg2 args] (apply swap! wrapped-atom f arg1 arg2 args))
+       (compareAndSet [_ oldv newv] (compare-and-set! wrapped-atom oldv newv))
+       (reset [_ newval] (reset! wrapped-atom newval))
+       IRef ;; TODO This is unofficially supported, it triggers watches on each update, not on commits. For proper listeners use the API.
+       (addWatch [_ key f] (add-watch wrapped-atom key f))
+       (removeWatch [_ key] (remove-watch wrapped-atom key))]))
+
+(defn connection? [x]
+  (instance? Connection x))
+
+#?(:clj
+   (defmethod print-method Connection
+     [^Connection conn ^java.io.Writer w]
+     (let [config (:config @(:wrapped-atom conn))]
+       (.write w "#datahike/Connection")
+       (.write w (pr-str [(ds/store-identity (:store config)) (:branch config)])))))
+
+(defn deref-conn [^Connection conn]
+  (let [wrapped-atom (.-wrapped-atom conn)]
+    (when (= @wrapped-atom :released)
+      (throw (ex-info "Connection has been released."
+                      {:type :connection-has-been-released})))
+    (if (not (w/streaming? (get @wrapped-atom :writer)))
+      (let [store  (:store @wrapped-atom)
+            stored (k/get store (:branch (:config @wrapped-atom)) nil {:sync? true})]
+        (log/trace "Fetched db for deref: " (:config stored))
+        (dsi/stored->db stored store))
+      @wrapped-atom)))
+
+(defn conn-from-db
+  "Creates a mutable reference to a given immutable database. See [[create-conn]]."
+  [db]
+  (Connection. (atom db :meta {:listeners (atom {})})))
+
+(s/def ::connection #(and (instance? Connection %)
+                          (not= @(:wrapped-atom %) :released)))
+
+(defn version-check [{:keys [meta config] :as db}]
+  (let [{dh-stored :datahike/version
+         hh-stored :hitchhiker.tree/version
+         pss-stored :persistent.set/version
+         ksv-stored :konserve/version} meta
+        {dh-now :datahike/version
+         hh-now :hitchhiker.tree/version
+         pss-now :persistent.set/version
+         ksv-now :konserve/version} (meta-data)]
+    (when-not (or (= dh-now "DEVELOPMENT")
+                  (= dh-stored "DEVELOPMENT")
+                  (>= (compare dh-now dh-stored) 0))
+      (dt/raise "Database was written with newer Datahike version."
+                {:type :db-was-written-with-newer-datahike-version
+                 :stored dh-stored
+                 :now dh-now
+                 :config config}))
+    (when (and hh-stored hh-now
+               (not (>= (compare hh-now hh-stored) 0)))
+      (dt/raise "Database was written with newer hitchhiker-tree version."
+                {:type :db-was-written-with-newer-hht-version
+                 :stored hh-stored
+                 :now hh-now
+                 :config config}))
+    (when-not (>= (compare pss-now pss-stored) 0)
+      (dt/raise "Database was written with newer persistent-sorted-set version."
+                {:type :db-was-written-with-newer-pss-version
+                 :stored pss-stored
+                 :now pss-now
+                 :config config}))
+    (when-not (>= (compare ksv-now ksv-stored) 0)
+      (dt/raise "Database was written with newer konserve version."
+                {:type   :db-was-written-with-newer-konserve-version
+                 :stored ksv-stored
+                 :now    ksv-now
+                 :config config}))))
+
+(defn ensure-stored-config-consistency [config stored-config]
+  (let [;; Remove runtime parameters and creation-time parameters
+        config (dissoc config :name :search-cache-size :store-cache-size)
+        stored-config (dissoc stored-config :initial-tx :name :search-cache-size :store-cache-size)
+        stored-config (merge {:writer dc/self-writer} stored-config)
+        stored-config (if (empty? (:index-config stored-config))
+                        (dissoc stored-config :index-config)
+                        stored-config)
+        ;; if we connect to remote allow writer to be different
+        [config stored-config] (if-not (= dc/self-writer config)
+                                 [(dissoc config :writer)
+                                  (dissoc stored-config :writer)]
+                                 [config stored-config])
+
+        ;; Validate store identities match (prevents connecting to wrong database)
+        ;; Store configuration details (backend, path, credentials) can differ
+        stored-store-id (get-in stored-config [:store :id])
+        connect-store-id (get-in config [:store :id])
+        _ (when (and stored-store-id connect-store-id
+                     (not= stored-store-id connect-store-id))
+            (dt/raise "Store identity mismatch: connecting to wrong database."
+                      {:type :store-identity-mismatch
+                       :stored-id stored-store-id
+                       :connect-id connect-store-id
+                       :config config
+                       :stored-config stored-config}))
+
+        ;; Remove entire :store from comparison (backend, path, credentials can change)
+        ;; Only the :id needs to match (checked above)
+        config (dissoc config :store)
+        stored-config (dissoc stored-config :store)]
+
+    (when-not (= config stored-config)
+      (dt/raise "Configuration does not match stored configuration. In some cases this check is too restrictive. If you are sure you are loading the right database with the right configuration then you can disable this check by setting :allow-unsafe-config to true in your config."
+                {:type          :config-does-not-match-stored-db
+                 :config        config
+                 :stored-config stored-config
+                 :diff          (diff config stored-config)}))))
+
+(defn- normalize-config [cfg]
+  (-> cfg
+      (dissoc :writer :store :store-cache-size :search-cache-size)))
+
+(defn -connect-impl* [config opts]
+  (async+sync (:sync? opts) *default-sync-translation*
+              (go-try-
+               (let [_ (log/debug "Using config " (update-in config [:store] dissoc :password))
+                     store-config (:store config)
+                     store-id (ds/store-identity store-config)
+                     conn-id [store-id (:branch config)]]
+                 (if-let [conn (get-connection conn-id)]
+                   (let [conn-config (:config @(:wrapped-atom conn))
+               ;; replace store config with its identity
+                         cfg (normalize-config config)
+                         conn-cfg (normalize-config conn-config)]
+                     (when-not (= cfg conn-cfg)
+                       (dt/raise "Configuration does not match existing connections."
+                                 {:type :config-does-not-match-existing-connections
+                                  :config cfg
+                                  :existing-connections-config conn-cfg
+                                  :diff (diff cfg conn-cfg)}))
+                     conn)
+                   (let [raw-store (<?- (ks/connect-store store-config opts))
+                         _         (when-not raw-store
+                                     (dt/raise "Backend does not exist." {:type   :backend-does-not-exist
+                                                                          :config store-config}))
+                         store     (ds/add-cache-and-handlers raw-store config)
+                         _ (<?- (ds/ready-store (assoc store-config :opts opts) store))
+                         stored-db (<?- (k/get store (:branch config) nil opts))
+                         _         (when-not stored-db
+                                     (ks/release-store store-config store opts)
+                                     (dt/raise "Database does not exist." {:type   :db-does-not-exist
+                                                                           :config config}))
+                         [config store stored-db]
+                         (let [intended-index (:index config)
+                               stored-index   (get-in stored-db [:config :index])]
+                           (if-not (= intended-index stored-index)
+                             (do
+                               (log/warn (str "Stored index does not match configuration. Please set :index explicitly to " stored-index " in config. The default index is now :datahike/persistent-set. Using stored index setting now, but this might throw an error in the future."))
+                               (let [config    (assoc config :index stored-index)
+                                     store     (ds/add-cache-and-handlers raw-store config)
+                                     _ (<?- (ds/ready-store (assoc store-config :opts opts) store))
+                                     stored-db (<?- (k/get store (:branch config) nil opts))]
+                                 [config store stored-db]))
+                             [config store stored-db]))
+                         _ (version-check stored-db)
+                         _ (when-not (:allow-unsafe-config config)
+                             (ensure-stored-config-consistency config (:config stored-db)))
+                         conn      (conn-from-db (dsi/stored->db (assoc stored-db :config config) store))]
+                     (swap! (:wrapped-atom conn) assoc :writer
+                            (w/create-writer (:writer config) conn))
+                     (add-connection! conn-id conn)
+                     conn))))))
+
+;; Multimethod dispatch for different writer backends
+
+(defn backend-dispatch [config & _]
+  (get-in config [:writer :backend] :self))
+
+(defmulti -connect* #'backend-dispatch)
+
+(defmethod -connect* :self [config opts]
+  (-connect-impl* config opts))
+
+;; public API
+
+(defn connect
+  "Connect to a Datahike database.
+   
+   Config can be a map or URI string. Opts map supports:
+   - :sync? (default true) - Block and return connection, or return channel for async"
+  ([] (connect {} {}))
+  ([config] (connect config {}))
+  ([config opts]
+   (let [opts (merge {:sync? true} opts)
+         normalized (cond
+                      (string? config) (dc/uri->config config)
+                      (map? config) config
+                      :else config)
+         loaded (dissoc (dc/load-config normalized) :initial-tx :remote-peer :name)]
+     (-connect* loaded opts))))
+
+(defn release
+  ([connection] (release connection false))
+  ([connection release-all?]
+   (when-not (= @(:wrapped-atom connection) :released)
+     (let [db      @(:wrapped-atom connection)
+           _ (log/info "Releasing connection, config store backend:"
+                       (get-in db [:config :store :backend]))
+           conn-id [(ds/store-identity (get-in db [:config :store]))
+                    (get-in db [:config :branch])]]
+       (if-not (get @*connections* conn-id)
+         (log/info "Connection already released." conn-id)
+         (let [new-conns (swap! *connections* update-in [conn-id :count] dec)]
+           (when (or release-all? (zero? (get-in new-conns [conn-id :count])))
+             (delete-connection! conn-id)
+             (w/shutdown (:writer db))
+             ;; Release the underlying store to clean up resources (memory registry, etc.)
+             (ks/release-store (get-in db [:config :store]) (:store db))
+             nil)))))))