Re: 'value' has special behaviour in alter system

[Jonathan S. Katz]

On 12/15/22 10:50 AM, David G. Johnston wrote:
On Thu, Dec 15, 2022 at 4:45 AM PG Doc comments form 
mailto:nore...@postgresql.org>> wrote:


The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/sql-altersystem.html

Description:

Documentation say
ALTER SYSTEM SET configuration_parameter { TO | = } { value | 'value' |
DEFAULT }

The variant 'value' has special, not obvious behaviour and must be
documented.


This syntax representation and accompanying text annoys me too.  It is 
logical behavior and described accurately, but I think readability could 
be improved.


I suggest changing it to:

SET configuration_parameter { TO | = } { value [, ...] | DEFAULT }

Values can be specified as unquoted alphanumeric+underscore sequences.  
If the value contains any non-alphanumeric (plus underscore) characters 
it should be enclosed in quotes (single or double, it does not matter).  
For settings that accept multiple values, separate each value to be 
supplied with a comma (and optional whitespace).


+1 in general. I would also suggest we add an example in the Examples 
section to show what the output is when you add single-quotes.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Tightening the trust auth advice

[Jonathan S. Katz]

On 1/12/23 4:32 AM, Magnus Hagander wrote:
The page at https://www.postgresql.org/docs/current/auth-trust.html 
 goes through 
some length to explain why Trust is sometimes a good idea.


Is it really though? And in particular, aren't there better choices?


This first case it lists sounds like a good case for "peer" 
authentication...and the multi-user case it lists also sounds like a goo 
use for "peer".


The case that I think "trust" is good at, which we don't list, is doing 
local development / testing of PG.


As a first step, I think we should put a  box on the page 
explicitly saying that that trust, unless limited in pg_hba, will allow 
any user to become superuser which allows them to bypass all other 
security restrictions.


+1

Second, we're kind of going out of our way to recommend setting unix 
socket permissions etc -- in those cases, wouldn't it in almost every 
case just be better for the user to use "peer" auth instead of trust, 
and we should recommend them to use that instead? Is it really any less 
appropriate and/or convenient? (It was listed as appropriate back in 
2001 in 6f0f5bf2fbe, but the world has changed a bit in 20+ years..)


Yeah, I think forwarding folks to the documentation on "peer" is a good 
idea here. I don't know if we want to keep any language around for 
historical context "Prior to "peer" auth, "trust" was used for this but 
on modern systems you can use "peer" instead for better security."


And finally, the sentence "It is seldom reasonable to use trust for any 
TCP/IP connections other than those from localhost (127.0.0.1)." should 
probably be amended with an ", and only reasonable for localhost if you 
trust every single user on the host"?


I'd invert it: "It is not recommended to use "trust" for any TCP/IP 
(non-local) connection. You should use "trust" with localhost 
(127.0.0.1) connections only if you trust every single user on that host."


Thoughts? I'll be happy to work up a patch if there's agreement on the 
general idea.


Reading through this, I'm not shocked there's still a good amount of 
"trust" prevalent in the wild. I agree with tightening this up.


Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: February 9th, 2023 Release links to a missing page

[Jonathan S. Katz]

On 2/15/23 1:59 PM, Kirk Wolak wrote:

It looks like a simple bad reference name:

On this line:

  * Fix the |psql|
 commands
|\sf| and |\ef| to handle SQL-language functions that have
SQL-standard function bodies
 (i.e. 
|BEGIN ATOMIC|).


the link for function bodies is called: "sql-create*procedure*.html"
and I believe it should be "sql-create*function*.html"


The end of the URL is correct. The problem is "currenet" should be 
"current". I've made that correction. Thanks!



Side Note:
On such a posting is there no direct link to SUBMIT a correction (by 
design?)


The release announcements go through the news system, which does not 
have a feedback collection mechanism as anyone can post news. Emailing 
pgsql-docs, or even better pgsql-www, seems to be good enough for this 
case as we can quickly fix it, but I'm open to other suggestions.


Thanks,

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: February 9th, 2023 Release links to a missing page

[Jonathan S. Katz]

On 2/19/23 3:55 PM, Kirk Wolak wrote:
On Wed, Feb 15, 2023 at 2:05 PM Jonathan S. Katz <mailto:jk...@postgresql.org>> wrote:


The release announcements go through the news system, which does not
have a feedback collection mechanism as anyone can post news. Emailing
pgsql-docs, or even better pgsql-www, seems to be good enough for this
case as we can quickly fix it, but I'm open to other suggestions.

Thank you.  Good answer as well...   I figured out to just send it here...


Well, that gives me an idea. In the release announcement, we could put a 
line that says "You can send any corrections or suggestions to the 
public pgsql-...@lists.postgresql.org mailing list" or something like 
that. That way, it would remove the guessing on what to do.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: February 9th, 2023 Release links to a missing page

[Jonathan S. Katz]

On 2/20/23 8:57 PM, Kirk Wolak wrote:
On Sun, Feb 19, 2023 at 4:55 PM Jonathan S. Katz 


Well, that gives me an idea. In the release announcement, we could
put a
line that says "You can send any corrections or suggestions to the
public pgsql-...@lists.postgresql.org
<mailto:pgsql-...@lists.postgresql.org> mailing list" or something like
that. That way, it would remove the guessing on what to do.

Perfect...  I love this community!


Thanks. As I'd probably forget before the next update announcement, I 
sketched out the draft of it to ensure it included a line[1] around how 
to report corrections/suggestions.


Thanks again!

Jonathan

[1] 
https://git.postgresql.org/gitweb/?p=press.git;a=commitdiff;h=c5d98a4a9caece103205d1a213b11fa96086bd13;hp=9bffe5a98298e034976708a29c88a98a4cec9831


OpenPGP_signature
Description: OpenPGP digital signature

Re: The use "Postgres" in docs

[Jonathan S. Katz]

On 3/14/23 7:31 AM, Alvaro Herrera wrote:

On 2023-Mar-14, Daniel Gustafsson wrote:


The docs use PostgreSQL and not Postgres in all but two places, which I think
we should change like in the attached to be consistent. Any objections to this?


Both are very new.  No objection to the change.


+1 -- good catch.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: confusing positioning of notes in connection settings

[Jonathan S. Katz]

On 5/31/23 7:53 AM, Daniel Gustafsson wrote:

On 31 May 2023, at 13:16, Peter Eisentraut  
wrote:



The first two hunks are pretty straightforward, they just move the existing 
text around.

For the other two, which are not supported on Windows, I added an explicit 
parenthetical note.  We don't list which of the Unix-like platforms support the 
respective options, but I suspect that it's all of them in practice?  
(Otherwise we should be more explicit.)  So I think calling out Windows 
explicitly is sensible, also considering that the first two settings are 
supported on Windows but the latter two are not.


I think this is a clear improvement over the current docs.


+1.

Small nit:

"which does not include Windows" =>
"which is not supported on Windows"

(in two places)


Should we call out Windows explicitly in the same way in the corresponding
options in the libpq connection string param docs as well?


Probably, but I see language like this:

"It is only supported on systems where TCP_USER_TIMEOUT is available; on 
other systems, it has no effect."


If this is really only unsupported / has different settings on Windows, 
I think it's OK to call that out. The original gripe was about 
readability, but if we think the description in the other settings is no 
clear enough, we can edit it.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

clarifying trigger/rule behavior on logical replication subscribers

[Jonathan S. Katz]

Hi,

While answering a question on "do triggers fire on a logical replication 
subscriber by default?" I tried to look up a reference to this behavior 
in the docs. There wasn't a clear reference point, but on the 
architecture page[1], I found this line that was closest to the answer:


"The apply process on the subscriber database always runs with 
session_replication_role set to replica, which produces the usual 
effects on triggers and constraints."


which assumes that the reader knows what the "usual effects" are.

Attached is a patch that disambiguates this.

Two additional items:

1. I do think this should be backpatched because it clarifies an 
existing behavior.


2. I don't know if we want to add a note about the trigger/rule behavior 
elsewhere in the logical replication section. I don't know if a reader 
would be expecting to find this in the "architecture" section.


Thanks,

Jonathan

[1] 
https://www.postgresql.org/docs/devel/logical-replication-architecture.html
From 23aaa7fe401d85736ebf426626b063075a75c918 Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Tue, 6 Jun 2023 09:51:32 -0400
Subject: [PATCH] doc: Clarify behavior of triggers/rules in a logical
 subscriber

By default, triggers and rules do not fire on a logical replication
subscriber based on the "session_replication_role" GUC being set to
"replica". However, the docs in the logical replication section assumed
that the reader understood how this GUC worked. This modifies the docs to
be more explicit, and link back to the GUC itself.
---
 doc/src/sgml/logical-replication.sgml | 10 +++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/logical-replication.sgml 
b/doc/src/sgml/logical-replication.sgml
index 59cf92e6a9..b18cff73ed 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1654,9 +1654,13 @@ CONTEXT:  processing remote data for replication origin 
"pg_16395" during "INSER
 
   
The apply process on the subscriber database always runs with
-   session_replication_role set
-   to replica, which produces the usual effects on triggers
-   and constraints.
+   session_replication_role
+   set to replica. This means that, by default,
+   triggers and rules will not fire on a replica. Users can optionally choose 
to
+   enable triggers and rules on a table using the
+   ALTER TABLE command
+   and the literal>ENABLE TRIGGER and ENABLE RULE
+   clauses.
   
 
   
-- 
2.37.1 (Apple Git-137.1)



OpenPGP_signature
Description: OpenPGP digital signature

Re: confusing positioning of notes in connection settings

[Jonathan S. Katz]

On 6/7/23 11:17 AM, Peter Eisentraut wrote:


The proposed text in the patch is

"This parameter is supported only on systems that {have this property} 
(which does not include Windows)."


I don't see how the change you are proposing is correct.


I see -- I had read it quickly and didn't sound it out. Nit withdrawn.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: large scale reliable software system

[Jonathan S. Katz]

On 6/21/23 12:52 PM, B M wrote:

Dear all,

After greeting,

I taught PostgreSQL myself and developed a small scale 
experimentalsoftware system using PostgreSQL in the back-end.


I would like to know your advices to develop a large scale reliable 
software system using PostgreSQL in the back-end, through which i can 
share the storage with the different system users where they login to 
the system through the web application front-end with different 
passwords and usernames , save the privacy of each user data, improve 
overall system security and performance, achieve fast response, make 
backups and save the stored data from loss. The system will be hosted on 
a cloud.


This mailing list is to discuss issues related to the PostgreSQL 
documentation, not system design. There are some other places you can 
have this discussion[1] (such as pgsql-general@), though many of the 
questions you have are generally broad topics that turn into very deep, 
detailed conversations.


Thanks,

Jonathan

[1] https://www.postgresql.org/support/



OpenPGP_signature
Description: OpenPGP digital signature

Re: Change "two" to "three" for decades of development in history

[Jonathan S. Katz]

On 6/22/23 9:23 PM, Tom Lane wrote:

Michael Paquier  writes:

"With multiple decades of development behind it, PostgreSQL.."


+1.  It sure seems silly trying to automate changing this.


+1. With the proposed language, we can revisit it once it gets to 
"centuries."


Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Clarify errhint in sources.sgml

[Jonathan S. Katz]

On 7/12/23 3:08 AM, Daniel Gustafsson wrote:

It was noted in 20230712015948.byqaftt57glwk...@awork3.anarazel.de that the
errhint example in sources.sgml isn't as helpful as it could be.  errhint
should use a complete sentence, but the example doesn't, so I propose the
attached change which makes it so.  The style for hints is clearly spelled out
further down on the page, but for anyone looking for a quick answer and not
reading the whole page the current example might be misleading.


+1. No need to bikeshed this one.

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

Hi Fabian,

On 8/10/23 3:55 AM, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/external-interfaces.html
Description:

Hi,

I'm reaching out to ask if the Swift Postgres could be included in the
listing here:

https://www.postgresql.org/docs/current/external-interfaces.html

Name: PostgresNIO
Language: Swift
Comments: Non-blocking, event-driven client built with SwiftNIO
Website: https://github.com/vapor/postgres-nio


As of late, we've been keeping the canonical list on the wiki page here, 
which already includes PostgresNIO:


https://wiki.postgresql.org/wiki/List_of_drivers

The last time this came up, I think we discussed linking to the wiki 
page from the docs, vs. trying to keep the docs up-to-date with all of 
the drivers available. Perhaps it's worth seeing if we want to make any 
changes to the docs page prior to the v16 GA?


Thanks,

Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Include rust as an externally maintained procedural language

[Jonathan S. Katz]

On 8/11/23 2:46 PM, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/15/external-pl.html
Description:

The documentation [1] contains a list of independently maintained procedural
languages. Recently, PL/Rust [2] has reached its version 1.0 [3] and appears
to be stable.

Major companies have expressed interest in the extension. Kiwi Copple, the
founder of Supabase, has stated his company is researching the language for
his platform [4]. Meanwhile, Amazon's RDS team has already announced support
for PL/Rust as a trusted language extension [5] on their PostgreSQL
instances [6].

Considering the increasing support and stability for PL/Rust, it should be
referenced within Postgresql's docs [1].


There's an up-to-date list of the different PL's in on this page in the 
wiki:


https://wiki.postgresql.org/wiki/PL_Matrix

Similar to this thread[1], I wonder if we just link to the wiki from the 
documentation, given it will be easier to maintain the list from there.


Thanks,

Jonathan

[1] 
https://www.postgresql.org/message-id/flat/169165415312.635.10247434927885764880%40wrigleys.postgresql.org




OpenPGP_signature
Description: OpenPGP digital signature

Re: ROWS vs RANGE in release notes for pg 16

[Jonathan S. Katz]

Hi Erwin,

On 8/18/23 7:41 PM, Erwin Brandstetter wrote:

The release notes for Postgres 16 says here:
https://www.postgresql.org/docs/16/release-16.html#RELEASE-16-PERFORMANCE 


 > Allow window functions to use ROWS mode internally when RANGE mode is 
specified but unnecessary (David Rowley)


But the fix also applies to the much more common case where no mode has 
been specified, RANGE unfortunately being the default - including the 
most common use case "row_number() OVER (ORDER BY col)". This is what 
made me investigate, test and eventually propose a fix in the first 
place. See:


https://www.postgresql.org/message-id/flat/CAGHENJ7LBBszxS%2BSkWWFVnBmOT2oVsBhDMB1DFrgerCeYa_DyA%40mail.gmail.com
 

https://www.postgresql.org/message-id/flat/CAApHDvohAKEtTXxq7Pc-ic2dKT8oZfbRKeEJP64M0B6%2BS88z%2BA%40mail.gmail.com
 


Also, I was hoping to get a mention in the release note for working this 
out:


 > Allow window functions to use the faster ROWS mode internally when 
RANGE mode is specified or would be used by default, but unnecessary 
(David Rowley, Erwin Brandstetter)


Thanks for flagging. I suggest adding the comment to the release notes 
thread on -hackers:


https://www.postgresql.org/message-id/flat/ZGaPa7M3gc2THeDJ%40momjian.us

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

On 8/21/23 7:58 AM, Daniel Gustafsson wrote:

On 11 Aug 2023, at 02:23, Jonathan S. Katz  wrote:



The last time this came up, I think we discussed linking to the wiki page from 
the docs, vs. trying to keep the docs up-to-date with all of the drivers 
available. Perhaps it's worth seeing if we want to make any changes to the docs 
page prior to the v16 GA?


The docs page does mention that the list is likely to be incomplete, with the
following sentence, but there is no mention of the Wiki page at all:

 "Table H.1 includes a list of some of these projects."

That being said, a lot of readers will likely skim over and immediately look at
the table, missing the small disclaimer.  I wonder if we aren't serving our
users better by removing the table and only referring to the Wiki page?  Having
two lists will prompt the discussion of what to include where over and over
again, which isn't helping anyone.


This is what I was saying. I was waiting on attempting a patch to see if 
there was consensus. There's now a couple of threads now with similar 
suggestions, I'll work on getting patches ready.


Thanks,

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

On 8/21/23 10:55 AM, Jonathan S. Katz wrote:

On 8/21/23 7:58 AM, Daniel Gustafsson wrote:

On 11 Aug 2023, at 02:23, Jonathan S. Katz  wrote:


