### Install vertica-python

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Installs the vertica-python library using pip. Supports installation of the latest release version or the latest commit from the master branch.

```bash
pip install vertica-python

pip install git+https://github.com/vertica/vertica-python.git@master
```

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

### Logging Configuration Examples

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates various ways to enable and configure logging for the vertica-python client. Logging can be enabled by setting `log_level` or `log_path`. Examples cover different log levels, file paths, and using root handlers.

```python
import vertica_python
import logging

## Example 1: write DEBUG level logs to './vertica_python.log'
conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             'log_level': logging.DEBUG}
with vertica_python.connect(**conn_info) as connection:
    # do things

## Example 2: write WARNING level logs to './path/to/logs/client.log'
conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             'log_path': 'path/to/logs/client.log'}
with vertica_python.connect(**conn_info) as connection:
   # do things

## Example 3: write INFO level logs to '/home/admin/logs/vClient.log'
conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             'log_level': logging.INFO,
             'log_path': '/home/admin/logs/vClient.log'}
with vertica_python.connect(**conn_info) as connection:
   # do things

## Example 4: use root handlers to process logs by setting 'log_path' to '' (empty string) 
conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             'log_level': logging.DEBUG,
             'log_path': ''}
with vertica_python.connect(**conn_info) as connection:
    # do things
```

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

### Install Kerberos Support

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Installs the optional Kerberos authentication support for vertica-python on Unix-like systems. This requires the 'kerberos' Python package and development headers for Python.

```bash
pip install kerberos

sudo [yum|apt-get|etc] install python-dev
```

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

### Running Vertica-Python Tests with Tox

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

Examples of common commands for running the vertica-python test suite using tox. Tox allows testing across multiple Python environments.

```bash
# Run all tests using tox:
tox

# Run tests on specified python versions with `tox -e ENV,ENV`
tox -e py312,py313

# Run specific tests by filename (e.g.) `test_notice.py`
tox -- vertica_python/tests/unit_tests/test_notice.py

# Run all unit tests on the python version 3.9:
tox -e py39 -- -m unit_tests

# Run all integration tests on the python version 3.10 with verbose result outputs:
tox -e py310 -- -v -m integration_tests

# Run an individual test on specified python versions.
# e.g.: Run the test `test_error_message` under `test_notice.py` on the python versions 3.8 and 3.9
tox -e py38,py39 -- vertica_python/tests/unit_tests/test_notice.py::NoticeTestCase::test_error_message
```

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

### TLS/SSL Configuration Examples

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Illustrates how to configure TLS/SSL connections in vertica-python using different 'tlsmode' settings, including 'require', 'verify-ca', and 'verify-full'.

```python
# [TLSMode: require]
import vertica_python
conn_info = {'host': '127.0.0.1',
             'user': 'some_user',
             'database': 'a_database',
             'tlsmode': 'require'}
connection = vertica_python.connect(**conn_info)
```

```python
# [TLSMode: verify-ca]
import vertica_python
conn_info = {'host': '127.0.0.1',
             'user': 'some_user',
             'database': 'a_database',
             'tlsmode': 'verify-ca',
             'tls_cafile': '/path/to/ca_file.pem' # CA certificate used to verify server certificate
            }
connection = vertica_python.connect(**conn_info)
```

```python
# [TLSMode: verify-full] + Mutual Mode
import vertica_python

conn_info = {'host': '127.0.0.1',
             'user': 'some_user',
             'database': 'a_database',
             'tlsmode': 'verify-full',
             'tls_cafile' : '/path/to/ca_file.pem',  # CA certificate used to verify server certificate
             'tls_certfile' : '/path/to/client.pem',  # (for mutual mode) client certificate
             'tls_keyfile' : '/path/to/client.key'  # (for mutual mode) client private key
            }
connection = vertica_python.connect(**conn_info)
```

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

### Nextset Navigation

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Provides a detailed example of how to navigate through multiple result sets generated by a single `execute()` call using `fetchone()` and `nextset()`.

```python
# Assuming 'cur' is an active cursor
cur.execute('SELECT 1; SELECT 2;')

# Fetch from the first result set
print(cur.fetchone())
# Output: [1]
print(cur.fetchone())
# Output: None

# Move to the next result set
print(cur.nextset())
# Output: True

# Fetch from the second result set
print(cur.fetchone())
# Output: [2]
print(cur.fetchone())
# Output: None

# Attempt to move to the next result set (which doesn't exist)
print(cur.nextset())
# Output: False
```

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

