### Build and Install Psycopg2 from Source

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/install.rst

Compile and install psycopg2 from its source code. This involves running build and install commands.

```console
$ python setup.py build
$ python setup.py install
```

--------------------------------

### Install psycopg2 from source

Source: https://github.com/psycopg/psycopg2/blob/master/README.rst

Build and install psycopg2 from a downloaded source package. This method requires build prerequisites.

```bash
$ python setup.py build
$ sudo python setup.py install
```

--------------------------------

### Build Environment for Psycopg Documentation

Source: https://github.com/psycopg/psycopg2/blob/master/doc/README.rst

Creates the virtual environment required for building the documentation. Ensure you have the same prerequisites as installing from source.

```bash
make env
```

--------------------------------

### Install psycopg2-binary using pip

Source: https://github.com/psycopg/psycopg2/blob/master/README.rst

Install the psycopg2-binary package from PyPI using pip. This package does not require a compiler or external libraries.

```bash
$ pip install psycopg2-binary
```

--------------------------------

### Import and use Psycopg2

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/install.rst

Demonstrates basic usage after installation, including connecting to a database, opening a cursor, executing a query, and fetching results.

```python
import psycopg2

# Connect to your postgres DB
conn = psycopg2.connect("dbname=test user=postgres")

# Open a cursor to perform database operations
cur = conn.cursor()

# Execute a query
cur.execute("SELECT * FROM my_data")

# Retrieve query results
records = cur.fetchall()
```

--------------------------------

### Install psycopg2 using pip

Source: https://github.com/psycopg/psycopg2/blob/master/README.rst

Install the psycopg2 package from PyPI using pip. This is the standard method for installing Python packages.

```bash
$ pip install psycopg2
```

--------------------------------

### Basic Psycopg2 Usage Example

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Demonstrates the core workflow of connecting to a database, creating a table, inserting data, querying, committing changes, and closing the connection.

```python
>>> import psycopg2

# Connect to an existing database
>>> conn = psycopg2.connect("dbname=test user=postgres")

# Open a cursor to perform database operations
>>> cur = conn.cursor()

# Execute a command: this creates a new table
>>> cur.execute("CREATE TABLE test (id serial PRIMARY KEY, num integer, data varchar);")

# Pass data to fill a query placeholders and let Psycopg perform
# the correct conversion (no more SQL injections!)
>>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)",
...      (100, "abc'def"))

# Query the database and obtain data as Python objects
>>> cur.execute("SELECT * FROM test;")
>>> cur.fetchone()
(1, 100, "abc'def")

# Make the changes to the database persistent
>>> conn.commit()

# Close communication with the database
>>> cur.close()
>>> conn.close()
```

--------------------------------

### Example DB API 2.0 Connection Constructor

Source: https://github.com/psycopg/psycopg2/blob/master/doc/pep-0249.txt

Illustrates the recommended order and usage of keyword parameters for the connect constructor, including dsn, user, and password.

```python
connect(dsn='myhost:MYDB',user='guido',password='234$')
```

--------------------------------

### start_replication_expert

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Starts a replication stream on the connection using a provided command. It allows for decoding messages and setting a feedback interval to the server.

```APIDOC
## start_replication_expert(command, decode=False, status_interval=10)

### Description
Start replication on the connection using provided |START_REPLICATION|_ command.

### Parameters
#### Parameters
- **command**: The full replication command. It can be a string or a `~psycopg2.sql.Composable` instance for dynamic generation.
- **decode** (bool): a flag indicating that unicode conversion should be performed on messages received from the server.
- **status_interval** (float): time between feedback packets sent to the server. Defaults to 10.

.. versionchanged:: 2.8.3
    added the *status_interval* parameter.
```

--------------------------------

### connection.tpc_prepare

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Performs the first phase of a transaction started with ~connection.tpc_begin(). A ~psycopg2.ProgrammingError is raised if this method is used outside of a TPC transaction.

```APIDOC
## connection.tpc_prepare()

### Description
Performs the first phase of a transaction started with `~connection.tpc_begin()`. A `~psycopg2.ProgrammingError` is raised if this method is used outside of a TPC transaction.

After calling `!tpc_prepare()`, no statements can be executed until `~connection.tpc_commit()` or `~connection.tpc_rollback()` will be called. The `~connection.reset()` method can be used to restore the status of the connection to `~psycopg2.extensions.STATUS_READY`: the transaction will remain prepared in the database and will be possible to finish it with `!tpc_commit(xid)` and `!tpc_rollback(xid)`.

See also: the |PREPARE TRANSACTION|_ PostgreSQL command.
```

--------------------------------

### Example of Binary adapter

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

The Binary adapter is for binary objects. It performs the same escaping as QuotedString and also escapes non-printable characters.

```python
>>> Binary("\x00\x08\x0F").getquoted()
"'\\000\\010\\017'"
```

--------------------------------

### ReplicationCursor.start_replication

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Initiates streaming replication on the connection. It can use a named slot or start from a specified LSN and timeline.