The last time this came up, I think we discussed linking to the wiki 
page from the docs, vs. trying to keep the docs up-to-date with all 
of the drivers available. Perhaps it's worth seeing if we want to 
make any changes to the docs page prior to the v16 GA?


The docs page does mention that the list is likely to be incomplete, 
with the

following sentence, but there is no mention of the Wiki page at all:

 "Table H.1 includes a list of some of these projects."

That being said, a lot of readers will likely skim over and 
immediately look at
the table, missing the small disclaimer.  I wonder if we aren't 
serving our
users better by removing the table and only referring to the Wiki 
page?  Having
two lists will prompt the discussion of what to include where over and 
over

again, which isn't helping anyone.


This is what I was saying. I was waiting on attempting a patch to see if 
there was consensus. There's now a couple of threads now with similar 
suggestions, I'll work on getting patches ready.


Suggested patch attached. Notes:

1. Replaced language to reference the wiki page
2. Replaced table with the URL
3. Changed the "licenses" comment to be more affirmative, i.e., there 
are language interfaces that are released under licenses different than 
the PostgreSQL Licence.


Jonathan
diff --git a/doc/src/sgml/external-projects.sgml 
b/doc/src/sgml/external-projects.sgml
index 2d0fd723b2..110692da7d 100644
--- a/doc/src/sgml/external-projects.sgml
+++ b/doc/src/sgml/external-projects.sgml
@@ -40,99 +40,17 @@

 
All other language interfaces are external projects and are distributed
-   separately.  includes a list of
-   some of these projects. Note that some of these packages might not be
-   released under the same license as PostgreSQL. 
For more
-   information on each language interface, including licensing terms, refer to
-   its website and documentation.
+   separately. A
+   https://wiki.postgresql.org/wiki/List_of_drivers";>list of 
language interfaces
+   is maintained on the PostgreSQL wiki. Note that some of these packages are
+   not released under the same license as 
PostgreSQL.
+   For more information on each language interface, including licensing terms,
+   refer to its website and documentation.
   
 
-  
-   Externally Maintained Client Interfaces
-
-   
-
- 
-  Name
-  Language
-  Comments
-  Website
- 
-
-
-
- 
-  DBD::Pg
-  Perl
-  Perl DBI driver
-  https://metacpan.org/dist/DBD-Pg";>
- 
-
- 
-  JDBC
-  Java
-  Type 4 JDBC driver
-  https://jdbc.postgresql.org/";>
- 
-
- 
-  libpqxx
-  C++
-  C++ interface
-  https://pqxx.org/";>
- 
-
- 
-  node-postgres
-  JavaScript
-  Node.js driver
-  https://node-postgres.com/";>
- 
-
- 
-  Npgsql
-  .NET
-  .NET data provider
-  https://www.npgsql.org/";>
- 
-
- 
-  pgtcl
-  Tcl
-  
-  https://github.com/flightaware/Pgtcl";>
- 
-
- 
-  pgtclng
-  Tcl
-  
-  https://sourceforge.net/projects/pgtclng/";>
- 
-
- 
-  pq
-  Go
-  Pure Go driver for Go's database/sql
-  https://github.com/lib/pq";>
- 
-
- 
-  psqlODBC
-  ODBC
-  ODBC driver
-  https://odbc.postgresql.org/";>
- 
-
- 
-  psycopg
-  Python
-  DB API 2.0-compliant
-  https://www.psycopg.org/";>
- 
-
-   
-  
+  
+https://wiki.postgresql.org/wiki/List_of_drivers";>
+  
  
 
  


OpenPGP_signature
Description: OpenPGP digital signature

Re: Include rust as an externally maintained procedural language

[Jonathan S. Katz]

On 8/12/23 12:45 PM, Bruce Momjian wrote:

On Fri, Aug 11, 2023 at 05:05:48PM -0400, Jonathan Katz wrote:

On 8/11/23 2:46 PM, PG Doc comments form wrote:



Considering the increasing support and stability for PL/Rust, it should be
referenced within Postgresql's docs [1].


There's an up-to-date list of the different PL's in on this page in the
wiki:

https://wiki.postgresql.org/wiki/PL_Matrix

Similar to this thread[1], I wonder if we just link to the wiki from the
documentation, given it will be easier to maintain the list from there.


Makes sense.


Please see attached patch that does exactly this. It follows similar 
semantics as [1].


Thanks,

Jonathan

[1] 
https://www.postgresql.org/message-id/flat/169165415312.635.10247434927885764880%40wrigleys.postgresql.org


diff --git a/doc/src/sgml/external-projects.sgml 
b/doc/src/sgml/external-projects.sgml
index 2d0fd723b2..57b47f7a75 100644
--- a/doc/src/sgml/external-projects.sgml
+++ b/doc/src/sgml/external-projects.sgml
@@ -170,58 +170,18 @@
   
In addition, there are a number of procedural languages that are developed
and maintained outside the core PostgreSQL
-   distribution.  lists some of these
-   packages. Note that some of these projects might not be released under the 
same
-   license as PostgreSQL. For more information on 
each
-   procedural language, including licensing information, refer to its website
+   distribution. A list of
+   https://wiki.postgresql.org/wiki/PL_Matrix";>procedural 
languages
+   is maintained on the PostgreSQL wiki. Note that some of these projects are
+   not released under the same license as 
PostgreSQL.
+   For more information on each procedural language, including licensing
+   information, refer to its website
and documentation.
   
 
-  
-   Externally Maintained Procedural Languages
-
-   
-
- 
-  Name
-  Language
-  Website
- 
-
-
-
- 
-  PL/Java
-  Java
-  https://tada.github.io/pljava/";>
- 
-
- 
-  PL/Lua
-  Lua
-  https://github.com/pllua/pllua-ng";>
- 
-
- 
-  PL/R
-  R
-  https://github.com/postgres-plr/plr";>
- 
-
- 
-  PL/sh
-  Unix shell
-  https://github.com/petere/plsh";>
- 
-
- 
-  PL/v8
-  JavaScript
-  https://github.com/plv8/plv8";>
- 
-
-   
-  
+  
+   https://wiki.postgresql.org/wiki/PL_Matrix";>
+  
  
 
  


OpenPGP_signature
Description: OpenPGP digital signature

Re: Include rust as an externally maintained procedural language

[Jonathan S. Katz]

On 8/22/23 3:24 AM, Daniel Gustafsson wrote:

On 22 Aug 2023, at 05:35, Jonathan S. Katz  wrote:

On 8/12/23 12:45 PM, Bruce Momjian wrote:

On Fri, Aug 11, 2023 at 05:05:48PM -0400, Jonathan Katz wrote:

On 8/11/23 2:46 PM, PG Doc comments form wrote:



Considering the increasing support and stability for PL/Rust, it should be
referenced within Postgresql's docs [1].


There's an up-to-date list of the different PL's in on this page in the
wiki:

https://wiki.postgresql.org/wiki/PL_Matrix

Similar to this thread[1], I wonder if we just link to the wiki from the
documentation, given it will be easier to maintain the list from there.

Makes sense.


Please see attached patch that does exactly this. It follows similar semantics 
as [1].


LGTM, let's apply it along with the patch in [1] to all branches.


Thanks!

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

On 8/22/23 3:10 AM, Daniel Gustafsson wrote:


This is in line with what I imagined as well, so unless anyone thinks otherwise
I will apply this and backpatch it to all branches.


I could argue it both ways on whether or not to backpatch. However, 
given the list of drivers should work with all supported PG releases, 
and it expands on the current known list, I'd +1 backpatching.


Jonathan


OpenPGP_signature
Description: OpenPGP digital signature

Re: Include PostgresNIO Swift client in the Documentation

[Jonathan S. Katz]

On 8/23/23 8:41 AM, Daniel Gustafsson wrote:

On 22 Aug 2023, at 16:25, Jonathan S. Katz  wrote:

On 8/22/23 3:10 AM, Daniel Gustafsson wrote:


This is in line with what I imagined as well, so unless anyone thinks otherwise
I will apply this and backpatch it to all branches.


I could argue it both ways on whether or not to backpatch. However, given the 
list of drivers should work with all supported PG releases, and it expands on 
the current known list, I'd +1 backpatching.


I opted for backpatching as the table is equally incomplete for all branches,
and the wiki equally applicable.


Agreed; thanks!

Jonathan



OpenPGP_signature
Description: OpenPGP digital signature

Re: Monetary Data Types Improvement

[Jonathan S. Katz]

On 3/20/24 11:07 AM, Dave Cramer wrote:



On Wed, 20 Mar 2024 at 10:59, Erik Wienhold > wrote:


On 2024-03-18 23:24 +0100, David Rowley wrote:
 > My vote would go to adding a deprecation notice to that section
of the
 > docs.  There's some talk [1] about how we discourage the usage of the
 > money type and that goes on to discuss the possibilities of moving it
 > into a contrib module.
 >
 > My hope would be that deprecation notice would steer most people away
 > from using it and therefore reduce the number of questions about it
 > due to fewer new use cases of it.
 >
 > [1]
https://www.postgresql.org/message-id/zxgh74ykj3iwv...@paquier.xyz


+1

Huh, I didn't know that it used to have a deprecation notice at some
point.  But that note was removed in 8.3:

https://www.postgresql.org/message-id/20071009123315.5fb283c1.darcy%40druid.net 



Sadly that was a mistake. Money is not really a useful type.


Here's[1] the latest "let's remove money" discussion (there's allegedly 
a hackers thread too, but I'm having trouble finding it.


+1 on reinstating the deprecation notice, given it'll be some years 
before we can fully remove it (at least based on the discussion).


Thanks,

Jonathan

[1] 
https://www.postgresql.org/message-id/flat/18240-c5da758d7dc1ecf0%40postgresql.org


OpenPGP_signature.asc
Description: OpenPGP digital signature

Re: A minor bug in doc. Hovering over heading shows # besides it.

[Jonathan S. Katz]

On 7/18/24 1:59 PM, Daniel Gustafsson wrote:

On 18 Jul 2024, at 15:49, Tom Lane  wrote:

Daniel Gustafsson  writes:

While not a standard the pilcrow [0] is, AFAICT from a bit of looking at other
docs, commonly used for this.  There is a lot of variability though so
whichever we choose it will be wrong one for someone.


I like this suggestion better because that's U+00B6, ie part of
LATIN-1, so it's *far* more likely to render correctly everywhere
than U+01F517 is.  We could also consider the section sign §
(U+00A7).

In any case, a tooltip would help reduce confusion.


Looking a bit closer, the Python documentation does just this, a pilcrow with a
tool-tip ("Link to this heading") when hovering over it


I forgot why we went with the "#" and not the (TIL the name) pilcrow 
symbol, but I'm generally used to seeing the pilcrow when I browse docs 
and may have voiced that at the time (though the record may show 
otherwise). So +1 to that.


Thanks,

Jonathan



OpenPGP_signature.asc
Description: OpenPGP digital signature

Re: Is this still accurate?

[Jonathan S. Katz]

Hi,On Jan 5, 2018, at 1:33 PM, Steve Atkins  wrote:On Jan 5, 2018, at 10:00 AM, Stephen Frost  wrote:Greetings,* Moser, Glen G (glen.mo...@charter.com) wrote:That's really the gist of the concern from a team member of mine.  Not that the 4TB number is wrong but that it could be misleading to assume that 4TB is some sort of upper bound.That's how this concern was relayed to me and I am just following up.Well, saying 'in excess of' is pretty clear, but I don't think thesentence is really adding much either, so perhaps we should just removeit.It's been useful a few times to reassure people that we can handle "large"databases operationally, rather than just having large theoretical limits.Updating it would be great, or wrapping a little more verbiage around the4TB number, but a mild -1 on removing it altogether.Here is a proposed patch that updates the wording:	"There are active PostgreSQL instances in production environments that manage many terabytes of data, as well as clusters managing petabytes.”The idea is that it gives a sense of scope for how big instances/clusters can run without fixing people on a number.  People can draw their own conclusions from the hard limits further down the page.Best,Jonathan

0001-Modify-sentence-on-production-PostgreSQL-instances-o.patch
Description: Binary data

Re: Is this still accurate?

[Jonathan S. Katz]

Hi,

> On Jan 6, 2018, at 9:45 AM, Magnus Hagander  wrote:
> 
> 
> 
> On Fri, Jan 5, 2018 at 8:09 PM, Jonathan S. Katz  <mailto:jk...@postgresql.org>> wrote:
> Hi,
> 
>> On Jan 5, 2018, at 1:33 PM, Steve Atkins > <mailto:st...@blighty.com>> wrote:
>> 
>> 
>>> On Jan 5, 2018, at 10:00 AM, Stephen Frost >> <mailto:sfr...@snowman.net>> wrote:
>>> 
>>> Greetings,
>>> 
>>> * Moser, Glen G (glen.mo...@charter.com <mailto:glen.mo...@charter.com>) 
>>> wrote:
>>>> That's really the gist of the concern from a team member of mine.  Not 
>>>> that the 4TB number is wrong but that it could be misleading to assume 
>>>> that 4TB is some sort of upper bound.
>>>> 
>>>> That's how this concern was relayed to me and I am just following up.
>>> 
>>> Well, saying 'in excess of' is pretty clear, but I don't think the
>>> sentence is really adding much either, so perhaps we should just remove
>>> it.
>> 
>> It's been useful a few times to reassure people that we can handle "large"
>> databases operationally, rather than just having large theoretical limits.
>> 
>> Updating it would be great, or wrapping a little more verbiage around the
>> 4TB number, but a mild -1 on removing it altogether.
> 
> Here is a proposed patch that updates the wording:
> 
>   "There are active PostgreSQL instances in production environments that 
> manage many terabytes of data, as well as clusters managing petabytes.”
> 
> The idea is that it gives a sense of scope for how big instances/clusters can 
> run without fixing people on a number.  People can draw their own conclusions 
> from the hard limits further down the page.
> 
> +1.

Changes pushed.

Jonathan

Re: Can we only add values to enums?

[Jonathan S. Katz]

> On Mar 15, 2018, at 11:33 PM, Euler Taveira  wrote:
> 
> 2018-03-12 20:28 GMT-03:00 PG Doc comments form :
>> I need to add a value to an enum, so I found this page, which answered my
>> question. However, I found it quite confusing that it only documents adding
>> a value. I would expect it to also document how to remove a value from an
>> enum? Is this not possible? If not, I consider it a bug. But either way, if
>> it is not possible, you should explicitly document it on this page.
>> 
> If it is not document, this means that it is not supported. It is not
> a bug. It is by design. Read the discussion about this feature at [1].
> Removing a enum value requires a table rewrite. I'm not sure it is
> worth a note.

I would say that’s the exact reason why it should be documented,
so it’s clear that it was by design.

We could also redirect people to DOMAINs if they need more
flexibility in what is added/removed from an “enum-like” type.

Jonathan

Re: Can we only add values to enums?

[Jonathan S. Katz]

> On Mar 16, 2018, at 10:48 AM, Tom Lane  wrote:
> 
> "Jonathan S. Katz"  writes:
>> I would say that’s the exact reason why it should be documented,
>> so it’s clear that it was by design.
> 
> Seems reasonable.  Maybe something in 8.7.4 enum implementation details?

I was going to take a crack at writing it, and noticed it had already
been committed:

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=013c0baaddd9df7e1f940184a8ab8e478214b46c
 
<https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=013c0baaddd9df7e1f940184a8ab8e478214b46c>

Thanks for the quick work!

Jonathan

Re: Blanks in the first line before the first word in the code boxes

[Jonathan S. Katz]

> On Mar 28, 2018, at 9:32 PM, Peter Eisentraut 
>  wrote:
> 
> On 3/28/18 21:30, Peter Eisentraut wrote:
>> On 3/23/18 08:56, Daniel Westermann wrote:
>>> is it only me who sees blanks before the first word in the first line of
>>> the code boxes, e.g. here:
>>> 
>>> https://www.postgresql.org/docs/9.6/static/sql-createtable.html
>>> https://www.postgresql.org/docs/10/static/sql-createtable.html
>>> 
>>> For the devel documentation it is fine:
>>> https://www.postgresql.org/docs/devel/static/sql-createtable.html
>>> 
>>> Tested in Firefox and Chrome.
>> 
>> Yeah, that looks weird.  I'll look into it.
> 
> Just looking at a nearby thread ... something is quite whacky with the
> web site stylesheet.  It didn't use to look like this.  Check this out:
> https://www.postgresql.org/docs/10/static/pgcrypto.html#id-1.11.7.35.5 
> 
Something is adding spaces - it’s within the “” tag, which causes browsers
to interpret each space literally.