### Installing Development Dependencies

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

Installs the necessary Python packages for developing the vertica-python library from the requirements-dev.txt file.

```shell
pip install -r requirements-dev.txt
```

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

### Connection Load Balancing Example

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Illustrates how to enable connection load balancing in vertica-python. Both the client and server must have load balancing enabled for it to function. This example shows connecting to a primary node and then observing redirection to another node after setting a load balancing policy.

```python
import vertica_python

conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'vdb',
             'connection_load_balance': True}

# Server enables load balancing
with vertica_python.connect(**conn_info) as conn:
    cur = conn.cursor()
    cur.execute("SELECT NODE_NAME FROM V_MONITOR.CURRENT_SESSION")
    print("Client connects to primary node:", cur.fetchone()[0])
    cur.execute("SELECT SET_LOAD_BALANCE_POLICY('ROUNDROBIN')")

with vertica_python.connect(**conn_info) as conn:
    cur = conn.cursor()
    cur.execute("SELECT NODE_NAME FROM V_MONITOR.CURRENT_SESSION")
    print("Client redirects to node:", cur.fetchone()[0])
```

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

### Executing Queries with vertica-python

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Provides a basic example of establishing a connection and creating a cursor to execute SQL commands and retrieve results. The `Connection` object manages the session, while the `Cursor` object handles query execution and data fetching.

```python
import vertica_python

conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'vdb'}

# Example usage would involve connecting and then using a cursor:
# with vertica_python.connect(**conn_info) as connection:
#     with connection.cursor() as cursor:
#         cursor.execute("SELECT version()")
#         print(cursor.fetchone())

```

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

### Override Vertica Test Configuration (File)

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

Example of overriding default Vertica test configuration using a `vp_test.conf` file. This file should be ignored by git.

```ini
# edit under [vp_test_config] section
VP_TEST_HOST=10.0.0.2
VP_TEST_PORT=5000
VP_TEST_USER=dbadmin
VP_TEST_DATABASE=vdb1
VP_TEST_PASSWORD=abcdef1234
VP_TEST_LOG_DIR=my_log/year/month/date
VP_TEST_LOG_LEVEL=DEBUG
```

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

### Override Vertica Test Configuration (Environment Variables)

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

Example of overriding Vertica test configuration using environment variables in a Linux shell. These variables should be unset after tests are completed.

```bash
# Set environment variables in linux
$ export VP_TEST_HOST=10.0.0.2
$ export VP_TEST_PORT=5000
$ export VP_TEST_USER=dbadmin
$ export VP_TEST_DATABASE=vdb1
$ export VP_TEST_PASSWORD=abcdef1234
$ export VP_TEST_LOG_DIR=my_log/year/month/date
$ export VP_TEST_LOG_LEVEL=DEBUG

# Delete your environment variables after tests
$ unset VP_TEST_PASSWORD
```

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

### Cancel Database Operation with Connection.cancel()

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates how to interrupt a running database operation using the `Connection.cancel()` method. This is useful for stopping long-running queries or preventing excessive resource usage. The example shows canceling a query from a separate process and canceling a query mid-fetch.

```python
from multiprocessing import Process
import time
import vertica_python

def cancel_query(connection, timeout=5):
    time.sleep(timeout)
    connection.cancel()

# Example 1: Cancel the query before Cursor.execute() return.
#            The query stops executing in a shorter time after the cancel message is sent.
with vertica_python.connect(**conn_info) as conn:
    cur = conn.cursor()

    # Call cancel() from a different process
    p1 = Process(target=cancel_query, args=(conn,))
    p1.start()

    try:
        cur.execute("<Long running query>")
    except vertica_python.errors.QueryCanceled as e:
        pass
    p1.join()
    
# Example 2: Cancel the query after Cursor.execute() return.
#            Less number of rows read after the cancel message is sent.
with vertica_python.connect(**conn_info) as conn:
    cur = conn.cursor()
    cur.execute("SELECT id, time FROM large_table")
    nCount = 0
    try:
        while cur.fetchone():
            nCount += 1
            if nCount == 100:
                conn.cancel()
    except vertica_python.errors.QueryCanceled as e:
        pass
        # nCount is less than the number of rows in large_table

```

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