```APIDOC
## ReplicationCursor.start_replication

### Description
Starts streaming replication on the connection. It can be configured to use a specific replication slot, start from a given LSN and timeline, and includes options for logical replication and status updates.

### Method
`start_replication(slot_name=None, slot_type=None, start_lsn=0, timeline=0, options=None, decode=False, status_interval=10)`

### Parameters
* **slot_name** (string) - Optional - The name of the replication slot to use. Required for logical replication.
* **slot_type** (string) - Optional - The type of replication: `REPLICATION_LOGICAL` or `REPLICATION_PHYSICAL`.
* **start_lsn** (integer or string) - Optional - The LSN position to start replicating from (e.g., 'XXX/XXX'). Defaults to 0.
* **timeline** (integer) - Optional - The WAL history timeline to start streaming from (only for physical replication).
* **options** (dict) - Optional - A dictionary of options for logical replication slots.
* **decode** (boolean) - Optional - If True, perform unicode conversion on received messages. Defaults to False.
* **status_interval** (integer) - Optional - Time in seconds between feedback packets sent to the server. Defaults to 10.

### Notes
* If `slot_name` is specified, it must exist and match the `slot_type`.
* If `slot_type` is not specified, it's inferred from the connection type.
* Logical replication requires a `slot_name` and is available from PostgreSQL 9.4.
* Physical replication can be used with or without a `slot_name` and is available from PostgreSQL 9.0.
* Specifying `start_lsn` allows resuming replication from a specific point.
* The server may adjust the starting position if the WAL file has been recycled.
```

--------------------------------

### Custom Adapter for Infinite Date Handling

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Provides an example of creating a custom adapter to map Python's date.max/min to PostgreSQL's 'infinity' and '-infinity' representations.

```python
import datetime
import psycopg2
import psycopg2.extensions

class InfDateAdapter:
    def __init__(self, wrapped):
        self.wrapped = wrapped
    def getquoted(self):
        if self.wrapped == datetime.date.max:
            return b"'infinity'::date"
        elif self.wrapped == datetime.date.min:
            return b"'-infinity'::date"
        else:
            return psycopg2.extensions.DateFromPy(self.wrapped).getquoted()

psycopg2.extensions.register_adapter(datetime.date, InfDateAdapter)

```

--------------------------------

### Subclassing Cursor for Logging

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/advanced.rst

This example demonstrates how to subclass `psycopg2.extensions.cursor` to add logging before and after query execution. It logs the SQL statement and arguments, and any exceptions raised during execution.

```python
import psycopg2
import psycopg2.extensions
import logging

class LoggingCursor(psycopg2.extensions.cursor):
    def execute(self, sql, args=None):
        logger = logging.getLogger('sql_debug')
        logger.info(self.mogrify(sql, args))

        try:
            psycopg2.extensions.cursor.execute(self, sql, args)
        except Exception, exc:
            logger.error("%s: %s" % (exc.__class__.__name__, exc))
            raise

conn = psycopg2.connect(DSN)
cur = conn.cursor(cursor_factory=LoggingCursor)
cur.execute("INSERT INTO mytable VALUES (%s, %s, %s);",
             (10, 20, 30))
```

--------------------------------

### Start Replication Stream

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Initiates the replication stream. You can specify a slot name, replication type, starting LSN, timeline, logical decoding options, and whether to decode unicode.

```python
cur.start_replication(slot_name="slot1", decode=True, status_interval=5)
```

--------------------------------

### Example of AsIs adapter

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

The AsIs adapter is useful for objects whose string representation is already valid as SQL. It returns the string representation of the wrapped object.

```python
>>> AsIs(42).getquoted()
'42'
```

--------------------------------

### Run Psycopg2 Test Suite

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/install.rst

Execute the Psycopg2 test suite from the source directory to verify the installation. This command runs the main test suite using Python.

```console
$ python -c "import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose
```

--------------------------------

### Asynchronous Replication Message Consumption Example

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Demonstrates how to continuously read and process replication messages asynchronously. It includes sending feedback after processing data and handling server keepalive requests.

```python
from select import select
from datetime import datetime

def consume(msg):
    # ...
    msg.cursor.send_feedback(flush_lsn=msg.data_start)

status_interval = 10.0
while True:
    msg = cur.read_message()
    if msg:
        consume(msg)
    else:
        now = datetime.now()
```

--------------------------------

### Register Default JSON/JSONB Adaptation with UltraJSON

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Use `register_default_json()` and `register_default_jsonb()` with `ujson.loads` for faster JSON parsing globally. Ensure UltraJSON is installed.

```python
psycopg2.extras.register_default_json(loads=ujson.loads, globally=True)
psycopg2.extras.register_default_jsonb(loads=ujson.loads, globally=True)
```

--------------------------------

### Python Logical Replication Consumer

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/advanced.rst