For the case of the “digest” function, the outputted HTML shows the first digest
function indented, the second one at the start of the new line.

Jonathan

Re: Blanks in the first line before the first word in the code boxes

[Jonathan S. Katz]

> On Mar 28, 2018, at 9:47 PM, Peter Eisentraut 
>  wrote:
> 
> On 3/28/18 21:36, Jonathan S. Katz wrote:
>> 
>>> On Mar 28, 2018, at 9:32 PM, Peter Eisentraut
>>> >> <mailto:peter.eisentr...@2ndquadrant.com>> wrote:
>>>> Yeah, that looks weird.  I'll look into it.
>>> 
>>> Just looking at a nearby thread ... something is quite whacky with the
>>> web site stylesheet.  It didn't use to look like this.  Check this out:
>>> https://www.postgresql.org/docs/10/static/pgcrypto.html#id-1.11.7.35.5
>> 
>> Something is adding spaces - it’s within the “” tag, which causes
>> browsers
>> to interpret each space literally.
>> 
>> For the case of the “digest” function, the outputted HTML shows the
>> first digest
>> function indented, the second one at the start of the new line.
> 
> Yeah, the spaces are in the source, so it's not a CSS issue.  But it
> doesn't come out like that if you build the docs locally.  So it's
> something in the web site code.

If I traced the code correctly, the line I suspect is such:

s = tidy.parseString(contents.encode('utf-8'), **tidyopts)

I know that the web infrastructure recently updated to the Django 1.11
series, I’m not sure if libtidy or the like were also updated with that. I’ll
defer to Magnus on that.

Jonathan

Re: Blanks in the first line before the first word in the code boxes

[Jonathan S. Katz]

> On Apr 3, 2018, at 10:55 AM, Peter Eisentraut 
>  wrote:
> 
> On 4/3/18 09:12, Magnus Hagander wrote:
>> I've pushed the fix and reloaded the 10 docs. I have not reloaded
>> earlier branches yet, but I'd be interested in some people reviewing a
>> bunch of pages in the 10 docs mainly to see if (1) it fixes all the
>> cases, and (2) it actually breaks some *other* cases. 
> 
> It looks correct now.

+1

Did a spot check on known broken pages and chose some others at
random. Viewed the 9.6, 10, and devel versions.  10 and devel both
looked correct, and the 9.6 was broken where expected.

The only thing I saw (and this may be something to look at the SGML
source) was some blocks that looked overly indented, but it was consistent
across all versions.  On

https://www.postgresql.org/docs/current/static/queries-with.html 


If you search for "WITH RECURSIVE search_graph(id, link, data, depth)”
the expression in the CTE is much more indented than similar CTEs above
it.

IMV I would not let this stop us from reloading the earlier versions as that
indentation is consistent across all versions (including 9.6, where it has the
initial indentation as well).

Jonathan

Re: Blanks in the first line before the first word in the code boxes

[Jonathan S. Katz]

> On Apr 4, 2018, at 8:59 PM, Peter Eisentraut 
>  wrote:
> 
> On 4/4/18 09:21, Jonathan S. Katz wrote:
>> The only thing I saw (and this may be something to look at the SGML
>> source) was some blocks that looked overly indented, but it was consistent
>> across all versions.  On
>> 
>> https://www.postgresql.org/docs/current/static/queries-with.html
>> 
>> If you search for "WITH RECURSIVE search_graph(id, link, data, depth)”
>> the expression in the CTE is much more indented than similar CTEs above
>> it.
> 
> This was that way in the source.  Probably originally 8-space tabs.

That was my hunch, but wanted to be triple-sure.

> I've fixed it now.

Awesome. Thanks!

Jonathan

Re: Pg_dumpall

[Jonathan S. Katz]

Hi,

> On Apr 7, 2018, at 10:55 AM, PG Doc comments form  
> wrote:
> 
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/10/static/backup-dump.html
> Description:
> 
> "The basic usage of this command is:
> 
> pg_dumpall > outfile
> The resulting dump can be restored with psql:
> 
> psql -f infile postgres
> (Actually, you can specify any existing database name to..."
> 
> Should this not read :
> psql-f outfile postgres

Technically it is correct: you’re dumping data to an output file,
and reading the data in from an input file.  The documentation
also makes reference to what the “outfile” and “infile” represent.

That being said, I can see how it can be confusing particularly
if you are reading through the documentation quickly.  Perhaps
a name like “dumpfile” would be more clear?

Jonathan

Re: Start with [ , end with )

[Jonathan S. Katz]

> On Apr 23, 2018, at 8:37 PM, Mike Toews  wrote:
> 
> On 24 April 2018 at 01:00, PG Doc comments form  
> wrote:
>> 8.17.2. Examples
>> 
>> CREATE TABLE reservation (room int, during tsrange);
>> INSERT INTO reservation VALUES
>>(1108, '[2010-01-01 14:30, 2010-01-01 15:30)');
>>   ^ ^
>> While not an Error, still...
> 
> See 8.17.3. Inclusive and Exclusive Bounds
> 
> This is an example with an inclusive lower bound "[" and an exclusive
> upper bound ")”.

When dealing with date/time ranges, it’s a very common use case to have
an inclusive lower-bound and exclusive upper-bound, especially when
dealing with scheduling.

Jonathan

Re: Appendix A. PostgreSQL Error Codes

[Jonathan S. Katz]

> On Apr 28, 2018, at 5:11 PM, Tom Lane  wrote:
> 
> "Andy Dossett"  writes:
>> The use case is pretty simple; my system has thrown an SQL error code, I
>> want to know what it means.
>> Having the list in 'order by sqlstate' sequence would save me from having to
>> hunt up and down the list. And I can easily determine if the error code is
>> missing; I can then raise another bug report.
> 
> Hm ... I'm not finding that to be a very compelling argument.  Reading the
> message text is usually *far* more illuminating, because the error codes
> are (in many cases) rather broad categories rather than exact conditions.
> For the use case of "why did I get this error", I'd say that looking in
> Appendix A is quite unhelpful, and sorting it differently wouldn't make
> it any more helpful.

Is this information we might want to add to the main part of the website?
We could provide the list of error codes in Appendix A as is right now,
reference to “see more info on "/support/sql-error-codes/“ or some URL.
The table on such a page could contain features such as:

- sortable by number vs. alphabetical
- “searchable” if needed (eliminate results)
- more information about what causes such errors, perhaps with an
example of the detailed message.

I don’t know if this would be helpful or not. Personally I’ve only looked
at the error codes section a handful of times, mostly out of curiosity or
experimenting with ORM/adapter type code.

Jonathan

Re: documentation synopsis grammar

[Jonathan S. Katz]

> On May 11, 2018, at 8:15 PM, Tom Lane  wrote:
> 
> "David G. Johnston"  writes:
>> I'm suspecting that our best bet is leave the notation page a bit vague and
>> just clear up confusion when it arises.  The example above, while probably
>> technically incorrect, is, I'm reasonably certain, common and saying its
>> wrong and fixing it is unlikely to happen given the rarity of questions
>> like this.
> 
> Yeah; a quick grep suggests that there are several hundred occurrences
> of this notation in our reference pages alone.  Even if somebody were
> initially confused, they'd soon figure it out, I should think.  Certainly
> we've had few if any complaints about this point before.
> 
> The bigger question though is, if we don't like this notation, what
> notation would we replace it with?  We could be formally correct by
> rewriting all of these syntax synopses in BNF, but I think most people
> are not terribly familiar with that and would be more confused, not less.
> Our actual bison grammar, which is BNF-equivalent I think, is certainly
> arcane enough to scare off non-experts.
> 
> There was a related discussion recently:
> 
> https://www.postgresql.org/message-id/flat/152110913499.1223.7026776990975251345%40wrigleys.postgresql.org
> 
> The problems discussed there with our description of set-operation syntax
> are really a lot worse than this issue, I think.  And yet we still opted
> not to change the documentation, because it seemed that anything that's
> more formally correct would also be a lot more incomprehensible.
> 
> I don't want to sound like I think what we've got now is the peak of
> perfection, because it isn't.  But we have to strike a balance between
> formal correctness and readability for users who aren't familiar with
> formal syntax notations.  It's a difficult problem.

Perhaps a way around it is having more practical examples that highlight
the way the language can be used.  Even with an understanding of the
PostgreSQL, let alone SQL, syntax, I find that I continue to learn things
the language can do even to this day when I see an example. Sometimes
the grammar masks a lot of the power :-)

I would think changing the grammar at this point would cause even more
confusion, but more examples to capture the power should shed more
light on how to do things.

Jonathan

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

> On Aug 5, 2018, at 6:57 PM, Tom Lane  wrote:
> 
> We've been around on this before, I know, but I got annoyed about it
> again while waiting around for test builds of the back-branch
> documentation.  I think that we need some policy about maintaining
> back-branch release notes that's not "keep everything, forever".
> The release notes are becoming an ever-larger fraction of the docs,
> and that's not good for documentation maintenance or for download
> bandwidth.  As an example, looking at the US-letter PDF version of
> the v10 docs, as things stand today:
> 
> Total page count: 3550
> Pages in release notes for 10.x: 41 (1%)
> Pages in release notes for older branches: 898 (25%)
> Pages in release notes for pre-9.2 branches: 546 (15%)
> 
> I've not measured directly, but it's a reasonable assumption that if
> we dropped all the back-branch release notes the documentation build
> time would drop about 25%, whichever format you were building.
> 
> I also live in fear of overrunning TeX's hard-wired limits, in the
> back branches that depend on a TeX-based PDF toolchain.  We've hit
> those before and been able to work around them, but I wouldn't count
> on doing so again, and I sure don't want to discover that we have a
> problem of that sort the day before a release deadline.  Trimming the
> release notes would definitely give us enough slack to not worry
> about that before all those branches are EOL.
> 
> We've discussed trimming the release notes before, and people have
> objected on the grounds that they like being able to access ancient
> notes from time to time.  I'm not unsympathetic to that issue, but
> does that access point need to be our daily working documentation?

I’ll reference old release notes when researching some historical
evolution of a feature, but it’s definitely not a part of daily work.

> Anyway, I'd like to propose a compromise position that I don't think
> has been discussed before: let's drop release notes for branches
> that were already EOL when a given branch was released.  So for
> example, 9.3 and before would go away from v12, due out next year.
> Working backwards, we'd drop 9.1 and before from v10, giving the 15%
> savings in page count that I showed above.  A quick measurement says
> that would also trim the size of the v10 tarball by about 4%, which
> is not a lot maybe but it's noticeable across a lot of downloads.

+1. This is also a time consuming process when working the release
itself, so any time savings is great.

> It seems to me that this would still provide enough historical
> info for just about any ordinary interest.  We could discuss ways
> of making a complete release-note archive available somewhere,
> if "go dig in the git repo" doesn't seem like an adequate answer
> for that.

Why not www.postgresql.org ? We could add it as a 
subnav to the
documentation section and just have the entire archive there. We could
then update the official docs to say “If you would like to reference release
notes for earlier versions, please visit ”

Jonathan



signature.asc
Description: Message signed with OpenPGP

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

> On Aug 6, 2018, at 11:09 AM, Tom Lane  wrote:
> 
> "Jonathan S. Katz"  writes:
>>> On Aug 5, 2018, at 6:57 PM, Tom Lane  wrote:
>>> ...  We could discuss ways
>>> of making a complete release-note archive available somewhere,
>>> if "go dig in the git repo" doesn't seem like an adequate answer
>>> for that.
> 
>> Why not www.postgresql.org <http://www.postgresql.org/>? We could add it as 
>> a subnav to the
>> documentation section and just have the entire archive there. We could
>> then update the official docs to say “If you would like to reference release
>> notes for earlier versions, please visit ”
> 
> Yeah, that should certainly be part of it.  The questions I have are
> 
> (1) Is it sufficient to have that info on the website?  People who want
> it locally can always fall back on searching the development git repo,
> but it'd be less convenient perhaps.

Skimming some other OSS projects and it seems to be all over the board.
Some have a webpage covering releases, some have nicer formatted
documentation with a release section, some just link to the CHANGELOG
in a repo.

We could do something like:

- Host release notes on .org
- Have a reference in the official release notes to the page on the website
that houses the historical notes.

That way we’re building “pointers” to the official releases notes as opposed
to having to build them every single time.

Though thinking on this further, we’d probably want to maintain the URLs
that have been generated through the years so they don’t all 404 at once.
That would require having the appropriate URL rules written out either in
pgweb itself or at the web server level.

> (2) How would we maintain that exactly?  It's not, for instance, possible
> to build the release notes as a standalone document right now.  (Bruce's
> eagerness to provide xrefs for just about everything is the main stumbling
> block, though there might be others.)

Well, as long as we are still housing the docs and those references are still
alive, it should be ok.

> The process I'm vaguely imagining is that when a release branch is EOL'd,
> before removing its release-NN.sgml file from the HEAD branch, we copy
> that file into some archive somewhere and do a one-time edit to make it
> buildable as part of a standalone release-notes document.  Maybe the
> "archive" contains a makefile and enough supporting stuff to build a
> document that has just the obsolete release notes, and somewhere we have
> a git repo for that.  Then anybody who wants local access can clone that
> repo (solving question 1), and we annually use it to build a new version
> of the old-release-notes document to put on the website.

Another option is we could have a script that just scrapes the data from
the already built docs and loads it into (file system, database, etc.). This 
could
become a part of the (minor/major) release process.

The biggest pain would be doing this the first time, as we’d have to get all
of the historical notes in a one-time sweep.

> This seems like a nontrivial amount of work, but maybe we can automate it
> to some extent.

If nontrivial work saves a lot of wasted time during the build process, I’m for
it.

Jonathan


signature.asc
Description: Message signed with OpenPGP

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

> On Aug 6, 2018, at 11:47 AM, Tom Lane  wrote:
> 
> "Jonathan S. Katz"  writes:
>> Though thinking on this further, we’d probably want to maintain the URLs
>> that have been generated through the years so they don’t all 404 at once.
>> That would require having the appropriate URL rules written out either in
>> pgweb itself or at the web server level.
> 
> I dunno, you think it's worth the trouble?  The whole premise of this
> proposal is that hardly anybody is looking at those pages.  If that's
> not the case, we shouldn't be doing this.

I took a look at the stats and directionally it’s incredibly low. More I get
concerned by introducing 404s that could hurt any SEO-related metrics,
but that could just be general concern vs. anything factual.

> OTOH, if we can easily set up a generic redirect rule like "if
> https://www.postgresql.org/docs/*/static/release-*.html
> doesn't exist, then redirect to
> https://www.postgresql.org/docs/old-release-notes/static/release-*.html";
> it might be worth doing.

And looking at how the docs are served, we could do this from pgweb,
which is fairly straightforward.

FWIW I’m thinking of something like:

`/docs/release-notes/release-X-Y(-Z)?.html`

and have them all live there. Of course the docs themselves would still
have their copy of the release notes, but we could at least have a single
repository of all the releases, which I do see on other OSS projects.

Jonathan



signature.asc
Description: Message signed with OpenPGP

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

> On Aug 6, 2018, at 12:55 PM, Tom Lane  wrote:
> 
> "Jonathan S. Katz"  writes:
>> FWIW I’m thinking of something like:
> 
>> `/docs/release-notes/release-X-Y(-Z)?.html`
> 
>> and have them all live there. Of course the docs themselves would still
>> have their copy of the release notes, but we could at least have a single
>> repository of all the releases, which I do see on other OSS projects.
> 
> I'm imagining this being a repo of only the obsolete branches' release
> notes, not the active ones.  Otherwise we are talking about maintaining
> two copies of active release note files (because of the xref problem).
> I personally will flat out refuse to do that; the overhead of maintaining
> the relnotes is high enough already.

Well I want to make this easier, not harder. Thinking about the process of
maintaining all, no matter what, I see making it more complicated for someone,
so I will drop that for now.

