README for point type

README

@@ -0,0 +1,309 @@
+Erlang PostgreSQL Database Client
+
+Asynchronous fork of https://github.com/wg/epgsql originally here:
+https://github.com/mabrek/epgsql and subsequently forked in order to
+provide a common fork for community development.
+
+
+* Motivation
+
+  When you need to execute several queries, it involves a number network
+  round-trips between the application and the database.
+  The PostgreSQL frontend/backend protocol supports request pipelining.
+  This means that you don't need to wait for the previous command to finish
+  before sending the next command. This version of the driver makes full use
+  of the protocol feature that allows faster execution.
+
+
+* Difference highlights
+
+  + 3 API sets: pgsql, apgsql and ipgsql:
+    pgsql maintains backwards compatibility with the original driver API,
+    apgsql delivers complete results as regular erlang messages,
+    ipgsql delivers results as messages incrementally (row by row)
+  + internal queue of client requests, so you don't need to wait for the
+    response to send the next request
+  + single process to hold driver state and receive socket data
+  + execution of several parsed statements as a batch
+  + binding timestamps in erlang:now() format
+  see CHANGES for full list.
+
+* Differences between devel branch and mabrek's original async fork:
+
+  + Unnamed statements are used unless specified otherwise.  This may
+    cause problems for people attempting to use the same connection
+    concurrently, which will no longer work.
+
+* Known problems
+
+  A timeout supplied at connect time works as a socket connect timeout,
+  not a query timeout. It passes all tests from original driver except for
+  the 3 failing timeout tests.
+  SSL performance can degrade if the driver process has a large inbox
+  (thousands of messages).
+  Usage of unnamed prepared statement and portals leads to unpredicted results
+  in case of concurrent access to same connection.
+
+
+* Connect
+
+  {ok, C} = pgsql:connect(Host, [Username], [Password], Opts).
+
+  Host      - host to connect to.
+  Username  - username to connect as, defaults to $USER.
+  Password  - optional password to authenticate with.
+  Opts      - property list of extra options. Supported properties:
+
+    + {database, String}
+    + {port,     Integer}
+    + {ssl,      Atom}       true | false | required
+    + {ssl_opts, List}       see ssl application docs in OTP
+    + {timeout,  Integer}    milliseconds, defaults to 5000
+    + {async,    Pid}        see Server Notifications section
+
+  {ok, C} = pgsql:connect("localhost", "username", [{database, "test_db"}]).
+  ok = pgsql:close(C).
+
+  The timeout parameter will trigger an {error, timeout} result when the
+  socket fails to connect within Timeout milliseconds.
+
+  Asynchronous connect example (applies to ipgsql too):
+
+  {ok, C} = apgsql:start_link(),
+  Ref = apgsql:connect(C, "localhost", "username", [{database, "test_db"}]),
+  receive
+    {C, Ref, connected} ->
+        {ok, C};
+    {C, Ref, Error = {error, _}} ->
+        Error;
+    {'EXIT', C, _Reason} ->
+        {error, closed}
+  end.
+
+
+* Simple Query
+
+  {ok, Columns, Rows}        = pgsql:squery(C, "select ...").
+  {ok, Count}                = pgsql:squery(C, "update ...").
+  {ok, Count, Columns, Rows} = pgsql:squery(C, "insert ... returning ...").
+
+  {error, Error}             = pgsql:squery(C, "invalid SQL").
+
+  Columns       - list of column records, see pgsql.hrl for definition.
+  Rows          - list of tuples, one for each row.
+  Count         - integer count of rows inserted/updated/etc
+
+  The simple query protocol returns all columns as text (Erlang binaries)
+  and does not support binding parameters.
+
+  Several queries separated by semicolon can be executed by squery.
+
+  [{ok, _, [{<<"1">>}]}, {ok, _, [{<<"2">>}]}] =
+    pgsql:squery(C, "select 1; select 2").
+
+  apgsql:squery returns result as a single message:
+
+  Ref = apgsql:squery(C, Sql),
+  receive
+    {C, Ref, Result} -> Result
+  end.
+  Result has same format as return value of pgsql:squery.
+
+  ipgsql:squery returns results incrementally for each query inside Sql and
+  for each row:
+
+  Ref = ipgsql:squery(C, Sql),
+  receive
+    {C, Ref, {columns, Columns}} ->
+        %% columns description
+        Columns;
+    {C, Ref, {data, Row}} ->
+        %% single data row
+        Row;
+    {C, Ref, {error, _E} = Error} ->
+        Error;
+    {C, Ref, {complete, {_Type, Count}}} ->
+        %% execution of one insert/update/delete has finished
+        {ok, Count}; % affected rows count
+    {C, Ref, {complete, _Type}} ->
+        %% execution of one select has finished
+        ok;
+    {C, Ref, done} ->
+        %% execution of all queries from Sql has finished
+        done;
+  end.
+
+
+* Extended Query
+
+  {ok, Columns, Rows}        = pgsql:equery(C, "select ...", [Parameters]).
+  {ok, Count}                = pgsql:equery(C, "update ...", [Parameters]).
+  {ok, Count, Columns, Rows} = pgsql:equery(C, "insert ... returning ...", [Parameters]).
+
+  {error, Error}             = pgsql:equery(C, "invalid SQL", [Parameters]).
+
+  Parameters    - optional list of values to be bound to $1, $2, $3, etc.
+
+  The extended query protocol combines parse, bind, and execute using
+  the unnamed prepared statement and portal. A "select" statement returns
+  {ok, Columns, Rows}, "insert/update/delete" returns {ok, Count} or
+  {ok, Count, Columns, Rows} when a "returning" clause is present. When
+  an error occurs, all statements result in {error, #error{}}.
+
+  PostgreSQL's binary format is used to return integers as Erlang
+  integers, floats as floats, bytea/text/varchar columns as binaries,
+  bools as true/false, etc. For details see pgsql_binary.erl and the
+  Data Representation section below.
+
+  Asynchronous api equery requires you to parse statement beforehand
+
+  Ref = apgsql:equery(C, Statement, [Parameters]),
+  receive
+    {C, Ref, Res} -> Res
+  end.
+  Statement - parsed statement (see parse below)
+  Res has same format as return value of pgsql:equery.
+
+  ipgsql:equery(C, Statement, [Parameters]) sends same set of messages as
+  squery including final {C, Ref, done}.
+
+
+* Parse/Bind/Execute
+
+  {ok, Statement} = pgsql:parse(C, [StatementName], Sql, [ParameterTypes]).
+
+  StatementName   - optional, reusable, name for the prepared statement.
+  ParameterTypes  - optional list of PostgreSQL types for each parameter.
+
+  For valid type names see pgsql_types.erl.
+
+  apgsql:parse sends {C, Ref, {ok, Statement} | {error, Reason}}.
+  ipgsql:parse sends:
+    {C, Ref, {types, Types}}
+    {C, Ref, {columns, Columns}}
+    {C, Ref, no_data} if statement will not return rows
+    {C, Ref, {error, Reason}}
+
+  ok = pgsql:bind(C, Statement, [PortalName], ParameterValues).
+
+  PortalName      - optional name for the result portal.
+
+  both apgsql:bind and ipgsql:bind send {C, Ref, ok | {error, Reason}}
+
+  {ok | partial, Rows} = pgsql:execute(C, Statement, [PortalName], [MaxRows]).
+  {ok, Count}          = pgsql:execute(C, Statement, [PortalName]).
+  {ok, Count, Rows}    = pgsql:execute(C, Statement, [PortalName]).
+
+  PortalName      - optional portal name used in bind/4.
+  MaxRows         - maximum number of rows to return (0 for all rows).
+
+  execute returns {partial, Rows} when more rows are available.
+
+  apgsql:execute sends {C, Ref, Result} where Result has same format as
+  return value of pgsql:execute.
+
+  ipgsql:execute sends
+    {C, Ref, {data, Row}}
+    {C, Ref, {error, Reason}}
+    {C, Ref, suspended} partial result was sent, more rows are available
+    {C, Ref, {complete, {_Type, Count}}}
+    {C, Ref, {complete, _Type}}
+
+  ok = pgsql:close(C, Statement).
+  ok = pgsql:close(C, statement | portal, Name).
+  ok = pgsql:sync(C).
+
+  All pgsql functions return {error, Error} when an error occurs.
+
+  apgsql and ipgsql close and sync functions send {C, Ref, ok}.
+
+
+* Batch execution
+
+  Batch execution is bind + execute for several prepared statements.
+  It uses unnamed portals and MaxRows = 0.
+
+  Results = pgsql:execute_batch(C, Batch).
+
+  Batch   - list of {Statement, ParameterValues}
+  Results - list of {ok, Count} or {ok, Count, Rows}
+
+  Example
+
+  {ok, S1} = pgsql:parse(C, "one", "select $1", [int4]),
+  {ok, S2} = pgsql:parse(C, "two", "select $1 + $2", [int4, int4]),
+  [{ok, [{1}]}, {ok, [{3}]}] =
+    pgsql:execute_batch(C, [{S1, [1]}, {S2, [1, 2]}]).
+
+  apgsql:execute_batch sends {C, Ref, Results}
+  ipgsql:execute_batch sends
+    {C, Ref, {data, Row}}
+    {C, Ref, {error, Reason}}
+    {C, Ref, {complete, {_Type, Count}}}
+    {C, Ref, {complete, _Type}}
+    {C, Ref, done} - execution of all queries from Batch has finished
+
+
+* Data Representation
+
+  null        = null
+  bool        = true | false
+  char        = $A | binary
+  intX        = 1
+  floatX      = 1.0
+  date        = {Year, Month, Day}
+  time        = {Hour, Minute, Second.Microsecond}
+  timetz      = {time, Timezone}
+  timestamp   = {date, time}
+  timestamptz = {date, time}
+  interval    = {time, Days, Months}
+  text        = <<"a">>
+  varchar     = <<"a">>
+  bytea       = <<1, 2>>
+  array       = [1, 2, 3]
+  point       = {10.1, 100.0}
+
+  record      = {int2, time, text, ...} (decode only)
+
+  timestamp and timestamptz parameters can take erlang:now() format {MegaSeconds, Seconds, MicroSeconds}
+
+* Errors
+
+  Errors originating from the PostgreSQL backend are returned as {error, #error{}},
+  see pgsql.hrl for the record definition. epgsql functions may also return
+  {error, What} where What is one of the following:
+
+  {unsupported_auth_method, Method}     - required auth method is unsupported
+  timeout                               - request timed out
+  closed                                - connection was closed
+  sync_required                         - error occured and pgsql:sync must be called
+
+* Server Notifications
+
+  PostgreSQL may deliver two types of asynchronous message: "notices" in response
+  to notice and warning messages generated by the server, and "notifications" which
+  are generated by the LISTEN/NOTIFY mechanism.
+
+  Passing the {async, Pid} option to pgsql:connect will result in these async
+  messages being sent to the specified process, otherwise they will be dropped.
+
+  Message formats:
+
+    {pgsql, Connection, {notification, Channel, Pid, Payload}}
+
+      Connection  - connection the notification occurred on
+
+      Channel     - channel the notification occurred on
+      Pid         - database session pid that sent notification
+      Payload     - optional payload, only available from PostgreSQL >= 9.0
+
+    {pgsql, Connection, {notice, Error}}
+
+      Connection  - connection the notice occurred on
+      Error       - an #error{} record, see pgsql.hrl
+
+
+* Mailing list
+
+  https://groups.google.com/forum/#!forum/epgsql
+