Обсуждение: Postgres.js driver - for Node.js

The following documentation comment has been logged on the website:

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

Hi. 

I recently finished a fast, 0 dependency driver for Node.js with a very user
friendly api.
I think would be great to include in the documentation and the Wiki page
(details below).

You can see it here https://github.com/porsager/postgres. 
I've also made some benchmarks comparing with other Node drivers available
that you can find here https://github.com/porsager/postgres-benchmarks

I hope you'll consider including it.

https://www.postgresql.org/docs/current/external-interfaces.html
>
Postgres.js    |    JavaScript    |    No    |    Yes    |    https://github.com/porsager/postgres

https://wiki.postgresql.org/wiki/List_of_drivers
> Postgres.js    |    JavaScript    |    Node.js
driver    |    https://github.com/porsager/postgres

Thank you
Rasmus Porsager.

On 1/8/20 3:06 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> I recently finished a fast, 0 dependency driver for Node.js with a very user
> friendly api.

Congratulations!

> I think would be great to include in the documentation and the Wiki page
> (details below).

I went ahead and updated the list of drivers page[1] to include postgres.js

The list on the documentation page has not been updated for a long time
(at least the list) -- I went back through 9.4 and saw the same list.

I believe there was some discussion around updating the documentation
page[2] awhile back. I forget how the conclusion was reached (no
action), but I recall things being discussed were the
criteria/validation for how a driver is included in the documentation
and how to keep the list up-to-date.

(The wiki is able to keep up with the fluidity a bit more easily :)

Perhaps it's worth revisting? There are certainly reasons to keep a
maintained list in the documentation, with the noted pain that goes with
it (and I may have inadvertently volunteered myself) as users are more
likely to discover things there than the wiki page.

Thanks,

Jonathan

[1] https://wiki.postgresql.org/wiki/List_of_drivers#Drivers
[2] https://www.postgresql.org/docs/current/external-interfaces.html

Thanks a lot Jonathan.

It would make sense to be a bit more critical about the drivers mentioned in the documentation, but I suppose that
requiressomeone with knowledge of each language to make a proper assessment. I'd be happy to answer any questions with
regardsto Postgres.js if you do revisit it at some point. 

By the way, I gotta say, it was an absolute pleasure implementing the PostgreSQL protocol, the documentation was
fantastic,and answered all the questions I had along the way. 

Thanks

Rasmus Porsager.

> On 9 Jan 2020, at 00.21, Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> On 1/8/20 3:06 PM, PG Doc comments form wrote:
>> The following documentation comment has been logged on the website:
>>
>> I recently finished a fast, 0 dependency driver for Node.js with a very user
>> friendly api.
>
> Congratulations!
>
>> I think would be great to include in the documentation and the Wiki page
>> (details below).
>
> I went ahead and updated the list of drivers page[1] to include postgres.js
>
> The list on the documentation page has not been updated for a long time
> (at least the list) -- I went back through 9.4 and saw the same list.
>
> I believe there was some discussion around updating the documentation
> page[2] awhile back. I forget how the conclusion was reached (no
> action), but I recall things being discussed were the
> criteria/validation for how a driver is included in the documentation
> and how to keep the list up-to-date.
>
> (The wiki is able to keep up with the fluidity a bit more easily :)
>
> Perhaps it's worth revisting? There are certainly reasons to keep a
> maintained list in the documentation, with the noted pain that goes with
> it (and I may have inadvertently volunteered myself) as users are more
> likely to discover things there than the wiki page.
>
> Thanks,
>
> Jonathan
>
> [1] https://wiki.postgresql.org/wiki/List_of_drivers#Drivers
> [2] https://www.postgresql.org/docs/current/external-interfaces.html
>

I'm wondering if the short list in the documentation [2] could be
replaced with a link to the corresponding wiki page [1] ?

Jonathan B

On 1/8/2020 3:21 PM, Jonathan S. Katz wrote:
> The list on the documentation page has not been updated for a long time
> (at least the list) -- I went back through 9.4 and saw the same list.
>
> (The wiki is able to keep up with the fluidity a bit more easily :)
>
> Perhaps it's worth revisting? There are certainly reasons to keep a
> maintained list in the documentation, with the noted pain that goes with
> it (and I may have inadvertently volunteered myself) as users are more
> likely to discover things there than the wiki page.
>
> [1] https://wiki.postgresql.org/wiki/List_of_drivers#Drivers
> [2] https://www.postgresql.org/docs/current/external-interfaces.html
>

On 1/8/20 7:00 PM, Jonathan Buhacoff wrote:
> I'm wondering if the short list in the documentation [2] could be
> replaced with a link to the corresponding wiki page [1] ?

>> [1] https://wiki.postgresql.org/wiki/List_of_drivers#Drivers
>> [2] https://www.postgresql.org/docs/current/external-interfaces.html

