pypsql 0.0.3a0

Functionality to connect and interact with PostgreSQL servers

pypSQL

pypsql is a lightweight framework for connecting to PostgreSQL databases, whether locally or remotely hosted. It builds on top of SQLAlchemy to provide a simple, Pythonic interface for establishing connections, running queries, and managing database sessions.

Contributors

Marius Liebald (maintainer)

Installation

pip install pypsql

Basic Usage

Provide database credentials

You can store the database connection details in a file, for example:

SERVER=<host name or address>   # e.g., localhost, 127.0.0.1, or a public IP
PORT=<port number>              # default: 5432
NAME_DATABASE=<database name>   # e.g., my_db
NAME_USER=<role>                # e.g., Alice
PASSWORD_USER=<password>        # e.g., 123abc

You may place this file anywhere on the client machine. Importantly, this step is optional. You can also provide the variables interactively via terminal prompts.

No SSH required

An SSH tunnel is not needed if:

• the server and client run on the same machine,
• the server and client are in the same (virtual) network, or
• the server is accessible via its public IP.

In this case, simply run the Python script:

import pypsql
from pathlib import Path

conn = pypsql.DatabaseConnector(
    path=Path(<path to the credential file>), # e.g., "/Users/marius/Desktop/" # if the .env file is located in the same directory as the script you are executing, you can leave this argument undefined
    db_credential_file=<name of credential file>   # e.g., ".env" (default) or "credentials.py"
)

sql_script = """
SELECT *
FROM customers
"""

df = conn.get_data(sql_script)

print(df)

Note that this example assumes the database contains a table named customers.

Connection via SSH

To be filled.

Official Documentation

The documentation is hosted under https://www.marius-liebald.com/pypsql/index.html

License

The package is distributed under the MIT license.

References

Bayer, Michael, and contributors. 2025. “SQLAlchemy.” https://www.sqlalchemy.org/.