Tentaclio PostgreSQL Connector

Warnings

• gotcha Direct import of `tentaclio_postgres` components is generally not needed. Its primary function is to extend the `tentaclio` library, so interactions are usually through `import tentaclio` and then using `tentaclio.db()` or `tentaclio.open()` with a `postgresql://` URL scheme.
  Fix: Always use the main `tentaclio` library for database and stream operations, relying on `tentaclio-postgres` to provide the underlying PostgreSQL connectivity.
• gotcha When writing data to a PostgreSQL table directly from a stream, Tentaclio uses a specific URL syntax: `postgresql://host/database::table`. Forgetting the `::table` part will lead to errors if you intend to stream data directly into a table.
  Fix: Ensure the correct `::table` suffix is appended to the PostgreSQL URL when specifying a target table for write operations (e.g., `tentaclio.open('postgresql://host/db::my_table', mode='w')`).
• gotcha Tentaclio supports automatic credential injection from environment variables. While convenient, expecting credentials only via the URL string or misconfiguring environment variables can lead to connection failures. Specifically, `TENTACLIO__PG_APPLICATION_NAME` can set the application name for PostgreSQL connections.
  Fix: Be aware of the environment variable precedence for credentials and connection parameters. Consult the main `tentaclio` documentation for full details on automatic credential injection via `TENTACLIO__CONN__` prefixed variables and database-specific settings like `TENTACLIO__PG_APPLICATION_NAME`.
• gotcha The `tentaclio-postgres` package is currently at version 0.0.1. This indicates it is either a very early-stage project, a meta-package, or its versioning doesn't strictly follow semantic versioning for feature changes but rather its integration readiness. Users should be aware of the project's maturity when adopting.
  Fix: Monitor the PyPI page or GitHub repository for updates and consult the `tentaclio` documentation for details on recommended versions or stability guarantees for database connectors.

Install

• pip install tentaclio-postgres Install stable version

Imports

• tentaclio

  import tentaclio

  The primary interaction is through the main 'tentaclio' library's `db` function, not directly from 'tentaclio_postgres'.

Quickstart

This quickstart demonstrates how to establish a connection to a PostgreSQL database using `tentaclio.db()`. It highlights the use of a PostgreSQL URL and shows how to execute a simple query. Credentials can be provided directly in the URL or automatically injected from environment variables, prefixed with `TENTACLIO__CONN__`.

import os
import tentaclio

# Configure a PostgreSQL connection string (replace with your actual URL)
# For local testing, you might use 'postgresql://user:password@localhost:5432/mydatabase'
# Credentials can also be injected via environment variables (e.g., TENTACLIO__CONN__MYDB_PG_URL)
# For this example, we'll use a placeholder and demonstrate env var usage for a real setup.
# os.environ['TENTACLIO__CONN__EXAMPLE_PG'] = 'postgresql://user:password@host:port/database'

pg_url = os.environ.get('TENTACLIO__CONN__EXAMPLE_PG', 'postgresql://user:password@localhost:5432/testdb')

try:
    with tentaclio.db(pg_url) as client:
        print(f"Successfully connected to PostgreSQL via Tentaclio using URL: {pg_url}")
        # Execute a simple query
        result = client.query("SELECT 1 as test_column")
        print(f"Query result: {result.fetchone()}")
except Exception as e:
    print(f"Could not connect to PostgreSQL or execute query: {e}")
    print("Please ensure a PostgreSQL database is running and the connection string is valid.")