This module defines the epgsql behaviour.
Required callback functions: handle_x_log_data/4.
Synchronous interface.
All functions block (with infinite timeout) until full result is available.bind_param() = any()
Value to be bound to placeholder ($1
, $2
etc)
cb_state() = term()
column() = #column{name = binary(), type = epgsql:epgsql_type(), oid = non_neg_integer(), size = -1 | pos_integer(), modifier = -1 | pos_integer(), format = integer(), table_oid = non_neg_integer(), table_attr_number = pos_integer()}
connect_error() = epgsql_cmd_connect:connect_error()
connect_option() = {host, host()} | {username, string()} | {password, password()} | {database, DBName::string()} | {port, PortNum::inet:port_number()} | {ssl, IsEnabled::boolean() | required} | {ssl_opts, SslOptions::ssl_options()} | {tcp_opts, TcpOptions::[gen_tcp:option()]} | {timeout, TimeoutMs::timeout()} | {async, Receiver::pid() | atom()} | {codecs, Codecs::[{epgsql_codec:codec_mod(), any()}]} | {nulls, Nulls::[any(), ...]} | {replication, Replication::string()} | {application_name, ApplicationName::string()}
connect_opts() = [connect_option()] | #{host => host(), username => string(), password => password(), database => string(), port => inet:port_number(), ssl => boolean() | required, ssl_opts => ssl_options(), tcp_opts => [gen_tcp:option()], timeout => timeout(), async => pid() | atom(), codecs => [{epgsql_codec:codec_mod(), any()}], nulls => [any(), ...], replication => string(), application_name => string()}
connection() = pid()
epgsql_type() = type_name() | {array, type_name()} | {unknown_oid, integer()}
equery_row() = tuple()
tuple of any().
error_reply() = {error, query_error()}
host() = inet:ip_address() | inet:hostname()
lsn() = integer()
ok_reply(RowType) = {ok, ColumnsDescription::[column()], RowsValues::[RowType]} | {ok, Count::non_neg_integer()} | {ok, Count::non_neg_integer(), ColumnsDescription::[column()], RowsValues::[RowType]}
password() = string() | iodata() | fun(() -> iodata())
pg_date() = epgsql_codec_datetime:pg_date()
pg_datetime() = epgsql_codec_datetime:pg_datetime()
pg_interval() = epgsql_codec_datetime:pg_interval()
pg_time() = epgsql_codec_datetime:pg_time()
query_error() = #error{severity = debug | log | info | notice | warning | error | fatal | panic, code = binary(), codename = atom(), message = binary(), extra = [{severity | detail | hint | position | internal_position | internal_query | where | schema_name | table_name | column_name | data_type_name | constraint_name | file | line | routine, binary()}]}
Error report generated by server
replication_option() = {align_lsn, boolean()}
Align last applied and flushed LSN with last received LSN after Primary keepalive message with ReplyRequired flag
replication_opts() = [replication_option()] | #{align_lsn => boolean()}
reply(RowType) = ok_reply(RowType) | error_reply()
sql_query() = iodata()
SQL query text
squery_row() = tuple()
tuple of binary().
ssl_options() = [ssl:tls_client_option()]
statement() = #statement{name = string(), columns = [#column{name = binary(), type = epgsql:epgsql_type(), oid = non_neg_integer(), size = -1 | pos_integer(), modifier = -1 | pos_integer(), format = integer(), table_oid = non_neg_integer(), table_attr_number = pos_integer()}], types = [epgsql:epgsql_type()], parameter_info = [epgsql_oid_db:oid_entry()]}
transaction_option() = {reraise, boolean()} | {ensure_committed, boolean()} | {begin_opts, iodata()}
transaction_opts() = [transaction_option()] | #{reraise => boolean(), ensure_committed => boolean(), begin_opts => iodata()}
type_name() = atom()
typed_param() = {epgsql_type(), bind_param()}
bind/3 | |
bind/4 | |
cancel/1 | cancel currently executing command. |
close/1 | close connection. |
close/2 | close statement. |
close/3 | close statement or portal. |
connect/1 | connects to the server and performs all the necessary handshakes. |
connect/2 | |
connect/3 | |
connect/4 | connects to the server and performs all the necessary handshakes (legacy interface). |
connect/5 | |
copy_done/1 | Tells server that the transfer of COPY data is done. |
copy_from_stdin/2 | Equivalent to copy_from_stdin(C, SQL, text). |
copy_from_stdin/3 | Switches epgsql into COPY-mode. |
copy_send_rows/3 | Send a batch of rows to COPY .. FROM STDIN WITH (FORMAT binary) in Erlang format. |
describe/2 | |
describe/3 | |
equery/2 | |
equery/3 | |
equery/4 | Executes extended query. |
execute/2 | |
execute/3 | |
execute/4 | |
execute_batch/2 | Executes batch of {statement(), [bind_param()]} extended queries. |
execute_batch/3 | Executes same statement() extended query with each parameter list of a Batch |
get_backend_pid/1 | Returns the OS pid of PostgreSQL backend OS process that serves this connection. |
get_cmd_status/1 | Returns last command status message. |
get_parameter/2 | |
handle_x_log_data/5 | |
parse/2 | |
parse/3 | |
parse/4 | |
prepared_query/3 | Similar to equery/3 , but uses prepared statement that can be reused multiple times. |
set_notice_receiver/2 | |
squery/2 | runs simple SqlQuery via given Connection |
standby_status_update/3 | sends last flushed and applied WAL positions to the server in a standby status update message via
given Connection |
start_replication/5 | |
start_replication/6 | |
start_replication/7 | instructs Postgres server to start streaming WAL for logical replication. |
sync/1 | |
sync_on_error/2 | |
update_type_cache/1 | |
update_type_cache/2 | |
with_transaction/2 | |
with_transaction/3 | Execute callback function with connection in a transaction. |
bind(C, Statement, Parameters) -> any()
bind(C::connection(), Statement::statement(), PortalName::string(), Parameters::[bind_param()]) -> epgsql_cmd_bind:response()
cancel(C::connection()) -> ok
cancel currently executing command
close(C::connection()) -> ok
close connection
close(C::connection(), Statement::statement()) -> epgsql_cmd_close:response()
close statement
close(C::connection(), Type::statement | portal, Name::iodata()) -> epgsql_cmd_close:response()
close statement or portal
connect(Opts::connect_opts()) -> {ok, Connection::connection()} | {error, Reason::connect_error()}
connects to the server and performs all the necessary handshakes
connect(Host, Opts) -> any()
connect(Host, Username, Opts) -> any()
connect(Host::host(), Username::string(), Password::password(), Opts::connect_opts()) -> {ok, Connection::connection()} | {error, Reason::connect_error()}
Host: host to connect to
Username: username to connect as, defaults to $USER
Password: optional password to authenticate with
Opts: proplist or map of extra options
returns: {ok, Connection}
otherwise {error, Reason}
connects to the server and performs all the necessary handshakes (legacy interface)
See also: connect/1.
connect(C::connection(), Host::host(), Username::string(), Password::password(), Opts::connect_opts()) -> {ok, Connection::connection()} | {error, Reason::connect_error()}
copy_done(C::connection()) -> epgsql_cmd_copy_done:response()
Tells server that the transfer of COPY data is done
Stops copy-mode and returns the number of inserted rows.copy_from_stdin(C, SQL) -> any()
Equivalent to copy_from_stdin(C, SQL, text).
copy_from_stdin(C::connection(), SQL::sql_query(), Format::text | {binary, [epgsql_type()]}) -> epgsql_cmd_copy_from_stdin:response()
SQL: have to be COPY ... FROM STDIN ...
statement
Format: data transfer format specification: text
or {binary, epgsql_type()}
. Have to
match WHERE (FORMAT ???)
from SQL (text
for text
/csv
OR {binary, ..}
for binary
).
returns: in case of success, {ok, [text | binary]}
tuple is returned. List describes the expected
payload format for each column of input. In current implementation all the atoms in a list
will be the same and will match the atom in Format
parameter. It may change in the future
if PostgreSQL will introduce alternative payload formats.
Switches epgsql into COPY-mode
When Format
is text
, Erlang IO-protocol should be used to transfer "raw" COPY data to the
server (see, eg, io:put_chars/2
and file:write/2
etc).
When Format
is {binary, Types}
, copy_send_rows/3
should be used instead.
{epgsql, connection(), {error, epgsql:query_error()}}
(similar to asynchronous notification,
see set_notice_receiver/2
) will be sent to the process that called copy_from_stdin
and all the subsequent IO-protocol requests will return error.
It's important to not call copy_done
if such error is detected!
copy_send_rows(C::connection(), Rows::[tuple() | [bind_param()]], Timeout::timeout()) -> ok | {error, ErrReason}
Rows: might be a list of tuples or list of lists. List of lists is slightly more efficient.
Send a batch of rows to COPY .. FROM STDIN WITH (FORMAT binary)
in Erlang format
equery/3
using data type specification from 3rd argument of copy_from_stdin/3
(number of columns in
each element of Rows
should match the number of elements in {binary, Types}
).
describe(C::connection(), Statement::statement()) -> epgsql_cmd_describe_statement:response()
describe(C::connection(), X2::portal, Name::iodata()) -> epgsql_cmd_describe_portal:response()
describe(C::connection(), X2::statement, Name::iodata()) -> epgsql_cmd_describe_statement:response()
equery(C, Sql) -> any()
equery(C::connection(), Sql::sql_query(), Parameters::[bind_param()]) -> epgsql_cmd_equery:response() | epgsql_sock:error()
equery(C::connection(), Name::string(), Sql::sql_query(), Parameters::[bind_param()]) -> epgsql_cmd_equery:response() | epgsql_sock:error()
Executes extended query
See also: epgsql_cmd_equery.
execute(C, S) -> any()
execute(C, S, N) -> any()
execute(C::connection(), S::statement(), PortalName::string(), N::non_neg_integer()) -> Reply
execute_batch(C::connection(), Batch::[{statement(), [bind_param()]}]) -> epgsql_cmd_batch:response()
Executes batch of {statement(), [bind_param()]}
extended queries
See also: epgsql_cmd_batch.
execute_batch(C::connection(), Statement::statement() | sql_query(), Batch::[[bind_param()]]) -> {[column()], epgsql_cmd_batch:response()}
Executes same statement() extended query with each parameter list of a Batch
See also: epgsql_cmd_batch.
get_backend_pid(C::connection()) -> integer()
Returns the OS pid of PostgreSQL backend OS process that serves this connection.
Similar toSELECT pg_get_pid()
, but does not need network roundtrips.
Returns last command status message.
If multiple queries were executed using squery/2
, separated by semicolon,
only the last query's status will be available.
See https://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQCMDSTATUS
get_parameter(C::connection(), Name::list() | binary()) -> {ok, binary() | undefined}
handle_x_log_data(Mod, StartLSN, EndLSN, WALRecord, Repl) -> any()
parse(C, Sql) -> any()
parse(C, Sql, Types) -> any()
parse(C::connection(), Name::iolist(), Sql::sql_query(), Types::[epgsql_type()]) -> epgsql_cmd_parse:response()
prepared_query(C::connection(), Statement::string() | statement(), Parameters::[bind_param()]) -> epgsql_cmd_prepared_query:response()
Similar to equery/3
, but uses prepared statement that can be reused multiple times.
See also: epgsql_cmd_prepared_query.
set_notice_receiver(C::connection(), PidOrName::undefined | pid() | atom()) -> {ok, Previous::pid() | atom()}
squery(Connection::connection(), SqlQuery::sql_query()) -> epgsql_cmd_squery:response() | epgsql_sock:error()
runs simple SqlQuery
via given Connection
See also: epgsql_cmd_squery.
standby_status_update(Connection::connection(), FlushedLSN::lsn(), AppliedLSN::lsn()) -> ok
sends last flushed and applied WAL positions to the server in a standby status update message via
given Connection
start_replication(Connection, ReplicationSlot, Callback, CbInitState, WALPosition) -> any()
start_replication(Connection, ReplicationSlot, Callback, CbInitState, WALPosition, PluginOpts) -> any()
start_replication(Connection::connection(), ReplicationSlot::string(), Callback, CbInitState::cb_state(), WALPosition::string(), PluginOpts::string(), Opts::replication_opts()) -> Response
Connection: connection in replication mode
ReplicationSlot: the name of the replication slot to stream changes from
Callback: Callback module which should have the callback functions implemented for message processing.
or a process which should be able to receive replication messages.
CbInitState: Callback Module's initial state
WALPosition: the WAL position XXX/XXX to begin streaming at.
"0/0" to let the server determine the start point.
PluginOpts: optional options passed to the slot's logical decoding plugin.
For example: "option_name1 'value1', option_name2 'value2'"
Opts: options of logical replication
returns: ok
otherwise {error, Reason}
instructs Postgres server to start streaming WAL for logical replication
sync(C::connection()) -> epgsql_cmd_sync:response()
sync_on_error(C, Error) -> any()
update_type_cache(C) -> any()
update_type_cache(C::connection(), Codecs::[{epgsql_codec:codec_mod(), Opts::any()}]) -> epgsql_cmd_update_type_cache:response() | {error, empty}
with_transaction(C::connection(), F::fun((connection()) -> Reply)) -> Reply | {rollback, any()}
with_transaction(C::connection(), F::fun((connection()) -> Reply), Opts0::transaction_opts()) -> Reply | {rollback, any()} | no_return()
Execute callback function with connection in a transaction. Transaction will be rolled back in case of exception. Options (proplist or map):
{rollback, ErrorReason}
will be returned. Default: true
false
""
Generated by EDoc