Skip to content
Back to top

# How to make a psycopg release

- Check if there is a new version or libpq or OpenSSL; in such case update `LIBPQ_VERSION` and/or `OPENSSL_VERSION` in `.github/workflows/packages-bin.yml`.

- Check if there is a new cibuildwheel release; if so, upgrade it in `.github/workflows/packages-bin.yml`.

- Use `tools/bump_version.py` to upgrade package version numbers.

- Push to GitHub to run the tests workflow.

- Build the packages by triggering manually the ones requested among:

  - Source packages

  - Binary packages

  - Pool packages

- Delete the `wheelhouse` directory if there is one.

- If all packages were built ok, push the new tag created by `bump_version.py`:

      git push --tags

- Download the `artifacts.zip` package from the last Packages workflow run.

- Unpack the packages in the wheelhouse dir:

      mkdir -p wheelhouse
      cd wheelhouse
      unzip ~/Downloads/artifact.zip

- If the package is a testing one, upload it on TestPyPI with:

      $ twine upload -r testpypi *

- If the package is stable, omit `-r testpypi`:

      $ twine upload *

- Run `tools/bump_version.py -l dev` to bump to the next dev version.

## When a new PostgreSQL major version is released

- Add the new version to `tools/update_errors.py` and run the script to add new error classes.

- If the script above found any change, document the version added at the bottom of `docs/api/errors.rst`.

- Run the script `tools/update_oids.py` to add new oids. Use `-h` to get an example docker command line to run a server locally.

- Check if there are new enum values to include in:

  - `psycopg_c/psycopg_c/pq/libpq.pxd`;

  - `psycopg/psycopg/pq/_enums.py`.

- Include the new version in GitHub Actions test and package grids.

- Bump `PG_VERSION` in the `macos` job of

  - `.github/workflows/packages-bin.yml`.

  - `.github/workflows/tests.yml`.

- Update the documented versions in:

  - `docs/basic/install.rst`;

  - `content/features/contents.lr` in the psycopg-website repository.

### Adding new libpq wrapper methods

The `psycopg.pq` module is a thin wrapper around the libpq, only doing the minimal work to make the library somewhat Pythonic (e.g. converting types and raising exceptions instead of returning error values).

When new functionalities are added to the libpq we often want to expose them to Python (either to allow Python users to use them directly or to build new features on top of them). The procedure touches several files, in order to add function wrappers to both the Python and the C implementation of the libpq, to the objects interfaces and every object implementing them, and eventually to bubble up to some Python object.

It is polite to add new top-level objects interfaces (such as `connection.info` or `Capabilities` only on minor releases (3.x), but if we need to add a libpq function wrapper to solve an issue we can do it in a bugfix release, without documenting it (e.g. `PQconnectionUsedGSSAPI` was added in 3.2.10 but only advertised in 3.3).

You can use PR 1140 as a reference for the work to do (code, tests, documentation). In this MR, the changes in the first commit are suitable to introduce a new function in a bugfix release, the second commit changes make the new functionality public.

## When a new Python major version is released

- Add the new version to the relevant test matrices in `.github/workflows/tests.yml` and `.github/workflows/packages-bin.yml`.

- Update `docs/basic/install.rst` with the correct range of supported Python versions.

- Add the `Programming Language :: Python :: 3.<X>` classifier to `psycopg/pyproject.toml`, `psycopg_c/pyproject.toml`, and `psycopg_pool/pyproject.toml`.

## When dropping end-of-life Python versions

- Update project metadata, `requires-python` and (maybe) package dependencies in `pyproject.toml` files of the corresponding `psycopg` directories.

- Update GitHub Actions workflow files in the `.github/workflows/` directory, e.g., `tests.yml`, `.3rd-party-tests.yml`, `packages-bin.yml`.

- Bump versions in the `tests/constraints.txt` file if it is necessary.

- bump `build-system.requires` in `*/pyproject.toml`. Install the packages with `pip install ./psycopg*/` and check eventual warnings.

- You may grep throughout the project for occurrences of a version to be dropped. However, favouring smaller pull requests is convenient and easy to review. An example for grepping `end-of-life` Python 3.8:

      git grep -E -e '\b3\.8\b' -e '\b(cp)?38\b' -e '\b3, 8\b'
      git grep -E -e '\b3\.9\b' -e '\b(cp)?39\b' -e '\b3, 9\b'

- Consider using pyupgrade with `--py3NN-plus` in order to refresh syntax to Python 3.NN (the new minimum supported version).

Examples:

- PR #977