pg.core — com.github.igrishaev/pg2-core 0.1.18

Common API to communicate with PostgreSQL server.

->codec-params clj

(->codec-params opt)

->config clj

(->config params)

Turn a Clojure map into an instance of Config.Builder.

->execute-params clj

(->execute-params opt)

Make an instance of ExecuteParams from a Clojure map.

->kebab clj

(->kebab column)

Turn a string column name into into a kebab-case formatted keyword.

->tx-level clj

(->tx-level level)

Turn a keyword or a string into on instance of TxLevel.

begin clj

(begin conn)

(begin conn tx-level)

(begin conn tx-level read-only?)

Open a new transaction. Possible arguments:

• tx-level: the custom isolation level, either a :kebab-case keyword, or a CAPS STRING, for example :read-committed or 'READ COMMITTED';
• read-only?: whether to run the transaction in read-only mode (default is false).

cancel-request clj

(cancel-request conn)

Send a cancellation request to the server. MUST be called in another thread! The cancellation is meant to interrupt a query that has frozen the server. There is no 100% guarantee it will work.

Not recommended to use directly. See the with-timeout macro.

clone clj

(clone conn)

Create a new Connection from a configuration of the given connection.

close clj

(close conn)

Close the connection to the database.

close-statement clj

(close-statement conn stmt)

Close the prepared statement.

closed? clj

(closed? conn)

True if the connection has been closed.

commit clj

(commit conn)

Commit the current transaction.

connect clj

(connect config)

(connect host port user password database)

Connect to the database. Given a Clojure config map, establish a TCP connection with the server and run the authentication pipeline. Returns an instance of the Connection class.

connection? clj

(connection? x)

True of the passed option is a Connection instance.

copy-in clj

(copy-in conn sql in)

(copy-in conn sql in opt)

Transfer the data from the client to the server using COPY protocol. The SQL expression must be something liek this:

COPY ... FROM STDIN ...

The in parameter is an instance of InputStream. The function doesn't close the stream assuming you can reuse it.

The opt map is used to specify format, CSV delimiters, type hints and other options (see README).

Return the number of rows processed by the server.

copy-in-maps clj

(copy-in-maps conn sql maps keys)

(copy-in-maps conn sql maps keys opt)

Like copy-in but accepts a list of Clojure maps.

The keys argument is list of keys which is used to convert each map into a tuple.

The opt argument is a map of options (COPY format, delimiters, etc).

Return the number of rows processed by the server.

copy-in-rows clj

(copy-in-rows conn sql rows)

(copy-in-rows conn sql rows opt)

Like copy-in but accepts not an input stream but a list of rows. Each row must be a list of values. The list might be lazy. Return a number of rows processed.

copy-out clj

(copy-out conn sql out)

(copy-out conn sql out opt)

Transfer the data from the server to the client using COPY protocol. The SQL expression must be something like this:

COPY ... TO STDOUT ...

The out parameter must be an instance of OutputStream.

The function doesn't close the stream assuming you can reuse it for multiple COPY OUT sessions.

The opt map allows to specify the data format, CSV delimiters other options (see the docs in README).

Return the number of rows read from the server.

COPY_FORMAT_BIN clj

COPY_FORMAT_CSV clj

COPY_FORMAT_TAB clj

created-at clj

(created-at conn)

Get the creation time as Unix timestamp (ms).

decode-bin clj

(decode-bin buf oid)

(decode-bin buf oid opt)

Decode a binary-encoded value from a ByteBuffer.

decode-txt clj

(decode-txt obj oid)

(decode-txt obj oid opt)

Decode a text-encoded value from a ByteBuffer.

encode-bin clj

(encode-bin obj)

(encode-bin obj oid)

(encode-bin obj oid opt)

Binary-encode a value into a ByteBuffer.

encode-txt clj

(encode-txt obj)

(encode-txt obj oid)

(encode-txt obj oid opt)

Text-encode a value into a string.

error! clj

(error! template & args)

execute clj

(execute conn sql)

(execute conn sql opt)

Execute a SQL expression and return the result.

This function is a series of steps:

• prepare a statement;
• bind parameters and obtain a portal;
• describe the portal;
• get the data from the portal;
• close the portal;
• close the statement;
• process the result of the fly.

execute-statement clj

(execute-statement conn stmt)

(execute-statement conn stmt opt)

Execute the given prepared statement and get the result. The way the result is processed heavily depends on the options.

get-error-fields clj

(get-error-fields e)

get-parameter clj

(get-parameter conn param)