### Typecasting Complex Data Types for SQL Literals

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Explains how to handle complex Python data types, such as arrays of dates, by explicitly typecasting them for SQL literals when executing queries. It shows an example of a failed insertion due to incorrect type and a successful insertion with proper typecasting.

```python
from datetime import date
cur.execute("CREATE TABLE table (a INT, b ARRAY[DATE])")
value = [date(2021, 6, 10), date(2021, 6, 12), date(2021, 6, 30)]

cur.execute("INSERT INTO table VALUES (%s, %s::ARRAY[DATE])", [100, value], use_prepared_statements=False)  # correct
# converted into a SQL command: INSERT INTO vptest VALUES (100, ARRAY['2021-06-10','2021-06-12','2021-06-30']::ARRAY[DATE])

# Client-side binding of cursor.executemany is different from cursor.execute internally
# But it also supports some of complex types mapping
cur.executemany("INSERT INTO table (a, b) VALUES (%s, %s)", [[100, value]], use_prepared_statements=False)
```

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

### Connect and Execute Basic SQL

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates how to establish a connection to a Vertica database, create a cursor, execute SQL commands like CREATE TABLE and INSERT, and fetch results.

```python
import vertica_python

# Assuming conn_info is a dictionary with connection details
# conn_info = {
#     'host': 'your_vertica_host',
#     'port': 5433,
#     'user': 'your_user',
#     'password': 'your_password',
#     'database': 'your_database'
# }

with vertica_python.connect(**conn_info) as conn:
    cur = conn.cursor()
    
    # Create a table
    cur.execute("CREATE TABLE tbl (a INT, b VARCHAR)")
    
    # Insert a row
    cur.execute("INSERT INTO tbl VALUES (1, 'aa')")
    inserted = cur.fetchall()  # [[1]]
    
    # Query the database
    cur.execute("SELECT * FROM tbl")
    datarow = cur.fetchone()         # [1, 'aa']
    remaining_rows = cur.fetchall()  # [] (if only one row was inserted)

    conn.commit()
```

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

### Connection String with Additional Info

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates establishing a Vertica connection using a connection string and additional keyword arguments, including password and backup server nodes.

```python
connection_str = "vertica://user:password@host:port/database"
additional_info = {
    'password': 'some_password',
    'backup_server_node': ['10.6.7.123', ('10.20.82.77', 6000)]
    }

with vertica_python.connect(dsn=connection_str, **additional_info) as conn:
   # do things
```

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

### Forking and Setting Up Remotes

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

Steps to fork the vertica-python repository and configure local Git remotes for 'origin' and 'upstream'.

```shell
git clone git@github.com:YOURUSERNAME/vertica-python.git
cd vertica-python
git remote add upstream git@github.com:vertica/vertica-python.git
git fetch upstream
```

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

### Basic Connection Usage

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates establishing a connection using a dictionary of connection information and utilizing a `with` statement for automatic closing.

```python
import vertica_python

conn_info = {
    "host": "your_host",
    "port": 5433,
    "user": "your_user",
    "password": "your_password",
    "database": "your_database"
}

# using `with` for auto connection closing after usage
with vertica_python.connect(**conn_info) as connection:
    # do things
```

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

### Using COPY FROM

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Details the methods for loading data into Vertica using the COPY FROM command via the vertica-python library. It covers loading from STDIN using `Cursor.copy()` with string or file-like objects, and mentions loading from server-side files using `Cursor.execute()`.

```APIDOC
COPY FROM Operations:

  Prerequisites:
    - For files not on STDIN, only client-side files should be loaded using these methods.
    - For server-side files, use `Cursor.execute("COPY target-table FROM 'path-to-data'")`.

  Method 1: COPY FROM STDIN with Cursor.copy()
    - Use `Cursor.copy(sql_command, data, buffer_size)`.
    - `sql_command`: The COPY FROM STDIN statement (e.g., "COPY test_copy (id, name) FROM stdin DELIMITER ',' ").
    - `data`: A string or a file-like object with a `read()` method.
    - `buffer_size`: Optional chunk size for streaming data (defaults to 128 KB).

    - Examples:
      cur.copy("COPY test_copy (id, name) FROM stdin DELIMITER ',' ", csv_data)
      with open("/tmp/binary_file.csv", "rb") as fs:
          cursor.copy("COPY table(field1, field2) FROM STDIN DELIMITER ',' ENCLOSED BY '"'",
                      fs, buffer_size=65536)
```

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

