tessl/pypi-vertica-python

Official native Python client for the Vertica database.

Overview

Eval results

Files

Connection Management

Name: tessl/pypi-vertica-python
Author: tessl

Core database connection functionality for establishing, managing, and terminating connections to Vertica databases. Supports various authentication methods, secure connections via TLS/SSL, connection pooling, and comprehensive parameter configuration.

Capabilities

Connection Functions

connect(**kwargs)

Creates a new connection to a Vertica database.

def connect(**kwargs) -> Connection:
    """
    Opens a new connection to a Vertica database.
    
    Parameters:
    - host (str): Database server hostname (default: 'localhost')
    - port (int): Database server port (default: 5433)
    - user (str): Username for authentication
    - password (str): Password for authentication (default: '')
    - database (str): Database name to connect to (default: '')
    - autocommit (bool): Enable autocommit mode (default: False)
    - ssl (bool): Use SSL/TLS connection (default: False)
    - tlsmode (str): TLS mode ('disable', 'allow', 'prefer', 'require', 'verify-ca', 'verify-full')
    - backup_server_node (list): List of backup server nodes for failover
    - binary_transfer (bool): Use binary protocol transfer (default: False)
    - request_complex_types (bool): Request complex type information (default: True)
    - log_level (int): Logging level (default: logging.WARNING)
    - log_path (str): Log file path (default: 'vertica_python.log')
    - oauth_access_token (str): OAuth access token for authentication
    - workload (str): Workload identifier for resource management
    - kerberos_service_name (str): Kerberos service name (default: 'vertica')
    - unicode_error (str): Unicode error handling mode
    - ssl_cert_file (str): Path to client certificate file
    - ssl_key_file (str): Path to client private key file
    - ssl_ca_file (str): Path to CA certificate file
    
    Returns:
    Connection: New database connection instance
    
    Raises:
    ConnectionError: If connection cannot be established
    """

parse_dsn(dsn)

Parses a connection string (DSN) into a dictionary of connection parameters.

def parse_dsn(dsn: str) -> dict:
    """
    Parse connection string (DSN) into a dictionary of keywords and values.
    
    Parameters:
    - dsn (str): Connection string in format 
                'vertica://user:password@host:port/database?param1=value1&param2=value2'
    
    Returns:
    dict: Dictionary containing connection parameters
    
    Raises:
    ValueError: If DSN format is invalid
    """

Connection Class

The Connection class represents a database connection and provides methods for transaction control, cursor creation, and connection management.

class Connection:
    """
    Database connection object implementing DB-API 2.0 interface.
    """
    
    def __init__(self, options: dict):
        """
        Initialize connection with connection parameters.
        
        Parameters:
        - options (dict): Connection configuration dictionary
        """
    
    def close(self) -> None:
        """
        Close the connection and free associated resources.
        Connection becomes unusable after this call.
        """
    
    def commit(self) -> None:
        """
        Commit any pending transaction to the database.
        
        Raises:
        DatabaseError: If commit fails
        """
    
    def rollback(self) -> None:
        """
        Roll back pending transaction to the start of the transaction.
        
        Raises:
        DatabaseError: If rollback fails
        """
    
    def cursor(self, cursor_type=None) -> 'Cursor':
        """
        Return a new cursor object using the connection.
        
        Parameters:
        - cursor_type (str, optional): Type of cursor to create ('list', 'dict', etc.)
        
        Returns:
        Cursor: New cursor instance
        
        Raises:
        InterfaceError: If connection is closed
        """
    
    def cancel(self) -> None:
        """
        Cancel the current database operation.
        
        Raises:
        OperationalError: If cancellation fails
        """
    
    def opened(self) -> bool:
        """
        Check if connection is open.
        
        Returns:
        bool: True if connection is open, False otherwise
        """
    
    def closed(self) -> bool:
        """
        Check if connection is closed.
        
        Returns:
        bool: True if connection is closed, False otherwise
        """
    
    def ssl(self) -> bool:
        """
        Check if connection is using SSL/TLS encryption.
        
        Returns:
        bool: True if connection uses SSL/TLS, False otherwise
        """
    
    @property
    def autocommit(self) -> bool:
        """
        Get or set autocommit mode.
        
        Returns:
        bool: Current autocommit setting
        """
    
    @autocommit.setter
    def autocommit(self, value: bool) -> None:
        """
        Set autocommit mode.
        
        Parameters:
        - value (bool): Enable (True) or disable (False) autocommit
        """
    
    @property
    def parameters(self) -> dict:
        """
        Get connection parameters.
        
        Returns:
        dict: Current connection parameters
        """
    
    @property
    def unicode_error(self) -> str:
        """
        Get or set unicode error handling mode.
        
        Returns:
        str: Current unicode error handling mode
        """
    
    @unicode_error.setter
    def unicode_error(self, value: str) -> None:
        """
        Set unicode error handling mode.
        
        Parameters:
        - value (str): Error handling mode ('strict', 'ignore', 'replace')
        """
    
    def __enter__(self) -> 'Connection':
        """
        Enter context manager.
        
        Returns:
        Connection: Self for context manager protocol
        """
    
    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
        """
        Exit context manager and close connection.
        
        Parameters:
        - exc_type: Exception type (if any)
        - exc_val: Exception value (if any)  
        - exc_tb: Exception traceback (if any)
        """