This Python code demonstrates how to connect to a PostgreSQL database using Psycopg2 for logical replication. It sets up a replication slot, starts streaming, and defines a consumer class to process incoming messages and send feedback. It includes error handling for slot creation and graceful shutdown.

```python
from __future__ import print_function
import sys
import psycopg2
import psycopg2.extras

conn = psycopg2.connect('dbname=psycopg2_test user=postgres',
   connection_factory=psycopg2.extras.LogicalReplicationConnection)
cur = conn.cursor()
try:
    # test_decoding produces textual output
    cur.start_replication(slot_name='pytest', decode=True)
except psycopg2.ProgrammingError:
    cur.create_replication_slot('pytest', output_plugin='test_decoding')
    cur.start_replication(slot_name='pytest', decode=True)

class DemoConsumer(object):
    def __call__(self, msg):
        print(msg.payload)
        msg.cursor.send_feedback(flush_lsn=msg.data_start)

democonsumer = DemoConsumer()

print("Starting streaming, press Control-C to end...", file=sys.stderr)
try:
   cur.consume_stream(democonsumer)
except KeyboardInterrupt:
   cur.close()
   conn.close()
   print("The slot 'pytest' still exists. Drop it with "
      "SELECT pg_drop_replication_slot('pytest'); if no longer needed.", file=sys.stderr)
   print("WARNING: Transaction logs will accumulate in pg_xlog "
      "until the slot is dropped.", file=sys.stderr)
```

--------------------------------

### Insert Unicode Data

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Demonstrates inserting Unicode data into a PostgreSQL table using a cursor. This example assumes a connection and cursor are already established.

```python
>>> print(u, type(u))
àèìòù€ <type 'unicode'>

>>> cur.execute("INSERT INTO test (num, data) VALUES (%s,%s);", (74, u))
```

--------------------------------

### Consume Logical Replication Stream

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Example of a callable class to process logical replication messages and send feedback. Ensure to call `send_feedback` on the cursor associated with the message.

```python
class LogicalStreamConsumer(object):

    # ...

    def __call__(self, msg):
        self.process_message(msg.payload)
        msg.cursor.send_feedback(flush_lsn=msg.data_start)

consumer = LogicalStreamConsumer()
cur.consume_stream(consumer)
```

--------------------------------

### Registering a Wait Callback for Coroutine Support

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/advanced.rst

This example demonstrates how to implement and register a wait callback function for Psycopg to enable cooperative multithreading with coroutine libraries. It uses `select.select` to wait for socket events.

```python
def wait_select(conn):
    while True:
        state = conn.poll()
        if state == extensions.POLL_OK:
            break
        elif state == extensions.POLL_READ:
            select.select([conn.fileno()], [], [])
        elif state == extensions.POLL_WRITE:
            select.select([], [conn.fileno()], [])
        else:
            raise OperationalError("bad state from poll: %s" % state)
```

--------------------------------

### Connect using a connection string

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/module.rst

Establish a database connection using a libpq connection string. Ensure the string contains necessary parameters like dbname, user, and password.

```python
conn = psycopg2.connect("dbname=test user=postgres password=secret")
```

--------------------------------

### get_dsn_parameters()

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Gets the effective DSN parameters for the connection as a dictionary.

```APIDOC
## get_dsn_parameters()

### Description
Gets the effective DSN parameters for the connection as a dictionary. The `password` parameter is removed from the result. Requires libpq >= 9.3.

### Method
`connection.get_dsn_parameters()`

### Parameters
None

### Response
- **dsn_parameters** (dict) - A dictionary containing the DSN parameters for the connection (e.g., {'dbname': 'test', 'user': 'postgres', 'port': '5432', 'sslmode': 'prefer'}).
```

--------------------------------

### Build Psycopg Documentation

Source: https://github.com/psycopg/psycopg2/blob/master/doc/README.rst

Builds the rendered documentation after the environment is set up. The output will be in the 'html' directory.

```bash
make
```

--------------------------------

### Get Transaction Status

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Retrieves the current session transaction status as an integer. Symbolic constants are available in psycopg2.extensions.

```python
conn.get_transaction_status()
```

--------------------------------

### Opening a Logical Replication Connection

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Shows how to establish a connection specifically for logical replication using LogicalReplicationConnection.

```python
from psycopg2.extras import LogicalReplicationConnection
log_conn = psycopg2.connect(dsn, connection_factory=LogicalReplicationConnection)
log_cur = log_conn.cursor()
```

--------------------------------

### Connect using keyword arguments

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/module.rst

Establish a database connection by providing parameters as keyword arguments. This method is an alternative to using a connection string.

```python
conn = psycopg2.connect(dbname="test", user="postgres", password="secret")
```

--------------------------------

### connection.rollback

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Rolls back to the start of any pending transaction. If the connection is used in a 'with' statement, this is called automatically if an exception is raised.