### Create Vertica Connection

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates how to establish a connection to a Vertica database using the vertica-python library. It includes various connection parameters such as host, port, user, password, database, session label, error handling, SSL, autocommit, prepared statements, and connection timeout.

```python
import vertica_python

conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             # autogenerated session label by default,
             'session_label': 'some_label',
             # default throw error on invalid UTF-8 results
             'unicode_error': 'strict',
             # SSL is disabled by default
             'ssl': False,
             # autocommit is off by default
             'autocommit': True,
             # using server-side prepared statements is disabled by default
             'use_prepared_statements': False,
             # connection timeout is not enabled by default
             # 5 seconds timeout for a socket operation (Establishing a TCP connection or read/write operation)
             'connection_timeout': 5}

# simple connection, with manual close
try:
    connection = vertica_python.connect(**conn_info)
    # do things
finally:
    connection.close()
```

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

### Vertica Connection Options

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Lists and describes the available connection options for establishing a connection to a Vertica database using the vertica-python library.

```APIDOC
Connection Options:

- host: The server host of the connection. Can be a host name or an IP address.
  Default: "localhost"
- port: The port of the connection.
  Default: 5433
- user: The database user name to use to connect to the database.
  Default: (for non-OAuth connections) OS login user name; (for OAuth connections) ""
- password: The password to use to log into the database.
  Default: ""
- database: The database name.
  Default: ""
- autocommit: See [Autocommit](#autocommit).
  Default: False
- backup_server_node: See [Connection Failover](#connection-failover).
  Default: []
- binary_transfer: See [Data Transfer Format](#data-transfer-format). Use False for text format transfer.
  Default: False
- connection_load_balance: See [Connection Load Balancing](#connection-load-balancing).
  Default: False (disabled)
- connection_timeout: The number of seconds the client waits for a socket operation (Establishing a TCP connection or read/write operation).
  Default: None (no timeout)
- disable_copy_local: See [COPY FROM LOCAL](#method-2-copy-from-local-sql-with-cursorexecute).
  Default: False
- kerberos_host_name: See [Kerberos Authentication]. Defaults to the value of connection option `host`.
  Default: value of `host`
- kerberos_service_name: See [Kerberos Authentication].
  Default: "vertica"
- log_level: See [Logging].
- log_path: See [Logging].
- oauth_access_token: See [OAuth Authentication].
  Default: ""
- request_complex_types: See [SQL Data conversion to Python objects].
  Default: True
- session_label: Sets a label for the connection on the server. Appears in `_v_monitor.sessions_`.
  Default: auto-generated label `vertica-python-{version}-{random_uuid}`
- ssl: See [TLS/SSL].
  Default: None (tlsmode="prefer")
- tlsmode: Controls whether the connection to the server uses TLS encryption. See [TLS/SSL].
  Default: "prefer"
- tls_cafile: The name of a file containing trusted SSL certificate authority (CA) certificate(s). See [TLS/SSL].
- tls_certfile: The name of a file containing client's certificate(s). See [TLS/SSL].
- tls_keyfile: The name of a file containing client's private key. See [TLS/SSL].
- unicode_error: See [UTF-8 encoding issues]. Throws error on invalid UTF-8 results.
  Default: 'strict'
- use_prepared_statements: See [Passing parameters to SQL queries].
  Default: False
- workload: Sets the workload name associated with this session. Must be an existing workload name on the server.
  Default: ""
- dsn: Set Properties with Connection String. See [Set Properties with Connection String](#set-properties-with-connection-string).
```

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

### COPY FROM LOCAL with Cursor.execute()

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates using the `COPY FROM LOCAL` SQL command with `Cursor.execute()` to load data from local files or standard input into Vertica. It covers various scenarios including loading from multiple files, using STDIN, and handling rejected data.

