Metadata-Version: 2.4
Name: pypsql
Version: 0.0.3a0
Summary: Functionality to connect and interact with PostgreSQL servers
Author-email: Marius Liebald <maliedvp@gmail.com>
Project-URL: Homepage, https://www.marius-liebald.com/pypsql/
Project-URL: Documentation, https://www.marius-liebald.com/pypsql/
Project-URL: Source Code, https://github.com/maliedvp/pypsql
Project-URL: Bug Tracker, https://github.com/maliedvp/pypsql/issues
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pandas>=2.2.3
Requires-Dist: sqlalchemy>=2.0.41
Requires-Dist: sshtunnel>=0.4.0
Requires-Dist: psycopg2>=2.9.10
Requires-Dist: python-dotenv>=1.1.1
Provides-Extra: postgres
Requires-Dist: psycopg2>=2.9.10; extra == "postgres"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Dynamic: license-file

# pypSQL


<a href="https://www.marius-liebald.com/pypsql/index.html" style="float:right; margin-left:10px;">
<img src="docs/source/_static/img/pypsql_logo_dark.png" style="height:139px !important; width:auto !important;" alt="pypsql utilities website" />
</a>

<!-- badges: start -->

![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
<!-- badges: end -->

`pypsql` is a lightweight framework for connecting to PostgreSQL
databases, whether locally or remotely hosted. It builds on top of
[`SQLAlchemy`](https://www.sqlalchemy.org/) to provide a simple,
Pythonic interface for establishing connections, running queries, and
managing database sessions.

# Contributors

[Marius Liebald](https://www.marius-liebald.de) (maintainer)

# Installation

``` bash
pip install pypsql
```

# Basic Usage

## Provide database credentials

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

``` python
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:

``` python
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](LICENSE.txt).

# References

<div id="refs" class="references csl-bib-body hanging-indent"
entry-spacing="0">

<div id="ref-sqlalchemy2025" class="csl-entry">

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

</div>

</div>