> Maybe you could make the website look like that without any manual effort
> using a reverse redirection rule (redirecting from this new area back
> into the standard docs, for pages belonging to active branches).  But that
> seems pretty confusing, and prone to redirection loops if we also have the
> other thing.

Agreed.

So perhaps `/docs/archive/release-notes/release-X-Y-(-Z)?.html` will be where
they live.

I can make a quick prototype of this on pgweb just to see how easy it is to get
the release notes up in it. Basically, once the archived ones are in pgweb, we
would not need to have to build them anymore.

Jonathan



signature.asc
Description: Message signed with OpenPGP

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

> On Aug 6, 2018, at 3:27 PM, Tom Lane  wrote:
> 
> I wrote:
>> Hm, so the only objection I can think of is that this results in the old
>> release notes only being available on the website; there's no other way
>> to access them, short of digging around in the git repo.  But maybe that's
>> enough.
> 
> Actually, a concrete reason why that might not be good is that it results
> in having a single point of failure: once we remove branch N's relnotes
> from the active branches, the only copy of that data is the one in the
> archive table the docload script is filling.  Given, say, a bug in the
> docload script that causes it to overwrite the wrong table entries,
> can we recover?

Well, the release notes are still in the git history as well as the tarballs.
One could always pull an older tarball of PostgreSQL with the full
release.sgml and load from there.

Jonathan


signature.asc
Description: Message signed with OpenPGP

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

> On Aug 6, 2018, at 3:37 PM, Tom Lane  wrote:
> 
> "Jonathan S. Katz"  writes:
>>> On Aug 6, 2018, at 3:27 PM, Tom Lane  wrote:
>>> Actually, a concrete reason why that might not be good is that it results
>>> in having a single point of failure: once we remove branch N's relnotes
>>> from the active branches, the only copy of that data is the one in the
>>> archive table the docload script is filling.  Given, say, a bug in the
>>> docload script that causes it to overwrite the wrong table entries,
>>> can we recover?
> 
>> Well, the release notes are still in the git history as well as the tarballs.
>> One could always pull an older tarball of PostgreSQL with the full
>> release.sgml and load from there.
> 
> True ... as long as those older tarballs represent data that our current
> workflow can process.  For instance, if we did another documentation
> format change (from XML to something else), the older tarballs would
> perhaps no longer be useful for this purpose.
> 
> On the other hand, it's hard to believe that we'd make such a conversion
> without tools to help.  So probably if the situation came up, we could
> cobble together something that would allow ingesting the old format.

Attached is a (rough) working copy of the patch to pgweb. It can:

- Extract the release notes from the docload and puts them into their
own table
- Display the release notes via pgweb akin to earlier screenshots

It needs:

- The notes actually exposed in the navigation tree
- Review how some of the xrefs are translated (esp. non-release ones)
- Dependency on all major versions being cataloged in our “Version”
table on pgweb, which currently we do not do
- Magnus review, as to do this I introduced a new Python dependency

I was able to successfully load all of the release notes from the 10.4
tarball and spot checked view several different major/minor version
combinations.

It’s not near production ready, but wanted to demonstrate that it would
not be too hard to get this done.

Jonathan



release-notes.patch
Description: Binary data


signature.asc
Description: Message signed with OpenPGP

Re: how to modify the navfooter

[Jonathan S. Katz]

> On Aug 7, 2018, at 6:21 PM, Richard Swagerman  
> wrote:
> 
> Where is the content of the navfooter established?
> I would like to make some modifications to this footer, but I am unable to 
> figure out where the source that generates it.
> 
> I am building the documentation following the instructions from "Building The 
> Documentation" in Appendix J, currently on 9.6.
> 
> I am using the command:
> make STYLE=website html
> 
> I can see the generated navfooter div section in the output html. I must be 
> missing something, because I cannot find a file in the git branch that 
> includes the class named "navfooter" or or any other words like "Navigation 
> footer", "Next", or "Prev".
> 
> I have limited understanding of stylesheets (whether dsl or xsl), but I am 
> hoping that I can make the small modifications needed for our use.

I’m not as familiar with the doc builds but it looks like this is available
in the “stylesheet.xsl” file.

> I am also curious about the docFooter div section that appears in the 
> publicly published PostgreSQL documentation pages. It does not appear when I 
> build the docs.
> Is there a reason that the copyright does not appear on each page when I do 
> the doc build?
> Is there some way to get it included when I do the doc build?
> What file is used that contains the format (style?) info for that generated 
> html div section?

That is in the pgweb[1] project, i.e. this file[2]. My understanding
is that probably will not be included in the doc build, as there is
content in it that is specific to the website :-)

[1] https://git.postgresql.org/gitweb/?p=pgweb.git;a=summary 
[2] 
https://git.postgresql.org/gitweb/?p=pgweb.git;a=blob;f=templates/docs/docspage.html;
 



signature.asc
Description: Message signed with OpenPGP

Re: 25.3. Continuous Archiving : Unix examples with Windows-style variables %-$

[Jonathan S. Katz]

Hi,

> On Aug 23, 2018, at 5:54 AM, PG Doc comments form  
> wrote:
> 
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/9.4/static/continuous-archiving.html
> Description:
> 
> Most examples in "25.3. Continuous Archiving and Point-in-Time Recovery
> (PITR)" use Unix commands and paths, but all variables are written as
> Windows batch file variables (Windows "%var" / Unix "$var”).

These are special variables that PostgreSQL replaces regardless of
operating system. Per the paragraph above the examples:

"In archive_command, %p is replaced by the path name of the
file to archive, while %f is replaced by only the file name.”

Thanks,

Jonathan



signature.asc
Description: Message signed with OpenPGP

Re: "System roles" mentioned in psql documentation

[Jonathan S. Katz]

> On Aug 23, 2018, at 3:58 AM, Michael Paquier  wrote:
> 
> Hi all,
> 
> I have noticed that psql documentation mentions "system roles", however
> in all other parts of the docs, we use the term "default roles".
> Shouldn't we make this term more consistent and also add a link to the
> table describing those roles?  Please see the attached.

I did a quick search for other cases of “system roles” with nothing coming
up, so it looks like you caught the only reference. LGTM.

Thanks!

Jonathan



signature.asc
Description: Message signed with OpenPGP

Re: retroactive pg10 relnotes: sequence changes

[Jonathan S. Katz]

On Aug 28, 2018, at 1:02 PM, Magnus Hagander  wrote:On Tue, Aug 28, 2018 at 6:34 PM, Alvaro Herrera  wrote:HelloA customer of ours was taken by surprise by a change in Postgres 10 on atrial upgrade from 9.6.  They were using sequences from SERIAL columns alittle unorthodoxly, and their stuff stopped working: essentially, theyhacked the default _expression_ so that it'd automatically use negativenumbers when the sequence reached INT_MAX.  Since pg10 changed sequencesto stop emitting values at that point, it raised an error rather thanemit the negative numbers.(In 9.6 and prior, the sequence would emit values past INT_MAX; it wasthe column that raised the error.  In pg10 things were changed so thatit is now the sequence that raises the error.)My proposal now is to document this issue in the Postgres 10 releasenotes.  "It's a little late for that!" I hear you say, but keep this inmind: many users have *not* yet upgraded to 10, and they'll keep doingit for years to come still.  So I disagree that now is too late.  Wefailed to warn people that already upgraded, but we're still on time toalert people yet to upgrade.I attach both the patch and a screenshot to show how minor the visualeffect of the change is.(If people hate this, another option is to make it a separate bulletpoint.)Looks reasonable to me. And I definitely think we should do it -- people will be upgrading to 10 for years to come, so claiming it's too late is definitely not correct. +1.I have attached patch where I suggested some alternate wording andremove the parenthetical comment, as I don’t believe that should bean aside.Jonathan

sequences-10.patch
Description: Binary data


signature.asc
Description: Message signed with OpenPGP

Re: retroactive pg10 relnotes: sequence changes

[Jonathan S. Katz]

On Aug 28, 2018, at 1:09 PM, Jonathan S. Katz <jk...@postgresql.org> wrote:On Aug 28, 2018, at 1:02 PM, Magnus Hagander <mag...@hagander.net> wrote:On Tue, Aug 28, 2018 at 6:34 PM, Alvaro Herrera <alvhe...@2ndquadrant.com> wrote:HelloA customer of ours was taken by surprise by a change in Postgres 10 on atrial upgrade from 9.6.  They were using sequences from SERIAL columns alittle unorthodoxly, and their stuff stopped working: essentially, theyhacked the default _expression_ so that it'd automatically use negativenumbers when the sequence reached INT_MAX.  Since pg10 changed sequencesto stop emitting values at that point, it raised an error rather thanemit the negative numbers.(In 9.6 and prior, the sequence would emit values past INT_MAX; it wasthe column that raised the error.  In pg10 things were changed so thatit is now the sequence that raises the error.)My proposal now is to document this issue in the Postgres 10 releasenotes.  "It's a little late for that!" I hear you say, but keep this inmind: many users have *not* yet upgraded to 10, and they'll keep doingit for years to come still.  So I disagree that now is too late.  Wefailed to warn people that already upgraded, but we're still on time toalert people yet to upgrade.I attach both the patch and a screenshot to show how minor the visualeffect of the change is.(If people hate this, another option is to make it a separate bulletpoint.)Looks reasonable to me. And I definitely think we should do it -- people will be upgrading to 10 for years to come, so claiming it's too late is definitely not correct. +1.I have attached patch where I suggested some alternate wording andremove the parenthetical comment, as I don’t believe that should bean aside.Per off-list discussion from Bruce, re-attaching the patch. Apparentlyit was only available in HTML mimepart. Hopefully this gets it intothe archives.Jonathan

sequences-10-v2.patch
Description: Binary data


signature.asc
Description: Message signed with OpenPGP

Proposed HTML Documentation Styles

[Jonathan S. Katz]

Hi,

As part of the effort to modernize the look and feel of PostgreSQL.org
and associated web projects, Sarah & I have worked on applying the new
styles to the documentation. The main goals of the project were:

- To have the documentation styles match that of the main website
- To make the documentation easier to view on mobile devices
- To set up the web-based documentation for future usability changes and
improvements

Other than reversing how the versions are display at the top of the
website, we did not change any of the documentation structure and do not
intend to as part of this version of the project.

We have created a prototype of the new styles that can be viewed here,
with the credentials below:

http://174.138.60.30/docs/
pgdocs / newstyles

When browsing through this site, please note:

- All interactions are confined to the "/docs" folder
- Not all of the docs are loaded and they are not all the latest
versions - this is just for beta testing purposes
- Search in the prototype does not work

We are looking for feedback in the following areas:

- Things that may have degraded the user experience, e.g. things that
are difficult to read
- Visual bugs and errors

Our goal is to launch these changes with the upcoming major release, so
we appreciate your diligence in providing helpful feedback so we can
provide the best possible experience.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Proposed HTML Documentation Styles

[Jonathan S. Katz]

Hi Pavel,

On 10/4/18 12:02 PM, Pavel Stehule wrote:

> When I am going to document, then I see (about 0.5 sec) big PostgreSQL
> logo. It is not pleasant effect.

That's cache related - we won't need to worry about that on the
production site.

> 
> I don't like table style - middle vertical line is too black
> 
> Used colour palette is maybe too red based.
> 
> All my notes are subjective, just my feeling

Thanks for your feedback!

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Proposed HTML Documentation Styles

[Jonathan S. Katz]

On 10/4/18 12:28 PM, Alvaro Herrera wrote:
> On 2018-Oct-04, Pavel Stehule wrote:
> 
>> čt 4. 10. 2018 v 17:50 odesílatel Jonathan S. Katz 
>> napsal:
>>
>> When I am going to document, then I see (about 0.5 sec) big PostgreSQL
>> logo. It is not pleasant effect.
>>
>> I don't like table style - middle vertical line is too black
>>
>> Used colour palette is maybe too red based.
> 
> Yeah, it's heavily red and I didn't like that very much either, though I
> can live with it if everyone else loves it.

We can always see if we can find something more palatable. In some
earlier testing there were some issues with the blue, but perhaps there
are some better ways to achieve the proper PostgreSQL color palette.

> 
> This TOC looks a bit odd, with those bold black elements amongst all
> that red: http://174.138.60.30/docs/10/static/ecpg.html  I suppose these
> should just be bold without changing the color.
> 
> This page http://174.138.60.30/docs/9.4/static/libpq-connect.html
> has some keywords inside "Warning" and "Note" boxes. Those keywords
> acquire a gray background instead of inheriting the background color of
> the box, as in the original stylesheets.  Really odd-looking.

Thanks - both of the above have been noted and will be fixed.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Proposed HTML Documentation Styles

[Jonathan S. Katz]

On 10/4/18 12:33 PM, Jonathan S. Katz wrote:
> On 10/4/18 12:28 PM, Alvaro Herrera wrote:
>> This TOC looks a bit odd, with those bold black elements amongst all
>> that red: http://174.138.60.30/docs/10/static/ecpg.html  I suppose these
>> should just be bold without changing the color.
>>
>> This page http://174.138.60.30/docs/9.4/static/libpq-connect.html
>> has some keywords inside "Warning" and "Note" boxes. Those keywords
>> acquire a gray background instead of inheriting the background color of
>> the box, as in the original stylesheets.  Really odd-looking.
> 
> Thanks - both of the above have been noted and will be fixed.

Updates for this have been pushed to the test website. Thanks for reporting!

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Proposed HTML Documentation Styles

[Jonathan S. Katz]

Hi Dean,

On 10/4/18 3:41 PM, Dean Rasheed wrote:
> On Thu, 4 Oct 2018 at 16:50, Jonathan S. Katz  wrote:
>> As part of the effort to modernize the look and feel of PostgreSQL.org
>> and associated web projects, Sarah & I have worked on applying the new
>> styles to the documentation.
>>
>> We are looking for feedback in the following areas:
>>
>> - Things that may have degraded the user experience, e.g. things that
>> are difficult to read
>> - Visual bugs and errors
>>
> 
> There seems to be a problem with the layout some of the tables. For
> example on this page:
> 
> http://174.138.60.30/docs/10/static/functions-math.html
> 
> the description column is far too narrow, leading to descriptions with
> one or two words per line, spread over dozens of lines.

Sorry for the slow reply on this one - it took a little bit more time to
troubleshoot. This should now be fixed - please let me know if you are
still having issues.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Proposed HTML Documentation Styles

[Jonathan S. Katz]

Hi Dean,

On 10/11/18 3:01 AM, Dean Rasheed wrote:
> On Thu, 11 Oct 2018 at 06:49, Dean Rasheed  wrote:
>> For example, attached are screenshots taken from my Android tablet
> 
> For the record, that was a Samsung Galaxy Tab S2 8.0, with a screen
> resolution of 2048x1536 and a device pixel ratio of 2.0, I think. So
> the logical resolution is 1024x768, and in portrait mode, the logical
> width is 768 pixels.

Unfortunately HTML tables are not great in mobile web. With that said,
we pushed up a change that should keep them from exploding as much to
the right. We've also bumped up the font-size slightly from the current
site so they could be slightly easier to read.

(Note: when testing in the browser, they appear to be illegible unless
you have super vision, but when on an actual device they are legible).

There is only so much we can do now without redesigning how the tables
are assembled.

Thanks again for your feedback!

Best,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Proposed HTML Documentation Styles

[Jonathan S. Katz]

On 10/4/18 11:50 AM, Jonathan S. Katz wrote:
> Hi,
> 
> As part of the effort to modernize the look and feel of PostgreSQL.org
> and associated web projects, Sarah & I have worked on applying the new
> styles to the documentation. The main goals of the project were:
> 
> - To have the documentation styles match that of the main website
> - To make the documentation easier to view on mobile devices
> - To set up the web-based documentation for future usability changes and
> improvements

Thank you everyone for your feedback. We launched the new documentation
styles this morning. Please let us know if you find any issues or have
any additional feedback.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Proposed HTML Documentation Styles

[Jonathan S. Katz]

Hi Alexander,

On 10/16/18 2:44 PM, Alexander Romanenko wrote:
> I am having problem with distinguishing tables from the description body
> without shadows. Without a shadow, stronger border and headings,  like
> in old version, tables likes function parameter lists blends in with
> description paragraphs.

I went ahead and made a change to make the table section headers to
stand out more in the documentation and verified on the documentation
for all supported versions.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Images in the official documentation

[Jonathan S. Katz]

Hi Jürgen,

On 11/14/18 8:36 AM, Jürgen Purtz wrote:
> After many mails, F2F-discussions and some experiments - everything
> without a concrete result - I hereby start a new initiative concerning
> SVG tools. The attached PDF file describes my recommendation. The two
> SVG files are examples for working in this sense.

It looks like you put a lot of effort into this, thanks! Those SVGs do
look great, and it's IMO it's a much needed feature to support images in
our documentation :) I will leave it to others to discuss if the
generated SVGs are a technical fit for the documentation code.

