Metadata-Version: 2.4
Name: psycopg-yugabytedb
Version: 3.3.4.1rc1
Summary: YugabyteDB smart-driver fork of psycopg 3 — adds cluster-aware and topology-aware load balancing
Author-email: Daniele Varrazzo <daniele.varrazzo@gmail.com>, Yugabyte <support@yugabyte.com>
License-Expression: LGPL-3.0-only
Project-URL: Homepage, https://www.yugabyte.com/
Project-URL: Documentation, https://docs.yugabyte.com/preview/drivers-orms/python/
Project-URL: Upstream psycopg, https://psycopg.org/
Project-URL: Code, https://github.com/yugabyte/psycopg-yugabytedb
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Database
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: typing-extensions>=4.6; python_version < "3.13"
Requires-Dist: tzdata; sys_platform == "win32"
Provides-Extra: c
Requires-Dist: psycopg-yugabytedb-c==3.3.4.1rc1; implementation_name != "pypy" and extra == "c"
Provides-Extra: binary
Requires-Dist: psycopg-yugabytedb-binary==3.3.4.1rc1; implementation_name != "pypy" and extra == "binary"
Provides-Extra: pool
Requires-Dist: psycopg-pool; extra == "pool"
Provides-Extra: test
Requires-Dist: anyio>=4.0; extra == "test"
Requires-Dist: mypy>=1.19.0; implementation_name != "pypy" and extra == "test"
Requires-Dist: pproxy>=2.7; extra == "test"
Requires-Dist: pytest>=6.2.5; extra == "test"
Requires-Dist: pytest-cov>=3.0; extra == "test"
Requires-Dist: pytest-randomly>=3.5; extra == "test"
Provides-Extra: dev
Requires-Dist: ast-comments>=1.1.2; extra == "dev"
Requires-Dist: black>=26.1.0; extra == "dev"
Requires-Dist: codespell>=2.2; extra == "dev"
Requires-Dist: cython-lint>=0.16; extra == "dev"
Requires-Dist: dnspython>=2.1; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: isort[colors]>=6.0; extra == "dev"
Requires-Dist: isort-psycopg; extra == "dev"
Requires-Dist: mypy>=1.19.0; extra == "dev"
Requires-Dist: pre-commit>=4.0.1; extra == "dev"
Requires-Dist: types-setuptools>=57.4; extra == "dev"
Requires-Dist: types-shapely>=2.0; extra == "dev"
Requires-Dist: wheel>=0.37; extra == "dev"
Provides-Extra: docs
Requires-Dist: Sphinx>=9.1; extra == "docs"
Requires-Dist: furo==2025.12.19; extra == "docs"
Requires-Dist: sphinx-autobuild>=2025.8.25; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=3.10.2; extra == "docs"
Dynamic: license-file

YugabyteDB Psycopg 3: Database adapter for Python
=================================================

Psycopg 3 is a modern implementation of a PostgreSQL adapter for Python.
This is the YugabyteDB smart-driver fork, distributed as ``psycopg-yugabytedb``.

This distribution contains the pure Python package ``psycopg``.

.. Note::

    Despite the lack of number in the package name, this package is the
    successor of psycopg2_.

    Please use the psycopg2 package if you are maintaining an existing program
    using psycopg2 as a dependency. If you are developing something new,
    Psycopg 3 is the most current implementation of the adapter.

    .. _psycopg2: https://pypi.org/project/psycopg2/


YugabyteDB smart driver
-----------------------

This fork (distribution name ``psycopg-yugabytedb``) extends psycopg 3 with
cluster-aware and topology-aware connection load balancing for `YugabyteDB`_.
The import name stays ``psycopg`` — existing code is unchanged. Adding
``load_balance_hosts=true`` to the conninfo string opts into the smart driver.

.. _YugabyteDB: https://www.yugabyte.com/

Opt in with one parameter:

.. code-block:: python

    import psycopg

    conn = psycopg.connect(
        "host=h1,h2,h3 port=5433 user=yugabyte dbname=yugabyte "
        "load_balance_hosts=true"
    )

The driver discovers every live tserver via ``yb_servers()`` on the first
connect, then distributes subsequent connects across them with a least-loaded
picker (random tie-break, atomic under a per-cluster lock). One contact point
in ``host=…`` is enough to bootstrap; the rest of the cluster is discovered.

Smart-driver conninfo parameters:

.. list-table::
   :header-rows: 1
   :widths: 30 14 12 44

   * - Parameter
     - Values
     - Default
     - Description
   * - ``load_balance_hosts``
     - ``true`` / ``false`` /
       ``disable`` / ``random``
     - absent
     - ``true`` enables the smart driver. ``false`` is equivalent to libpq's
       ``disable``. ``disable`` / ``random`` pass through to libpq unchanged.
   * - ``topology_keys``
     - ``cloud.region.zone``
       (comma-separated for
       multiple keys)
     - none
     - Restrict picks to tservers matching at least one placement. Zone may
       be ``*`` for any zone in that cloud/region. Cloud / region wildcards
       are rejected. Strict in v1 — no cluster-wide fallback if all
       matching nodes are down.
   * - ``yb_servers_refresh_interval``
     - seconds (integer)
     - ``300``
     - How often to re-query ``yb_servers()``. Clamped to ``[0, 600]``.
   * - ``failed_host_reconnect_delay_secs``
     - seconds (integer)
     - ``5``
     - How long to quarantine a node after a failed connect, before
       reconsidering it. Clamped to ``[0, 60]``.

Topology-aware example — bind traffic to one zone:

.. code-block:: python

    conn = psycopg.connect(
        "host=h1,h2,h3 port=5433 user=yugabyte dbname=yugabyte "
        "load_balance_hosts=true "
        "topology_keys=cloud1.datacenter1.zoneA"
    )

The upstream ``psycopg-pool`` connection pool works unchanged with the smart
driver — the dispatcher sits underneath the pool, so pool-managed connections
honour the configured policy too.

The fork is `pre-release`_. Install with ``pip install --pre psycopg-yugabytedb``
or pin to ``3.3.4.1rc1``. It cannot coexist with upstream ``psycopg`` in the
same environment (both install into ``site-packages/psycopg/``).

.. _pre-release: https://packaging.python.org/en/latest/specifications/version-specifiers/#pre-releases


Installation
------------

In short, run the following::

    pip install --upgrade pip           # to upgrade pip
    pip install "psycopg[binary,pool]"  # to install package and dependencies

If something goes wrong, and for more information about installation, please
check out the `Installation documentation`__.

.. __: https://www.psycopg.org/psycopg3/docs/basic/install.html#


Hacking
-------

For development information check out `the project readme`__.

.. __: https://github.com/psycopg/psycopg#readme


Copyright (C) 2020 The Psycopg Team