```APIDOC
## connection.rollback

### Description
Roll back to the start of any pending transaction. Closing a connection without committing the changes first will cause an implicit rollback to be performed.

### Method
rollback()

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Opening a Physical Replication Connection

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Demonstrates how to establish a connection for physical replication using PhysicalReplicationConnection. Both replication connection types use ReplicationCursor.

```python
from psycopg2.extras import PhysicalReplicationConnection
phys_conn = psycopg2.connect(dsn, connection_factory=PhysicalReplicationConnection)
phys_cur = phys_conn.cursor()
```

--------------------------------

### Get Server Parameter Status

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Looks up a current parameter setting of the server. Returns None if the server did not report the requested parameter.

```python
conn.get_parameter_status('server_encoding')
```

--------------------------------

### Interacting with libpq using ctypes

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Demonstrates how to access the internal PGconn pointer and use it with ctypes to call libpq functions, such as retrieving the server version.

```python
import ctypes
import ctypes.util
libpq = ctypes.pydll.LoadLibrary(ctypes.util.find_library('pq'))
libpq.PQserverVersion.argtypes = [ctypes.c_void_p]
libpq.PQserverVersion.restype = ctypes.c_int
libpq.PQserverVersion(conn.pgconn_ptr)
```

--------------------------------

### Creating a Connection String

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Constructs a valid connection string from keyword arguments, merging them with an existing DSN if provided. Keyword arguments override values from the DSN.

```python
psycopg2.extensions.make_dsn(dsn=None, **kwargs)
```

--------------------------------

### Set Isolation Level to Autocommit

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Set the connection's isolation level to autocommit. This mode does not start transactions and bypasses commit/rollback requirements.

```python
from psycopg2.extensions import ISOLATION_LEVEL_AUTOCOMMIT
conn.set_isolation_level(ISOLATION_LEVEL_AUTOCOMMIT)
```

--------------------------------

### Get DSN Parameters

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Retrieves the effective DSN parameters for the connection as a dictionary. The password parameter is removed from the result. Requires libpq >= 9.3.

```python
conn.get_dsn_parameters()
```

--------------------------------

### Get Protocol Version

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Returns a read-only integer representing the frontend/backend protocol version being used. Currently, Psycopg supports protocol 3.

```python
conn.protocol_version
```

--------------------------------

### Get Backend PID

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Returns the process ID (PID) of the backend server process you connected to. Note that this PID belongs to a process on the database server host.

```python
conn.get_backend_pid()
```

--------------------------------

### Execute Batch with Prepared Statements

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Shows how to use execute_batch with PostgreSQL prepared statements. This can offer further performance benefits by caching query plans and reducing data transfer.

```python
cur.execute("PREPARE stmt AS big and complex SQL with $1 $2 params")
execute_batch(cur, "EXECUTE stmt (%s, %s)", params_list)
cur.execute("DEALLOCATE stmt")
```

--------------------------------

### Example of QuotedString adapter

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

The QuotedString adapter is for string-like objects. It returns the string enclosed in single quotes, escaping any single quotes and backslashes within the string.

```python
>>> QuotedString(r"O'Reilly").getquoted()
"'O''Reilly'"
```

--------------------------------

### SQL Query with Named Parameters

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Demonstrates inserting data using named parameters (e.g., %(name)s) in the SQL query and providing values in a dictionary. This allows for flexible ordering and repetition of values.

```python
>>> cur.execute("""
...     INSERT INTO some_table (an_int, a_date, another_date, a_string)
...     VALUES (%(int)s, %(date)s, %(date)s, %(str)s);
...     """,
...     {'int': 10, 'str': "O'Reilly", 'date': datetime.date(2005, 11, 18)})
```

--------------------------------

### mogrify

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/cursor.rst

Returns a query string with arguments bound, exactly as it would be sent to the database. The returned string is always bytes.

```APIDOC
## mogrify(operation [, parameters])

### Description
Return a query string after arguments binding. The string returned is
exactly the one that would be sent to the database running the
`~cursor.execute()` method or similar.

The returned string is always a bytes string.

### Method
mogrify

### Parameters
#### Positional Parameters
- **operation** (string) - The SQL query or command.
- **parameters** (sequence or mapping, optional) - Parameters to bind to the query.

### Example
```python
>>> cur.mogrify("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
"INSERT INTO test (num, data) VALUES (42, E'bar')"
```

### Extension
The `mogrify()` method is a Psycopg extension to the |DBAPI|.
```

--------------------------------

### Checking libpq Dynamic Library Runtime Dependency

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/faq.rst

Provides a shell command to inspect the libpq dynamic library that a Psycopg2 _psycopg.so file is linked against at runtime. This is useful for diagnosing ImportError issues related to mismatched libpq versions.

```shell
$ ldd /path/to/packages/psycopg2/_psycopg.so | grep libpq
```

--------------------------------

### Getting libpq Version

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Returns the version number of the loaded libpq dynamic library as an integer. Raises NotSupportedError if psycopg2 was compiled with a libpq version older than 9.1.

```python
psycopg2.extensions.libpq_version()
```

--------------------------------

### adapt(obj)

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Returns the SQL representation of an object. It's the entry point for the adaptation mechanism and can be used to adapt complex objects by recursively calling itself on their components. Raises `ProgrammingError` if adaptation is unknown.

```APIDOC
## adapt(obj)

