The ClojureScript client of stratus (Clojars com.stratus-db/client), for server-side callers (Node): transit-json requests (keywords, UUIDs and instants native), gzipped transit-json responses (fetch inflates them). Every function returns a js/Promise.
The hosted API (https://api.stratus-db.com), with an API key:
(def conn (client/connect "https://api.stratus-db.com" {:api-key (.-STRATUS_API_KEY js/process.env)})) (-> (client/create-db! conn {:name "orders" :primary-key :order/id}) (.then (fn [{:keys [id]}] (client/transact! conn id {:tx [{:order/id (client/squuid) :total 5}]}))))
Databases are at <url>/v1/dbs/<id>/..., the key sent as "Authorization: Bearer <key>".
The internal service (techascent's), with requests signed: (client/connect catalog-url {:sign f}), f taking the request as a js object in the AWS SDK signer's shape ({:method :protocol :hostname :port :path :query :headers :body}) to a promise of it signed - stratus-db.sigv4/ signer (clients/cljs/sigv4, not published: it needs the AWS SDK's signer, which the hosted API doesn't, so this library has no npm dependencies). Databases are addressed by id: their Function URLs come from the catalog, cached, and looked up again periodically (:resolve-ms, default 5 minutes) and when a URL fails (403, 404). Busy databases answer 429: retried with backoff. The high-level functions resolve to the response body and reject with an ex-info {:status :error :message} on an error; call gives {:status :body} as it is. The query language: docs/query.md.
The ClojureScript client of stratus (Clojars com.stratus-db/client), for server-side callers
(Node): transit-json requests (keywords, UUIDs and instants native), gzipped transit-json
responses (fetch inflates them). Every function returns a js/Promise.
The hosted API (https://api.stratus-db.com), with an API key:
(def conn (client/connect "https://api.stratus-db.com" {:api-key (.-STRATUS_API_KEY js/process.env)}))
(-> (client/create-db! conn {:name "orders" :primary-key :order/id})
(.then (fn [{:keys [id]}] (client/transact! conn id {:tx [{:order/id (client/squuid) :total 5}]}))))
Databases are at <url>/v1/dbs/<id>/..., the key sent as "Authorization: Bearer <key>".
The internal service (techascent's), with requests signed: (client/connect catalog-url {:sign
f}), f taking the request as a js object in the AWS SDK signer's shape ({:method :protocol
:hostname :port :path :query :headers :body}) to a promise of it signed - stratus-db.sigv4/
signer (clients/cljs/sigv4, not published: it needs the AWS SDK's signer, which the hosted API
doesn't, so this library has no npm dependencies). Databases are addressed by id: their
Function URLs come from the catalog, cached, and looked up again periodically (:resolve-ms,
default 5 minutes) and when a URL fails (403, 404). Busy
databases answer 429: retried with backoff. The high-level functions resolve to the response
body and reject with an ex-info {:status :error :message} on an error; call gives
{:status :body} as it is. The query language: docs/query.md.(await-index conn id att)(await-index conn id att timeout-ms)A promise resolving when att's index is :ready (to the db info), rejecting when it is :failed or after timeout-ms (default 60000).
A promise resolving when att's index is :ready (to the db info), rejecting when it is :failed or after timeout-ms (default 60000).
(call url method path)(call url method path body)(call url method path body opts)method path body (a value, sent as transit) to function URL url: a promise of {:status :body}, retried while throttled (429). opts: :sign (a signer, as connect's), :caller (unsigned, for a local service), :retries (default 200).
method path body (a value, sent as transit) to function URL url: a promise of {:status
:body}, retried while throttled (429). opts: :sign (a signer, as connect's), :caller
(unsigned, for a local service), :retries (default 200).(call-catalog conn method path)(call-catalog conn method path body)method path body to the catalog: a promise of {:status :body}.
method path body to the catalog: a promise of {:status :body}.
(call-db conn id method path)(call-db conn id method path body)method path body to database id: a promise of {:status :body}. Hosted: <url>/v1/dbs/<id>. The internal service: its Function URL, a 403 or 404 re-resolving it and retrying once if it changed.
method path body to database id: a promise of {:status :body}. Hosted: <url>/v1/dbs/<id>. The
internal service: its Function URL, a 403 or 404 re-resolving it and retrying once if it
changed.(catalog-history conn)(catalog-history conn {:keys [from limit]})One page of the catalog's events from t :from (default 1), at most :limit (default 100, at most 1000): {:events [{:t :op :id ... :meta {:caller :time}}] :next t-or-nil} - who created, renamed and deleted which database, and its storage when measured: the catalog's audit trail.
One page of the catalog's events from t :from (default 1), at most :limit (default 100, at
most 1000): {:events [{:t :op :id ... :meta {:caller :time}}] :next t-or-nil} - who created,
renamed and deleted which database, and its storage when measured: the catalog's audit trail.(catalog-history-all conn)(catalog-history-all conn opts)Every catalog event from :from on, following :next: a promise of a vector.
Every catalog event from :from on, following :next: a promise of a vector.
(connect url)(connect url opts)A connection to the service at url: the hosted API's base URL with :api-key, else the internal service's catalog URL. opts: :api-key (hosted); :sign :caller (as call's), :resolve-ms (internal).
A connection to the service at url: the hosted API's base URL with :api-key, else the internal service's catalog URL. opts: :api-key (hosted); :sign :caller (as call's), :resolve-ms (internal).
(create-db! conn spec)Creates a database {:name :primary-key}: its {:id :url}.
Creates a database {:name :primary-key}: its {:id :url}.
(create-key! conn)(create-key! conn {:keys [name scope]})A new key: {:key (shown once) :record}. :scope - database ids it may reach (default all).
A new key: {:key (shown once) :record}. :scope - database ids it may reach (default all).
(db-by-name conn name)The record of the live database named name (names are unique among live databases; a deleted one's name is free again). Fails 404 when there is none.
The record of the live database named name (names are unique among live databases; a deleted one's name is free again). Fails 404 when there is none.
(db-info conn id){:id :primary-key :t :checkpoint-t :indexes :index-errors}.
{:id :primary-key :t :checkpoint-t :indexes :index-errors}.
(db-record conn id)Database id's record, deleted or not.
Database id's record, deleted or not.
(db-url conn id)A promise of database id's URL (nil when the catalog has none), cached for :resolve-ms.
A promise of database id's URL (nil when the catalog has none), cached for :resolve-ms.
(dbs conn)(dbs conn {:keys [deleted?]})The live databases' records, oldest first; deleted ones too with {:deleted? true}. A record: {:id :name :primary-key :created :state :url :deleted :storage}.
The live databases' records, oldest first; deleted ones too with {:deleted? true}. A record:
{:id :name :primary-key :created :state :url :deleted :storage}.(delete-db! conn id)(drop-index! conn id att)(excise! conn id {:keys [rows attributes]})Excises :rows (primary keys) and :attributes ([{:pk :att}]) - erasure: gone from the current state, its indexes and history (and, hosted, the database's forks): {:t :rows :attributes}.
Excises :rows (primary keys) and :attributes ([{:pk :att}]) - erasure: gone from the current
state, its indexes and history (and, hosted, the database's forks): {:t :rows :attributes}.(fork! conn id)(fork! conn id opts)Forks database id (hosted): a new database, this one as of transaction :t (default its latest), recorded in both logs: the fork's record ({:id :fork-of {:db :t} ...}).
Forks database id (hosted): a new database, this one as of transaction :t (default its
latest), recorded in both logs: the fork's record ({:id :fork-of {:db :t} ...}).(history conn id)(history conn id {:keys [from limit]})One page of database id's history from t :from (default 1), at most :limit entries (default 100, at most 1000): {:entries [{:t :type :time :commands ...}] :next t-or-nil}. A transaction's entry carries its caller's ARN, its time and its commands ({:pk :att :value :op}): the audit trail.
One page of database id's history from t :from (default 1), at most :limit entries (default
100, at most 1000): {:entries [{:t :type :time :commands ...}] :next t-or-nil}. A
transaction's entry carries its caller's ARN, its time and its commands ({:pk :att :value
:op}): the audit trail.(history-all conn id)(history-all conn id opts)Every history entry from :from on, following :next: a promise of a vector.
Every history entry from :from on, following :next: a promise of a vector.
(keys-list conn)The account's keys' records (no secrets).
The account's keys' records (no secrets).
(measure-storage! conn id)Measures database id's storage now ({:bytes :objects}, deleted or not) into the catalog's audit log: its record, :storage updated.
Measures database id's storage now ({:bytes :objects}, deleted or not) into the catalog's
audit log: its record, :storage updated.(pull conn id pks)The rows of pks, in order, nil for a missing one.
The rows of pks, in order, nil for a missing one.
(query conn id q)One page of query q (docs/query.md): {:rows :next :t}.
One page of query q (docs/query.md): {:rows :next :t}.
(query-all conn id q)Every row of query q, following :next: a promise of a vector.
Every row of query q, following :next: a promise of a vector.
(rename-db! conn id name)(request-index! conn id att)Requests attribute att's index: {:att :state} (:building until built).
Requests attribute att's index: {:att :state} (:building until built).
(resolve! conn)Refreshes the connection's database URLs from the catalog: a promise of {id url}.
Refreshes the connection's database URLs from the catalog: a promise of {id url}.
(revoke-key! conn key-id)Revokes key key-id: its record.
Revokes key key-id: its record.
(squuid)A sequential UUID: created later in this process, it sorts after every earlier one, even within a millisecond or when the clock steps back (a full sequence carries into the time).
A sequential UUID: created later in this process, it sorts after every earlier one, even within a millisecond or when the clock steps back (a full sequence carries into the time).
(transact! conn id tx){:tx [maps] :retract [maps] :delete [pks] :tx-id id}: {:t :pks}. Every map carries its primary key (squuid makes new ones). :tx-id (optional; a UUID or a string) makes a retry safe: if a transaction with that id is already committed, nothing is applied and the answer is the first one's with :duplicate true (409 :tx-id-reused if it had other commands). :match (optional; row maps: a primary key and attributes) is a compare-and-set: each attribute must hold that value now (nil: absent; numbers across types, as queries' :=), else nothing is applied and it rejects with 409 :conflict.
{:tx [maps] :retract [maps] :delete [pks] :tx-id id}: {:t :pks}. Every map carries its
primary key (squuid makes new ones). :tx-id (optional; a UUID or a string) makes a retry
safe: if a transaction with that id is already committed, nothing is applied and the answer
is the first one's with :duplicate true (409 :tx-id-reused if it had other commands).
:match (optional; row maps: a primary key and attributes) is a compare-and-set: each
attribute must hold that value now (nil: absent; numbers across types, as queries' :=),
else nothing is applied and it rejects with 409 :conflict.The client's version: the pom's (clients/cljs/pom.xml), which release-cljs.yml checks against it.
The client's version: the pom's (clients/cljs/pom.xml), which release-cljs.yml checks against it.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |