Document how to run postgres integration tests

[edublancas]

We need to create a tutorial showing how to run postgres integration tests. It should cover the following:

• instructions to install dependencies (dockerctx, psycopg2, pgspecial<2)
• tips for fixing common errors

e.g., if docker isn't running, I get the following:

docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

• commands to run tests

Note that postgres tests are distributed in two files: test_postgreSQL.py and src/tests/integration/test_generic_db_operations.py, however, the latter contains tests for other databases so the tutorial should demonstrate how to run postgres tests and skip the rest.

Another problem I encountered is that when running postgres tests in the test_generic_db_operations.py, the command gets stuck for ~1 minute if I don't have psycopg2 installed. there seems to be something wrong with our tests since failing to import psycopg2 should be fairly quickly, and the command should exit within a few seconds, so we need to investigate and fix that as well.

We can put this guide in a separate ipynb file, and link from here, to the new tutorial. note that we'll have to exclude the tutorial from execution since readthedocs cannot spin up docker containers.

Take into account that you should automate as much aspects as you can. Ideally, a developer would open your tutorial, run the commands from start to finish, and have all the postgres tests run without having to do any manual modifications to the configuration, or source code. The existing tutorials in the documentation are good examples; however, note that the linked tutorial targets end-users (jupysql users) and this tutorial targets jupysql developers.

When opening the PR, verify that all check in the CI pass. If there are issues, fix them before requesting a review. If in doubt, you can ask for help.

To write the tutorial, you can write a notebook with the bash-kernel

Note: the comments on this issue are locked. If you need to ask questions, please open a draft PR, tag me and ask your questions.