Upgrade to psycopg3

[bmos]

This PR picks up from #987

What is this change?

• Update minimum version of SQLAlchemy to 2.0.51
• Replace psycopg2-binary package with psycopg[binary] >= 3.3.4
• Update all psycopg documentation links
• Update all psycopg2 imports to equivalent psycopg imports
• Add client_encoding arg to redshift connection

Considerations for discussion

• Psycopg3 may be required to support python 3.15, as psycopg2-binary is a blocker in Test python 3.15 #1902
• It's technically possible to support both for some period of time with a deprecation message, although it would be pretty messy. Would we want that?

How to test the changes (if needed)

• Need to run live tests locally, as there is only 56% code coverage without live tests.
  I have not run the live tests. Postgres, Redshift, and Alchemy are the parts that are most in need of validation.

Breaking Changes

Breaking changes are changes to our public API which may require existing users to change their code. If there are no breaking changes, any existing parsons user should not need to do anything after updating their parsons version.

Does this PR introduce breaking changes?

• label: Breaking change — This PR introduces one or more breaking changes.
• label: Non-breaking change — This PR does not introduce one or more breaking changes.

Details (if needed)

Breaking changes to parameterization

A few parameterization patterns that worked with psycopg2 no longer work with psycopg3.
They are detailed on the migration guide, but these in particular should be highlighted:

• You can no longer use IN %s with a tuple

  This would work with psycopg2 but will not work with psycopg3: conn.execute("SELECT * FROM foo WHERE id IN %s", parameters=[(10,20,30)])
  Instead, this format is advised: conn.execute("SELECT * FROM foo WHERE id = ANY(%s)", parameters=[[10,20,30]])

• You can no longer use IS %s
  This would work with psycopg2 but will not work with psycopg3: conn.execute("SELECT * FROM foo WHERE field IS %s", [None])
  Instead, IS NOT DISTINCT FROM %s should be used conn.execute("SELECT * FROM foo WHERE field IS NOT DISTINCT FROM %s", [None])

• Copy methods are refactored and consolidated in psycopg3, including breaking changes.
  See the migration guide for details.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
parsons/databases
alchemy.py					19-22
parsons/databases/postgres
postgres.py					55
postgres_core.py					40, 49-53, 61-64
parsons/databases/redshift
redshift.py					135-151, 155-157
parsons/utilities
ssh_utilities.py
Project Total

This report was generated by python-coverage-comment-action

[shaunagm]

Psycopg2 was historically the single biggest source of installation issues for Parsons, so I am wary of touching it, especially with known breaking changes, before November. But we can queue this to merge afterwards (once it's ready of course).

[bmos]

Absolutely. That's why I have kept this a draft for now.

I think we need pretty comprehensive testing from people who are already using these features. Especially because the supported queries appear to have changed pretty dramatically in version 3.