Metadata-Version: 2.1
Name: sql_via_code
Version: 0.1.6
Summary: A Python package to execute SQL queries and procedures and manage backups.
Author: Afik Ratzon
Author-email: afik.ratzon@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: aiofiles==24.1.0
Requires-Dist: aiomysql==0.2.0
Requires-Dist: aioodbc==0.5.0
Requires-Dist: aiosqlite==0.20.0
Requires-Dist: asyncpg==0.30.0
Requires-Dist: backports.tarfile==1.2.0
Requires-Dist: build==1.2.2.post1
Requires-Dist: certifi==2024.8.30
Requires-Dist: cffi==1.17.1
Requires-Dist: charset-normalizer==3.4.0
Requires-Dist: colorama==0.4.6
Requires-Dist: cryptography==44.0.0
Requires-Dist: docutils==0.21.2
Requires-Dist: greenlet==3.1.1
Requires-Dist: idna==3.10
Requires-Dist: importlib_metadata==8.5.0
Requires-Dist: iniconfig==2.0.0
Requires-Dist: jaraco.classes==3.4.0
Requires-Dist: jaraco.context==6.0.1
Requires-Dist: jaraco.functools==4.1.0
Requires-Dist: keyring==25.5.0
Requires-Dist: markdown-it-py==3.0.0
Requires-Dist: mdurl==0.1.2
Requires-Dist: more-itertools==10.5.0
Requires-Dist: nh3==0.2.19
Requires-Dist: numpy==2.1.3
Requires-Dist: oracledb==2.5.1
Requires-Dist: packaging==24.2
Requires-Dist: pandas==2.2.3
Requires-Dist: pkginfo==1.11.2
Requires-Dist: pluggy==1.5.0
Requires-Dist: pycparser==2.22
Requires-Dist: Pygments==2.18.0
Requires-Dist: PyMySQL==1.1.1
Requires-Dist: pyodbc==5.2.0
Requires-Dist: pyproject_hooks==1.2.0
Requires-Dist: pytest==8.3.4
Requires-Dist: pytest-asyncio==0.24.0
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: pytz==2024.2
Requires-Dist: pywin32-ctypes==0.2.3
Requires-Dist: readme_renderer==44.0
Requires-Dist: requests==2.32.3
Requires-Dist: requests-toolbelt==1.0.0
Requires-Dist: rfc3986==2.0.0
Requires-Dist: rich==13.9.4
Requires-Dist: setuptools==75.6.0
Requires-Dist: six==1.16.0
Requires-Dist: SQLAlchemy==2.0.36
Requires-Dist: tabulate==0.9.0
Requires-Dist: twine==6.0.1
Requires-Dist: typing_extensions==4.12.2
Requires-Dist: tzdata==2024.2
Requires-Dist: urllib3==2.2.3
Requires-Dist: wheel==0.45.1
Requires-Dist: zipp==3.21.0

# sql_via_code

## Overview

sql_via_code is a library for executing SQL queries, stored procedures, table backups, and reading queries from files, all with a clean and simple interface.

---

## Features

1. **Query Execution**: Execute SQL queries and fetch the results as a pandas DataFrame.
2. **Stored Procedure Execution**: Run stored procedures with input parameters.
3. **Table Backup**: Automatically back up a specified table's data before executing a query or procedure.
4. **Query from File**: Read SQL queries from external files to improve maintainability.

---

## Functions

### `get_query_from_db`
Executes a SQL query and optionally backs up a table.

#### Parameters:
- `query` *(str)*: SQL query to execute.
- `table_to_backup` *(str or None)*: Table to back up. Pass `None` to skip the backup.
- `env_file_name` *(str, optional)*: Path to the `.env` file for database credentials (default is `.env`).
- `params` *(dict, optional)*: Query parameters.

#### Returns:
- A `pandas.DataFrame` containing query results.

---

### `exec_procedure_from_db`
Executes a stored procedure and optionally backs up a table.

#### Parameters:
- `procedure_name` *(str)*: Name of the stored procedure.
- `table_to_backup` *(str or None)*: Table to back up. Pass `None` to skip the backup.
- `env_file_name` *(str, optional)*: Path to the `.env` file for database credentials (default is `.env`).
- `params` *(dict, optional)*: Procedure parameters.

#### Returns:
- A `pandas.DataFrame` containing procedure output.

---

### `get_query_from_file`
Reads a SQL query from a file.

#### Parameters:
- `file_path` *(str)*: Path to the `.sql` or `.txt` file containing the query.

#### Returns:
- A `str` containing the SQL query.

#### Example:
```python
from sql_via_code import get_query_from_file, get_query_from_db

query = get_query_from_file("queries/select_employees.sql")
result_df = await get_query_from_db(query, table_to_backup="employees")
print(result_df)
```

---

## Installation

To install the package and dependencies:

```bash
pip install sql_via_code
```

---

## Dependencies

The project requires the following libraries:

- `pandas==2.2.3`
- `SQLAlchemy==2.0.36`
- `python-dotenv==1.0.1`
- `pyodbc==5.2.0`
- `aiofiles==24.1.0`
- `tabulate==0.9.0`
- `asyncpg==0.30.0` *(for PostgreSQL)*
- `aiomysql==0.2.0` *(for MySQL)*
- `aiosqlite==0.20.0` *(for SQLite)*

---

## Environment Setup

Ensure you have a `.env` file in the root directory with the following database configuration:

```plaintext
DB_TYPE=your_db_type
USER=your_username
PASSWORD=your_password
HOST=your_host
NAME=your_database_name
DRIVER=your_driver
```

Example `.env` file for MSSQL:

```plaintext
DB_TYPE=mssql
USER=admin
PASSWORD=secretpassword
HOST=127.0.0.1
NAME=my_database
DRIVER=ODBC Driver 17 for SQL Server
```

Example `.env` file for SQLite:

```plaintext
DB_TYPE=sqlite
NAME=example.db
```

---

## Usage Examples

### Example 1: Executing a Query with Backup

```python
from sql_via_code import get_query_from_db

query = "SELECT * FROM employees"
result_df = await get_query_from_db(query, table_to_backup="employees")
print(result_df)
```

---

### Example 2: Executing a Stored Procedure

```python
from sql_via_code import exec_procedure_from_db

procedure_name = "sp_get_employee_data"
params = {"department": "Sales"}
result_df = await exec_procedure_from_db(procedure_name, table_to_backup="employees", params=params)
print(result_df)
```

---

### Example 3: Reading Query from File

```python
from sql_via_code import get_query_from_file, get_query_from_db

query = get_query_from_file("queries/select_employees.sql")
result_df = await get_query_from_db(query, table_to_backup="employees")
print(result_df)
```

---

## Supported Databases

| Database    | DB_TYPE   | Required Fields                                    |
|-------------|-----------|----------------------------------------------------|
| SQLite      | sqlite    | NAME                                               |
| PostgreSQL  | postgresql| USER, PASSWORD, HOST, NAME                         |
| MySQL       | mysql     | USER, PASSWORD, HOST, NAME                         |
| MSSQL       | mssql     | USER, PASSWORD, HOST, NAME, DRIVER                 |
| Oracle      | oracle    | USER, PASSWORD, HOST, NAME                         |

---

## License

MIT License