I would recommend that you transfer the contents of your proposal to the
PostgreSQL wiki (https://wiki.postgresql.org/) as it would make it
easier for others to collaborate on and contribute to it. If you need
help with it, please feel free to ping me.

The one thing that I see is if we would like to have a style guide,
primarily around colors, for images we put into the repo. I know that
somehow correlates with the definition of "bike shed" but it could also
help reduce that in the future. As we do have a PostgreSQL color
palette, I also see that as an opportunity to reduce potential
bikeshedding as well.

Thanks!

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Documentation for create unique index is insuficient and (because of that) incorrect

[Jonathan S. Katz]

On 11/19/18 9:05 PM, Bruce Momjian wrote:
> On Tue, Oct 23, 2018 at 06:29:55PM +, PG Doc comments form wrote:
>> The following documentation comment has been logged on the website:
>>
>> Page: https://www.postgresql.org/docs/11/static/indexes-unique.html
>> Description:
>>
>> In https://www.postgresql.org/docs/11/static/indexes-unique.html there are
>> omited clausules
>>
>> For example WHERE clausule is omited. 
>>
>> In https://www.postgresql.org/docs/11/static/sql-createindex.html you can
>> see the right sintax with all the clausules.
> 
> The first URL is an example and is not intended to be the complete
> syntax.
> 

In fairness, the "INCLUDE" clause was added, which is new to PostgreSQL
11, so it could raise the question as to why aren't other clauses there.

Perhaps we could add some more examples? For instance, why one might
want to use "INCLUDE" with a unique index. And perhaps a case of the
"partial unique index" (which I have used in production systems before).

Thanks!

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Documentation for create unique index is insuficient and (because of that) incorrect

[Jonathan S. Katz]

On 11/20/18 9:59 AM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> On 11/19/18 9:05 PM, Bruce Momjian wrote:
>>> On Tue, Oct 23, 2018 at 06:29:55PM +, PG Doc comments form wrote:
>>>> In https://www.postgresql.org/docs/11/static/indexes-unique.html there are
>>>> omited clausules
> 
>>> The first URL is an example and is not intended to be the complete
>>> syntax.
> 
>> In fairness, the "INCLUDE" clause was added, which is new to PostgreSQL
>> 11, so it could raise the question as to why aren't other clauses there.
> 
> Yes.  That was a dumb idea; the correct fix is to take that out, because
> it's not appropriate here.  There might be room for an additional section
> later in the chapter that discusses INCLUDE, but we shouldn't be
> cluttering the discussion of fundamental concepts like unique indexes
> with that.

Shows how closely I read the docs. +1 on removing INCLUDE from UNIQUE
indexes.

Also +1 on having a section on covering indexes.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Documentation for create unique index is insuficient and (because of that) incorrect

[Jonathan S. Katz]

On 11/20/18 1:08 PM, Alvaro Herrera wrote:
> On 2018-Nov-20, Tom Lane wrote:
> 
>> So what I think I should do is reformulate that discussion to talk
>> about making covering indexes with INCLUDE, and then mention in
>> passing that you can also do it without that as long as you don't mind
>> the payload columns being part of the index semantics.
> 
> That seems sensible.

+1

> 
>> I'm also wondering whether to move that section someplace earlier
>> in chapter 11.  Right now it's near the end because it's mostly
>> info about an implementation detail; but it wouldn't be hard to
>> make the argument that covering indexes are more important than,
>> say, indexes with custom collations.  Should we move it, and if
>> so to where?
> 
> I think right next to 11.5, which currently completes the topic of how
> are indexes used, is a good place.

I would vote at least before 11.9. You could make arguments how
understand how multicolumn, expression indexes, partials, etc. could be
more important, or at least used for frequently in the wild (at least
for now). And once we've explained those types then you could understand
how to use covering indexes appropriately.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: tickling the lesser contributor's withering ego

[Jonathan S. Katz]

On 12/27/18 4:53 AM, Magnus Hagander wrote:
> 
> 
> On Fri, Dec 21, 2018 at 4:17 PM Alvaro Herrera  > wrote:
> 
> On 2018-Dec-21, Tom Lane wrote:
> 
> > Alvaro Herrera  > writes:
> > > I propose the following patch, which will make those links stable --
> > > then we can add the following links to the contributors page:
> > >
> 
> https://www.postgresql/org/docs/10/release-10.html#RELEASE-10-ACKNOWLEDGEMENTS
> > >
> 
> https://www.postgresql/org/docs/11/release-11.html#RELEASE-11-ACKNOWLEDGEMENTS
> >
> > Seems reasonable, but note the lag time --- unless somebody does
> > something out of the ordinary, those pages won't actually have
> > such tags till after the February minor releases.
> 
> Good point.  That seems acceptable to me.
> 
> 
> Good. While it *can* be worked around, it's a PITA and it risks getting
> overwritten by other things, since the normal docs loads are based off
> release tarballs. We can make them off a snapshot tarball, but it's a
> pain :)
> 
> Oh, and +1 for stable links like that in general. That would be one good
> step.

Agreed on above points.

> 
> Not having considered what to do with, but it could also be interesting
> to teach the loader to read the structured data out of the XML file and
> store it in one of these weird things called a "database". That could be
> used for things like matching on the contributors list and add a little
> per-version badge to which versions they are known to contribute etc.
> That would require us to be quite consistent in the naming of people,
> and also not to have duplicates though, but maybe it can be valuable?

Not to hijack this, but there are some similar(-ish; we can debate
semantics, but it's a similar idea) things mentioned here[1] in
conjunction to the release note trimming. If we are going to go on the
"store stuff in the database" route around additional information the
docs, I'd suggest we tackle the release note trimming as well (and I
volunteer myself for that) as that should have significant impact across
the project (esp. full build time!).

I'm all for highlighting contributors and their work - so perhaps we can
combine both efforts since there might be a common solution to both? :)

(and RE dupes: I also hear that these database things are good tools for
helping to eliminate such things ;-)

Thanks,

Jonathan

[1]
https://www.postgresql.org/message-id/flat/19252.1533509841%40sss.pgh.pa.us



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 8/30/18 4:15 PM, Magnus Hagander wrote:
> On Fri, Aug 10, 2018 at 1:38 AM, Peter Eisentraut
>  > wrote:
> 
> On 06/08/2018 00:57, Tom Lane wrote:
> > Anyway, I'd like to propose a compromise position that I don't think
> > has been discussed before: let's drop release notes for branches
> > that were already EOL when a given branch was released.  So for
> > example, 9.3 and before would go away from v12, due out next year.
> > Working backwards, we'd drop 9.1 and before from v10, giving the 15%
> > savings in page count that I showed above.  A quick measurement says
> > that would also trim the size of the v10 tarball by about 4%, which
> > is not a lot maybe but it's noticeable across a lot of downloads.
> 
> Why not go further and just ship the release notes of the current major
> version.  If you want to look at the release notes of version 11, read
> the documentation for version 11.  Who reads the documentation of
> version 12 to get the release notes of version 11?
> 
> 
> +1 for that. At least if we get a generic release notes index up on the
> website, easy to find.

So circling back on this, Peter's point makes a lot of sense.

If you want to see release notes for other major versions, there would
be URLs to the other major versions, but that would be far less costly
than keeping the actual release notes in each tarball.

So for example, let's take PostgreSQL 11:

https://www.postgresql.org/docs/11/release.html

We could do something like:

==snip==
- Release 11.1
Migration to Version 11.1
Changes
- Release 11.0
Migration to Version 11.1
Changes

Older Major Versions:

PostgreSQL 10 [URL to https://www.postgresql.org/docs/10/release.html]
PostgreSQL 9.6 [URL to https://www.postgresql.org/docs/9.6/release.html]
etc. etc.
== snip ==

That would both save significant space and hopefully solve the archiving
problem, as we would have the older docs available with all of their
respective versions.

The downside would be the PDFs, you would not have all the release notes
for, say PostgreSQL 10, in the PostgreSQL 11 PDFs. But I would argue
does that really matter? I could see that being helpful if you're
migrating between versions, but if you're using PostgreSQL 11, you're
using PostgreSQL 11 and the information for that version is the most
relevant.

It also seems like it'd make it easier to maintain the release notes
too, which would be another big win in addition to the build speedup.

Thoughts?

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: protocol-message-formats <- display format

[Jonathan S. Katz]

On 1/8/19 2:33 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/11/protocol-message-formats.html
> Description:
> 
> Hi,
> 
> It would improve the readability if we add further tabulation to the
> description of each message.
> Also, make the message title bold to visually distinguish it from the
> description.
> 
> I would gladly modify the css to make this happen.

Looking at a version[1] before the the redesign, it appears there was
further indentation, so yes, this should be added back in.

I believe the titles are used in other places with that style, so we'd
have to make sure any changes to that don't affect readability on other
pages.

Thanks,

Jonathan

[1]
https://web.archive.org/web/20180309050904/https://www.postgresql.org/docs/9.6/static/protocol-message-formats.html



signature.asc
Description: OpenPGP digital signature

Re: protocol-message-formats <- display format

[Jonathan S. Katz]

On 1/9/19 10:13 AM, Jonathan S. Katz wrote:
> On 1/8/19 2:33 PM, PG Doc comments form wrote:
>> The following documentation comment has been logged on the website:
>>
>> Page: https://www.postgresql.org/docs/11/protocol-message-formats.html
>> Description:
>>
>> Hi,
>>
>> It would improve the readability if we add further tabulation to the
>> description of each message.
>> Also, make the message title bold to visually distinguish it from the
>> description.
>>
>> I would gladly modify the css to make this happen.
> 
> Looking at a version[1] before the the redesign, it appears there was
> further indentation, so yes, this should be added back in.

Attached is a patch to correct this. I tested several pages that are
affected by the "VARIABLELIST" style in multiple versions, and it
appears to be an overall improvement.

I will apply to pgweb shortly.

Thanks,

Jonathan
From 79253866e3ff99047c6bc6e4b79da6ecbb4823c8 Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Wed, 9 Jan 2019 10:31:46 -0500
Subject: [PATCH] Add further indentation to variable lists to distinguish
 groups.

This was an regression introduced by the new styles that affects
readability of nested variables lists (e.g. on the message protocol
page). This brings the look more in line with the previous documentation
styles and should help with readability.
---
 media/css/main.css | 15 +++
 1 file changed, 15 insertions(+)

diff --git a/media/css/main.css b/media/css/main.css
index 7b11456..c0cf16d 100644
--- a/media/css/main.css
+++ b/media/css/main.css
@@ -941,6 +941,21 @@ code,
 font-weight: 300;
 }
 
+#docContent .VARIABLELIST dt,
+#docContent .variablelist dt {
+font-family: monospace;
+font-weight: 300;
+}
+
+#docContent .variablelist dd {
+margin-top: 1rem;
+}
+
+#docContent .VARIABLELIST dd,
+#docContent .variablelist dd {
+margin-inline-start: 2rem;
+}
+
 #docContent ul.itemizedlist {
 margin-left: 2.5rem;
 }
-- 
2.14.3 (Apple Git-98)



signature.asc
Description: OpenPGP digital signature

Re: Font size of nested headlines counterintuitive

[Jonathan S. Katz]

