Documentation should suggest psycopg3, not psycopg2 anymore

[ratijas]

What happens?

Documentation about PostgreSQL integration suggests using psycopg2, which is an outdated version of the project.

It recommends installing psycopg2-binary and "pgspecial<2" together, but that just won't work, because

• "pgspecial<2" depends on psycopg2, and
• psycopg2-binary does not "provide" psycopg2 in terms of a package management, and
• installing psycopg2 from source requires some config in $PATH and possibly other weirdness.

It also states: "JupySQL supports the following connectors.", but that's a link to an outdated version of sqlalchemy 1.4, while the relevant and actually installed/used one is 2.0.x! The new link would be https://docs.sqlalchemy.org/en/20/dialects/postgresql.html which lists "psycopg (a.k.a. psycopg 3)" amongst the options.

According to the devs of pgspecial, the answer to all those issue at once would be to just use psycopg 3 instead or 2.

To Reproduce

Follow the docs for PostgreSQL integration.

OS:

Linux

JupySQL Version:

0.11.1

Full Name:

Ivan Tkachenko

Affiliation:

None

[ratijas]

JupySQL kinda "just works" with psycopg 3 and pgspecial 2. Users only need to change driver name in connections.ini or URL string from drivername = postgresql to drivername = postgresql+psycopg.

[dvarrazzo]

Thank you for the update request @ratijas

For a more complete clarification:

• Python packages metadata don't allow to specify something like "the psycopg2-binary distribution package includes the psycopg2 package"
• The reason why psycopg2-binary is distributed separately is because in the past it was unstable (due to conficts in old version of OpenSSL), so installing the binary was discouraged. Because PyPI/Pip don't offer an "opt-in" option for binary installation, but only an opt-out option, a pip install command with default parameters would have install a potentially defective package, and this default was considered bad. Splitting the -binary package away was a poor man's way to obtain an opt-in option.
• Psycopg 3 cleaned up this mess by making the psycopg-binary package ad optional add-on, while the psycopg package provides the entire interface. Therefore libraries can specify psycopg only in their dependencies (e.g. configuring psycopg > 3.2 in the project.dependencies list of the project's pyproject.toml file) and users are free to choose whether to include or not the pre-compiled C speedup too (e.g. by adding psycopg[binary] in a requirements.in to be compiled to a requirements.txt by pip-tools or similar) in order to avoid the need of having build tools at install time.

All the details are in the install documentation.