Re: PQParam version 0.5

Tom Lane wrote:
> Andrew Chernow <ac@esilo.com> writes:
>> Here is the lastest pgparam patch.  It is patched against a fresh
>> checkout on 2007-12-05.
>
> What is this for?  Why is it a good idea?  It appears to be a fairly
> enormous increase in the size of libpq's API, and I really don't think
> I want to buy into the idea that libpq should know explicitly about each
> and every backend datatype.  The 100% lack of any documentation in the
> patch isn't helping you sell it, BTW.
>
>             regards, tom lane
>
>

 >>enormous increase in the size of libpq's API
We can dramatically reduce the exports by using macros, if preferred.

 >>The 100% lack of any documentation
Okay, we will do this.  For starters, take a look at test.c.  Below is a
brief description:

1. Managed params, rather than manually building PQexecParam arrays;
which is a little error prone and tedious.

   PQputint4(conn, 5);
   PQputtextptr(conn, "abc");
   PQparamExec(conn, "INSERT INTO t VALUES ($1, $2)", 1, NULL);
   // the NULL arg is a PGresult**, which is auto-cleared
   // when NULL.  Otherwise *result is assigned.

   // or use the print-style: we changed the argument order since
   // our last release, it felt off.
   PGresult *r;
   PQparamExecf(conn, "SELECT * FROM foo(%d, %t)", 1, &r, 5, "abc");

2. In binary result mode, the user has no idea how the data is formatted
and there are no demarshaling functions, thus making the binary
parameterized API impractical.  So, we made PQget functions that support
text or binary results.  The benefit of supporting both is that the new
PQget functions can be used regardless of how the query was executed.

   long long i8;
   PGinet inet;
   PQgetint8(res, 0, 0, &i8);
   PQgetinet(res, 0, 1, &inet);

   // coming soon. Currently, no way of doing this now.
   PGarr arr;
   int item, itemlen;
   PQgetarr(res, 0, 0, &arr);
   // access 2 dim "2d" array - arr[2][7]
   itemlen = PQgetarr2d(&arr, &item, 2, 7);

3. Client & server should both understand how data is formatted over the
wire, otherwise the data received by the client is not useful.  Things
like int4 or even a BOX are not that tricky, but other types are or may
change between versions.

4. Why do atoi(PQgetvalue(...)) everywhere?

Andrew