Postgres and other database interfaces

[aberba]

On Saturday, 24 February 2018 at 05:33:56 UTC, Joe wrote:
> Back on 13 January, I posted in the Learn forum some questions 
> regarding using Postgres and got a reply that stated the 
> following:
>
> On Monday, 15 January 2018 at 02:28:29 UTC, Matthias Klumpp 
> wrote:
>> In any case, please don't start another Postgres library and 
>> consider contributing to one of the existing ones, so that we 
>> maybe have one really awesome, 100% complete library at some 
>> point.
>
> I'm revisiting this because I now have had the chance to look 
> at the various libraries and IMHO the "really awesome, 100% 
> complete library" depends on the users' goals and their 
> definition of awesome and complete.
>
> Aside from ddbc which is like ODBC/JDBC and thus supports 
> multiple db's (not my interest), I've found five 
> Postgres-specific libraries worthy of further exploration:
>
> 1. derelict-pq. This is the most downloaded one and is simply a 
> binding over libpq, so AFAICT it's nearly 100% complete. It's 
> also well-documented, in part because the Derelict libraries 
> provide overall guidance, but mainly because a D user can refer 
> directly to the comprehensive libpq documentation and (C) 
> examples. The only strange fact is that it's been stuck in a 
> beta.3 release for the last five months.
>
> 2. dpq2. Second most downloaded and built on top of 
> derelict-pq. The "documentation" consists of a README listing 
> the features and a single example, which appears to focus on 
> support for JSON/BSON.
>
> 3. vibe-d-postgresql. Third most downloaded and built on top of 
> dpq2. Docs consist of a single example program.
>
> 4. ddb. About the same number of downloads as the above. 
> Implemented on top of front/backend protocol. No documentation 
> although repository has a folder with two sample programs.
>
> 5. dpq. Implements its own wrapper over libpq and has some ORM 
> functionality. Docs are a README with example program.
>
> The main issue is that, other than derelict-pq, using any of 
> these libraries involves reading the library code and 
> understanding the sui generis interfaces implemented by each.
>
> I'm new to the D community, but coming from Python, the 
> contrast is significant. First there is the well-documented PEP 
> 249 (https://www.python.org/dev/peps/pep-0249/) promulgated by 
> the Python DB-SIG (and note that 249 is v.2), which led to the 
> implementation of psycopg (also well-documented including 
> various extensions to the API) and many other adapters to 
> Postgres and other databases.
Some developers spend hours writing code but don't feel the need 
to speed minutes documenting or at least showing how to use their 
code. Part of the reason others roll their own (one they will 
understand).  Goes on and on.

If its for their personal use,  then they shouldn't put it on dub 
to saturate the ecosystem.

I sometimes go around sending pull requests to some with sample I 
got from their unittests or "example"  folder. Worst case,  they 
send you a link to the C library they wrote bindings for... "oh 
its easy to know by looking at the C docs". Some don't even 
border... this is common with C libraries. C has libs but hard to 
figure out how to use without going through code.

Laugh at,  as one may,  Javascript npm libraries are well 
documented so there's high adoption. OP even agrees derelict-pq 
is well documented so it has a higher usage. All Dub libraries 
with good docs are those that are downloaded. Most importantly, a 
description of package and a sample/demo is the README.md file. A 
link to generated docs may follow to more info. Only generated 
docs don't cut it.


If you document your code well,  others will use and contribute 
to it without rolling their own. Docs on library purpose and 
sample usage at least.

> "The most used Dub libraries are those well documented."