Added something new

Author: Peng Ren

README.md

@@ -1,2 +1,233 @@
 # PyMongoSQL
-Python DB API 2.0 (PEP 249) client for MongoDB
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![MongoDB](https://img.shields.io/badge/MongoDB-4.0+-green.svg)](https://www.mongodb.com/)
+
+PyMongoSQL is a Python [DB API 2.0 (PEP 249)](https://www.python.org/dev/peps/pep-0249/) client for [MongoDB](https://www.mongodb.com/). It provides a familiar SQL interface to MongoDB, allowing developers to use SQL queries to interact with MongoDB collections.
+
+## Objectives
+
+PyMongoSQL implements the DB API 2.0 interfaces to provide SQL-like access to MongoDB. The project aims to:
+
+- Bridge the gap between SQL and NoSQL by providing SQL query capabilities for MongoDB
+- Support standard SQL DQL (Data Query Language) operations including SELECT statements with WHERE, ORDER BY, and LIMIT clauses
+- Provide seamless integration with existing Python applications that expect DB API 2.0 compliance
+- Enable easy migration from traditional SQL databases to MongoDB
+- Support field aliasing and projection mapping for flexible result set handling
+- Maintain high performance through direct `db.command()` execution instead of high-level APIs
+
+## Features
+
+- **DB API 2.0 Compliant**: Full compatibility with Python Database API 2.0 specification
+- **SQL Query Support**: SELECT statements with WHERE conditions, field selection, and aliases
+- **MongoDB Native Integration**: Direct `db.command()` execution for optimal performance
+- **Connection String Support**: MongoDB URI format for easy configuration
+- **Result Set Handling**: Support for `fetchone()`, `fetchmany()`, and `fetchall()` operations
+- **Field Aliasing**: SQL-style field aliases with automatic projection mapping
+- **Context Manager Support**: Automatic resource management with `with` statements
+- **Transaction Ready**: Architecture designed for future DML operation support (INSERT, UPDATE, DELETE)
+
+## Requirements
+
+- **Python**: 3.9, 3.10, 3.11, 3.12, 3.13+
+- **MongoDB**: 4.0+
+
+## Dependencies
+
+- **PyMongo** (MongoDB Python Driver)
+  - pymongo >= 4.15.0
+
+- **ANTLR4** (SQL Parser Runtime)
+  - antlr4-python3-runtime >= 4.13.0
+
+## Installation
+
+```bash
+pip install pymongosql
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/your-username/PyMongoSQL.git
+cd PyMongoSQL
+pip install -e .
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from pymongosql import connect
+
+# Connect to MongoDB
+connection = connect(
+    host="mongodb://localhost:27017",
+    database="test_db"
+)
+
+cursor = connection.cursor()
+cursor.execute('SELECT name, email FROM users WHERE age > 25')
+print(cursor.fetchall())
+```
+
+### Using Connection String
+
+```python
+from pymongosql import connect
+
+# Connect with authentication
+connection = connect(
+    host="mongodb://username:password@localhost:27017/database?authSource=admin"
+)
+
+cursor = connection.cursor()
+cursor.execute('SELECT * FROM products WHERE category = ?', ['Electronics'])
+
+for row in cursor:
+    print(row)
+```
+
+### Context Manager Support
+
+```python
+from pymongosql import connect
+
+with connect(host="mongodb://localhost:27017", database="mydb") as conn:
+    with conn.cursor() as cursor:
+        cursor.execute('SELECT COUNT(*) as total FROM users')
+        result = cursor.fetchone()
+        print(f"Total users: {result['total']}")
+```
+
+### Field Aliases and Projections
+
+```python
+from pymongosql import connect
+
+connection = connect(host="mongodb://localhost:27017", database="ecommerce")
+cursor = connection.cursor()
+
+# Use field aliases for cleaner result sets
+cursor.execute('''
+    SELECT 
+        name AS product_name,
+        price AS cost,
+        category AS product_type
+    FROM products 
+    WHERE in_stock = true
+    ORDER BY price DESC
+    LIMIT 10
+''')
+
+products = cursor.fetchall()
+for product in products:
+    print(f"{product['product_name']}: ${product['cost']}")
+```
+
+### Query with Parameters
+
+```python
+from pymongosql import connect
+
+connection = connect(host="mongodb://localhost:27017", database="blog")
+cursor = connection.cursor()
+
+# Parameterized queries for security
+min_age = 18
+status = 'active'
+
+cursor.execute('''
+    SELECT name, email, created_at 
+    FROM users 
+    WHERE age >= ? AND status = ?
+''', [min_age, status])
+
+users = cursor.fetchmany(5)  # Fetch first 5 results
+while users:
+    for user in users:
+        print(f"User: {user['name']} ({user['email']})")
+    users = cursor.fetchmany(5)  # Fetch next 5
+```
+
+## Supported SQL Features
+
+### SELECT Statements
+- Field selection: `SELECT name, age FROM users`
+- Wildcards: `SELECT * FROM products`
+- Field aliases: `SELECT name AS user_name, age AS user_age FROM users`
+
+### WHERE Clauses
+- Equality: `WHERE name = 'John'`
+- Comparisons: `WHERE age > 25`, `WHERE price <= 100.0`
+- Logical operators: `WHERE age > 18 AND status = 'active'`
+
+### Sorting and Limiting
+- ORDER BY: `ORDER BY name ASC, age DESC`
+- LIMIT: `LIMIT 10`
+- Combined: `ORDER BY created_at DESC LIMIT 5`
+
+## Architecture
+
+PyMongoSQL uses a multi-layer architecture:
+
+1. **SQL Parser**: Built with ANTLR4 for robust SQL parsing
+2. **Query Planner**: Converts SQL AST to MongoDB query plans
+3. **Command Executor**: Direct `db.command()` execution for performance
+4. **Result Processor**: Handles projection mapping and result set iteration
+
+## Connection Options
+
+```python
+from pymongosql.connection import Connection
+
+# Basic connection
+conn = Connection(host="localhost", port=27017, database="mydb")
+
+# With authentication
+conn = Connection(
+    host="mongodb://user:pass@host:port/db?authSource=admin",
+    database="mydb"
+)
+
+# Connection properties
+print(conn.host)           # MongoDB connection URL
+print(conn.port)           # Port number
+print(conn.database_name)  # Database name
+print(conn.is_connected)   # Connection status
+```
+
+## Error Handling
+
+```python
+from pymongosql import connect
+from pymongosql.error import ProgrammingError, SqlSyntaxError
+
+try:
+    connection = connect(host="mongodb://localhost:27017", database="test")
+    cursor = connection.cursor()
+    cursor.execute("INVALID SQL SYNTAX")
+except SqlSyntaxError as e:
+    print(f"SQL syntax error: {e}")
+except ProgrammingError as e:
+    print(f"Programming error: {e}")
+```
+
+## Development Status
+
+PyMongoSQL is currently focused on DQL (Data Query Language) operations. Future releases will include:
+
+- **DML Operations**: INSERT, UPDATE, DELETE statements
+- **Advanced SQL Features**: JOINs, subqueries, aggregations
+- **Schema Operations**: CREATE/DROP collection commands
+- **Transaction Support**: Multi-document ACID transactions
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+PyMongoSQL is distributed under the [MIT license](https://opensource.org/licenses/MIT).

pymongosql/cursor.py

@@ -96,56 +96,54 @@ def _parse_sql(self, sql: str) -> QueryPlan:
             raise SqlSyntaxError(f"Failed to parse SQL: {e}")
 
     def _execute_query_plan(self, query_plan: QueryPlan) -> None:
-        """Execute a QueryPlan against MongoDB"""
+        """Execute a QueryPlan against MongoDB using db.command"""
         try:
-            # Get collection
+            # Get database
             if not query_plan.collection:
                 raise ProgrammingError("No collection specified in query")
 
-            collection = self.connection.get_collection(query_plan.collection)
+            db = self.connection.database
 
-            # Build MongoDB query
-            find_filter = query_plan.filter_stage or {}
+            # Build MongoDB find command
+            find_command = {"find": query_plan.collection, "filter": query_plan.filter_stage or {}}
 
             # Convert projection stage from alias mapping to MongoDB format
-            find_projection = None
             if query_plan.projection_stage:
                 # Convert {"field": "alias"} to {"field": 1} for MongoDB
-                find_projection = {field: 1 for field in query_plan.projection_stage.keys()}
-
-            _logger.debug(f"Executing MongoDB query: filter={find_filter}, projection={find_projection}")
-
-            # Execute find query
-            self._mongo_cursor = collection.find(find_filter, find_projection)
+                find_command["projection"] = {field: 1 for field in query_plan.projection_stage.keys()}
 
             # Apply sort if specified
             if query_plan.sort_stage:
-                sort_spec = [
-                    (field, direction) for sort_dict in query_plan.sort_stage for field, direction in sort_dict.items()
-                ]
-                self._mongo_cursor = self._mongo_cursor.sort(sort_spec)
+                sort_spec = {}
+                for sort_dict in query_plan.sort_stage:
+                    for field, direction in sort_dict.items():
+                        sort_spec[field] = direction
+                find_command["sort"] = sort_spec
 
             # Apply skip if specified
             if query_plan.skip_stage:
-                self._mongo_cursor = self._mongo_cursor.skip(query_plan.skip_stage)
+                find_command["skip"] = query_plan.skip_stage
 
             # Apply limit if specified
             if query_plan.limit_stage:
-                self._mongo_cursor = self._mongo_cursor.limit(query_plan.limit_stage)
+                find_command["limit"] = query_plan.limit_stage
+
+            _logger.debug(f"Executing MongoDB command: {find_command}")
+
+            # Execute find command directly
+            result = db.command(find_command)
 
-            # Create result set
-            self._result_set = self._result_set_class(
-                mongo_cursor=self._mongo_cursor, query_plan=query_plan, **self._kwargs
-            )
+            # Create result set from command result
+            self._result_set = self._result_set_class(command_result=result, query_plan=query_plan, **self._kwargs)
 
             _logger.info(f"Query executed successfully on collection '{query_plan.collection}'")
 
         except PyMongoError as e:
-            _logger.error(f"MongoDB query execution failed: {e}")
-            raise DatabaseError(f"Query execution failed: {e}")
+            _logger.error(f"MongoDB command execution failed: {e}")
+            raise DatabaseError(f"Command execution failed: {e}")
         except Exception as e:
-            _logger.error(f"Unexpected error during query execution: {e}")
-            raise OperationalError(f"Query execution error: {e}")
+            _logger.error(f"Unexpected error during command execution: {e}")
+            raise OperationalError(f"Command execution error: {e}")
 
     def execute(self: _T, operation: str, parameters: Optional[Dict[str, Any]] = None) -> _T:
         """Execute a SQL statement