SQLconnect 0.2.0
Package to simplify connections to SQL databases.
Keywords: SQL database connection configuration

<div align="center">
  <img alt="SQLconnect logo" src="https://raw.githubusercontent.com/JustinFrizzell/SQLconnect/main/images/logo.png"><br>
</div>

---

<p align="center">
<a href="https://pypi.org/project/SQLconnect/"><img alt="PyPI" src="https://img.shields.io/pypi/v/SQLconnect"></a>
<a href='https://sqlconnect.readthedocs.io/en/latest/?badge=latest'><img src='https://readthedocs.org/projects/sqlconnect/badge/?version=latest' alt='Documentation Status' /></a>
<a href="https://github.com/JustinFrizzell/SQLconnect/blob/main/LICENCE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-purple.svg"></a>
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
</p>

**SQLconnect** is a Python package designed to simplify the process of connecting to SQL databases. It uses a `connections.yaml` file for database configuration and a `.env` file for secure credentials management. SQLconnect supports executing SQL from `.sql` files or Python strings, and retrieving data into pandas DataFrames. This package is particularly useful for data analysts and developers who need a straightforward way to interact with SQL databases.

## Features

- Allows easy configuration and management of database connections using a `connections.yaml` file.

- Supports the use of a `.env` file for secure storage of database credentials, enhancing security.

- Leverages SQLAlchemy for database connections, providing a robust and flexible framework for SQL operations.

- Enables executing SQL queries and directly retrieving the results into pandas DataFrames, facilitating easy data manipulation and analysis.

- Capable of handling multiple database connections, allowing users to switch between different databases as needed.

- Provides functionality to execute SQL queries either by reading from an external file or directly from a string.

## Installation

```bash
pip install SQLconnect
```

## Configuration

To use SQLconnect, create a `connections.yaml` file in the root of your project (or in your home directory) with the following example structure:

```yaml
connections:
  Database_PROD:
    sqlalchemy_driver: 'mssql+pyodbc'
    odbc_driver: 'SQL+Server'
    server: 'prod-server.database.com'
    database: 'ProdDB'
    username: '${DB_PROD_USERNAME}' # References DB_PROD_USERNAME in .env
    password: '${DB_PROD_PASSWORD}' # References DB_PROD_PASSWORD in .env
    options:
      - 'Trusted_Connection=No'
```

Also create a `.env` file in the root of your project (or in your home directory) with the following example structure:

```bash
# This file should be kept secure and not checked into version control (add to .gitignore)
# Production Database Credentials
DB_PROD_USERNAME=prodUser
DB_PROD_PASSWORD=prodPassword
```

Replace the example values with your actual database connection details.

## Usage

Here's a quick example to get you started:

```python
import SQLconnect as sc

# Set up a database connection, all configuration is handled with connections.yaml and .env
connection = sc.SQLconnector("Database_PROD")

# Assign the results of a query to a pandas DataFrame
df = connection.sql_to_df("your_query.sql")

# Explore the dataframe with pandas
print(df.describe())
```

## Documentation

Full documentation for SQLconnect can be found at https://sqlconnect.readthedocs.io/

## License

This project is licensed under the [MIT License](https://raw.githubusercontent.com/JustinFrizzell/SQLconnect/main/LICENCE).