{"id":6910,"library":"tentaclio-postgres","title":"Tentaclio PostgreSQL Connector","description":"Tentaclio-postgres is a Python package that provides the necessary dependencies and extends the core Tentaclio library to enable seamless connections to PostgreSQL databases. It acts as a connector, allowing users to interact with PostgreSQL via Tentaclio's unified URL-based interface for data streams and database clients. The current version is 0.0.1. It is part of the broader Tentaclio ecosystem, which shows active development and updates.","status":"active","version":"0.0.1","language":"en","source_language":"en","source_url":"https://github.com/octoenergy/tentaclio","tags":["database","postgresql","tentaclio","connector","io","data access"],"install":[{"cmd":"pip install tentaclio-postgres","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core library providing the unified API for I/O and database connections.","package":"tentaclio"},{"reason":"Common PostgreSQL driver implicitly installed by tentaclio-postgres for synchronous connections.","package":"psycopg2-binary","optional":true},{"reason":"Used by tentaclio for database abstraction and ORM capabilities.","package":"sqlalchemy","optional":true}],"imports":[{"note":"The primary interaction is through the main 'tentaclio' library's `db` function, not directly from 'tentaclio_postgres'.","symbol":"tentaclio","correct":"import tentaclio"}],"quickstart":{"code":"import os\nimport tentaclio\n\n# Configure a PostgreSQL connection string (replace with your actual URL)\n# For local testing, you might use 'postgresql://user:password@localhost:5432/mydatabase'\n# Credentials can also be injected via environment variables (e.g., TENTACLIO__CONN__MYDB_PG_URL)\n# For this example, we'll use a placeholder and demonstrate env var usage for a real setup.\n# os.environ['TENTACLIO__CONN__EXAMPLE_PG'] = 'postgresql://user:password@host:port/database'\n\npg_url = os.environ.get('TENTACLIO__CONN__EXAMPLE_PG', 'postgresql://user:password@localhost:5432/testdb')\n\ntry:\n    with tentaclio.db(pg_url) as client:\n        print(f\"Successfully connected to PostgreSQL via Tentaclio using URL: {pg_url}\")\n        # Execute a simple query\n        result = client.query(\"SELECT 1 as test_column\")\n        print(f\"Query result: {result.fetchone()}\")\nexcept Exception as e:\n    print(f\"Could not connect to PostgreSQL or execute query: {e}\")\n    print(\"Please ensure a PostgreSQL database is running and the connection string is valid.\")\n","lang":"python","description":"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__`."},"warnings":[{"fix":"Always use the main `tentaclio` library for database and stream operations, relying on `tentaclio-postgres` to provide the underlying PostgreSQL connectivity.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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')`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.0.1"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}