Subject: Add clarification example to EXEC SQL CONNECT with password

From: Alan B <[email-masked]>
Date: Thu, 20 Sep 2012 18:17:15 +0200

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 [email-masked];

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

EXEC SQL BEGIN DECLARE SECTION;
const char *target = "[email-masked]";
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

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 25 Jan 2013 11:19:42 -0500

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.
> 
> EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john;
> 

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  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
new file mode 100644
index 63aaf89..bf01857
*** 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 = "[email-masked]";
  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 = "[email-masked]";
  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

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

---

From: Tom Lane <[email-masked]>
Date: Fri, 25 Jan 2013 12:25:32 -0500

> *************** EXEC SQL CONNECT TO unix:postgresql://sq

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

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 25 Jan 2013 12:29:59 -0500

> How is a reader supposed to know that he doesn't have to do both

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.

---

From: Tom Lane <[email-masked]>
Date: Fri, 25 Jan 2013 12:50:12 -0500

> 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

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 25 Jan 2013 13:19:21 -0500

> example, which would also help with making the following two paras

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

index bf01857..6326439
*************** EXEC SQL END DECLARE SECTION;
*** 199,205 ****
  
--- 199,205 ----
  
! /* or 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

---

From: Tom Lane <[email-masked]>
Date: Fri, 25 Jan 2013 13:41:06 -0500

> 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

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 25 Jan 2013 13:43:01 -0500

> as a fourth, independent example.  Please remove the blank line.

How is this?

index bf01857..4d904cd
*************** const char *passwd = "secret";
*** 198,205 ****
--- 198,204 ----

---

From: Tom Lane <[email-masked]>
Date: Fri, 25 Jan 2013 13:43:59 -0500

> How is this?

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

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 25 Jan 2013 13:46:47 -0500

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

Thanks, done.

---

From: Alan B <[email-masked]>
Date: Mon, 20 Jan 2014 12:50:47 +0100

Hi Bruce, Tom,
Great to see this addressed, thanks.

Alan