Re: Certificate authentication docs in multiple places

[Steve Atkins]

> On 10 Apr 2023, at 08:56, Michael Paquier  wrote:
> 
> On Tue, Mar 28, 2023 at 04:28:24PM +0200, Peter Eisentraut wrote:
>> Sure, some cross-linking between those two sections seems sensible.
> 
> Steve, would you like to propose a patch?

Yes, I’ll do that once I get some time to get the doc toolchain working.

Cheers,
  Steve

Certificate authentication docs in multiple places

[Steve Atkins]

A couple of times recently I’ve been chatting with someone about using 
certificate authentication, and the docs they’ve found on it are the ones in 
section 21.12 (Client Authentication -> Certificate Authentication).

But the useful documentation about how to set it up and use it is in section 
19.9.3 (Secure TCP/IP Connections with SSL -> Using Client Certificates), where 
you’re less likely to find it while thinking about authentication.

Should we add a link from the former to the latter?

Cheers,
  Steve

Re: Updating the intro for packages - improve usability, reduce new user confusion

[Steve Atkins]

> On Nov 29, 2018, at 10:17 AM, Steve Atkins  wrote:
> 
> 
> 
>> On Nov 29, 2018, at 9:36 AM, Christoph Berg  wrote:
>> 
>> Re: Dmitry Igrishin 2018-11-29 
>> 
>>>> Could you please add the reference to the Pgfe client library to the
>>>> documentation?
>>>> The patch is provided.
>> 
>>> diff --git a/doc/src/sgml/external-projects.sgml 
>>> b/doc/src/sgml/external-projects.sgml
>>> index 347b830..c74e391 100644
>>> --- a/doc/src/sgml/external-projects.sgml
>>> +++ b/doc/src/sgml/external-projects.sgml
>>> @@ -83,6 +83,13 @@
>>> 
>>> 
>>> 
>>> +  Pgfe
>>> +  C++
>>> +  An API inspired by libpq
>>> +  https://github.com/dmitigr/pgfe;>
>> 
>> Has that been around long enough, and is widely used, so it qualifies
>> for mentioning here? I've never heard of it, and it's not packaged for
>> Debian.
> 
> No. It's been discussed at least once before that I've noticed, and IIRC
> the conclusion was "add it to the wiki", which I did in May.
> 
> https://wiki.postgresql.org/wiki/Client_Libraries

And while it looks like it has the potential to become a decent enough library 
it's
own documentation says that it's beta-quality, has an unstable API and isn't
ready to be used in production.

Cheers,
  Steve

Re: Updating the intro for packages - improve usability, reduce new user confusion

[Steve Atkins]

> On Nov 29, 2018, at 9:36 AM, Christoph Berg  wrote:
> 
> Re: Dmitry Igrishin 2018-11-29 
> 
>>> Could you please add the reference to the Pgfe client library to the
>>> documentation?
>>> The patch is provided.
> 
>> diff --git a/doc/src/sgml/external-projects.sgml 
>> b/doc/src/sgml/external-projects.sgml
>> index 347b830..c74e391 100644
>> --- a/doc/src/sgml/external-projects.sgml
>> +++ b/doc/src/sgml/external-projects.sgml
>> @@ -83,6 +83,13 @@
>>  
>> 
>>  
>> +  Pgfe
>> +  C++
>> +  An API inspired by libpq
>> +  https://github.com/dmitigr/pgfe;>
> 
> Has that been around long enough, and is widely used, so it qualifies
> for mentioning here? I've never heard of it, and it's not packaged for
> Debian.

No. It's been discussed at least once before that I've noticed, and IIRC
the conclusion was "add it to the wiki", which I did in May.

https://wiki.postgresql.org/wiki/Client_Libraries

Cheers,
  Steve

Re: Images in the official documentation

[Steve Atkins]

> On Feb 25, 2018, at 6:45 PM, Craig Ringer <cr...@2ndquadrant.com> wrote:
> 
> On 26 February 2018 at 04:12, Steve Atkins <st...@blighty.com> wrote:
> 
> Writing SVG by hand maybe doesn't seem the best idea.
> 
> I understand the attraction to people who want to store everything as 
> diffable text, but images of this sort are unlikely to get updated by others, 
> which means they're unlikely to be maintained as the things they're intended 
> to document change. It also means that the people best suited to generating 
> diagrams are the least likely to do so, and vice-versa.
> 
> 
> 
> Yeah, I think it'd just effectively preserve the status quo by rendering 
> anyone who's willing to add images and designs to the docs unable - or 
> unlikely to be willing - to do so. 

Yup. I do think that graphics would be nice in a few places, and that SVG is 
likely the best format for them.

There are quite a few tools that could be integrated with varying amounts of 
effort into the documentation generation workflow.


# ASCII language or ascii art to SVG

# asciitosvg

https://github.com/dhobsd/asciitosvg

Inspired by ditaa, similar in functionality

## blockdiag, seqdiag, actdiag, nwdiag

http://blockdiag.com

Generates various box and arrow diagrams from a DOT-ish input language.

## ditaa

