Metadata-Version: 2.4
Name: explicit-sql
Version: 0.0.4
Summary: Human mind friendly SQL generator
Author-email: Ivan Zakutnii <zakutnii.ivan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: database,duckdb,orm-alternative,python,python310,python311,python312,sql,sql-generator,type-safe,typeddict
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: SQL
Classifier: Topic :: Database
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# explicit-sql

A human mind friendly SQL generator for DuckDB.

## Overview

I genuinely do not like ORMs because of the Object–relational impedance mismatch. 
While we have many good ORMs that can speed up development of POCs and MVPs drastically, 
this project aims at a simpler idea: implement a human mind friendly and type-safe SQL generator for all basic operations:

- CREATE TABLE
- DROP TABLE
- INSERT INTO
- SELECT FROM
- UPDATE
- DELETE
- And more...

I found myself developing this when working on simple side-projects using DuckDB and realized there was no interface to generate SQL queries from TypedDict definitions.

## Philosophy

The goal is to stay as close to "raw" Python as possible. 
For table schemas, I chose TypedDict, and besides that have only two classes:

1. TableConfig - for configuration settings
2. ExplicitTable - a container class for both the TypedDict definition and config

This minimalist approach should be enough to achieve a useful, type-safe SQL generator without the complexity of ORMs.

## Requirements

- Python 3.10+

## Installation

```bash
pip install explicit-sql
```

## Quick Example

```python
from explicit_sql import TableDefinition, TableConfig, ExplicitTable, create_table_sql

# Define your table schema
class UsersTable(TableDefinition):
    id: int
    name: str
    is_active: bool | None

users_config = TableConfig(
    name="users",
    schema="public",
    primary_key_name="id",
    primary_key_type=int,
)

users_table = ExplicitTable(
    config=users_config,
    table_definition=UsersTable
)

create_table_sql = create_table_sql(users_table)
print(create_table_sql)

insert_payload: UsersTable = {
    "amount": 500,
    "name": "John Doe",
    "is_active": True,
}
print(insert_sql(users_table, insert_payload))


print(
    select_sql(
        users_table,
        select_columns=["name", "amount"],
        where_values={"is_active": True},
        order_by=["amount"],
        limit=10,
    )
)

# Select all columns
print(select_sql(users_table, limit=10))

```

## Roadmap

See the [milestone plan](milestone_plan.md) for the development roadmap.

## License

MIT
