Обсуждение: Add clarification example to EXEC SQL CONNECT with password

Hi list,
Hope this is the right place to suggest that change in the docs, otherwise is there a ticket management system for this stuff somewhere?

Paying attention to the documentation at http://www.postgresql.org/docs/8.4/static/ecpg-connect.html and subsequent versions of the page (I am using 8.4), there is the option to specify "user-name" in various ways. However this may be confused as a single parameter to the connect string while it is a combination of 1 or 2 parameters that cannot go into a single string.

To avoid confusion I suggest providing a complete example in "Here are some examples of CONNECT statements:" as follows:

EXEC SQL CONNECT TO mydb@sql.mydomain.com;

EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john;

EXEC SQL BEGIN DECLARE SECTION;
const char *target = "mydb@sql.mydomain.com";
const char *user = "john";
const char *passwd = "secret";
EXEC SQL END DECLARE SECTION;...

EXEC SQL CONNECT TO :target USER :user USING :passwd;
or 
EXEC SQL CONNECT TO :target USER :user/:passwd;

To make the distinction of parameters and string variables evident.

Alan

On Thu, Sep 20, 2012 at 06:17:15PM +0200, Alan B wrote:
> Hi list,
> Hope this is the right place to suggest that change in the docs, otherwise is
> there a ticket management system for this stuff somewhere?
>
> Paying attention to the documentation at http://www.postgresql.org/docs/8.4/
> static/ecpg-connect.html and subsequent versions of the page (I am using 8.4),
> there is the option to specify "user-name" in various ways. However this may be
> confused as a single parameter to the connect string while it is a combination
> of 1 or 2 parameters that cannot go into a single string.
>
> To avoid confusion I suggest providing a complete example in "Here are some
> examples of CONNECT statements:" as follows:
>
>
> EXEC SQL CONNECT TO mydb@sql.mydomain.com;
>
> EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john;
>
> EXEC SQL BEGIN DECLARE SECTION;
> const char *target = "mydb@sql.mydomain.com";
> const char *user = "john";
> const char *passwd = "secret";
> EXEC SQL END DECLARE SECTION;
>  ...
>
> EXEC SQL CONNECT TO :target USER :user USING :passwd;
> or
> EXEC SQL CONNECT TO :target USER :user/:passwd;
>
> To make the distinction of parameters and string variables evident.

I had a look at this just now, and you are right that it is very
confusing.  I couldn't even figure out how to explain it in text, and
agree that your example is the best solution.

Attached patch applied to git head and 9.2.  Thanks.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

Bruce Momjian <bruce@momjian.us> writes:
> *** a/doc/src/sgml/ecpg.sgml
> --- b/doc/src/sgml/ecpg.sgml
> *************** EXEC SQL CONNECT TO unix:postgresql://sq
> *** 194,202 ****
>   EXEC SQL BEGIN DECLARE SECTION;
>   const char *target = "mydb@sql.mydomain.com";
>   const char *user = "john";
>   EXEC SQL END DECLARE SECTION;
>    ...
> ! EXEC SQL CONNECT TO :target USER :user;
>   </programlisting>
>      The last form makes use of the variant referred to above as
>      character variable reference.  You will see in later sections how C
> --- 194,205 ----
>   EXEC SQL BEGIN DECLARE SECTION;
>   const char *target = "mydb@sql.mydomain.com";
>   const char *user = "john";
> + const char *passwd = "secret";
>   EXEC SQL END DECLARE SECTION;
>    ...
> ! EXEC SQL CONNECT TO :target USER :user USING :passwd;
> !
> ! EXEC SQL CONNECT TO :target USER :user/:passwd;
>   </programlisting>
>      The last form makes use of the variant referred to above as
>      character variable reference.  You will see in later sections how C

This sure looks like it has broken the intention of the paragraph
immediately after the example.  Also, it seems like you are providing
two alternative ways of doing the same thing, but not explaining that.
How is a reader supposed to know that he doesn't have to do both
commands?

            regards, tom lane

On Fri, Jan 25, 2013 at 12:25:32PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > *** a/doc/src/sgml/ecpg.sgml
> > --- b/doc/src/sgml/ecpg.sgml
> > *************** EXEC SQL CONNECT TO unix:postgresql://sq
> > *** 194,202 ****
> >   EXEC SQL BEGIN DECLARE SECTION;
> >   const char *target = "mydb@sql.mydomain.com";
> >   const char *user = "john";
> >   EXEC SQL END DECLARE SECTION;
> >    ...
> > ! EXEC SQL CONNECT TO :target USER :user;
> >   </programlisting>
> >      The last form makes use of the variant referred to above as
> >      character variable reference.  You will see in later sections how C
> > --- 194,205 ----
> >   EXEC SQL BEGIN DECLARE SECTION;
> >   const char *target = "mydb@sql.mydomain.com";
> >   const char *user = "john";
> > + const char *passwd = "secret";
> >   EXEC SQL END DECLARE SECTION;
> >    ...
> > ! EXEC SQL CONNECT TO :target USER :user USING :passwd;
> > !
> > ! EXEC SQL CONNECT TO :target USER :user/:passwd;
> >   </programlisting>
> >      The last form makes use of the variant referred to above as
> >      character variable reference.  You will see in later sections how C
>
> This sure looks like it has broken the intention of the paragraph
> immediately after the example.  Also, it seems like you are providing
> two alternative ways of doing the same thing, but not explaining that.
> How is a reader supposed to know that he doesn't have to do both
> commands?