It takes ascii art of box and arrow diagrams and turns them into nice svg. Also 
supports boxes that look like "storage" cylinders, documents, clouds and 
computers.

## erd

https://github.com/BurntSushi/erd

Entity relationship diagrams, from a plain text input. Uses DOT and graphviz 
under the covers.

## Markdeep

http://casual-effects.com/markdeep/

In-browser javascript rendering of ascii art, particularly boxes and arrows.

Alternate implementation, https://github.com/blampe/goat, converts to SVG via 
CLI.

## Mermaid

Flowcharts and sequence diagrams from a markdown-esque input.

## mscgen

Message sequence chart inputs in a DOT-ish language to SVG

## plantuml

http://plantuml.com

It supports a human-editable descriptive text input language and generates from 
it:

  sequence diagrams
  various box + arrow style diagrams
  flowcharts
  state diagrams
  etc.


## shaape

https://github.com/christiangoltz/shaape

Converts ascii art to SVG. Rather nice.

## svgbob

https://github.com/ivanceras/svgbobrus

Ascii art to SVG. Likely good for boxes and arrows.

## syntrax

https://kevinpt.github.io/syntrax/

Railroad diagrams (like the ones SQLite docs are known for).

## umlet

http://www.umlet.com

Pointy-clicky editor, but also converts plain text to uml, sequence, activity 
diagrams

# Interactive editor

## SVG-Edit

https://github.com/SVG-Edit/svgedit

Open source, browser based interactive SVG editor. Seems to generate fairly 
clean SVG.

Cheers,
  Steve

Re: Images in the official documentation

[Steve Atkins]

> On Feb 25, 2018, at 4:00 AM, Jürgen Purtz  wrote:
> 
> As an addition to my mail from January 2016 concerning graphics 
> (https://www.postgresql.org/message-id/568A9148.30303%40purtz.de) I propose 
> to use SVG (after switching to XML) - but not an SVG which is generated by 
> Inkscape or similar tools. Those editors generate very ugly and chatty 
> commands. This form is not easy to read or understand. Therefore we shall use 
> nothing but a simple text editor and write every line by our self. The 
> process is divided into two parts:
> As a basis we shall develop an SVG library containing a bunch of "atomic" 
> symbols of simple graphical elements (rectangle, arrow, ...) up to complex 
> elements (magnetic disc, laptop, cloud, UML-elements, ...). The SVG routines 
> creating those symbols shall accept parameters for position, size, rotation, 
> colour, ... . This library shortens the individual SVG files, it ensures a 
> consistent rendering of common graphical elements, it is diff-able, and it 
> will reach a stable state - some day.
> 
> The real graphics shall use the elements of the library and add individual 
> SVG elements. The rules for this part are the same as above: create SVG 
> commands with vi (or similar), store it in git.
> If such an approach works (we must distribute the docs across a wide range of 
> different systems, a proof-of-system is necessary) and the community accepts 
> my proposal, I would like to work on the library-part - starting after 
> finishing my actual project in about 6 weeks from now. The attached file 
> contains a very first draft as of Jan. 2016.

Writing SVG by hand maybe doesn't seem the best idea.

I understand the attraction to people who want to store everything as diffable 
text, but images of this sort are unlikely to get updated by others, which 
means they're unlikely to be maintained as the things they're intended to 
document change. It also means that the people best suited to generating 
diagrams are the least likely to do so, and vice-versa.

Cheers,
  Steve

Re: Advice on Contiguous IDs

[Steve Atkins]

> On Jan 9, 2018, at 1:06 AM, Brian McKiernan  
> wrote:
> 
> 
> Hi Folks,
> 
> Looking for some help/advice - not sure if this is the appropriate channel.

pgsql-general would be a better bet.

> 
> My Issue:
> My primary keys in a certain table are not contiguous.

That itself isn't a problem at all. If there's a business requirement for them 
to be contiguous that's the issue to consider first.

> 
> What I have done so far:
> I have checked the documentation and found: 
> https://wiki.postgresql.org/wiki/FAQ#Why_are_there_gaps_in_the_numbering_of_my_sequence.2FSERIAL_column.3F_Why_aren.27t_my_sequence_nu
> mbers_reused_on_transaction_abort.3F
> 
> My Question:
> 1) What event would cause the CACHE clause in CREATE SEQUENCE to make an out 
> of sequence next number?

It causes PostgreSQL to assign batches of numbers to each connection that needs 
one, making it more likely that they'll be used out of order or that some won't 
be used at all.

Using cache just makes it more obvious, though. There's no guarantee that a 
sequence will give you consecutive numbers, nor that they'll be ordered, in 
general. About the only thing that is guaranteed is that they'll be unique.

> 2) In all cases am I correct in my thinking that in order to create 
> contiguous primary key IDs then performance will greatly suffer? Do we have 
> an idea of how bad this will generally be or what does that depend upon?

Yes. You will have to effectively serialize all inserts into those tables, 
eliminating any concurrency.

You'd need to have a pretty compelling hard business requirement for 
consecutive numbers before it'd be worth considering.

Cheers,
  Steve

Re: Is this still accurate?

[Steve Atkins]

> 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 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.

Cheers,
  Steve