### Description
Returns the SQL representation of *obj* as an `ISQLQuote`. Raises a `~psycopg2.ProgrammingError` if how to adapt the object is unknown. In order to allow new objects to be adapted, register a new adapter for it using the `register_adapter()` function.

The function is the entry point of the adaptation mechanism: it can be used to write adapters for complex objects by recursively calling `!adapt()` on its components.
```

--------------------------------

### LogicalReplicationConnection

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

A connection factory for establishing logical replication connections.

```APIDOC
## LogicalReplicationConnection

### Description
This connection factory class is used to establish a connection specifically for logical replication purposes.

### Usage
Pass `psycopg2.extras.LogicalReplicationConnection` as the `connection_factory` argument to `psycopg2.connect()`.

### Example
```python
from psycopg2.extras import LogicalReplicationConnection

conn = psycopg2.connect(dsn, connection_factory=LogicalReplicationConnection)
cur = conn.cursor()
# ... perform replication operations ...
```

### Related Classes
- `psycopg2.extras.ReplicationMessage`
```

--------------------------------

### Waiting for connection file descriptor for writing

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Use this snippet when connection.poll() returns POLL_WRITE. It demonstrates how to use select.select to wait for the connection file descriptor to be ready for writing.

```python
select.select([], [conn.fileno()], [])
```

--------------------------------

### Disable binary packages with pip

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/install.rst

Install Psycopg2 from source, disabling the automatic use of pre-compiled binary packages. This ensures usage of system libraries and requires build prerequisites.

```console
$ pip install --no-binary :all: psycopg2
```

--------------------------------

### connection.info

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Provides access to a `psycopg2.extensions.ConnectionInfo` object, which exposes detailed information about the native libpq connection.

```APIDOC
## connection.info

### Description
A `psycopg2.extensions.ConnectionInfo` object exposing information about the native libpq connection.

### Attributes
- **info**: A `psycopg2.extensions.ConnectionInfo` object.
```

--------------------------------

### Call PL/pgSQL Function and Get Cursor Name

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Calls a PL/pgSQL function that returns a cursor and assigns the cursor name. This is the first step in accessing a cursor returned by a function.

```python
cur1 = conn.cursor()
cur1.callproc('reffunc', ['curname'])
```

--------------------------------

### Get Server Version

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Returns a read-only integer representing the backend server version. The number is formed by concatenating major, minor, and revision numbers (e.g., 8.1.5 becomes 80105).

```python
conn.server_version
```

--------------------------------

### psycopg2.connect

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/module.rst

Creates a new database session and returns a connection object. Connection parameters can be provided via a DSN string, keyword arguments, or a combination of both. It also supports custom connection and cursor factories, and asynchronous connections.

```APIDOC
## connect(dsn=None, connection_factory=None, cursor_factory=None, async=False, **kwargs)

### Description
Create a new database session and return a new `connection` object.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **dsn** (string) - Optional - The connection parameters as a libpq connection string.
- **connection_factory** (callable) - Optional - A callable object taking a *dsn* string argument to specify a different connection factory.
- **cursor_factory** (callable) - Optional - A factory for cursor objects. If specified, the connection's `~connection.cursor_factory` is set to it.
- **async** (boolean) - Optional - If `True`, an asynchronous connection will be created.
- **kwargs** - Any other connection parameter supported by the client library/server can be passed as keyword arguments.

### Connection Parameters
- **dbname** (string) - The database name.
- **user** (string) - User name used to authenticate.
- **password** (string) - Password used to authenticate.
- **host** (string) - Database host address (defaults to UNIX socket if not provided).
- **port** (integer) - Connection port number (defaults to 5432 if not provided).

### Request Example
```python
# Using DSN string
conn = psycopg2.connect("dbname=test user=postgres password=secret")

# Using keyword arguments
conn = psycopg2.connect(dbname="test", user="postgres", password="secret")

# Using a mix of both
conn = psycopg2.connect("dbname=test user=postgres", password="secret")
```

### Response
#### Success Response
- **connection** (`~psycopg2.extensions.connection`) - A new connection object.

#### Response Example
```python
# Example of a connection object (actual representation may vary)
<connection object at 0x...>
```

