strange syntax

2020-07-15 Thread PG Doc comments form 
The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/manage-ag-overview.html
Description:

this sentence looks strange:
"Schemas are a purely logical structure and who can access what is managed
by the privilege system"
https://www.postgresql.org/docs/12/manage-ag-overview.html

especially this part: "who can access what is managed by"

Re: Transaction Management

2020-07-15 Thread James King 
Hi Bruce,

Thanks for taking a look at this.

This is really about making a limitation obvious.  In other parts of the
documentation, like table partitioning, limitations are really spelled out,
good solid health warnings for those uninitiated.  For transactions we have
found that procedures cannot handle commit and rollbacks when marked as
security definer, we found this out through trial and error (we don't have
a clue as to why the limitation is in there and are trying to figure it
out).  The only reference we found in the documentation was on
https://www.postgresql.org/docs/11/sql-createprocedure.html with the line "A
 SECURITY DEFINER procedure cannot execute transaction control statements
(for example, COMMIT and ROLLBACK, depending on the language)."  We only
spotted this when digging as to find any information as to why we received
this error.

My reasoning of raising the point is it would have been really helpful for
us if the limitation was listed on the versions for
https://www.postgresql.org/docs/13/plpgsql-transactions.html so we didn't
sleepwalk into a limitation and if documented there we can see when the
limitation is raised (we can't figure out what the problem is with security
definer as it works so well for our use case).

Thanks,
James

On Tue, 14 Jul 2020 at 21:23, Bruce Momjian  wrote:

> On Tue, Jul  7, 2020 at 10:46:59AM +, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/12/plpgsql-transactions.html
> > Description:
> >
> > Hello,
> >
> > We are looking to use transaction management and have run into a
> limitation
> > when the procedure is security definer.  There doesn't appear to be any
> > reference to this in the
> > https://www.postgresql.org/docs/13/plpgsql-transactions.html so we
> cannot
> > see when the limitation is lifted.
> >
> > Are you able to clarify the situation with this between PG11, 12 and
> 13?  We
> > are hoping the limitation is lifted as we cannot see what the reason for
> the
> > limitation is.
>
> You are going to need to be more specific if you want help, and this
> doesn't seem like a documentation problem either.
>
> --
>   Bruce Momjian  https://momjian.us
>   EnterpriseDB https://enterprisedb.com
>
>   The usefulness of a cup is in its emptiness, Bruce Lee
>
>

-- 


James King

COO & Co-Founder

E:

W:

A:

ja...@yobota.xyz 

yobota.xyz

Bentima House, 168-172 Old Street

EC1V 9BP

Installation instructions vs binaries

2020-07-15 Thread Magnus Hagander 
It's kind of strange that if you start your PostgreSQL journey by reading
our instructions, you get nothing useful about installing PostgreSQL from
binary packages other than "go ask somebody else about it". Yet we have
pretty good step by step instructions on our *website* for it.

Attached patch adds a chapter to the docs about installing from binaries,
and refers those users to the website download instructions (and updates
the Windows instructions to include an actual link to the website).

It also adds mention of it in a few other places - -there are probably more
that could use some help with that in the future. But I've seen a lot of
people get confused by our documentation assuming everything is from source
when it comes to initdb and pg_ctl that I think it's worth specially
mentioning it there.

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://www.redpill-linpro.com/ 
commit a8321c6fff84c2a6be887b824ac090c49f724f55
Author: Magnus Hagander 
Date:   Wed Jul 15 13:12:28 2020 +0200

Expand installation documentation to cover binary installations

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 64b5da0070..463bdfd29c 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -36,6 +36,7 @@
 
 
 
+
 
 
 