Return a certain connection parameter by its name, e.g. 'server_encoding', 'application_name', etc.

get-parameters clj

(get-parameters conn)

Return a {String->String} map of all the connection parameters.

IConnectable clj protocol

-borrow-connection clj

(-borrow-connection this)

-return-connection clj

(-return-connection this conn)

id clj

(id conn)

Get a unique ID of the connection.

idle? clj

(idle? conn)

True if the connection is in the idle state.

in-transaction? clj

(in-transaction? conn)

True if the connection is in transaction at the moment.

is-ssl? clj

(is-ssl? conn)

True if the Connection is SSL-encrypted.

json-wrap clj

(json-wrap x)

Wrap a value into a JSON.Wrapper class to force JSON encoding.

listen clj

(listen conn channel)

Subscribe the connection to a given channel.

notify clj

(notify conn channel message)

Send a text message to the given channel.

on-connection clj macro

(on-connection [bind source] & body)

Perform a block of code while the bind symbol is bound to a Connection object. If the source is a config map, the connection gets closed. When the source is a pool, the connection gets borrowed and returned afterwards. For existing connection, nothing is happening at the end.

pid clj

(pid conn)

Get PID of the connection on the server.

prepare clj

(prepare conn sql)

(prepare conn sql opt)

Get a new prepared statement from a raw SQL string. The SQL might have parameters. There is an third optional parameter oids to specify the non-default types of the parameters. Must be a List of OID enum.

The function returns an instance of the PreparedStatement class bound to the current connection.

prepared-statement? clj

(prepared-statement? x)

True if it's an instance of the PreparedStatement class.

query clj

(query conn sql)

(query conn sql opt)

Run a SQL expression WITH NO parameters. The result gets sent back in text mode always by the server.

rollback clj

(rollback conn)

Rollback the current transaction.

set-read-only clj

(set-read-only conn)

Set the current transaction read-only.

set-tx-level clj

(set-tx-level conn level)

Set transaction isolation level for the current transaction.

ssl-context clj

(ssl-context {:keys [key-file cert-file ca-cert-file]})

Build a SSLContext instance from a Clojure map. All the keys point to local files.

ssl-context-reader clj

(ssl-context-reader mapping)

ssl? clj

(ssl? conn)

True if the connection is encrypted with SSL.

status clj

(status conn)

Return the current transaction status, one of :I, :T, or :E.

tx-error? clj

(tx-error? conn)

True if the transaction has failed but hasn't been rolled back yet.

TX_READ_COMMITTED clj

TX_READ_UNCOMMITTED clj

TX_REPEATABLE_READ clj

TX_SERIALIZABLE clj

unlisten clj

(unlisten conn channel)

Unsubscribe the connection from a given channel.

with-conn clj macro

(with-conn [bind config] & body)

Just a shorter version of with-connection.

with-connection clj macro

(with-connection [bind config] & body)

Execute the body while the bind symbol is bound to the new Connection instance. The connection gets closed when exiting the macro.

with-lock clj macro

(with-lock [conn] & body)

with-statement clj macro

(with-statement [bind conn sql oids] & body)

Execute the body while the bind symbol is bound to the new PreparedStatement instance. The statement gets created from the SQL expression and optional list of OIDs. It gets closed when exiting the macro.

with-timeout clj macro

(with-timeout [conn ms-timeout] & body)

Set a timeout in which, if a query has not been executed in time, a cancellation request is sent to the server. Wrap a query with that macro when there is a chance for a server to freeze completely due to a non-optimized SQL. The ms-timeout is amount of milliseconds in which the cancel request will be sent.

with-tx clj macro

(with-tx [conn] & body)

(with-tx [conn {:keys [isolation-level read-only? rollback?]}] & body)

Wrap a block of code into a transaction, namely:

• run BEGIN before executing the code;
• capture all possible exceptions;
• should an exception was caught, ROLLBACK...
• and re-throw it;
• if no exception was caught, COMMIT.

Accepts a map of the following options:

• isolation-level: a keyword/string to set the isolation level;
• read-only?: to set the transaction read only;
• rollback?: to ROLLBACK a transaction even if it was successful.

Nested transactions are consumed by the most outer transaction. For example, you have two nested with-tx blocks:

(with-tx [...] ;; 1 (do-this ...) (with-tx [...] ;; 2 (do-that ...)))

In this case, only the first block will produce BEGIN and COMMIT commands. The second block will expand into the body only:

(pg/begin ...) (do-this ...) (do-that ...) (pg/commit ...)