IIRC that was one option that was floated. And IIRC there are two
potential issues that arise:

1. While it does easy the administration burden, it's still technically
a validation of drivers in that list. Maybe that's ok, based on what happens

2. We do ship out documents as PDFs, and said PDFs can be used offline.
If one is trying to understand which drivers are available and they see
a link to it, it may not be terribly helpful :(

That all said, perhaps it's time to update the list in the documentation
and create the guidance in terms of what it takes to have a driver
included in the documentation. I'd be happy to draft up some criteria.

When I last curated the list, I did try to bring it down to specifically
drivers (e.g., not ORMs or tools that enhance PostgreSQL connectivity).

Also, while scanning the list, I also saw that someone recently added
several drivers that appear to be non-OSS. Additionally, a few of the
entries are *not* drivers, which I have gone ahead and removed[1]. I
would say at a minimum, in both the wiki and the docs, we should only
list drivers that are OSS (in particular, so we can actually validate if
they use libpq and support SCRAM), but I will wait until there is some
consensus before removing the other closed-source ones.

Jonathan

[1]
https://wiki.postgresql.org/index.php?title=List_of_drivers&diff=34554&oldid=34553

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 1/8/20 7:00 PM, Jonathan Buhacoff wrote:
>> I'm wondering if the short list in the documentation [2] could be
>> replaced with a link to the corresponding wiki page [1] ?

> ...
> Also, while scanning the list, I also saw that someone recently added
> several drivers that appear to be non-OSS.

Yeah, the lack of curation there is exactly why we generally *don't* link
to the wiki from the formal docs.  We should make more of an effort to
transpose vetted info about this topic into the docs, though.

> ... I will wait until there is some
> consensus before removing the other closed-source ones.

Hm.  I'd vote against including those in the docs' list, because we can't
as-a-community review their quality and suitability.  However, I'm not
sure that there's anything wrong with having them in the wiki's list
as long as they're appropriately marked as not-OSS.

            regards, tom lane

On 1/8/20 7:59 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> On 1/8/20 7:00 PM, Jonathan Buhacoff wrote:
>>> I'm wondering if the short list in the documentation [2] could be
>>> replaced with a link to the corresponding wiki page [1] ?
> 
>> ...
>> Also, while scanning the list, I also saw that someone recently added
>> several drivers that appear to be non-OSS.
> 
> Yeah, the lack of curation there is exactly why we generally *don't* link
> to the wiki from the formal docs.  We should make more of an effort to
> transpose vetted info about this topic into the docs, though.

I'd be fine with taking a crack at this. I had some notes (I think I put
it on -hackers during the SCRAM discussion) on how I reorganized the
list, with what determined what was on the list, and what was an
unsupported driver.

>> ... I will wait until there is some
>> consensus before removing the other closed-source ones.
> 
> Hm.  I'd vote against including those in the docs' list, because we can't
> as-a-community review their quality and suitability. 

100% agree there.

> However, I'm not
> sure that there's anything wrong with having them in the wiki's list
> as long as they're appropriately marked as not-OSS.

I had an offline suggestion about including a "License" column, which
seems like a good idea in general as we also have in the docs. And if we
are going to include more drivers in the docs, we'd (read "I'd" for this
first pass) have to pull those together anyway.

My personal preference would be to at least separate the open source
from the closed source, but certain things we include in the column
(e.g. supports SCRAM) we would not be able to validate on a closed
source driver. But perhaps if we include said drivers on that page, we'd
not include that info.

(Also my preference with the closed source drivers would be to keep them
listed here:
https://www.postgresql.org/download/products/2-drivers-and-interfaces/
...which I realized adds yet another twist to this discussion because
one could then say "Why not list them all here?" And then it is a
curated listed as it goes through the pgweb team...and then we could
potentially link it from the docs...)

Jonathan

Greetings,

* Jonathan S. Katz (jkatz@postgresql.org) wrote:
> On 1/8/20 7:59 PM, Tom Lane wrote:
> > "Jonathan S. Katz" <jkatz@postgresql.org> writes:
> >> On 1/8/20 7:00 PM, Jonathan Buhacoff wrote:
> >>> I'm wondering if the short list in the documentation [2] could be
> >>> replaced with a link to the corresponding wiki page [1] ?
> >
> >> ...
> >> Also, while scanning the list, I also saw that someone recently added
> >> several drivers that appear to be non-OSS.
> >
> > Yeah, the lack of curation there is exactly why we generally *don't* link
> > to the wiki from the formal docs.  We should make more of an effort to
> > transpose vetted info about this topic into the docs, though.
>
> I'd be fine with taking a crack at this. I had some notes (I think I put
> it on -hackers during the SCRAM discussion) on how I reorganized the
> list, with what determined what was on the list, and what was an
> unsupported driver.

I agree with putting useful and vetted info into the docs, in general.