diff --git a/doc/src/sgml/install-binaries.sgml b/doc/src/sgml/install-binaries.sgml
new file mode 100644
index 00..36405e74cc
--- /dev/null
+++ b/doc/src/sgml/install-binaries.sgml
@@ -0,0 +1,24 @@
+
+
+ Installation from Binaries
+
+ 
+  installation
+  binaries
+ 
+
+ 
+  PostgreSQL is available in the form of binary
+  packages for most common operating systems today. When available, this is
+  the recommended way to install PostgreSQL for users of the system. Building
+  from source (see ) is only recommended for
+  people developing PostgreSQL or extensions.
+ 
+
+ 
+  For an updated list of platforms providing binary packages, please visit
+  the Download section on the PostgreSQL website at
+  https://www.postgresql.org/download/";> and follow the
+  instructions for the specific platform.
+ 
+
diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml
index e2b8a4de57..587707b79b 100644
--- a/doc/src/sgml/install-windows.sgml
+++ b/doc/src/sgml/install-windows.sgml
@@ -11,7 +11,8 @@
  
   It is recommended that most users download the binary distribution for
   Windows, available as a graphical installer package
-  from the PostgreSQL website. Building from source
+  from the PostgreSQL website at
+  https://www.postgresql.org/download/";>. Building from source
   is only intended for people developing PostgreSQL
   or extensions.
  
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 552303e211..ce9bdb1297 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -21,7 +21,7 @@ documentation.  See standalone-profile.xsl for details.
   PostgreSQL using the source code
   distribution.  If you are installing a pre-packaged distribution,
   such as an RPM or Debian package, ignore this chapter
-  and read the packager's instructions instead.
+  and see  instead.
  
 
  
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index c41ce9499b..730d5fdc34 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -154,6 +154,7 @@ break is not needed in a wider output rendering.

   
 
+  &installbin;
   &installation;
   &installw;
   &runtime;
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 937bb2e8ac..b1b06ed689 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -26,6 +26,11 @@
binaries.
   
 
+  
+   When PostgreSQL is installed using binary packages, the user account is
+   normally created automatically by the package system.
+  
+
   
To add a Unix user account to your system, look for a command
useradd or adduser. The user
@@ -85,6 +90,14 @@
described in the previous section.
   
 
+  
+   
+When PostgreSQL is installed using binary packages, the initialization
+process may be automatic or look slightly different. Refer to the
+documentation for these packages for more information.
+   
+  
+
   

 As an alternative to the -D option, you can set
@@ -305,6 +318,15 @@ postgres$ initdb -D /usr/local/pgsql/data
  
   Starting the Database Server
 
+  
+   
+When PostgreSQL is installed using binary packages, starting and stopping
+of the system is normally integrated with the service management on the
+platform. Refer to the documentation for the documentation for these
+packages and the platform for more information.
+   
+  
+
   
Before anyone can access the database, you must start the database
server. The database server program is called

Re: docs: psql and variable interpolation

2020-07-15 Thread Philippe Beaudoin 


Le 13/07/2020 à 17:45, David G. Johnston a écrit :
On Monday, July 13, 2020, Philippe Beaudoin 
mailto:philippe.beaud...@dalibo.com>> 
wrote:


The first sentence of this SQL interpolation chapter says "A key
feature of psql variables is that you can substitute
(“interpolate”) them into regular SQL statements, as well as the
arguments of meta-commands." But nothing in this chapter indicates
that there are exceptions.

May be we could have a wording adjustment with something like : "A
key feature of psql variables is that you can substitute
(“interpolate”) them into regular SQL statements, as well as the
arguments of meta-commands (unless specifically noted)."


Having “unless otherwise noted” be implied doesn’t seem like a big 
failing.  As for this case it is documented as being an exception:


“Unlike most other meta-commands, the entire remainder of the line is 
always taken to be the arguments of |\copy|, and neither variable 
interpolation nor backquote expansion are performed in the arguments.”


If it is only \copy that is an exception I’d rather just say (except 
\copy} and not have the user meticulously read each item for the 
single exception.  This extends to if there are a few.


As far as I know, the \! metacommand is another exception. But I don't 
know if there are some others.




David J.




*DALIBO*
*L'expertise PostgreSQL*
43, rue du Faubourg Montmartre
75009 Paris *Philippe Beaudoin*
*Consultant Avant-Vente*
+33 (0)1 84 72 76 11
+33 (0)7 69 14 67 21
philippe.beaud...@dalibo.com
Valorisez vos compétences PostgreSQL, certifiez-vous chez Dalibo 
 !

Re: docs: psql and variable interpolation

