Docs clarification about `psycopg[c]`

[adamsol]

In my team, we've had a similar discussion as in django/djangoproject.com#2215, django/djangoproject.com#2212 (comment), or django/djangoproject.com#2212 (comment).

Currently, the documentation says:

A “Local installation” results in a performing and maintainable library. The library will include the speed-up C module and will be linked to the system libraries (libpq, libssl…) so that system upgrade of libraries will upgrade the libraries used by Psycopg 3 too. This is the preferred way to install Psycopg for a production site.

suggesting that the [c] version is considerably better than [binary] (which doesn't have those nice adjectives in its description). In reality, I find no performance difference, which is also confirmed in django/djangoproject.com#2212 (comment). And the "maintainability" part is quite difficult to assess. Some issues with openssl were mentioned in #1156 (comment), but it seems this is no longer a problem.

Could the docs be more specific about how much better the local installation actually is for a production site? As most Python packages relying on compiled extensions are distributed with pre-built binaries, I still (despite having read all the linked comments) find it difficult to understand why psycopg should be the only one requiring GCC and all the other dependencies. For example, are the advantages enough to justify installing different versions in dev and prod environments, possibly risking some inconsistent behavior?

Of course, I mean the case when binary installation is available for our system. If it's not, then there's no decision to make.

---

Bonus question: is it expected that installing psycopg[c] takes way more time than it did for psycopg2, even though they both require compilation? It's actually one of the main reasons for me to avoid this version, as admins installing/upgrading the application may think the process is stuck.

Installation time comparison

> time pip install psycopg2
...

Successfully installed psycopg2-2.9.11

real    0m8.050s
user    0m6.452s
sys     0m1.307s

> time pip install psycopg[c]
...

Successfully installed psycopg-3.2.12 psycopg-c-3.2.12

real    0m28.106s
user    0m26.093s
sys     0m1.646s

Interestingly, it was even 2 times slower not so long ago:

> time pip install psycopg[c]==3.2.9
...

Successfully installed psycopg-3.2.9 psycopg-c-3.2.9

real    0m56.894s
user    0m54.169s
sys     0m2.329s

[dvarrazzo]

I can try and extend on the topic.

However no difference in performance is expected: the difference is about maintainability. If libpq or openssl are upgraded in the system, psycopg[c] will use those versions, whereas psycopg[binary] will keep on using the versions it was packaged with. I appreciate it is not for you, but for someone this might be a bonus or even a deal breaker.

I honestly use [binary] in my projects because they are deployed as docker images. Bad mouthing of the binary package (which I've done a lot, it has been a major cause of frustration) was mostly referred to psycopg2 when it was packaged with OpenSSL 0.9.8, conflicting with the Python-distributed version (the python executable would have dynamically bound with two different version of OpenSSL and apparently there were incompatibilities in local objects).

Now it's ok, but in the future? Binding to a single library still feels more hygienic.

The difference in timing with psycopg2 is caused by the fact that the pg2 C code is about 15k hand-written LoC, pg3 is generated by Cython and result in a C source of about 150k LoC.

There are no size-meaningful code differences between the two versions, but I see that 3.2.9 was packaged with Cython 3.0.12, 3.2.12 with Cython 3.1.6; by what I can see in the generated code, the former is compatible with Python 2.7/3.3+, the latter with Python 3.8+, so this might cause the difference. The difference in size between the two version is about 5% smaller for pg 3.1.12.