(add-listener! client channel-name k l)Hands channel-name's notifications to l, a Listener, from the time LISTEN has run, and returns k, which unlisten takes to remove it. listen, clunk.async/listen and clunk.node/listen are built on it. Ends l with an error at once if the client can't listen.
Hands channel-name's notifications to l, a Listener, from the time LISTEN has run, and returns k, which unlisten takes to remove it. listen, clunk.async/listen and clunk.node/listen are built on it. Ends l with an error at once if the client can't listen.
What a query's :cancel takes: a token from cancel-token, or anything else that can say whether it has fired. The connection asks before a pooled query starts, and after each socket read and batch while it runs, never once per row.
What a query's :cancel takes: a token from cancel-token, or anything else that can say whether it has fired. The connection asks before a pooled query starts, and after each socket read and batch while it runs, never once per row.
(cancelled? token)True once token has fired.
True once token has fired.
(cancel! token)Fires token: a query given it that still waits for a pool's connection never runs, and a running one stops after the current batch.
Fires token: a query given it that still waits for a pool's connection never runs, and a running one stops after the current batch.
(cancel-token)A token to pass as a query's :cancel, and to fire with cancel!.
A token to pass as a query's :cancel, and to fire with cancel!.
(connect {:keys [state ready message-socket config]})Starts the connection: authenticates, then serves queued queries one at a time. Returns the server's ReadyForQuery message as a CompletableFuture on the JVM (deref it with @) and a js/Promise in ClojureScript, failed with the error if connecting or authenticating fails. Queries made before it is ready wait their turn. On the JVM the future completes on the connection's reader thread; see execute.
Starts the connection: authenticates, then serves queued queries one at a time. Returns the server's ReadyForQuery message as a CompletableFuture on the JVM (deref it with @) and a js/Promise in ClojureScript, failed with the error if connecting or authenticating fails. Queries made before it is ready wait their turn. On the JVM the future completes on the connection's reader thread; see execute.
(error? x)True for the error values clunk hands over in place of a row or a notification, and fails futures and promises with.
True for the error values clunk hands over in place of a row or a notification, and fails futures and promises with.
(execute client sql)(execute client sql {:keys [cancel] :as opts})Runs sql on a client or a pool, sql being a string or a vector of a statement and its parameters as for query, and returns all its rows as a vector of maps: a CompletableFuture on the JVM (deref it with @) and a js/Promise in ClojureScript. A failed query fails it with the error.
With a :cancel token, as for query, cancel! fails it with an error whose ex-data has :cancelled true, and stops the server after the current batch of :fetch-size rows.
On the JVM the future completes on the connection's reader thread, so a function given to thenApply, whenComplete and the like runs there, and the connection reads nothing more until it returns. It must not block, and must never wait for another query on the same client or pool: a pool may lend that very connection to the query, which then waits forever. The ...Async variants run it on another thread.
Runs sql on a client or a pool, sql being a string or a vector of a statement and its parameters as for query, and returns all its rows as a vector of maps: a CompletableFuture on the JVM (deref it with @) and a js/Promise in ClojureScript. A failed query fails it with the error. With a :cancel token, as for query, cancel! fails it with an error whose ex-data has :cancelled true, and stops the server after the current batch of :fetch-size rows. On the JVM the future completes on the connection's reader thread, so a function given to thenApply, whenComplete and the like runs there, and the connection reads nothing more until it returns. It must not block, and must never wait for another query on the same client or pool: a pool may lend that very connection to the query, which then waits forever. The ...Async variants run it on another thread.
(fail! {:keys [sink done]} err)Ends a request that won't run, with err unless it's nil.
Ends a request that won't run, with err unless it's nil.
(listen client channel-name f)(listen client channel-name f {:keys [max-queued] :or {max-queued 1000}})Listens for notifications on channel-name, a LISTEN channel, from the time LISTEN has run, and calls f with each, a map of :channel, :payload and the notifying backend's :pid. When the listener ends, f is called once more: with an error value if it ended with one, else with nil. Returns a handle for unlisten.
On a pool, every listener shares one connection of its own, which the pool never lends to queries and which doesn't count toward :max-size.
f never runs on the connection's reader: on the JVM each listener calls it from a thread of its own, and in JS from a microtask, one call at a time. So a slow f doesn't hold up queries; instead, a listener with :max-queued (default 1000) notifications waiting for f ends with an error. If LISTEN fails, or the connection drops, it ends with an error; clunk/close and unlisten end it with nil. UNLISTEN goes once no listener is left on the name.
Listens for notifications on channel-name, a LISTEN channel, from the time LISTEN has run, and calls f with each, a map of :channel, :payload and the notifying backend's :pid. When the listener ends, f is called once more: with an error value if it ended with one, else with nil. Returns a handle for unlisten. On a pool, every listener shares one connection of its own, which the pool never lends to queries and which doesn't count toward :max-size. f never runs on the connection's reader: on the JVM each listener calls it from a thread of its own, and in JS from a microtask, one call at a time. So a slow f doesn't hold up queries; instead, a listener with :max-queued (default 1000) notifications waiting for f ends with an error. If LISTEN fails, or the connection drops, it ends with an error; clunk/close and unlisten end it with nil. UNLISTEN goes once no listener is left on the name.
Where a channel name's notifications go; see add-listener!. The reader calls these, so they must not wait.
Where a channel name's notifications go; see add-listener!. The reader calls these, so they must not wait.
(-notify! l notification)Takes a notification. Returns true; :full if l has fallen behind, which ends it with an error; or false if its reader has gone, which ends it quietly.
Takes a notification. Returns true; :full if l has fallen behind, which ends it with an error; or false if its reader has gone, which ends it quietly.
(-stop! l err)Ends l, with err unless it's nil. Called once.
Ends l, with err unless it's nil. Called once.
(notify client channel-name payload)Sends payload, a string, to the listeners of channel-name with pg_notify, on a client or a pool. Returns a CompletableFuture or js/Promise of nil, failed if the server refuses it.
Sends payload, a string, to the listeners of channel-name with pg_notify, on a client or a pool. Returns a CompletableFuture or js/Promise of nil, failed if the server refuses it.
(plan client sql)(plan client sql {:keys [fetch-size]})Returns a reducible that runs sql each time it is reduced and hands each row to the reducing function as it arrives, so the rows are never all in memory. Works with reduce, transduce, into and run!; a reduced value, as from take, stops early. A failed query throws its error. It blocks the reducing thread, so don't reduce it inside a go block. On a pool, the reduce holds one connection until it returns.
sql is a string or a vector of a statement and its parameters, as for query. The server sends rows in batches of :fetch-size (default 1000), so stopping early stops the server too.
Returns a reducible that runs sql each time it is reduced and hands each row to the reducing function as it arrives, so the rows are never all in memory. Works with reduce, transduce, into and run!; a reduced value, as from take, stops early. A failed query throws its error. It blocks the reducing thread, so don't reduce it inside a go block. On a pool, the reduce holds one connection until it returns. sql is a string or a vector of a statement and its parameters, as for query. The server sends rows in batches of :fetch-size (default 1000), so stopping early stops the server too.
(query client sql sink)(query client sql sink {:keys [cancel fetch-size js-rows?]})Runs sql on a client or a pool and hands its rows to sink, a Sink, as they arrive: -row! with each row map, keyed by column name; -flush! as each run of rows ends; -error! with an error value if the query fails or a value fails to decode; and -end!, once, last. A sink that returns false gets nothing more, and the server stops. Returns nil. This is the low-level API that execute, plan, clunk.async and clunk.node build on.
sql is a string, or a vector of a statement and the values of its parameters $1, $2, ..., as in ["SELECT * FROM city WHERE id = $1" 42]. A string with no parameters can hold several statements.
To stop early, pass a :cancel token from cancel-token, and fire it with cancel!: a query still waiting for a pool's connection doesn't run at all (its sink just ends), and a running one hands over no more rows after the current socket read. With :cancel, the server sends rows in batches of :fetch-size (1000 unless given), so cancelling also stops the server after the current batch. Such a query, like one with parameters, is one statement.
In ClojureScript, :js-rows? true makes each row a plain JS object keyed by column name instead of a map, as clunk.node hands rows to JavaScript.
Runs sql on a client or a pool and hands its rows to sink, a Sink, as they arrive: -row! with each row map, keyed by column name; -flush! as each run of rows ends; -error! with an error value if the query fails or a value fails to decode; and -end!, once, last. A sink that returns false gets nothing more, and the server stops. Returns nil. This is the low-level API that execute, plan, clunk.async and clunk.node build on. sql is a string, or a vector of a statement and the values of its parameters $1, $2, ..., as in ["SELECT * FROM city WHERE id = $1" 42]. A string with no parameters can hold several statements. To stop early, pass a :cancel token from cancel-token, and fire it with cancel!: a query still waiting for a pool's connection doesn't run at all (its sink just ends), and a running one hands over no more rows after the current socket read. With :cancel, the server sends rows in batches of :fetch-size (1000 unless given), so cancelling also stops the server after the current batch. Such a query, like one with parameters, is one statement. In ClojureScript, :js-rows? true makes each row a plain JS object keyed by column name instead of a map, as clunk.node hands rows to JavaScript.
What query, execute and plan run sql on: a Client, or a pool of clients (clunk.pool).
What query, execute and plan run sql on: a Client, or a pool of clients (clunk.pool).
(close this)Closes the connection, or every connection of a pool.
Closes the connection, or every connection of a pool.
(listener this)The client that listen and unlisten use: a client itself, or a pool's connection for listeners, which it never lends to queries. Returns an error value if it can't connect.
The client that listen and unlisten use: a client itself, or a pool's connection for listeners, which it never lends to queries. Returns an error value if it can't connect.
(submit this request)Queues request, a map with :sql, :params, :fetch-size, :sink (where its rows go; see Sink) and :cancel (see Cancel, or nil), to run on a connection. Ends the sink at once if it can't. A request's optional :done function is called once the query has finished on its connection.
Queues request, a map with :sql, :params, :fetch-size, :sink (where its rows go; see Sink) and :cancel (see Cancel, or nil), to run on a connection. Ends the sink at once if it can't. A request's optional :done function is called once the query has finished on its connection.
Where a query's rows go; see query. The connection calls these in order, on the JVM from its reader thread, and ends every sink exactly once. Each returns false once the reader has gone, so the connection can stop the server. They may block on the JVM, which pushes back on the server. In JS they can't, so a sink pushes back by calling clunk.message-socket's pause on ms, and resume once it has room again.
Where a query's rows go; see query. The connection calls these in order, on the JVM from its reader thread, and ends every sink exactly once. Each returns false once the reader has gone, so the connection can stop the server. They may block on the JVM, which pushes back on the server. In JS they can't, so a sink pushes back by calling clunk.message-socket's pause on ms, and resume once it has room again.
(-end! sink ms)(-error! sink ms err)(-flush! sink ms)Hands over rows held back so far.
Hands over rows held back so far.
(-row! sink ms row)ms is the message socket the query runs on, or nil.
ms is the message socket the query runs on, or nil.
(unlisten client x)Stops listening: x is what listen returned (or clunk.async/listen's channel), which ends, or a channel name, whose listeners all end. Sends UNLISTEN once no listener is left on the name. Returns a CompletableFuture or js/Promise that settles once the server has stopped sending them, or nil if there was nothing to stop.
Stops listening: x is what listen returned (or clunk.async/listen's channel), which ends, or a channel name, whose listeners all end. Sends UNLISTEN once no listener is left on the name. Returns a CompletableFuture or js/Promise that settles once the server has stopped sending them, or nil if there was nothing to stop.
(with-lock lock f)Calls f holding lock on the JVM. JS has one thread, so it just calls it.
Calls f holding lock on the JVM. JS has one thread, so it just calls 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 |