2020-07-15 Thread Tom Lane 
Philippe Beaudoin  writes:
> Le 13/07/2020 à 17:45, David G. Johnston a écrit :
>> If it is only \copy that is an exception I’d rather just say (except 
>> \copy} and not have the user meticulously read each item for the 
>> single exception.  This extends to if there are a few.

> As far as I know, the \! metacommand is another exception. But I don't 
> know if there are some others.

Looking at the psql source code, the commands that use OT_WHOLE_LINE
argument parsing are

\copy
\ef, \ev
\sf, \sv
\help
\!

There's also OT_FILEPIPE argument parsing, which acts like WHOLE_LINE
if the argument starts with "|" (and otherwise is normal AFAICS).
That's used by

\g, \gx
\o
\w

regards, tom lane

Re: List of pages from versions 9, 10, and 11 that don't exist in "current"

2020-07-15 Thread Michael Christofides 
Sorry I forgot to say that I updated my docs redirect extension to handle a
few more of these cases. If anyone else wants to use it, it’s here:
https://github.com/mchristofides/pg_docs_bot

Cheers,
Michael


On Sun, 26 Apr 2020 at 13:03, Michael Christofides 
wrote:

> Thank you Jonathan.
>
> Yes good thinking on a thorough way, I may need to go down that route.
> I hadn't considered entries that exist in new versions but have
> changed name or URL, glad to hear these might be handled well on the
> docs themselves soon. I'll consider how to avoid getting in the way
> there.
>
> As a starting point, I remembered that depesz's site has the ability
> to search release notes between versions. A search for deprecated
> found me a few more:
> https://why-upgrade.depesz.com/show?from=9.0&to=12.2&keywords=deprecated
>
> Thanks again.
>
> On Sat, Apr 25, 2020 at 6:26 PM Jonathan S. Katz 
> wrote:
> >
> > On 4/25/20 1:12 PM, Michael Christofides wrote:
> > > Hi there,
> > >
> > > Does anyone have an easy way of seeing which pages from the 9.x, 10,
> > > or 11 docs don't have a "current" version?
> >
> > I don't have an easy way, but I have a pedantic way:
> >
> > 1. Set up the pgweb app[1]
> > 2. Set up the requirements for the docload.py utility
> > (tools/docs/docload.py)
> > 3. Download the release source PG12 all the way down. You would really
> > only need one, likely the latest (e.g. at the time of this writing 12.2,
> > 11.7, ...)
> > 4. Load each one into the database. You may need to explicitly create
> > the "Version" objects in the admin for pgweb
> > 5. Write SQL to see which filenames are present in an earlier version
> > but not a later one.
> >
> > > For context, I've built a Firefox extension that redirects old
> > > versions of the docs to their "current" version, except when either:
> > > * you're already on the docs, or
> > > * when a "current" version of the page doesn't exist.
> >
> > Sounds interesting. There is presently a patch[3] that could/should help
> > to address this case. The challenge, outside of the file that was the
> > impetus for the patch, would be finding the forwarding addresses for the
> > new pages. I believe Step 5 in the above would help with that.
> >
> > Thanks!
> >
> > Jonathan
> >
> > [1] https://www.postgresql.org/developer/related-projects/
> > [2] https://www.postgresql.org/ftp/source/
> > [3]
> >
> https://www.postgresql.org/message-id/4490e710-85f7-87a9-74dd-793d27440bed%40postgresql.org
> >
>

Re: Documentation Issue?

2020-07-15 Thread Thomas Munro 
On Wed, Jul 15, 2020 at 5:25 AM PG Doc comments form
 wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/tutorial-join.html
> Description:
>
> The documentation at https://www.postgresql.org/docs/12/tutorial-join.html
> shows this query:
>
> SELECT *
> FROM weather, cities
> WHERE city = name;
>
> And then presents the following query as "an alternate form" that is "not as
> commonly used as the one above":
>
> SELECT *
> FROM weather INNER JOIN cities ON (weather.city = cities.name);
>
> Isn't that backwards?  Isn't the first query the old ANSI-89 syntax?
> Shouldn't we be using then newer "INNER JOIN" syntax?

+1

Would you like to review the patch proposed over here?

https://www.postgresql.org/message-id/flat/158996922318.7035.10603922579567326239%40wrigleys.postgresql.org