Connection Parameters

Authentication Parameters

user: Database username
password: Database password
oauth_access_token: OAuth token for OAuth authentication
kerberos_service_name: Service name for Kerberos authentication

Network Parameters

host: Server hostname or IP address
port: Server port (default: 5433)
backup_server_node: List of backup servers for load balancing/failover

Security Parameters

ssl: Enable SSL/TLS encryption
tlsmode: TLS connection mode ('disable', 'allow', 'prefer', 'require', 'verify-ca', 'verify-full')
ssl_cert_file: Client certificate file path
ssl_key_file: Client private key file path
ssl_ca_file: CA certificate file path

Behavior Parameters

database: Target database name
autocommit: Enable autocommit mode
binary_transfer: Use binary protocol for better performance
request_complex_types: Request metadata for complex types
unicode_error: Unicode error handling ('strict', 'ignore', 'replace')
workload: Workload identifier for resource management

Logging Parameters

log_level: Python logging level (logging.DEBUG, logging.INFO, etc.)
log_path: Path to log file

Usage Examples

Basic Connection

import vertica_python

# Simple connection
conn = vertica_python.connect(
    host='myserver.example.com',
    port=5433,
    user='myuser',
    password='mypassword',
    database='mydb'
)

# Use connection
cursor = conn.cursor()
cursor.execute("SELECT version()")
result = cursor.fetchone()
print(result[0])

# Clean up
cursor.close()
conn.close()

Context Manager Usage

with vertica_python.connect(
    host='myserver.example.com',
    user='myuser',
    password='mypassword',
    database='mydb'
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT COUNT(*) FROM my_table")
        count = cur.fetchone()[0]
        print(f"Row count: {count}")
    # Cursor automatically closed
# Connection automatically closed

SSL Connection

conn = vertica_python.connect(
    host='secure.example.com',
    user='myuser',
    password='mypassword',
    database='mydb',
    ssl=True,
    tlsmode='verify-full',
    ssl_ca_file='/path/to/ca-cert.pem'
)

Connection String (DSN) Usage

dsn = "vertica://myuser:mypassword@myserver.example.com:5433/mydb?ssl=true&autocommit=true"
params = vertica_python.parse_dsn(dsn)
conn = vertica_python.connect(**params)

Load Balancing with Backup Servers

conn = vertica_python.connect(
    host='primary.example.com',
    backup_server_node=[
        'backup1.example.com:5433',
        'backup2.example.com:5433'
    ],
    user='myuser',
    password='mypassword',
    database='mydb'
)

Install with Tessl CLI