PostgreSQL Database Wrapper

Common errors

• ModuleNotFoundError: No module named 'pgdb'

  cause The `pgdb` library is not installed in your Python environment.
  fix Install the library using pip: `pip install pgdb`

• psycopg2.OperationalError: connection to server at "localhost" (::1), port 5432 failed: FATAL: password authentication failed for user "postgres"

  cause Incorrect database connection parameters (host, port, database name, user, or password) or the PostgreSQL server is not running/accessible.
  fix Double-check the `host`, `database`, `user`, and `password` arguments passed to `pgdb.connect()`. Ensure your PostgreSQL server is running and accessible from your application's environment.

• AttributeError: 'module' object has no attribute 'connect'

  cause This error can occur if you attempt to access `connect` incorrectly, for example, after a `from pgdb import *` or if the module itself is shadowed.
  fix Always import `pgdb` as a module (`import pgdb`) and then call the function via the module namespace (`pgdb.connect(...)`). Ensure no other file or module named `pgdb.py` is in your Python path that might shadow the installed library.

Warnings

• gotcha `pgdb` specifically requires `psycopg2-binary`. If you have `psycopg2` installed, `pgdb` might attempt to use it, but its `setup.py` explicitly lists `psycopg2-binary`.
  Fix: Ensure `psycopg2-binary` is installed: `pip install psycopg2-binary`. If you have `psycopg2` and encounter issues, consider uninstalling it before installing `pgdb`.
• gotcha As a simple wrapper, `pgdb` offers basic database interaction but lacks advanced features like ORM capabilities, sophisticated connection pooling, or asynchronous operations found in larger, more actively maintained libraries (e.g., SQLAlchemy, asyncpg).
  Fix: Evaluate your project's needs. For complex applications requiring advanced features, consider using `psycopg2` directly or a more comprehensive ORM/database client library.
• deprecated The `pgdb` library has not been updated since February 2022, indicating a lack of active development or maintenance. This could lead to compatibility issues with newer Python versions or PostgreSQL features.
  Fix: For new projects or long-term critical applications, consider using more actively maintained PostgreSQL libraries like `psycopg2` (or `psycopg` for Python 3.7+), `psycopg2-binary`, or ORMs like SQLAlchemy that have robust community support and regular updates.

Install

• pip install pgdb Install pgdb

Imports

• connect

  import pgdb

  The `connect` function is directly accessible as `pgdb.connect` after importing the `pgdb` module.

Quickstart

This quickstart demonstrates how to establish a connection, create a table, insert data, and fetch results using `pgdb`. It utilizes environment variables for database credentials, falling back to common defaults for local testing. It also includes basic error handling and resource cleanup.

import pgdb
import os

DB_HOST = os.environ.get('PGDB_HOST', 'localhost')
DB_NAME = os.environ.get('PGDB_DATABASE', 'test_db')
DB_USER = os.environ.get('PGDB_USER', 'postgres')
DB_PASS = os.environ.get('PGDB_PASSWORD', 'mysecretpassword') # REMEMBER to change in prod

conn = None
try:
    conn = pgdb.connect(host=DB_HOST, database=DB_NAME, user=DB_USER, password=DB_PASS)
    cursor = conn.cursor()

    # Cleanup for re-runs and create table
    cursor.execute("DROP TABLE IF EXISTS example_data;")
    cursor.execute("CREATE TABLE example_data (id SERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL);")
    conn.commit()

    # Insert data
    cursor.execute("INSERT INTO example_data (name) VALUES ('Alice'), ('Bob'), ('Charlie');")
    conn.commit()

    # Fetch and print data
    cursor.execute("SELECT id, name FROM example_data;")
    print("Fetched data:")
    for row in cursor.fetchall():
        print(row)

except pgdb.Error as e:
    print(f"Database error: {e}")
    if conn:
        conn.rollback() # Rollback on error
finally:
    if conn:
        conn.close()