```python
import sys
import vertica_python

conn_info = {'host': '127.0.0.1',
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             # False by default
             #'disable_copy_local': True,
             # Don't support executing COPY LOCAL operations with prepared statements
             'use_prepared_statements': False
             }

with vertica_python.connect(**conn_info) as connection:
    cur = connection.cursor()
    
    # Copy from local file
    cur.execute("COPY table(field1, field2) FROM LOCAL"
                " 'data_Jan_*.csv','data_Feb_01.csv' DELIMITER ','"
                " REJECTED DATA 'path/to/write/rejects.txt'"
                " EXCEPTIONS 'path/to/write/exceptions.txt'",
                buffer_size=65536
    )
    print("Rows loaded:", cur.fetchall())
    
    # Copy from local stdin
    cur.execute("COPY table(field1, field2) FROM LOCAL STDIN DELIMITER ','", copy_stdin=sys.stdin)
    print("Rows loaded:", cur.fetchall())

    # Copy from local stdin (compound statements)
    with open('f1.csv', 'r') as fs1, open('f2.csv', 'r') as fs2:
        cur.execute("COPY tlb1(field1, field2) FROM LOCAL STDIN DELIMITER ',';"
                    "COPY tlb2(field1, field2) FROM LOCAL STDIN DELIMITER ',';",
                    copy_stdin=[fs1, fs2], buffer_size=65536)
    print("Rows loaded 1:", cur.fetchall())
    cur.nextset()
    print("Rows loaded 2:", cur.fetchall())
    
    # Copy from local stdin (StringIO)
    from io import StringIO
    data = "Anna|123-456-789\nBrown|555-444-3333\nCindy|555-867-53093453453\nDodd|123-456-789\nEd|123-456-789"
    cur.execute("COPY customers (firstNames, phoneNumbers) FROM LOCAL STDIN ENFORCELENGTH RETURNREJECTED AUTO",
                copy_stdin=StringIO(data))

```

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

### Vertica-Python Cursor Execute Chaining

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Shows a shortcut for chaining `execute()` with fetch operations like `fetchone()` or `fetchall()` for more concise code.

```python
row = cursor.execute(...).fetchone()

for row in cur.execute(...).fetchall():
    ...
```

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

### Creating a New Git Branch

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

How to create a new branch for your development work with a descriptive name.

```shell
git checkout -b my-fix-branch
```

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

### Configuring Git User Information

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

Commands to set your global Git username and email address, essential for making commits.

```shell
git config --global user.name "John Smith"
git config --global user.email "email@example.com"
```

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

### Handling Multiple Statements and Results

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Illustrates how to execute a single SQL command containing multiple statements and how to iterate through the results of each statement using `nextset()`.

```python
# Assuming 'cur' is an active cursor
cur.execute("SELECT 1; SELECT 2; SELECT 3")

while True:
    rows = cur.fetchall()
    print(rows)
    if not cur.nextset():
        break
# Expected Output:
# [[1]]
# [[2]]
# [[3]]
```

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

### Customizing SSL with SSLContext

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates how to use Python's `ssl.SSLContext` object to customize underlying SSL connection options for Vertica connections, covering 'require', 'verify-ca', and 'verify-full' modes.

```python
import vertica_python
import ssl

# [TLSMode: require]
# Ensure connection is encrypted.
ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
ssl_context.check_hostname = False
ssl_context.verify_mode = ssl.CERT_NONE

conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'database': 'a_database',
             'ssl': ssl_context}
connection = vertica_python.connect(**conn_info)
```

```python
# [TLSMode: verify-ca]
# Ensure connection is encrypted, and client trusts server certificate.
ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
ssl_context.verify_mode = ssl.CERT_REQUIRED
ssl_context.check_hostname = False
ssl_context.load_verify_locations(cafile='/path/to/ca_file.pem') # CA certificate used to verify server certificate

conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'database': 'a_database',
             'ssl': ssl_context}
connection = vertica_python.connect(**conn_info)
```

```python
# [TLSMode: verify-full]
# Ensure connection is encrypted, client trusts server certificate,
# and server hostname matches the one listed in the server certificate.
ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
ssl_context.verify_mode = ssl.CERT_REQUIRED
ssl_context.check_hostname = True
ssl_context.load_verify_locations(cafile='/path/to/ca_file.pem') # CA certificate used to verify server certificate

conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'database': 'a_database',
             'ssl': ssl_context}
connection = vertica_python.connect(**conn_info)
```

```python
import vertica_python
import ssl

# [TLSMode: verify-full]
# Ensure connection is encrypted, client trusts server certificate,

```

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

### Staging and Committing Changes

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

Standard Git commands to stage all changes and create a commit. Commit messages should be descriptive and adhere to a 72-character line limit, including the issue number if applicable.

```shell
git add .
git commit -m 'Added two more tests for #166'
```

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

### Safe SQL Query Execution with Placeholders

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates the correct way to execute SQL queries using %s placeholders with vertica-python to prevent SQL injection. It shows the wrong way using string formatting and the correct way using parameter tuples.

```python
cur = connection.cursor()
data = (1, "O'Reilly")
cur.execute("SELECT * FROM a_table WHERE a = %s AND b = %s", data)  # correct
# converted into a SQL command: SELECT * FROM a_table WHERE a = 1 AND b = 'O''Reilly'

cur.fetchall()
# [ [1, "O'Reilly"] ]
```

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

### TLS/SSL Connection Modes

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Provides an overview of TLS/SSL modes ('disable', 'prefer', 'require', 'verify-ca', 'verify-full') and their corresponding 'ssl' parameter settings for Vertica connections.

```APIDOC
TLS/SSL Connection Modes:

- tlsmode: 'disable'
  ssl: False
  Description: Only try a non-TLS connection.

- tlsmode: 'prefer' (Default)
  ssl: (not set)
  Description: First try a TLS connection; if TLS is disabled on the server, then fallback to a non-TLS connection. If TLS is enabled on the server and TLS connection fails, the client rejects the connection.

- tlsmode: 'require'
  ssl: True
  Description: Connects using TLS without verifying certificates. If the TLS connection attempt fails, the client rejects the connection.

- tlsmode: 'verify-ca'
  ssl: (not set)
  Description: Connects using TLS and confirms that the server certificate has been signed by a trusted certificate authority.
  Requires: tls_cafile

- tlsmode: 'verify-full'
  ssl: (not set)
  Description: Connects using TLS, confirms that the server certificate has been signed by a trusted certificate authority, and verifies that the host name matches the name provided in the server certificate.
  Requires: tls_cafile
```

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

### Fetch All Results as Dictionary

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates how to fetch query results as a list of dictionaries, where keys are column names.

```python
# Assuming 'connection' is an active connection object
cur = connection.cursor('dict') # Specify 'dict' cursor
cur.execute("SELECT * FROM a_table LIMIT 2")
results = cur.fetchall()
print(results)
# Example Output:
# [ {'id': 1, 'value': 'something'}, {'id': 2, 'value': 'something_else'} ]
connection.close()
```

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

### Client-Side Binding with Named Parameters

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates client-side binding using named parameters (e.g., `:propA`) for SQL queries. This method requires `use_prepared_statements` to be `False` and automatically converts Python objects to SQL literals on the client side, offering robustness against SQL injection.

```python
cur = connection.cursor()
data = {'propA': 1, 'propB': 'stringValue'}
cur.execute("SELECT * FROM a_table WHERE a = :propA AND b = :propB", data, use_prepared_statements=False)
```

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

### Connection String Parsing

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Shows how to parse a connection string using `vertica_python.parse_dsn` and its integration with `vertica_python.connect`.

```python
import vertica_python

connection_str = ('vertica://admin@localhost:5433/db1?connection_load_balance=True&connection_timeout=1.5&' 
                  'session_label=vpclient+123%7E456')
print(vertica_python.parse_dsn(connection_str))
# Expected output: {'user': 'admin', 'host': 'localhost', 'port': 5433, 'database': 'db1', ...}
```

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

### Connection Failover Configuration

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates how to configure connection failover by providing a list of backup server nodes. The client will attempt to connect to these backup hosts if the primary host is unreachable. Each backup host can be a string (using the default port) or a (host, port) tuple.

```python
import vertica_python

conn_info = {'host': 'unreachable.server.com',
             'port': 888,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             'backup_server_node': ['123.456.789.123', 'invalid.com', ('10.20.82.77', 6000)]}
connection = vertica_python.connect(**conn_info)
```

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

### Server-Side Binding with Prepared Statements

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates using server-side prepared statements with question mark placeholders ('?') for executing SQL queries. This method sends the query and parameters separately to the server and is effective against SQL injection. It supports single statements and can be enabled at the connection level or overridden per execution.

```python
import vertica_python

conn_info = {'host': '127.0.0.1',
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             'use_prepared_statements': True,
             }

with vertica_python.connect(**conn_info) as connection:
    cur = connection.cursor()
    cur.execute("CREATE TABLE tbl (a INT, b VARCHAR)")
    cur.execute("INSERT INTO tbl VALUES (?, ?)", [1, 'aa'])
    cur.execute("INSERT INTO tbl VALUES (?, ?)", [2, 'bb'])
    cur.executemany("INSERT INTO tbl VALUES (?, ?)", [(3, 'foo'), (4, 'xx'), (5, 'bar')])
    cur.execute("COMMIT")

    cur.execute("SELECT * FROM tbl WHERE a>=? AND a<=? ORDER BY a", (2,4))
    cur.fetchall()
    # [[2, 'bb'], [3, 'foo'], [4, 'xx']]
```

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

### Handling Quoted Placeholders and Named Parameters

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Illustrates the correct usage of placeholders, especially when dealing with string literals and named parameters in INSERT statements. It highlights the incorrect practice of manually quoting placeholders.

```python
cur.execute("INSERT INTO table VALUES (:propA)", {'propA': "someString"})   # correct
cur.execute("INSERT INTO table VALUES (%s)", ("someString",))   # correct
```

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

### Automated Testing with Tox

Source: https://github.com/vertica/vertica-python/blob/master/requirements-dev.txt

Tox is a generic virtual environment management and test command line tool. It automates and standardizes testing in Python, ensuring your project works across different Python versions and environments.

```shell
tox
```

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

### Fetch All Results as List

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Shows the standard way to retrieve all rows from a query result set into a list of lists.

```python
# Assuming 'connection' is an active connection object
cur = connection.cursor()
cur.execute("SELECT * FROM a_table LIMIT 2")
results = cur.fetchall()
print(results)
# Example Output:
# [ [1, 'something'], [2, 'something_else'] ]
```

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

### Connection String Format

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Details the format of the connection string used for establishing database connections, including parameters and their structure.

```APIDOC
Connection String Format:

vertica://(user):(password)@(host):(port)/(database)?(arg1=val1&arg2=val2&...)

- The `(arg1=val1&arg2=val2&...)` section can handle string, numeric, and boolean values. Blank and invalid values are ignored.
- The connection string is parsed by `vertica_python.parse_dsn()`.
- The parsed result is merged with `**kwargs` in `vertica_python.connect()`. If a keyword exists in both sources, the `**kwargs` value overrides the parsed DSN value.
```

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

### Bulk Insert with executemany

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Shows how to efficiently insert multiple rows into a table using the `executemany` method, with options for prepared statements.

```python
# Assuming 'cur' is an active cursor and 'conn' is an active connection
# Insert data using prepared statements (recommended for performance)
cur.executemany("INSERT INTO tbl(a, b) VALUES (?, ?)", [(2, 'bb'), (3, 'foo'), (4, 'xx'), (5, 'bar')], use_prepared_statements=True)

# Insert data without prepared statements
# cur.executemany("INSERT INTO tbl(a, b) VALUES (%s, %s)", [(6, 'bb'), (7, 'foo'), (8, 'xx'), (9, 'bar')], use_prepared_statements=False)

# conn.commit() # Commit changes after operations
```

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

### Testing with Pytest

Source: https://github.com/vertica/vertica-python/blob/master/requirements-dev.txt

Pytest is a popular Python testing framework used to write simple and scalable tests. It discovers tests automatically and provides rich output for test results.

```shell
pytest
```

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

### Overriding Prepared Statements and Client-Side Binding

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Illustrates how to override the `use_prepared_statements` setting per `execute` call and demonstrates client-side binding using named parameters (`:name`) when server-side prepared statements are disabled. It highlights potential errors when mixing placeholders with incorrect `use_prepared_statements` settings.

```python
import vertica_python

conn_info = {'host': '127.0.0.1',
             'user': 'some_user',
             'password': 'some_password',
             'database': 'a_database',
             'use_prepared_statements': True,
             }

with vertica_python.connect(**conn_info) as connection:
    cur = connection.cursor()
    cur.execute("CREATE TABLE tbl (a INT, b VARCHAR)")

    # Executing compound statements
    cur.execute("INSERT INTO tbl VALUES (?, ?); COMMIT", [1, 'aa'])
    # Error message: Cannot insert multiple commands into a prepared statement

    # Disable prepared statements but forget to change placeholders (?)
    cur.execute("INSERT INTO tbl VALUES (?, ?); COMMIT;", [1, 'aa'], use_prepared_statements=False)
    # TypeError: not all arguments converted during string formatting

    cur.execute("INSERT INTO tbl VALUES (%s, %s); COMMIT;", [1, 'aa'], use_prepared_statements=False)
    cur.execute("INSERT INTO tbl VALUES (:a, :b); COMMIT;", {'a': 2, 'b': 'bb'}, use_prepared_statements=False)

# Disable using server-side prepared statements at connection level
conn_info['use_prepared_statements'] = False
with vertica_python.connect(**conn_info) as connection:
    cur = connection.cursor()

    # Try using prepared statements
    cur.execute("INSERT INTO tbl VALUES (?, ?)", [3, 'foo'])
    # TypeError: not all arguments converted during string formatting

    cur.execute("INSERT INTO tbl VALUES (?, ?)", [3, 'foo'], use_prepared_statements=True)

    # Query using named parameters
    cur.execute("SELECT * FROM tbl WHERE a>=:n1 AND a<=:n2 ORDER BY a", {'n1': 2, 'n2': 4})
    cur.fetchall()
    # [[2, 'bb'], [3, 'foo']]
```

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

### SSL Connection with Certificate Verification

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Establishes a secure connection to Vertica using SSL/TLS with client certificate verification. Requires a CA certificate file to verify the server's certificate and optionally client certificate and key files for mutual TLS authentication.

```python
import ssl
import vertica_python

ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)ssl_context.verify_mode = ssl.CERT_REQUIREDssl_context.check_hostname = Truessl_context.load_verify_locations(cafile='/path/to/ca_file.pem') # CA certificate used to verify server certificate

# For Mutual mode, provide client certificate and client private key to ssl_context.
# CA certificate used to verify client certificate should be set at the server side.
ssl_context.load_cert_chain(certfile='/path/to/client.pem', keyfile='/path/to/client.key')

conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'database': 'a_database',
             'ssl': ssl_context}
connection = vertica_python.connect(**conn_info)
```

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

### Pushing Local Branch to GitHub

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

Command to push your local branch to the remote repository on GitHub. This makes your changes available for review.

```shell
git push origin my-fix-branch
```

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

### Autocommit Configuration

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Explains how to configure and manage the autocommit setting for a Vertica connection using vertica-python. Autocommit can be enabled at connection startup or toggled dynamically using the `connection.autocommit` attribute. When autocommit is enabled, transactions are automatically committed upon completion of statements.

```APIDOC
Autocommit Setting:

  Configuration:
    - Enable autocommit at connection startup via the 'autocommit' parameter in connection info.
    - Example:
      conn_info = {
          'host': '127.0.0.1',
          'user': 'some_user',
          'password': 'some_password',
          'database': 'a_database',
          'autocommit': True
      }

  Dynamic Control:
    - Set the autocommit status using the `connection.autocommit` attribute.
    - Example:
      connection.autocommit = False

  Behavior:
    - If autocommit is True: Statements automatically commit their transactions.
    - If autocommit is False: `commit()` or `rollback()` must be manually invoked.

  Important Note:
    - If changing autocommit status after fetching results, ensure results are fetched before modifying the setting, as `Cursor.execute()` is used internally and can clear previous query results.
```

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

### Apache 2.0 License Header

Source: https://github.com/vertica/vertica-python/blob/master/CONTRIBUTING.md

The required Apache 2.0 license header for all files in the project. Ensure the year is updated accordingly. This header must be included at the top of every file.

```text
Copyright (c) [yyyy] Open Text.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

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

### Registering Custom SQL Literal Adapters

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Demonstrates how to extend vertica-python's capabilities by registering custom adapter functions for Python types that are not natively supported. This allows for custom serialization of objects into SQL literals.

```python
class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

# Adapter should return a string value
def adapt_point(point):
    return "STV_GeometryPoint({},{})".format(point.x, point.y)

cur = conn.cursor()
cur.register_sql_literal_adapter(Point, adapt_point)

cur.execute("INSERT INTO geom_data (geom) VALUES (%s)", [Point(1.23, 4.56)])
cur.execute("select ST_asText(geom) from geom_data")
cur.fetchall()
# [['POINT (1.23 4.56)']]

```

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

### Binary Data Transfer Configuration

Source: https://github.com/vertica/vertica-python/blob/master/README.md

Shows how to configure the vertica-python client to use binary data transfer format instead of the default text format. Binary transfer is generally more efficient for large data but can have slight precision differences for FLOAT and timezone handling for TIMESTAMPTZ compared to text.

```python
import vertica_python

conn_info = {'host': '127.0.0.1',
             'port': 5433,
             'user': 'some_user',
             'password': 'some_password',
             'database': 'vdb',
             'binary_transfer': True  # False by default
             }

# Server enables binary transfer
with vertica_python.connect(**conn_info) as conn:
    cur = conn.cursor()
    ...
```