Psycopg is the most popular PostgreSQL database adapter for the Python
programming language. Its main features are the complete implementation of
the Python DB API 2.0 specification and the thread safety (several threads can
share the same connection). It was designed for heavily multi-threaded
applications that create and destroy lots of cursors and make a large number
of concurrent "INSERT"s or "UPDATE"s.
Psycopg 2 is mostly implemented in C as a libpq wrapper, resulting in being
both efficient and secure. It features client-side and server-side cursors,
asynchronous communication and notifications, "COPY TO/COPY FROM" support.
Many Python types are supported out-of-the-box and adapted to matching
PostgreSQL data types; adaptation can be extended and customized thanks to a
flexible objects adaptation system.
Psycopg 2 is both Unicode and Python 3 friendly.
Documentation
-------------
Documentation is included in the ``doc`` directory and is `available online`__.
.. __: https://www.psycopg.org/docs/
For any other resource (source code repository, bug tracker, mailing list)
please check the `project homepage`__.
.. __: https://psycopg.org/
Installation
------------
Building Psycopg requires a few prerequisites (a C compiler, some development
packages): please check the install_ and the faq_ documents in the ``doc`` dir
or online for the details.
If prerequisites are met, you can install psycopg like any other Python
package, using ``pip`` to download it from PyPI_::
$ pip install psycopg2-yugabytedb
or using ``setup.py`` if you have downloaded the source package locally::
$ python setup.py build
$ sudo python setup.py install
Note - The YugabyteDB Psycopg2 requires Postgresql version 11 or above (preferrably 14)
.. _PyPI: https://pypi.org/project/psycopg2-yugabytedb/
.. _install: https://www.psycopg.org/docs/install.html#install-from-source
.. _faq: https://www.psycopg.org/docs/faq.html#faq-compile
:Linux/OSX: |gh-actions|
:Windows: |appveyor|
.. |gh-actions| image:: https://github.com/psycopg/psycopg2/actions/workflows/tests.yml/badge.svg
:target: https://github.com/psycopg/psycopg2/actions/workflows/tests.yml
:alt: Linux and OSX build status
.. |appveyor| image:: https://ci.appveyor.com/api/projects/status/github/psycopg/psycopg2?branch=master&svg=true
:target: https://ci.appveyor.com/project/psycopg/psycopg2/branch/master
:alt: Windows build status
YugabyteDB Psycopg2 Features
============================
Yugabyte Psycopg2 driver is a distributed python driver for YSQL built on the PostgreSQL psycopg2 driver. Although the upstream PostgreSQL psycopg2 driver works with YugabyteDB, the Yugabyte driver enhances YugabyteDB by eliminating the need for external load balancers.
* It is cluster-aware, which eliminates the need for an external load balancer.
* It is topology-aware, which is essential for geographically-distributed applications. The driver uses servers that are part of a set of geo-locations specified by topology keys.
Load balancing
--------------
The Yugabyte Psycopg2 driver has the following load balancing features:
* Uniform load balancing
In this mode, the driver makes the best effort to uniformly distribute the connections to each YugabyteDB server. For example, if a client application creates 100 connections to a YugabyteDB cluster consisting of 10 servers, then the driver creates 10 connections to each server. If the number of connections are not exactly divisible by the number of servers, then a few may have 1 less or 1 more connection than the others. This is the client view of the load, so the servers may not be well balanced if other client applications are not using the Yugabyte JDBC driver.
* Topology-aware load balancing
Because YugabyteDB clusters can have servers in different regions and availability zones, the YugabyteDB JDBC driver is topology-aware, and can be configured to create connections only on servers that are in specific regions and zones. This is useful for client applications that need to connect to the geographically nearest regions and availability zone for lower latency; the driver tries to uniformly load only those servers that belong to the specified regions and zone.
The Yugabyte Psycopg2 driver can be configured with pooling as well.
Usage
-----
Load balancing connection properties:
The following connection properties need to be added to enable load balancing:
* load_balance - enable cluster-aware load balancing by setting this property to true or any; disabled by default. `This section`_ explains the different values for `load_balance` parameter.
* topology_keys - provide comma-separated geo-location values to enable topology-aware load balancing. Geo-locations can be provided as cloud.region.zone.
* yb_servers_refresh_interval - The list of servers, to balance the connection load on, is refreshed periodically every 5 minutes by default. This time can be regulated by this property.
.. _`This section`: #read-replica-cluster
Pass new connection properties for load balancing in the connection URL or in the dictionary. To enable uniform load balancing across all servers, you set the load-balance property to True in the URL, as per the following example.
Connection String::
conn = psycopg2.connect("dbname=database_name host=hostname port=port user=username password=password load_balance=true")
Connection Dictionary::
conn = psycopg2.connect(user = 'username', password='xxx', host = 'hostname', port = 'port', dbname = 'database_name', load_balance='True')
To specify topology keys, you set the topology_keys property to comma separated values, as per the following example.
Connection String::
conn = psycopg2.connect("dbname=database_name host=hostname port=port user=username password=password load_balance=any topology_keys=cloud1.region1.zone1,cloud2.region2.zone2")
Connection Dictionary::
conn = psycopg2.connect(user = 'username', password='xxx', host = 'hostname', port = 'port', dbname = 'database_name', load_balance='any', topology_keys='cloud1.region1.zone1,cloud2.region2.zone2')
Multiple topologies can also be passed to the Topology Keys property, and each of them can also be given a preference value, as per the following example.::
conn = psycopg2.connect("host=127.0.0.1 port=5433 user=yugabyte dbname=yugabyte load_balance=True topology_keys=cloud1.region1.zone1:1,cloud2.region2.zone2:2")
The preference value (appended after :) is optional. So it is compatible with previous syntax of specifying cloud placements.
Preference value :1 means primary placement zone(s), value :2 means first fallback, value :3 means second fallback and so on.
Other Connection Parameters
---------------------------
* fallback_to_topology_keys_only - Applicable only for TopologyAware Load Balancing. When set to true, the smart driver does not attempt to connect to servers outside of primary and fallback placements specified via property. The default behaviour is to fallback to any available server in the entire cluster.(default value: false)
* failed_host_ttl_seconds - The driver marks a server as failed with a timestamp, when it cannot connect to it. Later, whenever it refreshes the server list via yb_servers(), if it sees the failed server in the response, it marks the server as UP only if failed_host_ttl_seconds time has elapsed. (The yb_servers() function does not remove a failed server immediately from its result and retains it for a while.)(default value: 5 seconds)
Read Replica Cluster
--------------------
psycopg2 smart driver also enables load balancing across nodes in primary clusters which have associated Read Replica cluster.
The connection property `load_balance` allows five values using which users can distribute connections among different combination of nodes as per their requirements:
- `only-rr` - Create connections only on Read Replica nodes
- `only-primary` - Create connections only on primary cluster nodes
- `prefer-rr` - Create connections on Read Replica nodes. If none available, on any node in the cluster including primary cluster nodes
- `prefer-primary` - Create connections on primary cluster nodes. If none available, on any node in the cluster including Read Replica nodes
- `any` or `true` - Equivalent to value true. Create connections on any node in the primary or Read Replica cluster
default value is false
Raw data
{
"_id": null,
"home_page": "https://psycopg.org/",
"name": "psycopg2-yugabytedb",
"maintainer": "Sfurti Sarah",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "ssarah@yugabyte.com",
"keywords": null,
"author": "Yugabyte",
"author_email": "pypi@yugabyte.com",
"download_url": "https://files.pythonhosted.org/packages/2a/e3/ebf88ac527b9bbc75c0e4bd35dab3fb0582267695284792b56427e65ae85/psycopg2_yugabytedb-2.9.3.4.tar.gz",
"platform": "any",
"description": "Psycopg is the most popular PostgreSQL database adapter for the Python\nprogramming language. Its main features are the complete implementation of\nthe Python DB API 2.0 specification and the thread safety (several threads can\nshare the same connection). It was designed for heavily multi-threaded\napplications that create and destroy lots of cursors and make a large number\nof concurrent \"INSERT\"s or \"UPDATE\"s.\n\nPsycopg 2 is mostly implemented in C as a libpq wrapper, resulting in being\nboth efficient and secure. It features client-side and server-side cursors,\nasynchronous communication and notifications, \"COPY TO/COPY FROM\" support.\nMany Python types are supported out-of-the-box and adapted to matching\nPostgreSQL data types; adaptation can be extended and customized thanks to a\nflexible objects adaptation system.\n\nPsycopg 2 is both Unicode and Python 3 friendly.\n\n\nDocumentation\n-------------\n\nDocumentation is included in the ``doc`` directory and is `available online`__.\n\n.. __: https://www.psycopg.org/docs/\n\nFor any other resource (source code repository, bug tracker, mailing list)\nplease check the `project homepage`__.\n\n.. __: https://psycopg.org/\n\n\nInstallation\n------------\n\nBuilding Psycopg requires a few prerequisites (a C compiler, some development\npackages): please check the install_ and the faq_ documents in the ``doc`` dir\nor online for the details.\n\nIf prerequisites are met, you can install psycopg like any other Python\npackage, using ``pip`` to download it from PyPI_::\n\n $ pip install psycopg2-yugabytedb\n\nor using ``setup.py`` if you have downloaded the source package locally::\n\n $ python setup.py build\n $ sudo python setup.py install\n\nNote - The YugabyteDB Psycopg2 requires Postgresql version 11 or above (preferrably 14)\n\n.. _PyPI: https://pypi.org/project/psycopg2-yugabytedb/\n.. _install: https://www.psycopg.org/docs/install.html#install-from-source\n.. _faq: https://www.psycopg.org/docs/faq.html#faq-compile\n\n:Linux/OSX: |gh-actions|\n:Windows: |appveyor|\n\n.. |gh-actions| image:: https://github.com/psycopg/psycopg2/actions/workflows/tests.yml/badge.svg\n :target: https://github.com/psycopg/psycopg2/actions/workflows/tests.yml\n :alt: Linux and OSX build status\n\n.. |appveyor| image:: https://ci.appveyor.com/api/projects/status/github/psycopg/psycopg2?branch=master&svg=true\n :target: https://ci.appveyor.com/project/psycopg/psycopg2/branch/master\n :alt: Windows build status\n\nYugabyteDB Psycopg2 Features\n============================\n\nYugabyte Psycopg2 driver is a distributed python driver for YSQL built on the PostgreSQL psycopg2 driver. Although the upstream PostgreSQL psycopg2 driver works with YugabyteDB, the Yugabyte driver enhances YugabyteDB by eliminating the need for external load balancers.\n\n* It is cluster-aware, which eliminates the need for an external load balancer.\n* It is topology-aware, which is essential for geographically-distributed applications. The driver uses servers that are part of a set of geo-locations specified by topology keys.\n\nLoad balancing\n--------------\n\nThe Yugabyte Psycopg2 driver has the following load balancing features:\n\n* Uniform load balancing\n\nIn this mode, the driver makes the best effort to uniformly distribute the connections to each YugabyteDB server. For example, if a client application creates 100 connections to a YugabyteDB cluster consisting of 10 servers, then the driver creates 10 connections to each server. If the number of connections are not exactly divisible by the number of servers, then a few may have 1 less or 1 more connection than the others. This is the client view of the load, so the servers may not be well balanced if other client applications are not using the Yugabyte JDBC driver.\n\n* Topology-aware load balancing\n\nBecause YugabyteDB clusters can have servers in different regions and availability zones, the YugabyteDB JDBC driver is topology-aware, and can be configured to create connections only on servers that are in specific regions and zones. This is useful for client applications that need to connect to the geographically nearest regions and availability zone for lower latency; the driver tries to uniformly load only those servers that belong to the specified regions and zone.\nThe Yugabyte Psycopg2 driver can be configured with pooling as well.\n\nUsage\n-----\n\nLoad balancing connection properties:\n\nThe following connection properties need to be added to enable load balancing:\n\n* load_balance - enable cluster-aware load balancing by setting this property to true or any; disabled by default. `This section`_ explains the different values for `load_balance` parameter.\n* topology_keys - provide comma-separated geo-location values to enable topology-aware load balancing. Geo-locations can be provided as cloud.region.zone.\n* yb_servers_refresh_interval - The list of servers, to balance the connection load on, is refreshed periodically every 5 minutes by default. This time can be regulated by this property.\n\n.. _`This section`: #read-replica-cluster\n\nPass new connection properties for load balancing in the connection URL or in the dictionary. To enable uniform load balancing across all servers, you set the load-balance property to True in the URL, as per the following example.\n\nConnection String::\n\n conn = psycopg2.connect(\"dbname=database_name host=hostname port=port user=username password=password load_balance=true\")\n\nConnection Dictionary::\n\n conn = psycopg2.connect(user = 'username', password='xxx', host = 'hostname', port = 'port', dbname = 'database_name', load_balance='True')\n\nTo specify topology keys, you set the topology_keys property to comma separated values, as per the following example.\n\nConnection String::\n\n conn = psycopg2.connect(\"dbname=database_name host=hostname port=port user=username password=password load_balance=any topology_keys=cloud1.region1.zone1,cloud2.region2.zone2\")\n\nConnection Dictionary::\n\n conn = psycopg2.connect(user = 'username', password='xxx', host = 'hostname', port = 'port', dbname = 'database_name', load_balance='any', topology_keys='cloud1.region1.zone1,cloud2.region2.zone2')\n\nMultiple topologies can also be passed to the Topology Keys property, and each of them can also be given a preference value, as per the following example.::\n\n conn = psycopg2.connect(\"host=127.0.0.1 port=5433 user=yugabyte dbname=yugabyte load_balance=True topology_keys=cloud1.region1.zone1:1,cloud2.region2.zone2:2\")\n\nThe preference value (appended after :) is optional. So it is compatible with previous syntax of specifying cloud placements.\n\nPreference value :1 means primary placement zone(s), value :2 means first fallback, value :3 means second fallback and so on.\n\nOther Connection Parameters\n---------------------------\n\n* fallback_to_topology_keys_only - Applicable only for TopologyAware Load Balancing. When set to true, the smart driver does not attempt to connect to servers outside of primary and fallback placements specified via property. The default behaviour is to fallback to any available server in the entire cluster.(default value: false)\n\n* failed_host_ttl_seconds - The driver marks a server as failed with a timestamp, when it cannot connect to it. Later, whenever it refreshes the server list via yb_servers(), if it sees the failed server in the response, it marks the server as UP only if failed_host_ttl_seconds time has elapsed. (The yb_servers() function does not remove a failed server immediately from its result and retains it for a while.)(default value: 5 seconds)\n\nRead Replica Cluster\n--------------------\n\npsycopg2 smart driver also enables load balancing across nodes in primary clusters which have associated Read Replica cluster.\n\nThe connection property `load_balance` allows five values using which users can distribute connections among different combination of nodes as per their requirements:\n\n- `only-rr` - Create connections only on Read Replica nodes\n- `only-primary` - Create connections only on primary cluster nodes\n- `prefer-rr` - Create connections on Read Replica nodes. If none available, on any node in the cluster including primary cluster nodes\n- `prefer-primary` - Create connections on primary cluster nodes. If none available, on any node in the cluster including Read Replica nodes\n- `any` or `true` - Equivalent to value true. Create connections on any node in the primary or Read Replica cluster\n\ndefault value is false\n",
"bugtrack_url": null,
"license": "LGPL with exceptions",
"summary": "psycopg2 - Python-PostgreSQL Database Adapter",
"version": "2.9.3.4",
"project_urls": {
"Code": "https://github.com/yugabyte/psycopg2",
"Documentation": "https://www.psycopg.org/docs/",
"Download": "https://pypi.org/project/psycopg2-yugabytedb/",
"Homepage": "https://psycopg.org/",
"Issue Tracker": "https://github.com/psycopg/psycopg2/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "37c125c52a9eaf55bc6896300dd857aa9a78ca374bdf0424acde582c25fd3b03",
"md5": "760e201019e11d6fb36a702d9ca9dafc",
"sha256": "b97776bfdc78510e6533d403e8d4b7a195ca78f80aa2f6726d1152b507a13409"
},
"downloads": -1,
"filename": "psycopg2_yugabytedb-2.9.3.4-cp312-cp312-macosx_13_0_arm64.whl",
"has_sig": false,
"md5_digest": "760e201019e11d6fb36a702d9ca9dafc",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.6",
"size": 153211,
"upload_time": "2024-11-22T13:00:48",
"upload_time_iso_8601": "2024-11-22T13:00:48.183563Z",
"url": "https://files.pythonhosted.org/packages/37/c1/25c52a9eaf55bc6896300dd857aa9a78ca374bdf0424acde582c25fd3b03/psycopg2_yugabytedb-2.9.3.4-cp312-cp312-macosx_13_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ae3ebf88ac527b9bbc75c0e4bd35dab3fb0582267695284792b56427e65ae85",
"md5": "c436684c7467f8fc0ee662222460cfe8",
"sha256": "acfe2c72f9da84b322d72e28c0f1bd27df239932eff58669f06b9048748c4e23"
},
"downloads": -1,
"filename": "psycopg2_yugabytedb-2.9.3.4.tar.gz",
"has_sig": false,
"md5_digest": "c436684c7467f8fc0ee662222460cfe8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 396986,
"upload_time": "2024-11-22T12:23:37",
"upload_time_iso_8601": "2024-11-22T12:23:37.943923Z",
"url": "https://files.pythonhosted.org/packages/2a/e3/ebf88ac527b9bbc75c0e4bd35dab3fb0582267695284792b56427e65ae85/psycopg2_yugabytedb-2.9.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 12:23:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yugabyte",
"github_project": "psycopg2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "psycopg2-yugabytedb"
}
JSON