Yeah, I was worried about that, so I added the blank line.  If you look
at the docs, we already are providing three connection examples, so now
there are four.  You can see the current docs here (the official ones
are not updated yet):

    http://momjian.us/pgsql_docs/ecpg-connect.html#ECPG-CONNECTING

I am open to suggestions.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

Bruce Momjian <bruce@momjian.us> writes:
> On Fri, Jan 25, 2013 at 12:25:32PM -0500, Tom Lane wrote:
>>> ! EXEC SQL CONNECT TO :target USER :user USING :passwd;
>>> !
>>> ! EXEC SQL CONNECT TO :target USER :user/:passwd;

>> This sure looks like it has broken the intention of the paragraph
>> immediately after the example.  Also, it seems like you are providing
>> two alternative ways of doing the same thing, but not explaining that.
>> How is a reader supposed to know that he doesn't have to do both
>> commands?

> Yeah, I was worried about that, so I added the blank line.  If you look
> at the docs, we already are providing three connection examples, so now
> there are four.  You can see the current docs here (the official ones
> are not updated yet):
>     http://momjian.us/pgsql_docs/ecpg-connect.html#ECPG-CONNECTING
> I am open to suggestions.

(looks at the whole section) As-is, it's definitely not good, because
before there were three independent examples, and now there are three
and a half --- the added example depends on the variables declared in
the third example.  But using the blank line means you've formatted it
as a stand-alone fourth example, which is not only wrong in itself but
it screws up the meanings of both of the subsequent paragraphs.

Perhaps changing that blank line to something like " /* or */" would
help?  Then it would look more like an alternative within the same
example, which would also help with making the following two paras
still be sensible.

            regards, tom lane

On Fri, Jan 25, 2013 at 12:50:12PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Fri, Jan 25, 2013 at 12:25:32PM -0500, Tom Lane wrote:
> >>> ! EXEC SQL CONNECT TO :target USER :user USING :passwd;
> >>> !
> >>> ! EXEC SQL CONNECT TO :target USER :user/:passwd;
>
> >> This sure looks like it has broken the intention of the paragraph
> >> immediately after the example.  Also, it seems like you are providing
> >> two alternative ways of doing the same thing, but not explaining that.
> >> How is a reader supposed to know that he doesn't have to do both
> >> commands?
>
> > Yeah, I was worried about that, so I added the blank line.  If you look
> > at the docs, we already are providing three connection examples, so now
> > there are four.  You can see the current docs here (the official ones
> > are not updated yet):
> >     http://momjian.us/pgsql_docs/ecpg-connect.html#ECPG-CONNECTING
> > I am open to suggestions.
>
> (looks at the whole section) As-is, it's definitely not good, because
> before there were three independent examples, and now there are three
> and a half --- the added example depends on the variables declared in
> the third example.  But using the blank line means you've formatted it
> as a stand-alone fourth example, which is not only wrong in itself but
> it screws up the meanings of both of the subsequent paragraphs.
>
> Perhaps changing that blank line to something like " /* or */" would
> help?  Then it would look more like an alternative within the same
> example, which would also help with making the following two paras
> still be sensible.

OK, how is this?  The C comment allows me to add 'or'.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

Bruce Momjian <bruce@momjian.us> writes:
> On Fri, Jan 25, 2013 at 12:50:12PM -0500, Tom Lane wrote:
>> (looks at the whole section) As-is, it's definitely not good, because
>> before there were three independent examples, and now there are three
>> and a half --- the added example depends on the variables declared in
>> the third example.  But using the blank line means you've formatted it
>> as a stand-alone fourth example, which is not only wrong in itself but
>> it screws up the meanings of both of the subsequent paragraphs.

> OK, how is this?  The C comment allows me to add 'or'.

It's still completely failing to address the problem that it's formatted
as a fourth, independent example.  Please remove the blank line.

            regards, tom lane

On Fri, Jan 25, 2013 at 01:41:06PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Fri, Jan 25, 2013 at 12:50:12PM -0500, Tom Lane wrote:
> >> (looks at the whole section) As-is, it's definitely not good, because
> >> before there were three independent examples, and now there are three
> >> and a half --- the added example depends on the variables declared in
> >> the third example.  But using the blank line means you've formatted it
> >> as a stand-alone fourth example, which is not only wrong in itself but
> >> it screws up the meanings of both of the subsequent paragraphs.
>
> > OK, how is this?  The C comment allows me to add 'or'.
>
> It's still completely failing to address the problem that it's formatted
> as a fourth, independent example.  Please remove the blank line.

How is this?

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +

Bruce Momjian <bruce@momjian.us> writes:
> On Fri, Jan 25, 2013 at 01:41:06PM -0500, Tom Lane wrote:
>> It's still completely failing to address the problem that it's formatted
>> as a fourth, independent example.  Please remove the blank line.

> How is this?

Yeah, that seems to work --- it looks like a single example now.

            regards, tom lane

On Fri, Jan 25, 2013 at 01:43:59PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Fri, Jan 25, 2013 at 01:41:06PM -0500, Tom Lane wrote:
> >> It's still completely failing to address the problem that it's formatted
> >> as a fourth, independent example.  Please remove the blank line.
>
> > How is this?
>
> Yeah, that seems to work --- it looks like a single example now.

Thanks, done.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +