natural-query-lib 0.1.3

Flexible SQL query builder written in Python! This library allows you to build and execute SQL queries with ease, while supporting dynamic parameters and JSON encoding for database compatibility.

natural_query_lib

natural_query_lib is a lightweight Python library designed to simplify SQL query building and execution. It combines a fluent API with dynamic parameter binding and JSON support, making it easier for developers to work with SQL databases in an efficient and Pythonic way.

---

🚀 Features

• Dynamic Query Building: Supports SELECT, INSERT, UPDATE, and DELETE queries with a clean, fluent interface.
• Dynamic Parameters: Easily pass parameters to queries for security and flexibility.
• JSON Encoding: Seamless integration with JSON to handle complex data structures.
• Asynchronous Execution: Built-in support for async query execution using asyncpg.
• Joins and Advanced Clauses: Build queries with joins, grouping, ordering, and limits effortlessly.
• Developer-Friendly: Lightweight, easy-to-learn, and focused on productivity.

---

📦 Installation

Install the library directly from PyPI:

pip install natural_query_lib

---

🛠️ Usage Examples

1. Build a Simple SELECT Query

from natural_query_lib import QueryBuilder, QueryType

query = (
    QueryBuilder(QueryType.SELECT)
    .from_table("users")
    .select_columns(["id", "name", "email"])
    .where("age > %s", [18])
    .set_limit(10)
    .build()
)

print(query)  # Output: SELECT id, name, email FROM users WHERE age > %s LIMIT 10

---

2. Execute Queries with Asyncpg

import asyncio
from natural_query_lib import QueryExecutor


async def main():
    executor = QueryExecutor("postgresql://user:password@localhost:5432/mydb")
    await executor.connect()

    query = "SELECT * FROM users WHERE age > $1"
    params = [18]

    results = await executor.fetch(query, params)
    for row in results:
        print(dict(row))

    await executor.close()


asyncio.run(main())

---

3. INSERT Data with JSON Support

from natural_query_lib import QueryBuilder, QueryType

query_builder = (
    QueryBuilder(QueryType.INSERT)
    .from_table("users")
    .values_json({
        "name": "John Doe",
        "email": "[e-mail]",
        "profile": {"age": 30, "location": "USA"}
    })
)

query = query_builder.build()
params = query_builder.get_parameters()

print(query)  # Output: INSERT INTO users (name, email, profile) VALUES (%s, %s, %s)
print(params)  # Output: ["John Doe", "[e-mail]", '{"age": 30, "location": "USA"}']

---

4. Complex Query with Joins

from natural_query_lib import QueryBuilder, QueryType, JoinType

query = (
    QueryBuilder(QueryType.SELECT)
    .from_table("orders o")
    .select_columns(["o.id", "o.total", "u.name"])
    .join(JoinType.INNER, "users u", "o.user_id = u.id")
    .where("o.total > %s", [100])
    .order_by_columns(["o.total DESC"])
    .build()
)

print(
    query)  # Output: SELECT o.id, o.total, u.name FROM orders o INNER JOIN users u ON o.user_id = u.id WHERE o.total > %s ORDER BY o.total DESC

---

🌟 Why Choose Natural Query?

✅ Fluent and Intuitive

• Build queries step by step in a readable and maintainable manner.

✅ Secure and Dynamic

• Parameterized queries help prevent SQL injection attacks.

✅ Asynchronous Execution

• Leverages asyncpg for high-performance database interactions.

✅ JSON Ready

• Easily handle JSON data structures without additional transformations.

✅ Lightweight

• Minimal dependencies and optimized for performance.

---

🤝 Contributing

We welcome contributions to make Natural Query even better! Feel free to:

• Report bugs or suggest features by opening an issue.
• Submit pull requests to improve functionality.

---

📜 License

Natural Query is licensed under the MIT License. See the LICENSE file for details.

---

Happy coding! 🎉