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

Common API to communicate with PostgreSQL server.

->codec-params clj

(->codec-params opt)

->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 src)

Produce another instance of a source with the same configuration.

close clj

(close src)

Close a data source. Closing a Connection terminates a session on the server side. Closing a Pool object terminates all open connections.

close-cached-statements clj

(close-cached-statements conn)

Close all the cached prepared statements and clean up the cache.

close-statement clj

(close-statement conn statement)

Close a prepared statement.

closed? clj

(closed? src)

Whether the data source was closed. A closed source cannot be reused again.

commit clj

(commit conn)

Commit the current transaction.

connect clj

(connect src)

(connect host port user password database)

Connect to the database. Given a Clojure config map or a URI string, 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 src sql in)

(copy-in src 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 src sql maps keys)

(copy-in-maps src 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 src sql rows)

(copy-in-rows src 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 src sql out)

(copy-out src 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 connection creation time as a 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.

execute clj

(execute src sql)

(execute src sql opt)

Execute a SQL expression and return a result. Arguments:

• src is a data source (a Connection, a Pool, a map, a URI string);
• sql is a SQL string expression;
• opt is a map of options.

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 statement)

(execute-statement conn statement opt)

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

get-error-fields clj deprecated

(get-error-fields e)

Get a map of error fields from an instance of PGErrorResponse. Deprecated, use ex-data instead.

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.

id clj

(id src)

Get a unique ID of this source (a Connection or a Pool).

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 a connection to a given channel.

notify clj

(notify src channel message)

Send a text message to a given channel.

pid clj

(pid conn)

Get PID of the connection on the server.

poll-notifications clj

(poll-notifications conn)

Perform an empty query so that pending notifications get flushed to the client. Doesn't guarantee though they will be sent for sure due to their async nature. The result is a number of notifications got and processed.

pool clj

(pool src)

(pool host port user password database)

Run a new Pool from a config map or a URI.

pool? clj

(pool? x)

True if a value is a Pool instance.

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.

Must be called against a Connection object since prepared statements cannot be shared across multiple connections.

prepared-statement? clj

(prepared-statement? x)

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

query clj

(query src sql)

(query src sql opt)

Run a SQL expression WITH NO parameters. The result is always sent back in text mode (binary mode doesn't work with the QUERY API). Arguments:

• src is a data source (a Connection, a Pool, a map, a URI string);
• sql is a SQL string without parameters (e.g. $1, etc);
• opt is a map of options.

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.

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_DEFAULTS clj

TX_READ_COMMITTED clj

TX_READ_UNCOMMITTED clj

TX_REPEATABLE_READ clj

TX_SERIALIZABLE clj

unlisten clj

(unlisten conn channel)

Unsubscribe a connection from a given channel.

with-conn clj macro

(with-conn [bind src] & body)

Just a shorter version of with-connection.

with-connection clj macro

(with-connection [bind src] & body)

Perform a block of code while the bind symbol is bound to a Connection object. If the src is a config map, the connection gets closed afterwards. When the src is a pool, the connection gets borrowed and returned to the pool without closing. For a connection, nothing happens when exiting the macro.

with-lock clj macro

(with-lock [conn] & body)

Perform a block of code while the connection is locked (no other threads can interfere).

with-pool clj macro

(with-pool [bind config] & body)

Execute the body while the bind symbol is bound to a new Pool instance. Close the pool afterwards.

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-transaction clj macro

(with-transaction [tx src] & body)

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

Obtain a connection from a source and perform a block of code wrapping the connection with a transaction, namely:

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

Arguments:

• tx is a symbol which a transactional connection is bound to;
• src is a data source (a map, a Pool, a Connection, a URI string).

The third argument is an optional map of parameters:

• 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-transaction blocks:

(with-transaction [tx1 {...}] ;; 1 (do-this ...) (with-transaction [tx2 tx1] ;; 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 ...)

with-tx clj macro deprecated

(with-tx [conn opts] & body)

DEPRECATED: use with-transaction above.

Acts like with-transaction but accepts a connection, not a data source. Thus, no a binding symbol required.