### Notes
- Either the *dsn* or at least one connection-related keyword argument is required.
- Keyword argument values take precedence over *dsn* values if the same parameter is specified in both.
- Other connection parameters supported by the client library/server can be passed.
- Asynchronous connections are supported via the `async` parameter.
```

--------------------------------

### Looking up Error Codes

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/errorcodes.rst

Shows how to use the `errorcodes.lookup()` function to get the symbolic name for a given PostgreSQL error code or error class. This is useful for interpreting the `pgcode` attribute of an exception.

```python
>>> try:
...     cur.execute("SELECT ouch FROM aargh;")
... except Exception as e:
...     pass
...
>>> errorcodes.lookup(e.pgcode[:2])
'CLASS_SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION'
>>> errorcodes.lookup(e.pgcode)
'UNDEFINED_TABLE'
```

--------------------------------

### Composing SQL Query as a String

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/sql.rst

Demonstrates how to convert a Composable SQL object into a plain SQL string using the as_string() method. This is useful for debugging or when the SQL string needs to be inspected or logged.

```python
query = sql.SQL("select {field} from {table} where {pkey} = %s").format(
    field=sql.Identifier('my_name'),
    table=sql.Identifier('some_table'),
    pkey=sql.Identifier('id'))

sql_string = query.as_string(cur)
```

--------------------------------

### Setting Session Transaction Characteristics

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Use `set_session` to configure transaction parameters like readonly or autocommit. When the connection is not in autocommit mode, these settings are applied at the start of the next transaction (e.g., with `BEGIN`).

```python
conn.set_session(readonly=True)

conn.set_session(readonly=True, autocommit=True)
```

--------------------------------

### PhysicalReplicationConnection

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

A connection factory for establishing physical replication connections.

```APIDOC
## PhysicalReplicationConnection

### Description
This connection factory class is used to establish a connection specifically for physical replication purposes.

### Usage
Pass `psycopg2.extras.PhysicalReplicationConnection` as the `connection_factory` argument to `psycopg2.connect()`.

### Example
```python
from psycopg2.extras import PhysicalReplicationConnection

conn = psycopg2.connect(dsn, connection_factory=PhysicalReplicationConnection)
cur = conn.cursor()
# ... perform replication operations ...
```

