Appendix G: Client API

The datalevin.client namespace is Datalevin's public administrative client API for a remote Datalevin server. Use it when you need to manage server-side databases, users, roles, permissions, read replicas, HA membership, or connected clients.

This appendix is a reference. Chapter 22 explains the operational model: server mode, RBAC, replicas, HA, monitoring, and deployment choices.

Most application reads and writes should still use ordinary connections from datalevin.core/get-conn or datalevin.core/create-conn. Use datalevin.client for server administration and cluster operations.

The appendix uses the Clojure names. Java, Python, and JavaScript expose the same administrative families with their normal naming conventions: for example Datalevin.newClient, new_client, and newClient; method names become listDatabases, list_databases, and listDatabases, respectively.

(require '[datalevin.client :as cl])

(def client
  (cl/new-client "dtlv://admin:secret@db-host:8898"))

The URI identifies the server and credentials. Database names are passed as separate arguments to the administrative functions.

1. Client Lifecycle

new-client performs authentication and maintains a connection pool. Creating a client includes secure password hashing work, so long-running tools should reuse one client instead of constructing a new one for every request.

Common options:

Credentials in the URI should be URL encoded when they contain special characters.

(def client
  (cl/new-client
    "dtlv://admin:secret@db-host:8898"
    {:pool-size 8
     :time-out 120000
     :ha-write-retry-timeout-ms 8000
     :ha-write-retry-delay-ms 150}))

(try
  (cl/list-databases client)
  (finally
    (cl/disconnect client)))

2. Database Administration

Database names supplied to create-database are normalized to kebab case by the server. Prefer stable, simple names and treat them as administrative identifiers, not user-facing display names.

create-database creates durable Datalog or KV database directories. The "engine" type for open-database is for server-side search engine activation, not for create-database.

Most application code does not call open-database directly. A remote get-conn or create-conn call opens the target database as needed. Use open-database from administrative code when you deliberately want to open or activate a server-side database without creating an application connection. The longest arity accepts schema, opts, and return-db-info?; schema applies to Datalog opens, and return-db-info? returns the server's database information map.

(cl/create-database client "app" :datalog)

(cl/open-database
  client
  "app"
  "datalog"
  {:user/email {:db/valueType :db.type/string
                :db/unique    :db.unique/identity}}
  {:wal? true})

(cl/list-databases client)

close-database is operationally stronger than closing one client connection: it asks the server to close the database and disconnect clients that are using it. Use it before maintenance operations such as dropping a database.

3. Users, Roles, and Permissions

Datalevin Server permissions are role based. Create users, create roles, grant permissions to roles, and assign roles to users.

3.1 Users

Passwords are stored as salted hashes on the server. User creation and password reset intentionally perform expensive password hashing.

3.2 Roles

3.3 Permissions

Permission actions:

Permission objects:

Actions and objects are hierarchical. A granted action satisfies requests for lower actions in the same chain, so :control satisfies :create, :alter, and :view; :create satisfies :alter and :view. A server-object grant satisfies database, user, and role object requests when the target rule also matches.

Selected operation permissions:

Example: read-only access to one database:

(cl/create-user client "alice" "initial-password")
(cl/create-role client :app.role/reader)

(cl/grant-permission
  client
  :app.role/reader
  :datalevin.server/view
  :datalevin.server/database
  "app")

(cl/assign-role client :app.role/reader "alice")

Example: administrative server control:

(cl/create-role client :app.role/admin)

(cl/grant-permission
  client
  :app.role/admin
  :datalevin.server/control
  :datalevin.server/server
  nil)

Use the narrowest permission that supports the task. Application users usually need database-scoped permissions, not server control.

4. Replication and HA

replica-status is for async read replicas. The returned map includes fields such as :replica-applied-lsn, :replica-source-durable-lsn, :replica-source-committed-lsn, :replica-lag-lsn, :replica-degraded-reason, and :replica-last-error.

(cl/replica-status client "app")

ha-update-membership! changes the authoritative membership for an open HA database. Chapter 22 explains the HA model, fencing, voters, leases, and the operational checks around this function.

The server accepts this call only outside with-transaction. The caller must have database alter permission for the target database and server control permission for the server. The target database must already be open and running consensus HA; the call is rejected for non-HA databases.

Useful spec keys:

(cl/ha-update-membership!
  client
  "app"
  {:ha-members
   [{:node-id 1 :endpoint "node-a:8898"}
    {:node-id 2 :endpoint "node-b:8898"}
    {:node-id 3 :endpoint "node-c:8898"}]
   :ha-control-plane
   {:voters [{:peer-id "node-a:9098" :promotable? true :ha-node-id 1}
             {:peer-id "node-b:9098" :promotable? true :ha-node-id 2}
             {:peer-id "node-c:9098" :promotable? true :ha-node-id 3}]}})

Membership updates are operator actions. Automating them without health checks, clock discipline, and rollback procedures can turn failover into a data-safety problem.

*ha-read-min-tx* is for read-after-write or monotonic-read requirements in remote Datalog HA clients. When it is bound to an integer transaction id, non-write Datalog read requests carry that minimum-tx requirement; stale read targets can reject the request, and the client will retry eligible HA endpoints.

5. System Database and Connected Clients

query-system is for administrative inspection. The query is a normal Datalog query, but unlike d/q, arguments do not include a DB object:

(cl/query-system
  client
  '[:find ?user
    :where [?u :user/name ?user]])

Use show-clients before disconnect-client:

(def clients (cl/show-clients client))

;; client-id must be a java.util.UUID value returned by show-clients.
(cl/disconnect-client client some-client-id)

Do not confuse disconnect-client with disconnect. disconnect-client disconnects another server-side client session. disconnect closes the administrative client object in your process. get-id returns the UUID of the current administrative client when you need to compare it with show-clients output.

6. Operational Notes

• Keep one administrative client per operation scope and reuse it.
• Close clients with disconnect or close-client when the operation scope ends.
• Use server URIs such as dtlv://admin:secret@host:8898; pass database names separately.
• URL encode usernames and passwords in URIs when they contain special characters.
• Prefer least-privilege roles for applications and reserve server control for operators.
• Treat close-database, drop-database, ha-update-membership!, and disconnect-client as operational actions that should be logged.
• Use Chapter 22 for deployment guidance and this appendix for function lookup.

Summary

datalevin.client is the public API for administering a Datalevin server. It is not the normal query or transaction surface for application data; that remains the connection API covered in the main chapters. Use the client namespace when the unit of work is the server, a database lifecycle operation, RBAC, replica status, HA membership, or connected-client management.