On 1/11/19 7:54 AM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/11/collation.html
> Description:
> 
> The font size of level 4 headlines (, e.g. "23.2.2.3. Creating New
> Collation Objects") is remarkably smaller than the font size of level 5
> headlines (, e.g. "23.2.2.3.1. libc collations") which is
> counterintuitive and at least a little bit confusing.
> 
Thanks for reporting. This has been adjusted so that the font size for
 blocks are explicitly smaller than  and larger.

Best,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Bug reporting guidelines order of instructions

[Jonathan S. Katz]

On 1/18/19 4:06 PM, Joe Conway wrote:
> On 1/17/19 9:29 AM, Alvaro Herrera wrote:
>> On 2019-Jan-17, Magnus Hagander wrote:
>>
>>> Per the docs comment today, I will remove the notes about majordomo at
>>> https://www.postgresql.org/docs/current/bug-reporting.html.
>>>
>>> However, this one also suggests email to the pgsql-bugs report as the
>>> primary choice "and you can also use the bugs form. Do we perhaps want to
>>> change the order of these and suggest the web form as the primary method,
>>> since that hands out bug ids?
>>
>> +1.
> 
> +(many)

+1, esp. based on the progress of this thread[1]

Jonathan

[1]
https://www.postgresql.org/message-id/flat/20190114221809.eymqah36d6uq5nir%40alap3.anarazel.de



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 1/25/19 6:46 PM, Bruce Momjian wrote:
> On Fri, Jan 25, 2019 at 06:41:20PM -0500, Tom Lane wrote:
>> Bruce Momjian  writes:
>>> I assume this means we would only keep the current release notes in the
>>> git tree too, e.g. 11.0, 11.1, 11.2, etc.
>>
>> Yeah, I'd imagine that each branch would have just its own release notes.
>>
>> I'm not sure whether to apply this policy retroactively to the supported
>> back branches or just establish it going forward.  Maintaining the notes
>> could be pretty confusing for the next few years if we do the latter,
>> though.
> 
> Agreed.  We would need to backpatch.
> 

I am in favor of backpatching.

The one "caveat" I will bring up is that once pushed and applied to the
site, we would bring introduce a lot of 404s into the website.

Doing some research on our traffic analytics on the past 6 months, the
only release notes that even registered in the top 500 pages visited
were the ones from whatever the newest release was (i.e. 10.4, 10.5,
11.0, 11.1). That, combined with that I don't think we will take an SEO
hit from unceremoniously removing the pages even with the sudden rise in
404s, should make it ok to backpatch.

Jonathan




signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 1/26/19 10:06 AM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> The one "caveat" I will bring up is that once pushed and applied to the
>> site, we would bring introduce a lot of 404s into the website.
> 
> Hm.  In principle we could probably insert some redirects, but
> I doubt it's worth the trouble.

The reason I didn't bring it up the redirect method was due to the
latter point: it'd be more trouble than its worth and for not much gain.
How often do people look at the 8.4.7 release notes anyway?

(...I have when researching various things, but that's not a regular
occurrence :-)

> 
> If I haven't heard objections, I'll see about making this happen
> during the first week of Feb (after the CF closes, but before
> it's time to do the February releases' notes).

Thank you! I was hoping to take a crack at doing this, but I would not
be able to do so in the above timeline. However, I should be able to review.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Release Notes for PostgreSQL v10.4 is same as release 9.6.9

[Jonathan S. Katz]

On 1/31/19 8:52 AM, Bruce Momjian wrote:
> On Thu, Jan 31, 2019 at 02:07:41PM +, PG Doc comments form wrote:
>> The following documentation comment has been logged on the website:
>>
>> Page: https://www.postgresql.org/docs/10/release-10-4.html
>> Description:
>>
>> I could see the features, release date are identical in version 10.4 and
>> 9.6.9. Can you please check and this could help in choosing the right
>> version for any upgrade plan?
>>
>> Reference documentation
>> https://www.postgresql.org/docs/10/release-10-4.html
>> https://www.postgresql.org/docs/9.6/release-9-6-9.html
> 
> I see different content at those two URLs.  I don't understand your
> question.

I think the question is which version they are considering to upgrade
to. Using the versioning guide:

https://www.postgresql.org/support/versioning/

Both of those are minor releases (i.e. 10.4, 9.6.9 respectively) for the
major versions that they support (i.e. 10, 9.6 respectively). They are
released on the same day as we release minor updates for all supported
versions on the same day.

If you are currently on 9.6, the easiest (and recommended) upgrade path
for minor fixes would be to go to the latest minor release as of this
writing (which is 9.6.11). Same if you are on 10, in which case the
latest minor release as of this writing is 10.6

If you are on 9.6 and want to go to 10 (or 11), that would be a
different upgrade path as that is considered a "major upgrade" (which is
covered both in the docs and the URL above)

I hope this helps.

Best,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 2/4/19 11:12 AM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> On 1/26/19 10:06 AM, Tom Lane wrote:
>>> If I haven't heard objections, I'll see about making this happen
>>> during the first week of Feb (after the CF closes, but before
>>> it's time to do the February releases' notes).
> 
>> Thank you! I was hoping to take a crack at doing this, but I would not
>> be able to do so in the above timeline. However, I should be able to review.
> 
> Attached is a diff showing what I'm thinking about, for HEAD; each
> active back branch would get a similar change.  I'd also "git rm"
> now-unreferenced files in relevant branches, but that'd just bulk up
> the diff so I've not shown it here.

Thanks on all accounts. I reviewed and its along the lines of what I was
thinking as well. The documentation in release.sgml on how to create
things is clear. I did not try applying the patch, but syntactically it
passes the eyeball test.


> It's not quite clear to me what the policy would be for removing
> back-branch links from this list when old versions drop out of support.
> Should we go back and remove them in surviving back branches, or just
> change HEAD?

Yeah, that was one of my first thoughts as I reviewed the patch. It's
one of those "once-a-year" things that are easily forgotten (e.g. with
EOL warnings, which is why we updated a few things around that). But as
long as they're added to the process of wrapping for the release, it
does not sound like its a huge burden.


> Note that this would change our workflow for release notes a bit,
> in that real editing work would happen in the back branches, rather
> than them just getting copies of text from HEAD.  I don't see a big
> problem there, but it's a bit different from how we've traditionally
> done things.

I guess one way to look at it: overhead of adding these additional
changes vs. overhead saved with build times + tarball size? Are the
extra X minutes of developer time worth it?

> 
> Just for the record, this change causes the time to build HEAD's
> HTML documentation to drop from ~120 sec to ~95 sec for me; the
> size of the resulting html/ directory drops from 21MB to 15MB,
> while the PDF output goes from 17MB to 12.2MB.  I didn't try to
> measure the impact on tarball size, but it should be noticeable.

Wow, 28-29% reduction in the file sizes, and 20% reduction in build
time! Nice.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 2/4/19 4:25 PM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> On 2/4/19 11:12 AM, Tom Lane wrote:
>>> It's not quite clear to me what the policy would be for removing
>>> back-branch links from this list when old versions drop out of support.
>>> Should we go back and remove them in surviving back branches, or just
>>> change HEAD?
> 
>> Yeah, that was one of my first thoughts as I reviewed the patch. It's
>> one of those "once-a-year" things that are easily forgotten (e.g. with
>> EOL warnings, which is why we updated a few things around that). But as
>> long as they're added to the process of wrapping for the release, it
>> does not sound like its a huge burden.
> 
> After a bit more thought, I'm inclined to propose that the policy be
> that we *don't* update the surviving back branches for branch retirement.
> The new wording in release.sgml should be adjusted to clarify this,
> along the lines of

...so I guess in turn, we would not update back branches with newer
releases as well, i.e. adding references about 12 to 10? That makes
sense, and eases some of the burden on releases.

>   Release notes for prior release branches can be found on the
>   PostgreSQL web site.  At the time of release of version 12,
>   these were the supported prior release branches:
> 
>   
> 
>   Release notes for older branches can be found at
>   .
> 
> In this way, the prior-release notes section just provides some handy
> links for recent past releases, and isn't purporting to offer
> up-to-the-minute info on what's in support.

+1

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 2/4/19 5:23 PM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> On 2/4/19 4:25 PM, Tom Lane wrote:
>>> After a bit more thought, I'm inclined to propose that the policy be
>>> that we *don't* update the surviving back branches for branch retirement.
> 
>> ...so I guess in turn, we would not update back branches with newer
>> releases as well, i.e. adding references about 12 to 10? That makes
>> sense, and eases some of the burden on releases.
> 
> No, I definitely didn't have any intention of putting in forward
> references to later releases.  That seems a bit weird.

Agreed. Anyway, I like the overall solution: +1

Thanks for writing the patch,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 2/5/19 1:02 AM, Andres Freund wrote:
> Hi,
> 
> On 2019-01-26 10:06:06 -0500, Tom Lane wrote:
>> "Jonathan S. Katz"  writes:
>>> The one "caveat" I will bring up is that once pushed and applied to the
>>> site, we would bring introduce a lot of 404s into the website.
>>
>> Hm.  In principle we could probably insert some redirects, but
>> I doubt it's worth the trouble.
>>
>> If I haven't heard objections, I'll see about making this happen
>> during the first week of Feb (after the CF closes, but before
>> it's time to do the February releases' notes).
> 
> Gah, I'd skipped this thread, because I was OK, if not happy, about the
> original modest proposal (trimming to supported versions). My fault.
> 
> For the record: I think this is a terrible idea. Makes it much harder to
> figure out what changed when, and requires per-branch incantations to
> grep through the log.   That's not to speak of the fact that now it's
> just about impossible to reference all releasenotes on the website in a
> useful manner now.

How frequently are you referencing release notes from older versions --
and I don't mean ones that are just deprecated, but things like 8.2? Or
even minor versions such as 8.2.5?

Is there a way to keep a balance on the code side: keep the source files
in but don't reference them to be built? That may not help with the
tarball size, but would certainly still help build times + lower
HTML/PDF output.

> 
> For crying out loud, super prominent and often referenced URLs like
> https://www.postgresql.org/docs/devel/release-10.html
> are now broken, and soon URLs like
> https://www.postgresql.org/docs/current/release-10.html
> will be too.

We can set up some redirect rules for this in pgweb. We have a record of
what the latest version is, so we can intercept anything going to
`/current/release-(1?[0-9]+(\.[0-9]?` (untested regex) and point it to
the correct version.

The original thought process was to _not_ do that given the effort, but
if it's just for `/current/` it may not be so bad.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 2/5/19 9:12 AM, Tom Lane wrote:

> Anyway, if people want something resembling the old presentation,
> I think the way to get there is to have some sort of aggregate
> release notes in a separate place on the web site.  We'd discussed
> that briefly upthread, but no one's volunteered to push it through.

I do have one patch for exactly that. Magnus and I disagreed on the
implementation, perhaps we can circle back around and find something we
both agree on.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 2/5/19 11:37 AM, Tom Lane wrote:
> I wrote:
>> BTW, while we're thinking about this --- I remembered that as things
>> stand, we've broken my historical practice of putting up first-draft
>> minor release notes for people to look at if they choose.  Those will
>> now be in the newest back branch, which we don't have an automatic
>> build-and-post pipeline for, AFAIK.  Now, maybe the people who would
>> review those notes are all comfortable with looking at the git
>> commitdiff anyway.  But somebody who preferred to wait for the next
>> guaibasaurus run and then look at the website is now out of luck.
>> Would it be possible to drive this aggregation off the git copies
>> of release-NN.sgml (from appropriate branches) instead of the last
>> released versions?  Or set up something equivalent to the devel
>> notes pipeline for back branches?
> 
> After further thought about that, I'm liking the idea that was
> discussed upthread of setting up a separate git repo for the
> aggregate release notes.  It'd have a simple(?) Makefile with
> the only build product being the aggregate release notes as
> HTML (maybe PDF too).  The constituent files would be copies
> of the release-NN.sgml files from the master code repo.  There'd
> be no particular need for multiple branches in this repo, it'd
> just be latest data all the time.
> 
> The main drawback of this approach is the need to copy the
> release-NN.sgml files from the master code repo.

This is where I had a slight moment of panic especially regarding the
release process. Yes, it's not often -- it's an extra step, but perhaps
in the end it saves a lot of headaches and allows us to cover the below.

>  But since
> we'd only touch it four or five times a year, that doesn't
> seem like unacceptable overhead to me.  The benefits are:
> 
> * It's not so hard to cope with the fact that the various
> branches don't all use the same docs toolchain.  We'd just
> agree that the release notes repo uses the current toolchain,
> and when transferring over old release notes, they'd have to
> be edited as necessary to make them build.
> 
> * The web site could be set up to build-and-publish from this
> repo automatically, more or less like the devel docs are published
> from the master code repo automatically.  That'd fix the problem
> I worry about above: drafts could be published by shoving them into
> the release note repo ahead of official release.

The original pgweb patch I wrote sort-of handled this: it basically
looked for release notes within the core repo, found ones that it did
not already have, and stuffed them into a table.

It should not be difficult to repurpose that code to load them in from a
separate repo, and perform that similar parsing.


> (Contrariwise, if we had say a security-related update we did
> *not* want to be visible immediately, we'd just delay transferring
> that to the release note repo.)

I don't see this as an insurmountable issue.

The contrary point I will make is handling this via a different method.
I believe one of the things Magnus objected to in the original patch
upthread (or in a private conversation) was that we were double-storing
the release note data in the patch I proposed. My way around that was
going to perform some careful scripting, i.e:

- Find the version of PostgreSQL from newest to oldest
- Find the associated release notes from newest to oldest
- Make available on the site

Which all should be doable from the current data we store. The advantage
is that allows us to leave everything as is when displaying release
notes on the site.

(which if we end up going this way, I'm happy to work on this)

> 
> I'd be willing to do most of the legwork in populating this repo,
> if someone else were to handle the website plumbing.

If we go down the new path, I would be happy to do the website work, it
will require Magnus sign-off if there is a schema change.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Release note trimming: another modest proposal

[Jonathan S. Katz]

On 2/5/19 12:17 PM, Andres Freund wrote:
> Hi,
> 
> On 2019-02-05 12:10:57 -0500, Tom Lane wrote:
>> Andres Freund  writes:
>>> On 2019-02-05 08:50:16 -0500, Jonathan S. Katz wrote:
>>>> The original thought process was to _not_ do that given the effort, but
>>>> if it's just for `/current/` it may not be so bad.
>>
>>> I think it definitely should also be on /devel/, that's what's out there
>>> on blog posts and such.  I am flummoxed that we're just giving up google
>>> juice by willy nilly returning 404 for stuff that's more widely linked
>>> than the average page. It's not like we are that good placed in searches
>>> (although that's primarily related to other things).
>>
>> I thought there was some concern that we were deoptimizing by having
>> multiple copies of substantially the same page.
> 
> I think that's an independent issue, given that the rest of the docs are
> largely duplicated between the versions too.

To chime in on this quickly, I remember researching the traffic to the
various release notes over a fairly large window -- other than when a
major release comes out, the traffic is so insignificant to all the
other release pages that dropping them down to 404s would barely register.

For minor releases, most people get the info from the news article (and
presumably email to -announce) by several orders of magnitude vs. the
release notes themselves.

The redirects would be a courtesy for our users rather than anything
affecting what's in search.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Tutorial section of documentation: enhancements needed

[Jonathan S. Katz]

Hi Laetitia,

On 2/12/19 3:06 AM, Lætitia Avrot wrote:
> To me, there are 2 options:
> - either, we change the "Tutorial" name of that chapter, so millenials
> don't think they will find a step by step doc on how to install,
> configure and connect to Postgres and add a tutorial page (the name can
> be changed) on the postgresql.org  website

I don't know if we need to change the name as much as it needs some
rewriting. Perhaps the whole section is simplified to a "getting
started" that gets people to download, install, and run PostgreSQL in
their desired environment, and then the basic commands to get started
(which I think we do a decent job of that portion?)

In my early days of using PostgreSQL, I remember this being in my
bookmarks for getting started:

https://www.postgresql.org/docs/current/install-short.html

Perhaps we can also boil something down for the modern methods of
installation.

Also I would not necessarily say this is a "millennial" issue, I think
this extends to many new users of PostgreSQL who, in particular, may not
be as used to the command-line. (I also say that as someone who is
technically considered a millennial ;-)

> - either we change the first part "getting started" to add practical
> installation steps (but it might be redundant with the download page of
> postgresql.org ), basic configuration (if needed,
> as how to open connection for your OS user, that kind of things) and how
> to connect with psql on several OS (Windows included).

+1. One thing to consider is that many people also use something like
pgAdmin (I've often heard people thing pgAdmin is PostgreSQL) which also
adds to the how people get started.

> I think we really need to take care of beginners who would like to
> install postgres on their laptop to "give it a try".

A section that was added as part of the website update last year and
subsequently poorly named by me was this:

https://www.postgresql.org/docs/online-resources/

Which contains a list of tutorials and other resources to help get
started with PostgreSQL. We could give this page a better name in the
hope that it helps people with more of the "getting started" pieces
until if/when we change the docs.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Responsive images in pgweb docs

[Jonathan S. Katz]

Hi,

First, many thanks on all the hard work for getting images into the
documentation, this is certainly a great new feature for ours users.

When testing the rendering of the images on the pgweb docs, I discovered
that they are not responsive (see attached) and in its current state,
basically makes any page that loads an image significantly more
challenging to read on mobile.

I've devised a solution to the problem, which will take work both on the
pgweb front as well as the SVG image generation.

The pgweb side is relatively simple: wherever we see ".figure" we can
tack on ".col-xl-8.col-lg-10.col-md-12" (Bootstrap grid codes) which
provides some readable images.

However, that in itself will not make the images responsive. It appears
that the width/height are at present hardcoded onto the SVG, for example
in doc/src/sgml/images/gin.svg you find:

From b4f94ee3b62d4eeec45cfa4fbba5375810d8ae59 Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Sun, 31 Mar 2019 10:16:26 -0400
Subject: [PATCH] Modify SVGs to not have view boxes that can scale based on
 viewing container.

This allows for responsive image viewing, particularly on the web.
---
 doc/src/sgml/images/gin.svg| 3 +--
 doc/src/sgml/images/pagelayout.svg | 8 
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/doc/src/sgml/images/gin.svg b/doc/src/sgml/images/gin.svg
index eacb5c8c16..493f0ffa76 100644
--- a/doc/src/sgml/images/gin.svg
+++ b/doc/src/sgml/images/gin.svg
@@ -4,8 +4,7 @@
 
 
-http://www.w3.org/2000/svg"; 
xmlns:xlink="http://www.w3.org/1999/xlink";>
+http://www.w3.org/2000/svg"; xmlns:xlink="http://www.w3.org/1999/xlink";>
 
 gin
 
diff --git a/doc/src/sgml/images/pagelayout.svg 
b/doc/src/sgml/images/pagelayout.svg
index 6b819a553e..95711c541f 100644
--- a/doc/src/sgml/images/pagelayout.svg
+++ b/doc/src/sgml/images/pagelayout.svg
@@ -1,8 +1,8 @@
 
-
   
@@ -37,4 +37,4 @@
 
 
   
-
\ No newline at end of file
+
-- 
2.14.3 (Apple Git-98)



signature.asc
Description: OpenPGP digital signature

Re: Responsive images in pgweb docs

[Jonathan S. Katz]

On 4/1/19 5:57 AM, Peter Eisentraut wrote:
> On 2019-03-31 16:23, Jonathan S. Katz wrote:
>> When testing the rendering of the images on the pgweb docs, I discovered
>> that they are not responsive (see attached) and in its current state,
>> basically makes any page that loads an image significantly more
>> challenging to read on mobile.
> 
> Image scaling is currently intentionally disabled for the HTML output
> (see ignore.image.scaling in stylesheet-html-common.xsl).  But if we
> turn it on, then the images will automatically be huge if you have large
> screen.  Is that better?

Yes - we can control how much of the screen the image will take up with
the Bootstrap grid CSS classes, which is what the patch on the pgweb
side does.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Responsive images in pgweb docs

[Jonathan S. Katz]

On 4/1/19 8:22 AM, Peter Eisentraut wrote:
> On 2019-04-01 13:23, Jonathan S. Katz wrote:
>>> Image scaling is currently intentionally disabled for the HTML output
>>> (see ignore.image.scaling in stylesheet-html-common.xsl).  But if we
>>> turn it on, then the images will automatically be huge if you have large
>>> screen.  Is that better?
>>
>> Yes - we can control how much of the screen the image will take up with
>> the Bootstrap grid CSS classes, which is what the patch on the pgweb
>> side does.
> 
> How do you do it outside of Bootstrap?

Effectively you're adjusting the width of the container, in this case,
as a percentage.

So borrowing from upthread, Bootstrap divides your viewport into 12
columns. In the "large screen" format, I specified for the image to load
within 8 of those columns (col-xl-8) which is equiv to a width of 75% of
the viewport.

Jonathan





signature.asc
Description: OpenPGP digital signature

Re: Clarity in partial index example.

[Jonathan S. Katz]

On 4/3/19 4:20 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/11/indexes-partial.html
> Description:
> 
> The example illustrating when a partial index can and cannot be used is a
> little misleading. The query which can use the partial index is:
> SELECT *
> FROM access_log
> WHERE url = '/index.html' AND client_ip = inet '212.78.10.32';
> 
> and the query which can't use the partial index is:
> SELECT *
> FROM access_log
> WHERE client_ip = inet '192.168.100.23';
> 
> Maybe I am misunderstanding the concept here but url = '/index.html' doesn't
> have any effect on this? If that's the case I would suggest either removing
> it from the first query or adding it to the second query.

You're correct, the url = '/index.html' does not affect if the partial
index is used in the example.

Based on how the example is set up, I'd propose using the "url"
parameter in both examples. I've attached a patch that does this, with
some additional wording around the examples.

Thanks,

Jonathan
From 97198351a066f43823573f7280111d78ee8895e7 Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Wed, 3 Apr 2019 17:58:17 -0400
Subject: [PATCH] Use consistent examples of queries demonstrating when a
 partial index is used.

---
 doc/src/sgml/indices.sgml | 6 --
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 3493f482b8..9a3f6d9b9e 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -814,11 +814,13 @@ SELECT *
 FROM access_log
 WHERE url = '/index.html' AND client_ip = inet '212.78.10.32';
 
-A query that cannot use this index is:
+as the above IP address falls into the range that is covered by the partial
+index. The following query cannot use the partial as it uses an IP address
+that is outside the range of the partial index:
 
 SELECT *
 FROM access_log
-WHERE client_ip = inet '192.168.100.23';
+WHERE url = '/index.html' AND client_ip = inet '192.168.100.23';
 

 
-- 
2.14.3 (Apple Git-98)



signature.asc
Description: OpenPGP digital signature

Re: Clarity in partial index example.

[Jonathan S. Katz]

On 4/3/19 6:30 PM, Tom Lane wrote:
> "Jonathan S. Katz"  writes:
>> On 4/3/19 4:20 PM, PG Doc comments form wrote:
>>> Maybe I am misunderstanding the concept here but url = '/index.html' doesn't
>>> have any effect on this? If that's the case I would suggest either removing
>>> it from the first query or adding it to the second query.
> 
>> You're correct, the url = '/index.html' does not affect if the partial
>> index is used in the example.
> 
>> Based on how the example is set up, I'd propose using the "url"
>> parameter in both examples. I've attached a patch that does this, with
>> some additional wording around the examples.
> 
> Yeah, this seems unnecessarily confusing.  I tweaked your extra wording
> a bit --- I didn't like referring to the index as covering a range,
> because it's really excluding a range not including one.

You're right, that makes sense.

> Pushed.

Thanks!

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Responsive images in pgweb docs

[Jonathan S. Katz]

On 4/4/19 7:17 AM, Peter Eisentraut wrote:
> Here is a patch to improve this a bit.  It turns back on making the SVG
> images in the HTML output scale with the page size.  I also added some
> CSS stuff to make the width 75% on large screens for a more pleasing look.
> 
> This fixes it for the gin image.  The pagelayout image still doesn't
> scale, presumably for the reasons you identified inside the SVG code.

Tested against the local patch I have for pgweb for importing the docs
with appropriate classes. The GIN SVG does indeed scale properly, thanks!

As you mention, pagelayout still does not properly scale as it needs the
fix to scale.

Given you kept the gin.svg as is and that has some of the widths on it,
I'd propose we just add the viewbox on pagelayout.svg, i.e.

viewBox="0.00 0.00 610.00 210.00"

Fix attached. I tested this in both the HTML build and with the import
into pgweb with new patch, and it scaled correctly.

Thanks,

Jonathan


From cc29aa43269ba7beb11a61aa93096698540af179 Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Thu, 4 Apr 2019 12:21:38 -0400
Subject: [PATCH 2/2] Make pagelayout.svg scalable based viewport.

---
 doc/src/sgml/images/pagelayout.svg | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/images/pagelayout.svg 
b/doc/src/sgml/images/pagelayout.svg
index 6b819a553e..3cf89f0a14 100644
--- a/doc/src/sgml/images/pagelayout.svg
+++ b/doc/src/sgml/images/pagelayout.svg
@@ -3,6 +3,7 @@
 xmlns='http://www.w3.org/2000/svg'
 width='610'
 height='210'
+viewBox='0.00 0.00 610.00 210.00'
 shape-rendering='geometricPrecision'
 version='1.0'>
   
@@ -37,4 +38,4 @@
 
 
   
-
\ No newline at end of file
+
-- 
2.14.3 (Apple Git-98)



signature.asc
Description: OpenPGP digital signature

Re: Clarification to pg_upgrade docs on reverting to old cluster

[Jonathan S. Katz]

On 4/5/19 8:26 AM, Magnus Hagander wrote:
> 
> 
> On Thu, Apr 4, 2019 at 11:14 PM Daniel Gustafsson  > wrote:
> 
> Reading the pg_upgrade reference page, I get the feeling that one of the
> bullets under "Reverting to old cluster" is a bit thin on detail to
> be helpful
> to newcomers:
> 
>     "If you ran pg_upgrade with --link, the data files are shared
> between the
>     old and new cluster.  If you started the new cluster, the new
> server has
>     written to those shared files and it is unsafe to use the old
> cluster."
> 
> This is perfectly correct, but it fails to provide information on
> what to do
> next in case reverting is in fact what the user wants.  The attached
> patch adds
> a short sentence saying the old cluster should be restored from
> backups at this
> point.
> 
> 
> Let's have two non-english natives discuss it :), but wouldn't it sound
> better with "in this case" than "at this point"? And as a really small
> nitpick, restore from backup, rather than backups? 

I would go with:

"If you need to restore the old cluster, you will have to do so using
backups that you took prior to the upgrade."

Or if you want to be overly verbose:

"If you need to restore the old cluster, you will have to do so using
backups that you made prior to the upgrade as the --link does not create
a copy of the old cluster files."

Jonathan



signature.asc
Description: OpenPGP digital signature

initdb recommendations

[Jonathan S. Katz]

Given some of the recent hubbub and analysis of CVE entries, one part of
the documentation[1] that could be further clarified is what initdb does
by default, i.e. creates a cluster where users can connect with trust
authentication. While this may be great for people who are hacking or
running PostgreSQL in a trusted local environment, this may not make
sense for many (most?) other systems.

The attached patch clarifies this fact and adds a "warning" box just
below the initdb examples that provides recommendations to create a more
secure environment. It also removes the section that discusses this
below the part that discusses securing the directory, as really this
explanation should go right after the "initdb" call.

(There could be an additional discussion about whether or not we want to
change the default behavior for initdb, but I would suggest that a safe
starting point would be to ensure we call this out)

Credits to Magnus for pointing this out, and Tom + Andrew D. for review
before posting to list.

Jonathan

[1] https://www.postgresql.org/docs/current/creating-cluster.html
From 1941d8e5c24f38798edd6a63b68a9687511f349c Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Fri, 5 Apr 2019 12:02:40 -0400
Subject: [PATCH] Add a warning about the client authentication defaults that
 initdb provides.

This also provides advice on how to securely set up initial client connection
configurations, and removes the section that explains similar steps that is
below the directory setup. This information should be around where its explained
how initdb is first called, anyway.
---
 doc/src/sgml/runtime.sgml | 46 --
 1 file changed, 24 insertions(+), 22 deletions(-)

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index fde9dbc134..dd1a8bc90f 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -85,6 +85,29 @@
described in the previous section.
   
 
+  
+
+  By default initdb sets up trust
+  client authentication for connecting to the database. This is not
+  recommended on multi-user systems where you do not trust all users, nor 
if
+  the database server will be made accessible to remote systems.
+
+
+  We recommend using the -W, --pwprompt,
+  or --pwfile flags to assign a password to the database
+  superuser, and to override the pg_hba.conf default
+  generation using -auth-local peer for local connections,
+  and -auth-host scram-sha-256 for remote connections. See
+   for more information on client
+  authentication methods.
+
+
+  If installing PostgreSQL from a distribution, we recommend you validate
+  your initially generated pg_hba.conf file to ensure
+  it meets your operational requirements.
+
+  
+
   

 As an alternative to the -D option, you can set
@@ -155,27 +178,6 @@ postgres$ initdb -D 
/usr/local/pgsql/data
for directories and 0640 for files.
   
 
-  
-   However, while the directory contents are secure, the default
-   client authentication setup allows any local user to connect to the
-   database and even become the database superuser. If you do not
-   trust other local users, we recommend you use one of
-   initdb's -W, --pwprompt
-   or --pwfile options to assign a password to the
-   database superuser.
- password
- of the superuser
-   
-   Also, specify -A md5 or
-   -A password so that the default trust 
authentication
-   mode is not used; or modify the generated pg_hba.conf
-   file after running initdb, but
-   before you start the server for the first time. (Other
-   reasonable approaches include using peer authentication
-   or file system permissions to restrict connections. See  for more information.)
-  
-
   
initdb also initializes the default
localelocale for the database 
cluster.
@@ -643,7 +645,7 @@ psql: could not connect to server: No such file or directory
 amount of anonymous mmap shared memory.
 Alternatively, a single large System V shared memory region can be used
 (see ).
-
+
 In addition a significant number of semaphores, which can be either
 System V or POSIX style, are created at server startup.  Currently,
 POSIX semaphores are used on Linux and FreeBSD systems while other
-- 
2.14.3 (Apple Git-98)



signature.asc
Description: OpenPGP digital signature

Re: initdb recommendations

[Jonathan S. Katz]

On 4/5/19 4:58 PM, Peter Eisentraut wrote:
> On 2019-04-05 18:11, Jonathan S. Katz wrote:
>> (There could be an additional discussion about whether or not we want to
>> change the default behavior for initdb, but I would suggest that a safe
>> starting point would be to ensure we call this out)
> 
> I think we should just change the defaults.  There is a risk of warning
> fatigue.  initdb does warn about this, so anyone who cared could have
> gotten the information.

It might actually be a combination of both updating the defaults and
modifying the documentation.

If we introduce better defaults, we'll need an explanation of what the
defaults are and why they are as such.

If we don't, we certainly need to warn the user what's happening. The
way it's currently written, it's very easy to miss.

I also don't see how it's warning fatigue when it's both a) a feature
that could put your system into a vulnerable state if you're not careful
and b) the only warning on that page.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: initdb recommendations

[Jonathan S. Katz]

On 4/8/19 8:25 AM, Peter Eisentraut wrote:
> On 2019-04-05 18:11, Jonathan S. Katz wrote:
>> +
>> +  We recommend using the -W, 
>> --pwprompt,
>> +  or --pwfile flags to assign a password to the 
>> database
>> +  superuser, and to override the pg_hba.conf 
>> default
>> +  generation using -auth-local peer for local 
>> connections,
>> +  and -auth-host scram-sha-256 for remote connections. 
>> See
>> +   for more information on client
>> +  authentication methods.
>> +
> 
> As discussed on hackers, we are not ready to support scram-sha-256 out
> of the box.  So this advice, or any similar advice elsewhere, would need
> to recommend "md5" as the setting --- which would probably be embarrassing.

Well, it's less embarrassing than trust, and we currently state:

"Also, specify -A md5 or -A password so that the default trust
authentication mode is not used"[1]

We could also modify it to say :

"and -auth-host scram-sha-256 for remote connections if
 your client supports it, otherwise -auth-host md5"

Jonathan

[1] https://www.postgresql.org/docs/current/creating-cluster.html






signature.asc
Description: OpenPGP digital signature

Re: initdb recommendations

[Jonathan S. Katz]

On 4/8/19 8:44 AM, Magnus Hagander wrote:
> On Mon, Apr 8, 2019 at 2:41 PM Jonathan S. Katz  <mailto:jk...@postgresql.org>> wrote:
> 
> On 4/8/19 8:25 AM, Peter Eisentraut wrote:
> > On 2019-04-05 18:11, Jonathan S. Katz wrote:
> >> +    
> >> +      We recommend using the -W,
> --pwprompt,
> >> +      or --pwfile flags to assign a password to
> the database
> >> +      superuser, and to override the
> pg_hba.conf default
> >> +      generation using -auth-local peer for
> local connections,
> >> +      and -auth-host scram-sha-256 for remote
> connections. See
> >> +       for more
> information on client
> >> +      authentication methods.
> >> +    
> >
> > As discussed on hackers, we are not ready to support scram-sha-256 out
> > of the box.  So this advice, or any similar advice elsewhere,
> would need
> > to recommend "md5" as the setting --- which would probably be
> embarrassing.
> 
> Well, it's less embarrassing than trust, and we currently state:
> 
> 
> Yes. Much less.
> 
> 
> "Also, specify -A md5 or -A password so that the default trust
> authentication mode is not used"[1]
> 
> We could also modify it to say :
> 
> "and -auth-host scram-sha-256 for remote connections if
>  your client supports it, otherwise -auth-host md5"
> 
> 
> That would be the best from a correctness, but if of course also makes
> things sound more complicated. I'm not sure where the right balance is
> there.

We could link here[1] from the docs on the line for "client supports it"

Jonathan

[1] https://wiki.postgresql.org/wiki/List_of_drivers




signature.asc
Description: OpenPGP digital signature

Re: Typo

[Jonathan S. Katz]

On 4/10/19 12:30 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/11/sql-createfunction.html
> Description:
> 
> I have noted that it seems not convenient.  
> "
> Writing
> SECURITY DEFINER
> Functions Safely
> "

So it appears what's being generated is:

Writing SECURITY DEFINER Functions
Safely

where on pgweb, the CSS on the "" block has no margins on the left
and right. Adding in the margins fixing the spacing in a large view
screen, but it looks funky on mobile. I could probably come up with some
sort of solution that works and is still responsive.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 3:20 PM, Joe Conway wrote:
> On 4/25/19 3:06 PM, Stephen Frost wrote:
>> Greetings,
>>
>> * Tom Lane (t...@sss.pgh.pa.us) wrote:
>>> Joe Conway  writes:
 On 4/25/19 1:08 PM, Joe Conway wrote:
> There is one image which can be used as an example though:
> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD
>>>
 Here is a more precise URL:
 https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD#l934
>>>
>>> Comparing that to what I see at
>>>
>>> https://www.postgresql.org/docs/devel/storage-page-layout.html
>>>
>>> does not lead to a warm feeling about our images-in-docs stuff
>>> really being ready for prime time.  It works OK in some browsers
>>> but others (at least Safari) cut off the image.
>>
>> Yeah, I'm seeing it cut off in Chrome too, initially, and then it seems
>> to fix itself if I resize the window down from 4k (and stay fixed even
>> if I then go back to the original, much larger, size).  That seems like
>> a CSS or layout issue though, not an issue with the image itself..?
> 
> 
> Yeah, I see the same thing in Chrome -- maybe Jonathan has an idea what
> is going on and how to best fix it?

See[1] - I'm not sure if the final piece is committed -- if when it is I
can finish fixing the pgweb part.

Jonathan

[1]
https://www.postgresql.org/message-id/flat/6d2442d1-84a2-36ef-e014-b6d1ece8a139%40postgresql.org




signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 4:52 PM, Jonathan S. Katz wrote:
> On 4/25/19 3:20 PM, Joe Conway wrote:
>> On 4/25/19 3:06 PM, Stephen Frost wrote:
>>> Greetings,
>>>
>>> * Tom Lane (t...@sss.pgh.pa.us) wrote:
>>>> Joe Conway  writes:
>>>>> On 4/25/19 1:08 PM, Joe Conway wrote:
>>>>>> There is one image which can be used as an example though:
>>>>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD
>>>>
>>>>> Here is a more precise URL:
>>>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD#l934
>>>>
>>>> Comparing that to what I see at
>>>>
>>>> https://www.postgresql.org/docs/devel/storage-page-layout.html
>>>>
>>>> does not lead to a warm feeling about our images-in-docs stuff
>>>> really being ready for prime time.  It works OK in some browsers
>>>> but others (at least Safari) cut off the image.
>>>
>>> Yeah, I'm seeing it cut off in Chrome too, initially, and then it seems
>>> to fix itself if I resize the window down from 4k (and stay fixed even
>>> if I then go back to the original, much larger, size).  That seems like
>>> a CSS or layout issue though, not an issue with the image itself..?
>>
>>
>> Yeah, I see the same thing in Chrome -- maybe Jonathan has an idea what
>> is going on and how to best fix it?
> 
> See[1] - I'm not sure if the final piece is committed -- if when it is I
> can finish fixing the pgweb part
OK, so I took a quick look at the existing SVGs with my patched version
of pgweb.

The short answer is that it's better: the SVGs are not responsive, but
they are displaying. There still needs to be work on the SVGs as
indicated in that thread to make them responsive[1].

With that said, the pgweb patch does fix their current display at least
in full view, so I pushed the current patch to pgweb to do that. The fix
will take effect the next time the nightly docload runs, or if someone
on pginfra forces it to occur more quickly.

Thanks,

Jonathan

[1]
https://www.postgresql.org/message-id/flat/6d2442d1-84a2-36ef-e014-b6d1ece8a139%40postgresql.org



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 5:22 PM, Jonathan S. Katz wrote:
> On 4/25/19 4:52 PM, Jonathan S. Katz wrote:
>> On 4/25/19 3:20 PM, Joe Conway wrote:
>>> On 4/25/19 3:06 PM, Stephen Frost wrote:
>>>> Greetings,
>>>>
>>>> * Tom Lane (t...@sss.pgh.pa.us) wrote:
>>>>> Joe Conway  writes:
>>>>>> On 4/25/19 1:08 PM, Joe Conway wrote:
>>>>>>> There is one image which can be used as an example though:
>>>>>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD
>>>>>
>>>>>> Here is a more precise URL:
>>>>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/storage.sgml;hb=HEAD#l934
>>>>>
>>>>> Comparing that to what I see at
>>>>>
>>>>> https://www.postgresql.org/docs/devel/storage-page-layout.html
>>>>>
>>>>> does not lead to a warm feeling about our images-in-docs stuff
>>>>> really being ready for prime time.  It works OK in some browsers
>>>>> but others (at least Safari) cut off the image.
>>>>
>>>> Yeah, I'm seeing it cut off in Chrome too, initially, and then it seems
>>>> to fix itself if I resize the window down from 4k (and stay fixed even
>>>> if I then go back to the original, much larger, size).  That seems like
>>>> a CSS or layout issue though, not an issue with the image itself..?
>>>
>>>
>>> Yeah, I see the same thing in Chrome -- maybe Jonathan has an idea what
>>> is going on and how to best fix it?
>>
>> See[1] - I'm not sure if the final piece is committed -- if when it is I
>> can finish fixing the pgweb part
> OK, so I took a quick look at the existing SVGs with my patched version
> of pgweb.
> 
> The short answer is that it's better: the SVGs are not responsive, but
> they are displaying. There still needs to be work on the SVGs as
> indicated in that thread to make them responsive[1].
> 
> With that said, the pgweb patch does fix their current display at least
> in full view, so I pushed the current patch to pgweb to do that. The fix
> will take effect the next time the nightly docload runs, or if someone
> on pginfra forces it to occur more quickly.

Good news - I did test against an older snapshot. With a newer snapshot,
the SVG on the GIN implementation page[1] is responsive but not the one
on the storage page layout[2], which is what the proposed fix in the
other thread handles.

Jonathan

[1] https://www.postgresql.org/docs/devel/gin-implementation.html
[2] https://www.postgresql.org/docs/devel/storage-page-layout.html



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 5:26 PM, Joe Conway wrote:
>
> Is there any written instruction anywhere with guidance on how the SVGs
> should be made?

https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/images/README;

but I would suggest we had some guidance on how to ensure the image
stays scalable.

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/25/19 6:54 PM, Joe Conway wrote:
> On 4/25/19 5:59 PM, Jonathan S. Katz wrote:
>> On 4/25/19 5:26 PM, Joe Conway wrote:
>>>
>>> Is there any written instruction anywhere with guidance on how the SVGs
>>> should be made?
>>
>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/images/README;
> 
> Awesome -- that is what I had been looking for. Shouldn't we add that to
> the actual documentation style guide?
> 
>> but I would suggest we had some guidance on how to ensure the image
>> stays scalable.
> 
> Since you seem to know the magic incarnations, can you propose some words?

Please see attached.

Jonathan
diff --git a/doc/src/sgml/images/README b/doc/src/sgml/images/README
index dd29486a09..81b426c066 100644
--- a/doc/src/sgml/images/README
+++ b/doc/src/sgml/images/README
@@ -59,3 +59,10 @@ Notes:
 - The width should be set to something.  This ensures that the image
   is scaled to fit the page in PDF output.  (Other widths than 100%
   might be appropriate.)
+
+- SVG images should be scalable as they will be rendered in a variety
+  of places (web, PDF, etc.) as well as in different viewports
+  (desktop, mobile, etc.). To help the images successfully scale,
+  please employe a "viewBox" attribute in the svg tag. For example,
+  to set an image to contain a default width and heigh of 400x300,
+  you would use viewBox="0.00 0.00 400.00 300.00"


signature.asc
Description: OpenPGP digital signature

Re: Documentation for partitioned indexes?

[Jonathan S. Katz]

On 4/26/19 2:53 PM, Alvaro Herrera wrote:
> On 2019-Apr-26, Tom Lane wrote:
> 
>> We appear to have a fair amount of support now for operations like
>> constructing a partitioned index piecemeal, e.g. adding indexes
>> to the partitions one at a time and then attaching them to a
>> parent partitioned index, with the parent ultimately transitioning
>> from "not valid" to "valid" once all the pieces are attached.
>>
>> However, I cannot find any coherent documentation explaining how
>> to do this (or why you'd want to).  Am I just looking in the wrong
>> places?
> 
> Hmm.  Under Notes for CREATE INDEX there is a paragraph on this:
> 
>   When CREATE INDEX is invoked on a partitioned table, the default
>   behavior is to recurse to all partitions to ensure they all have
>   matching indexes. Each partition is first checked to determine
>   whether an equivalent index already exists, and if so, that
>   index will become attached as a partition index to the index
>   being created, which will become its parent index. If no
>   matching index exists, a new index will be created and
>   automatically attached; the name of the new index in each
>   partition will be determined as if no index name had been
>   specified in the command. If the ONLY option is specified, no
>   recursion is done, and the index is marked invalid. (ALTER INDEX
>   ... ATTACH PARTITION marks the index valid, once all partitions
>   acquire matching indexes.) Note, however, that any partition
>   that is created in the future using CREATE TABLE ... PARTITION
>   OF will automatically have a matching index, regardless of
>   whether ONLY is specified.
> 
> I suppose I better add something in Chapter 5 (DDL), possibly inside the
> 5.10 section (Table Partitioning) -- a new 5.10.6 "Indexes for
> Partitioned Tables" perhaps?

+1; (though note on devel it's section 5.11, not that it matters in the
SGML)

I'd suggest keeping the title of the section similar to the one with
constraints, i.e. "Partitioning and Indexes"

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: SET ROLE documentation not entirely correct

[Jonathan S. Katz]

On 4/26/19 3:04 PM, Jonathan S. Katz wrote:
> On 4/25/19 6:54 PM, Joe Conway wrote:
>> On 4/25/19 5:59 PM, Jonathan S. Katz wrote:
>>> On 4/25/19 5:26 PM, Joe Conway wrote:
>>>>
>>>> Is there any written instruction anywhere with guidance on how the SVGs
>>>> should be made?
>>>
>>> https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=doc/src/sgml/images/README;
>>
>> Awesome -- that is what I had been looking for. Shouldn't we add that to
>> the actual documentation style guide?
>>
>>> but I would suggest we had some guidance on how to ensure the image
>>> stays scalable.
>>
>> Since you seem to know the magic incarnations, can you propose some words?
> 
> Please see attached.

v2 -- fixed typo in height, and modified some of the language.

Jonathan

diff --git a/doc/src/sgml/images/README b/doc/src/sgml/images/README
index dd29486a09..089375c485 100644
--- a/doc/src/sgml/images/README
+++ b/doc/src/sgml/images/README
@@ -59,3 +59,10 @@ Notes:
 - The width should be set to something.  This ensures that the image
   is scaled to fit the page in PDF output.  (Other widths than 100%
   might be appropriate.)
+
+- SVG images should be scalable as they will be rendered in a variety
+  of places (web, PDF, etc.) as well as in different viewports
+  (desktop, mobile, etc.). To help the images successfully scale,
+  please employe a "viewBox" attribute in the svg tag. For example,
+  to create with a default width and height of 400x300, you would use
+  viewBox="0.00 0.00 400.00 300.00"


signature.asc
Description: OpenPGP digital signature

Re: Why 'infinity' is not in range '[2019-01-02, infinity]'?

[Jonathan S. Katz]

On 4/29/19 12:12 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/11/rangetypes.html
> Description:
> 
> Hi.
> 
> May I read this:
> 
> But [today,infinity] means something different from [today,infinity) — the
> latter excludes the special timestamp value infinity.
> 
> as 
> 
> But [today,infinity] means something different from [today,infinity) — the
> **first includes** the special timestamp value infinity.
> 
> But previous paragraph says:
> 
> But note that these infinite values are never values of the range's element
> type, and can never be part of the range. (So there is no such thing as an
> inclusive infinite bound — if you try to write one, it will automatically be
> converted to an exclusive bound.)
> 
> if 'infinity' can not be the part of a range this will mean:
> 
> [today,infinity] means same as [today,infinity)
> 
> errr... which one is correct? Please fix documentation.

'infinity' in that case is a special type of date/timestamp:

https://www.postgresql.org/docs/current/datatype-datetime.html#id-1.5.7.13.19.8

which is what that paragraph is referring to. It's discussing
"infinity-like" objects you may see that are different than how range
types treat infinity.

I re-read the language, I would not advocate for making any changes.


> PS. The problem I am faced into:
> I am implementing be-temporal interface. I have current period. It can be
> [2019-01-01,2019-02-01),
> [2019-02-01,2019-03-01) and [2019-03-01,infinity) for the current month.
> 
> When I setup current_period to one of those I will get Orders at that
> period. The Orders have with 'last_bill_date' field which will show the date
> of Invoice for that Order.
> For new Order we can set 'infinity' into 'last_bill_date' which will mean
> that we should create Invoice.
> Now to select all Order for which we should create Invoice we can write:
> 
> select * from "order" o where o.last_bill_date +interval o.bill_interval <@
> current_period();
> 
> This seems obvious that infinity is part of [value, infinity) ( or
> [value,infinity] ) range. (in other words the 'infinity' is always the part
> of range with infinite inclusive or exclusive bound.
> 
> This is just view from my point, there can be things that I am not aware of.

You should drop the 'infinity' and just let it be NULL, i.e.

daterange('2019-03-01', NULL);

Jonathan



signature.asc
Description: OpenPGP digital signature

Additional "Creating a Cluster" Guidance for Windows Users

[Jonathan S. Katz]

Hi,

Per the last update release[1] I was going through some of our
documentation around creating clusters and noticed that we may want to
provide a bit more guidance around creating clusters on Windows:

https://www.postgresql.org/docs/current/creating-cluster.html

i.e.:

"Because the data directory contains all the data stored in the
database, it is essential that it be secured from unauthorized access.
initdb therefore revokes access permissions from everyone but the
PostgreSQL user, and optionally, group."

However, this does not explicitly state that initdb performs this
revocation only for *non-Windows systems* -- to lock down the data
directory after an initdb run on a Windows system, it requires manual
intervention.

I've attached a patch that explicitly states the above. I wrapped the
guidance in a "Warning" box given the data directory is exposed if not
locked down properly.

I would also recommend this is backpatched to 9.4. If in agreement on
the above methodology + wording, I can generate the backpatches.

Thanks,

Jonathan

[1] https://www.postgresql.org/about/news/1939/
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index e784268512..2ca49d2482 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -135,14 +135,23 @@ postgres$ initdb -D 
/usr/local/pgsql/data
   
Because the data directory contains all the data stored in the
database, it is essential that it be secured from unauthorized
-   access. initdb therefore revokes access
-   permissions from everyone but the
+   access. On all operating systems other than Windows,
+   initdb revokes access permissions from everyone but the
PostgreSQL user, and optionally, group.
Group access, when enabled, is read-only.  This allows an unprivileged
user in the same group as the cluster owner to take a backup of the
cluster data or perform other operations that only require read access.
   
 
+  
+   
+   If you are running PostgreSQL on Windows and create your cluster using
+   initdb, you will need to set the permissions on the data
+   directory manually. You should revoke all user access to the data directory
+   except for the PostgreSQL user.
+   
+  
+
   
Note that enabling or disabling group access on an existing cluster requires
the cluster to be shut down and the appropriate mode to be set on all


signature.asc
Description: OpenPGP digital signature

Re: a small fix for Release notes 11.3

[Jonathan S. Katz]

On 5/16/19 10:17 AM, Liudmila Mantrova wrote:
> Hello,
> 
> Please consider a mini-patch for 11.3 release notes that fixes
> pg_dump-related wording and also makes Jonathan's name consistent with
> how it's listed in contributors list.

I am flattered by your attention to detail around my name, but I'm ok
with it either way as long as my first/last names are spelled correctly :)

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: some grammar fixes for docs

[Jonathan S. Katz]

On 5/16/19 7:32 PM, Michael Paquier wrote:
> On Thu, May 16, 2019 at 05:11:37PM +0300, Liudmila Mantrova wrote:
>> I have noticed imperfect grammar in a couple of sgml files, please consider
>> a small patch (attached).
> 
> Thanks, Liudmila for caring about such matters.
> 
>> 
>> -Transaction which last more than limit 
>> milliseconds
>> +Transactions that last more than limit 
>> milliseconds
>>  are counted and reported separately, as late.
>> 
> 
> I don't see much of a difference between "which" or "that" in this
> context, and you are right about the plural for "Transactions".  Any
> native English speaker around or anybody with an extra opinion?
> 
>>   
>>Of the two operator classes for type point,
>>quad_point_ops is the default.  
>> kd_point_ops
>> -  supports the same operators but uses a different index data structure 
>> which
>> +  supports the same operators but uses a different index data structure that
>>may offer better performance in some applications.
>>   
> 
> Same here.

Technically it should be "that" - often you say "which" when one is
speaking, but in writing, in the above cases, "that" is grammatically
correct.

Thanks,

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: graphviz file extension

[Jonathan S. Katz]

On 5/24/19 8:28 AM, Joe Conway wrote:
> On 5/24/19 3:08 AM, Peter Eisentraut wrote:
>> It has come to my attention that the preferred file extension for
>> graphviz files is .gv rather than the .dot we are using.  So I propose
>> to change that for the one file we have so far (gin.dot) before we add
>> more files in the future.
> 
> 
> Agreed -- better to fix it now.

+1

Jonathan



signature.asc
Description: OpenPGP digital signature

Re: Add XSL stylesheet to fix up SVG files

[Jonathan S. Katz]

On 6/20/19 4:32 AM, Peter Eisentraut wrote:
> On 2019-06-11 13:19, Peter Eisentraut wrote:
>> Commit 29046c44f36099f4c979b1491fcf27db2f9184f9 manually edited the SVG
>> file generated by Ditaa, which was kind of what we wanted to avoid
>> having to do.  Here is an automated way to take care of the same thing,
>> by using an XSLT stylesheet.  This also takes care of another smaller
>> issue in the SVG generated by Graphviz.
> 
> committed

I have been away and have not been able to review/test this until now.
That said, I looked at the pages with SVGs on the devel docs and they
are still scaling correctly based on the viewport.

Thanks for automating the generation to handle this!

Jonathan



signature.asc
Description: OpenPGP digital signature