### Related Classes
- `psycopg2.extras.ReplicationMessage`
```

--------------------------------

### Binding Parameters with mogrify

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/cursor.rst

The `mogrify()` method returns a query string after arguments binding. The returned string is exactly what would be sent to the database. This is a Psycopg extension to the DBAPI.

```python
>>> cur.mogrify("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
"INSERT INTO test (num, data) VALUES (42, E'bar')"
```

--------------------------------

### Accessing internal PGresult pointer with pgresult_ptr

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/cursor.rst

Retrieve the cursor's internal PGresult pointer as an integer. This is useful for passing the raw libpq result structure to C functions, for example, using ctypes.

```python
>>> import ctypes
>>> libpq = ctypes.pydll.LoadLibrary(ctypes.util.find_library('pq'))
>>> libpq.PQcmdStatus.argtypes = [ctypes.c_void_p]
>>> libpq.PQcmdStatus.restype = ctypes.c_char_p

>>> curs.execute("select 'x'")
>>> libpq.PQcmdStatus(curs.pgresult_ptr)
b'SELECT 1'
```

--------------------------------

### copy_from

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/cursor.rst

Imports data from a file-like object into a table. It allows specifying columns to import and handles encoding for text-based files.

```APIDOC
## copy_from

### Description
Imports data from a file-like object into a table. It allows specifying columns to import and handles encoding for text-based files.

### Method
`copy_from(file, table, sep='\t', null='\\N', columns=None)`

### Parameters
#### Arguments
- **file** (file-like object) - The file-like object to read data from.
- **table** (string) - The name of the table to import data into.
- **sep** (string, optional) - The column separator in the file. Defaults to tab ('\t').
- **null** (string, optional) - The string representation of NULL values. Defaults to '\\N'.
- **columns** (iterable, optional) - An iterable with the names of the columns to import. If not specified, the entire table is assumed to match the file structure.

### Example
```python
>>> from io import StringIO
>>> f = StringIO("42\tfoo\n74\tbar\n")
>>> cur.copy_from(f, 'test', columns=('num', 'data'))
```

### Version Changes
- **2.0.6**: Added the *columns* parameter.
- **2.4**: Data read from files implementing `io.TextIOBase` are encoded in the connection `~connection.encoding`.
- **2.9**: Table and field names are now quoted. For schema-qualified tables, use `copy_expert()`.
```

--------------------------------

### Waiting for connection file descriptor for reading

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Use this snippet when connection.poll() returns POLL_READ. It demonstrates how to use select.select to wait for the connection file descriptor to be ready for reading.

```python
select.select([conn.fileno()], [], [])
```

--------------------------------

### Adapt INET Object for SQL

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extras.rst

Demonstrates adapting an Inet object for use in SQL queries. The output shows the Inet object formatted as a SQL string literal with the ::inet cast.

```python
>>> cur.mogrify("SELECT %s", (Inet('127.0.0.1/32'),))
"SELECT E'127.0.0.1/32'::inet"
```

--------------------------------

### AsIs

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

An adapter conforming to the `ISQLQuote` protocol for objects whose string representation is already valid as SQL.

```APIDOC
## class AsIs(object)

### Description
Adapter conform to the `ISQLQuote` protocol useful for objects whose string representation is already valid as SQL representation.

### Methods
* `getquoted()`: Return the `str()` conversion of the wrapped object.

    >>> AsIs(42).getquoted()
    '42'
```

--------------------------------

### adapters

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

A dictionary containing the currently registered object adapters. Use `register_adapter()` to add new adapters.

```APIDOC
## data adapters

### Description
Dictionary of the currently registered object adapters. Use `register_adapter()` to add an adapter for a new type.
```

--------------------------------

### make_dsn

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Creates a valid connection string from arguments, merging provided keyword arguments with an optional existing DSN string.

```APIDOC
## make_dsn(dsn=None, **kwargs)

### Description
Create a valid connection string from arguments. Put together the arguments in *kwargs* into a connection string. If *dsn* is specified too, merge the arguments coming from both the sources. If the same argument name is specified in both the sources, the *kwargs* value overrides the *dsn* value. The input arguments are validated: the output should always be a valid connection string (as far as `parse_dsn()` is concerned). If not raise `~psycopg2.ProgrammingError`.

### Parameters
#### Path Parameters
- **dsn** (string) - Optional - An existing connection string to merge with.
- **kwargs** (dict) - Key-value pairs representing connection parameters.
```

--------------------------------

### Python Date/Time Constructors from Ticks

Source: https://github.com/psycopg/psycopg2/blob/master/doc/pep-0249.txt

Provides sample implementations for DateFromTicks, TimeFromTicks, and TimestampFromTicks using the standard Python time module.

```Python
import time

def DateFromTicks(ticks):
    return apply(Date,time.localtime(ticks)[:3])

def TimeFromTicks(ticks):
    return apply(Time,time.localtime(ticks)[3:6])

def TimestampFromTicks(ticks):
    return apply(Timestamp,time.localtime(ticks)[:6])
```

--------------------------------

### Adapting Python Constants to SQL

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Demonstrates how Python's None, True, and False are converted to SQL NULL, true, and false literals respectively. This is useful for inserting or comparing constant values in SQL queries.

```python
>>> cur.mogrify("SELECT %s, %s, %s;", (None, True, False))
'SELECT NULL, true, false;'
```

--------------------------------

### Create DSN String

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Construct a Data Source Name (DSN) string from connection parameters. Useful for standardizing connection details.

```python
from psycopg2.extensions import make_dsn
make_dsn('dbname=foo host=example.com', password="s3cr3t")
```

--------------------------------

### Adapting Python List to PostgreSQL ARRAY

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Illustrates how a Python list is converted into a PostgreSQL ARRAY literal using mogrify.

```python
cur.mogrify("SELECT %s التقليدي;", ([10, 20, 30], ))
```

--------------------------------

### Create a signed Git tag for release

Source: https://github.com/psycopg/psycopg2/blob/master/doc/release.rst

Create a signed Git tag for the release. The tag name is derived from the VERSION environment variable by replacing dots with underscores. The tag message should include a summary of changes.

```bash
# Tag name will be 2_8_4
$ git tag -a -s ${VERSION//./_}
```

```text
Psycopg 2.8.4 released

What's new in psycopg 2.8.4
---------------------------

New features:

- Fixed bug blah (:ticket:`#42`).
...
```

--------------------------------

### Creating a Binary Object

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/module.rst

Use the Binary constructor to create an object capable of holding a binary string value. The adapted Python object is available via the 'adapted' attribute.

```python
Binary(string)
```

--------------------------------

### Boolean, Float, SQL_IN

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Specialized adapters for built-in Python objects.

```APIDOC
## Specialized Adapters

### Description
Specialized adapters for builtin objects.

- Boolean
- Float
- SQL_IN
```

--------------------------------

### Build Psycopg2 with a specific pg_config location

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/install.rst

Compile Psycopg2 using a pg_config executable located at a non-standard path. Use the build_ext command with the --pg-config option.

```console
$ python setup.py build_ext --pg-config /path/to/pg_config build
```

--------------------------------

### SQL Query with Positional Parameters

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Shows how to insert data into a table using positional parameters (%s) for different data types like integers, dates, and strings. Ensures proper SQL formatting for values, including strings with apostrophes.

```python
>>> cur.execute("""
...     INSERT INTO some_table (an_int, a_date, a_string)
...     VALUES (%s, %s, %s);
...     """,
...     (10, datetime.date(2005, 11, 18), "O'Reilly"))
```

--------------------------------

### register_adapter(class, adapter)

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Registers a new adapter for objects of a given class. The adapter should be a function that takes an object and returns an object conforming to the `ISQLQuote` protocol.

```APIDOC
## register_adapter(class, adapter)

### Description
Register a new adapter for the objects of class *class*.

*adapter* should be a function taking a single argument (the object to adapt) and returning an object conforming to the `ISQLQuote` protocol (e.g. exposing a `!getquoted()` method). The `AsIs` is often useful for this task.

Once an object is registered, it can be safely used in SQL queries and by the `adapt()` function.
```

--------------------------------

### Set PATH for pg_config

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/install.rst

Add the directory containing pg_config to your PATH environment variable. This is necessary if pg_config is not found in the default PATH.

```console
$ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH
```

--------------------------------

### ISQLQuote

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/extensions.rst

Represents the SQL adaptation protocol. Objects conforming to this protocol should implement a `getquoted()` method and optionally a `prepare()` method.

```APIDOC
## class ISQLQuote(wrapped_object)

### Description
Represents the SQL adaptation protocol. Objects conforming this protocol should implement a `getquoted()` and optionally a `prepare()` method.

Adapters may subclass `!ISQLQuote`, but is not necessary: it is enough to expose a `!getquoted()` method to be conforming.

### Attributes
* `_wrapped`: The wrapped object passed to the constructor.

### Methods
* `getquoted()`: Subclasses or other conforming objects should return a valid SQL string representing the wrapped object. In Python 3 the SQL must be returned in a `!bytes` object. The `!ISQLQuote` implementation does nothing.
* `prepare(conn)`: Prepare the adapter for a connection. The method is optional: if implemented, it will be invoked before `!getquoted()` with the connection to adapt for as argument. A conform object can implement this method if the SQL representation depends on any server parameter, such as the server version or the :envvar:`standard_conforming_string` setting. Container objects may store the connection and use it to recursively prepare contained objects: see the implementation for `psycopg2.extensions.SQL_IN` for a simple example.
```

--------------------------------

### Listening for Database Notifications

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/advanced.rst

This snippet demonstrates how to listen for notifications from a PostgreSQL database using the `select` module for non-blocking I/O. Ensure the connection is in autocommit mode.

```python
import select
import psycopg2
import psycopg2.extensions

conn = psycopg2.connect(DSN)
conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)

curs = conn.cursor()
curs.execute("LISTEN test;")

print("Waiting for notifications on channel 'test'")
while True:
    if select.select([conn],[],[],5) == ([],[],[]):
        print("Timeout")
    else:
        conn.poll()
        while conn.notifies:
            notify = conn.notifies.pop(0)
            print("Got NOTIFY:", notify.pid, notify.channel, notify.payload)
```

--------------------------------

### Upload signed packages to PyPI

Source: https://github.com/psycopg/psycopg2/blob/master/doc/release.rst

Upload the signed packages to the Python Package Index (PyPI) for stable releases. This command requires the 'twine' tool and assumes packages are located in the 'wheelhouse' directory.

```bash
$ twine upload -s wheelhouse/psycopg2-${VERSION}/*
```

--------------------------------

### Upload test packages to PyPI testing site

Source: https://github.com/psycopg/psycopg2/blob/master/doc/release.rst

Upload packages to the PyPI testing site for pre-release testing. This uses the 'testpypi' repository and requires proper configuration of '~/.pypirc'.

```bash
$ twine upload -s -r testpypi wheelhouse/psycopg2-${VERSION}/*
```

--------------------------------

### connection.tpc_begin

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/connection.rst

Begins a TPC transaction with the given transaction ID xid. This method should be called outside of a transaction.

```APIDOC
## connection.tpc_begin(xid)

### Description
Begins a TPC transaction with the given transaction ID *xid*.

This method should be called outside of a transaction (i.e. nothing may have executed since the last `~connection.commit()` or `~connection.rollback()` and connection.status is `~psycopg2.extensions.STATUS_READY`).

Furthermore, it is an error to call `!commit()` or `!rollback()` within the TPC transaction: in this case a `~psycopg2.ProgrammingError` is raised.

The *xid* may be either an object returned by the `~connection.xid()` method or a plain string: the latter allows to create a transaction using the provided string as PostgreSQL transaction id. See also `~connection.tpc_recover()`.
```

--------------------------------

### Disable binary packages in requirements.txt

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/install.rst

Specify to always compile Psycopg2 from source within a requirements.txt file by using the --no-binary option.

```none
psycopg2>=2.7,<2.8 --no-binary psycopg2
```

--------------------------------

### Fetch Data with Different Client Encoding (Python 2)

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Illustrates fetching the same Unicode data after changing the client encoding in Python 2. This demonstrates how the received 'str' representation changes based on the encoding.

```python
>>> conn.set_client_encoding('LATIN9')

>>> cur.execute("SELECT data FROM test WHERE num = 74")
>>> x = cur.fetchone()[0]
>>> print(type(x), repr(x))
<type 'str'> '\xe0\xe8\xec\xf2\xf9\xa4'
```

--------------------------------

### Using Python List with PostgreSQL ANY Operator

Source: https://github.com/psycopg/psycopg2/blob/master/doc/src/usage.rst

Demonstrates using a Python list with the PostgreSQL ANY operator in a WHERE clause.

```python
ids = [10, 20, 30]
cur.execute("SELECT * FROM data WHERE id = ANY(%s);", (ids,))
```