> >> ... I will wait until there is some
> >> consensus before removing the other closed-source ones.
> >
> > Hm.  I'd vote against including those in the docs' list, because we can't
> > as-a-community review their quality and suitability.
>
> 100% agree there.

I agree that we can't- but I'm also of the opinion that if we're going
to care about things the we "as-a-community" have reviewed, then we need
to actually *do* such a review, at some level, and not just list
everything there that is OSS.

There's a couple of levels of review here, at least imv-

a) It's a driver maintained by someone in the community who is active
   and takes responsibility for it (and therefore presumably either
   wrote the code or has done some amount of code-level review)

b) It's a driver that's been packaged by the community and is
   distributed through community resources

The items in 'a' are also, again in my personal view, eligible for
hosting on pginfra- things like the ODBC driver and the JDBC driver.
The items in 'b' probably also make sense to list and we expect the
packager to at least take some responsibility for dealing with issues,
even if they haven't done a code-level review.  It'd be nice if we
distinguished between those two somehow, but I'm not sure it's really
required.

I'm pretty skeptical about listing drivers beyond those categories in
our official documentation as it lends our credibility to them while
being completely outside of our control.

> > However, I'm not
> > sure that there's anything wrong with having them in the wiki's list
> > as long as they're appropriately marked as not-OSS.
>
> I had an offline suggestion about including a "License" column, which
> seems like a good idea in general as we also have in the docs. And if we
> are going to include more drivers in the docs, we'd (read "I'd" for this
> first pass) have to pull those together anyway.

I agree with having a license column (*cough* I might have also been the
one to make the offline suggestion, so don't consider this an
independent advocating of that ;).

> My personal preference would be to at least separate the open source
> from the closed source, but certain things we include in the column
> (e.g. supports SCRAM) we would not be able to validate on a closed
> source driver. But perhaps if we include said drivers on that page, we'd
> not include that info.

I don't think I agree with this- we don't validate anything for a closed
source driver, or an open source driver, to have it be listed on the
wiki- we don't really even control the wiki and we shouldn't be acting
like we do.  We can include if the driver supports SCRAM or not and
people can add that info in about whatever driver they're adding to the
list- or leave it blank if they don't know, and then someone else with
that info can choose to fill it in if they want.

> (Also my preference with the closed source drivers would be to keep them
> listed here:
> https://www.postgresql.org/download/products/2-drivers-and-interfaces/
> ...which I realized adds yet another twist to this discussion because
> one could then say "Why not list them all here?" And then it is a
> curated listed as it goes through the pgweb team...and then we could
> potentially link it from the docs...)

Linking it from the docs has the same issues as noted before though..
Maybe you could generate the docs by pulling from that list but I'm not
really a fan of that either..

Another option though would be to have the list of things from category
'a' and 'b' above be in our docs and then a link to the
drivers-and-interfaces page from the docs, and let people do what they
want with the wiki (maybe put a link at the top of such a page to the
official documentation page though, which makes it clearer that the wiki
isn't the official project position or curated list).

Thanks,

Stephen

Hi,

For this first round, going to truncate a bit of Stephen's thoughts
(sorry Stephen) just to cover where we are at:

On 1/9/20 12:00 PM, Stephen Frost wrote:
> Greetings,
> 
> * Jonathan S. Katz (jkatz@postgresql.org) wrote:
>> On 1/8/20 7:59 PM, Tom Lane wrote:

>>> However, I'm not
>>> sure that there's anything wrong with having them in the wiki's list
>>> as long as they're appropriately marked as not-OSS.
>>
>> I had an offline suggestion about including a "License" column, which
>> seems like a good idea in general as we also have in the docs. And if we
>> are going to include more drivers in the docs, we'd (read "I'd" for this
>> first pass) have to pull those together anyway.
> 
> I agree with having a license column (*cough* I might have also been the
> one to make the offline suggestion, so don't consider this an
> independent advocating of that ;).

I made a pass at the current Drivers list[1] and added in a link to all
of the license files. I would appreciate any verification to ensure I
captured them all correctly.

The added benefit of this URL is that we now have a direct link to the
source code for all of the projects on the page (whereas some were just
the project pages), which will help with checking if a project is
maintained or not :)

(It was also interesting to see which licenses all the drivers used. I
even learned of one I hadn't heard before, guess which one..)

Despite whether or not we should list out non-OSS drivers, I at least
broke them out for the time being. My feeling has not changed: we should
not list them on the wiki.

Anyway, from a quick scan, for the OSS licenses (knowing this is one of
those passionate topics), I don't see anything that I would not feel
comfortable linking to as part of our official documentation in this
batch (well...maybe one, but the spirit of the license is fine by me and
I would not staunchly object).

I think if we're comfortable where this is at, the next step would be to
define criteria for inclusion, which Stephen started in his previous
note. I'll let this bake for a bit and then follow up.

Thanks,

Jonathan

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