|
@@ -79,7 +79,9 @@ connect(Opts) -> {ok, Connection :: epgsql:connection()} | {error, Reason :: epg
|
|
|
|
|
|
connect(Host, Username, Password, Opts) -> {ok, C} | {error, Reason}.
|
|
connect(Host, Username, Password, Opts) -> {ok, C} | {error, Reason}.
|
|
```
|
|
```
|
|
|
|
+
|
|
example:
|
|
example:
|
|
|
|
+
|
|
```erlang
|
|
```erlang
|
|
{ok, C} = epgsql:connect("localhost", "username", "psss", #{
|
|
{ok, C} = epgsql:connect("localhost", "username", "psss", #{
|
|
database => "test_db",
|
|
database => "test_db",
|
|
@@ -146,7 +148,9 @@ Asynchronous connect example (applies to **epgsqli** too):
|
|
%% @doc runs simple `SqlQuery' via given `Connection'
|
|
%% @doc runs simple `SqlQuery' via given `Connection'
|
|
squery(Connection, SqlQuery) -> ...
|
|
squery(Connection, SqlQuery) -> ...
|
|
```
|
|
```
|
|
|
|
+
|
|
examples:
|
|
examples:
|
|
|
|
+
|
|
```erlang
|
|
```erlang
|
|
epgsql:squery(C, "insert into account (name) values ('alice'), ('bob')").
|
|
epgsql:squery(C, "insert into account (name) values ('alice'), ('bob')").
|
|
> {ok,2}
|
|
> {ok,2}
|
|
@@ -237,6 +241,7 @@ end.
|
|
{ok, Count, Columns, Rows} = epgsql:equery(C, "insert ... returning ...", [Parameters]).
|
|
{ok, Count, Columns, Rows} = epgsql:equery(C, "insert ... returning ...", [Parameters]).
|
|
{error, Error} = epgsql:equery(C, "invalid SQL", [Parameters]).
|
|
{error, Error} = epgsql:equery(C, "invalid SQL", [Parameters]).
|
|
```
|
|
```
|
|
|
|
+
|
|
`Parameters` - optional list of values to be bound to `$1`, `$2`, `$3`, etc.
|
|
`Parameters` - optional list of values to be bound to `$1`, `$2`, `$3`, etc.
|
|
|
|
|
|
The extended query protocol combines parse, bind, and execute using
|
|
The extended query protocol combines parse, bind, and execute using
|
|
@@ -276,17 +281,20 @@ end.
|
|
squery including final `{C, Ref, done}`.
|
|
squery including final `{C, Ref, done}`.
|
|
|
|
|
|
### Prepared Query
|
|
### Prepared Query
|
|
|
|
+
|
|
```erlang
|
|
```erlang
|
|
{ok, Columns, Rows} = epgsql:prepared_query(C, StatementName, [Parameters]).
|
|
{ok, Columns, Rows} = epgsql:prepared_query(C, StatementName, [Parameters]).
|
|
{ok, Count} = epgsql:prepared_query(C, StatementName, [Parameters]).
|
|
{ok, Count} = epgsql:prepared_query(C, StatementName, [Parameters]).
|
|
{ok, Count, Columns, Rows} = epgsql:prepared_query(C, StatementName, [Parameters]).
|
|
{ok, Count, Columns, Rows} = epgsql:prepared_query(C, StatementName, [Parameters]).
|
|
{error, Error} = epgsql:prepared_query(C, "non_existent_query", [Parameters]).
|
|
{error, Error} = epgsql:prepared_query(C, "non_existent_query", [Parameters]).
|
|
```
|
|
```
|
|
|
|
+
|
|
`Parameters` - optional list of values to be bound to `$1`, `$2`, `$3`, etc.
|
|
`Parameters` - optional list of values to be bound to `$1`, `$2`, `$3`, etc.
|
|
`StatementName` - name of query given with ```erlang epgsql:parse(C, StatementName, "select ...", []).```
|
|
`StatementName` - name of query given with ```erlang epgsql:parse(C, StatementName, "select ...", []).```
|
|
|
|
|
|
With prepared query one can parse a query giving it a name with `epgsql:parse` on start and reuse the name
|
|
With prepared query one can parse a query giving it a name with `epgsql:parse` on start and reuse the name
|
|
for all further queries with different parameters.
|
|
for all further queries with different parameters.
|
|
|
|
+
|
|
```erlang
|
|
```erlang
|
|
epgsql:parse(C, "inc", "select $1+1", []).
|
|
epgsql:parse(C, "inc", "select $1+1", []).
|
|
epgsql:prepared_query(C, "inc", [4]).
|
|
epgsql:prepared_query(C, "inc", [4]).
|
|
@@ -322,11 +330,13 @@ squery including final `{C, Ref, done}`.
|
|
For valid type names see `pgsql_types.erl`.
|
|
For valid type names see `pgsql_types.erl`.
|
|
|
|
|
|
`epgsqla:parse/2` sends `{C, Ref, {ok, Statement} | {error, Reason}}`.
|
|
`epgsqla:parse/2` sends `{C, Ref, {ok, Statement} | {error, Reason}}`.
|
|
|
|
+
|
|
`epgsqli:parse/2` sends:
|
|
`epgsqli:parse/2` sends:
|
|
- - `{C, Ref, {types, Types}}`
|
|
|
|
- - `{C, Ref, {columns, Columns}}`
|
|
|
|
- - `{C, Ref, no_data}` if statement will not return rows
|
|
|
|
- - `{C, Ref, {error, Reason}}`
|
|
|
|
|
|
+
|
|
|
|
+- `{C, Ref, {types, Types}}`
|
|
|
|
+- `{C, Ref, {columns, Columns}}`
|
|
|
|
+- `{C, Ref, no_data}` if statement will not return rows
|
|
|
|
+- `{C, Ref, {error, Reason}}`
|
|
|
|
|
|
```erlang
|
|
```erlang
|
|
ok = epgsql:bind(C, Statement, [PortalName], ParameterValues).
|
|
ok = epgsql:bind(C, Statement, [PortalName], ParameterValues).
|
|
@@ -351,6 +361,7 @@ both `epgsqla:bind/3` and `epgsqli:bind/3` send `{C, Ref, ok | {error, Reason}}`
|
|
return value of `epgsql:execute/3`.
|
|
return value of `epgsql:execute/3`.
|
|
|
|
|
|
`epgsqli:execute/3` sends
|
|
`epgsqli:execute/3` sends
|
|
|
|
+
|
|
- `{C, Ref, {data, Row}}`
|
|
- `{C, Ref, {data, Row}}`
|
|
- `{C, Ref, {error, Reason}}`
|
|
- `{C, Ref, {error, Reason}}`
|
|
- `{C, Ref, suspended}` partial result was sent, more rows are available
|
|
- `{C, Ref, suspended}` partial result was sent, more rows are available
|
|
@@ -367,7 +378,6 @@ All epgsql functions return `{error, Error}` when an error occurs.
|
|
|
|
|
|
`epgsqla`/`epgsqli` modules' `close` and `sync` functions send `{C, Ref, ok}`.
|
|
`epgsqla`/`epgsqli` modules' `close` and `sync` functions send `{C, Ref, ok}`.
|
|
|
|
|
|
-
|
|
|
|
### Batch execution
|
|
### Batch execution
|
|
|
|
|
|
Batch execution is `bind` + `execute` for several prepared statements.
|
|
Batch execution is `bind` + `execute` for several prepared statements.
|
|
@@ -389,7 +399,9 @@ example:
|
|
```
|
|
```
|
|
|
|
|
|
`epgsqla:execute_batch/3` sends `{C, Ref, Results}`
|
|
`epgsqla:execute_batch/3` sends `{C, Ref, Results}`
|
|
|
|
+
|
|
`epgsqli:execute_batch/3` sends
|
|
`epgsqli:execute_batch/3` sends
|
|
|
|
+
|
|
- `{C, Ref, {data, Row}}`
|
|
- `{C, Ref, {data, Row}}`
|
|
- `{C, Ref, {error, Reason}}`
|
|
- `{C, Ref, {error, Reason}}`
|
|
- `{C, Ref, {complete, {_Type, Count}}}`
|
|
- `{C, Ref, {complete, {_Type, Count}}}`
|
|
@@ -482,6 +494,7 @@ Message formats:
|
|
```erlang
|
|
```erlang
|
|
{epgsql, Connection, {notification, Channel, Pid, Payload}}
|
|
{epgsql, Connection, {notification, Channel, Pid, Payload}}
|
|
```
|
|
```
|
|
|
|
+
|
|
- `Connection` - connection the notification occurred on
|
|
- `Connection` - connection the notification occurred on
|
|
- `Channel` - channel the notification occurred on
|
|
- `Channel` - channel the notification occurred on
|
|
- `Pid` - database session pid that sent notification
|
|
- `Pid` - database session pid that sent notification
|
|
@@ -490,6 +503,7 @@ Message formats:
|
|
```erlang
|
|
```erlang
|
|
{epgsql, Connection, {notice, Error}}
|
|
{epgsql, Connection, {notice, Error}}
|
|
```
|
|
```
|
|
|
|
+
|
|
- `Connection` - connection the notice occurred on
|
|
- `Connection` - connection the notice occurred on
|
|
- `Error` - an `#error{}` record, see `epgsql.hrl`
|
|
- `Error` - an `#error{}` record, see `epgsql.hrl`
|
|
|
|
|
|
@@ -510,7 +524,9 @@ Executes a function in a PostgreSQL transaction. It executes `BEGIN` prior to ex
|
|
`ROLLBACK` if the function raises an exception and `COMMIT` if the function returns without an error.
|
|
`ROLLBACK` if the function raises an exception and `COMMIT` if the function returns without an error.
|
|
If it is successful, it returns the result of the function. The failure case may differ, depending on
|
|
If it is successful, it returns the result of the function. The failure case may differ, depending on
|
|
the options passed.
|
|
the options passed.
|
|
|
|
+
|
|
Options (proplist or map):
|
|
Options (proplist or map):
|
|
|
|
+
|
|
- `reraise` (default `true`): when set to true, the original exception will be re-thrown after rollback,
|
|
- `reraise` (default `true`): when set to true, the original exception will be re-thrown after rollback,
|
|
otherwise `{rollback, ErrorReason}` will be returned
|
|
otherwise `{rollback, ErrorReason}` will be returned
|
|
- `ensure_committed` (default `false`): even when the callback returns without exception,
|
|
- `ensure_committed` (default `false`): even when the callback returns without exception,
|
|
@@ -522,7 +538,6 @@ Options (proplist or map):
|
|
appending them to `"BEGIN "` string. Eg `{begin_opts, "ISOLATION LEVEL SERIALIZABLE"}`.
|
|
appending them to `"BEGIN "` string. Eg `{begin_opts, "ISOLATION LEVEL SERIALIZABLE"}`.
|
|
Beware of SQL injection! The value of `begin_opts` is not escaped!
|
|
Beware of SQL injection! The value of `begin_opts` is not escaped!
|
|
|
|
|
|
-
|
|
|
|
### Command status
|
|
### Command status
|
|
|
|
|
|
`epgsql{a,i}:get_cmd_status(C) -> undefined | atom() | {atom(), integer()}`
|
|
`epgsql{a,i}:get_cmd_status(C) -> undefined | atom() | {atom(), integer()}`
|
|
@@ -571,10 +586,10 @@ See [pluggable_types.md](pluggable_types.md)
|
|
epgsql is a community driven effort - we welcome contributions!
|
|
epgsql is a community driven effort - we welcome contributions!
|
|
Here's how to create a patch that's easy to integrate:
|
|
Here's how to create a patch that's easy to integrate:
|
|
|
|
|
|
-* Create a new branch for the proposed fix.
|
|
|
|
-* Make sure it includes a test and documentation, if appropriate.
|
|
|
|
-* Open a pull request against the `devel` branch of epgsql.
|
|
|
|
-* Passing build in travis
|
|
|
|
|
|
+- Create a new branch for the proposed fix.
|
|
|
|
+- Make sure it includes a test and documentation, if appropriate.
|
|
|
|
+- Open a pull request against the `devel` branch of epgsql.
|
|
|
|
+- Passing build in travis
|
|
|
|
|
|
## Test Setup
|
|
## Test Setup
|
|
|
|
|
|
@@ -582,11 +597,10 @@ In order to run the epgsql tests, you will need to install local
|
|
Postgres database.
|
|
Postgres database.
|
|
|
|
|
|
NOTE: you will need the postgis and hstore extensions to run these
|
|
NOTE: you will need the postgis and hstore extensions to run these
|
|
-tests! On Ubuntu, you can install them with a command like this:
|
|
|
|
-
|
|
|
|
-1. apt-get install postgresql-9.3-postgis-2.1 postgresql-contrib
|
|
|
|
|
|
+tests! On Ubuntu, you can install them with a command like this:
|
|
|
|
|
|
-2. `make test` # Runs the tests
|
|
|
|
|
|
+1. `apt-get install postgresql-9.3-postgis-2.1 postgresql-contrib`
|
|
|
|
+1. `make test` # Runs the tests
|
|
|
|
|
|
NOTE 2: It's possible to run tests on exact postgres version by changing $PATH like
|
|
NOTE 2: It's possible to run tests on exact postgres version by changing $PATH like
|
|
|
|
|