buildaquery 0.2.0__tar.gz → 0.4.0__tar.gz

{buildaquery-0.2.0 → buildaquery-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: buildaquery
-Version: 0.2.0
-Summary: A Python-based query builder for PostgreSQL.
+Version: 0.4.0
+Summary: A Python-based query builder for PostgreSQL, SQLite, MySQL, and Oracle.
 License: MIT
 License-File: LICENSE.txt
 Author: Anirudh Bhattacharya
@@ -21,6 +21,8 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: Pygments (==2.19.2)
 Requires-Dist: colorama (==0.4.6)
+Requires-Dist: mysql-connector-python (==9.4.0)
+Requires-Dist: oracledb (>=3.4.2,<4.0.0)
 Requires-Dist: packaging (==26.0)
 Requires-Dist: pluggy (==1.6.0)
 Requires-Dist: psycopg (==3.3.3)
@@ -33,7 +35,7 @@ Description-Content-Type: text/markdown
 
 # Build-a-Query
 
-A Python-based query builder designed to represent, compile, and execute SQL queries using a dialect-agnostic Abstract Syntax Tree (AST). Supports PostgreSQL and SQLite.
+A Python-based query builder designed to represent, compile, and execute SQL queries using a dialect-agnostic Abstract Syntax Tree (AST). Supports PostgreSQL, SQLite, MySQL, and Oracle.
 
 ## Features
 
@@ -44,7 +46,12 @@ A Python-based query builder designed to represent, compile, and execute SQL que
 - **DDL Support**: Basic schema management with `CREATE TABLE` and `DROP TABLE`.
 - **Visitor Pattern Traversal**: Extensible architecture for analysis and compilation.
 - **Secure Compilation**: Automatic parameterization to prevent SQL injection.
-- **Execution Layer**: Built-in support for executing compiled queries via `psycopg` (PostgreSQL) and the standard library `sqlite3` (SQLite).
+- **Execution Layer**: Built-in support for executing compiled queries via `psycopg` (PostgreSQL), `mysql-connector-python` (MySQL), `oracledb` (Oracle), and the standard library `sqlite3` (SQLite).
+
+## Dialect Notes
+- MySQL does not support `INTERSECT` / `EXCEPT` or `DROP TABLE ... CASCADE` in this implementation (the compiler raises `ValueError`).
+- SQLite does not support `DROP TABLE ... CASCADE` (the compiler raises `ValueError`).
+- Oracle does not support `IF EXISTS` / `IF NOT EXISTS` in `DROP TABLE`/`CREATE TABLE` (the compiler raises `ValueError`), and `EXCEPT` is compiled as `MINUS`.
 
 ## Installation
 
@@ -61,6 +68,12 @@ pip install buildaquery
 - **PostgreSQL database**: A running PostgreSQL instance (version 12+ recommended). You can set this up locally, via Docker, or use a cloud service.
   - Example with Docker: `docker run --name postgres -e POSTGRES_PASSWORD=yourpassword -d -p 5432:5432 postgres:15`
 - `psycopg` (automatically installed as a dependency) - the PostgreSQL adapter for Python.
+- **MySQL database**: A running MySQL instance (version 8.0+ recommended).
+  - Example with Docker: `docker run --name mysql -e MYSQL_ROOT_PASSWORD=yourpassword -e MYSQL_DATABASE=buildaquery -d -p 3306:3306 mysql:8.0`
+- `mysql-connector-python` (automatically installed as a dependency) - the MySQL adapter for Python.
+- **Oracle database**: A running Oracle instance (Oracle XE is suitable for development).
+  - Example with Docker (Oracle XE): `docker run --name oracle-xe -e ORACLE_PASSWORD=yourpassword -e APP_USER=buildaquery -e APP_USER_PASSWORD=yourpassword -d -p 1521:1521 gvenzl/oracle-xe:21-slim`
+- `oracledb` (automatically installed as a dependency) - the Oracle adapter for Python.
 - `python-dotenv` (automatically installed as a dependency) - for loading environment variables from a `.env` file.
 - **SQLite**: Uses Python's standard library `sqlite3` module.
   - **SQLite Version**: SQLite 3.x via Python's `sqlite3` module (the exact SQLite version depends on your Python build; check `sqlite3.sqlite_version` at runtime).
@@ -84,6 +97,10 @@ DB_USER=postgres
 DB_PASSWORD=yourpassword
 ```
 
+For MySQL, you can use a connection URL directly in code (e.g., `mysql://user:password@host:3306/dbname`) or set your own environment variables and construct the URL similarly.
+
+For Oracle, use a connection URL in the format `oracle://user:password@host:port/service_name` (for example: `oracle://buildaquery:password@127.0.0.1:1521/XEPDB1`).
+
 ### For Developers
 
 Clone the repository and set up the development environment:
@@ -209,7 +226,87 @@ drop_stmt = DropStatementNode(table=users_table, if_exists=True)
 executor.execute(drop_stmt)
 ```
 
-For more examples, see the `examples/` directory.
+### MySQL Quick Start
+
+```python
+from buildaquery.execution.mysql import MySqlExecutor
+from buildaquery.abstract_syntax_tree.models import (
+    CreateStatementNode, TableNode, ColumnDefinitionNode,
+    InsertStatementNode, ColumnNode, LiteralNode,
+    SelectStatementNode, StarNode, DropStatementNode
+)
+
+executor = MySqlExecutor(connection_info="mysql://root:password@127.0.0.1:3306/buildaquery")
+
+users_table = TableNode(name="users")
+create_stmt = CreateStatementNode(
+    table=users_table,
+    columns=[
+        ColumnDefinitionNode(name="id", data_type="INT AUTO_INCREMENT", primary_key=True),
+        ColumnDefinitionNode(name="name", data_type="VARCHAR(255)", not_null=True),
+        ColumnDefinitionNode(name="age", data_type="INT")
+    ]
+)
+executor.execute(create_stmt)
+
+insert_stmt = InsertStatementNode(
+    table=users_table,
+    columns=[ColumnNode(name="name"), ColumnNode(name="age")],
+    values=[LiteralNode(value="Alice"), LiteralNode(value=30)]
+)
+executor.execute(insert_stmt)
+
+select_stmt = SelectStatementNode(
+    select_list=[StarNode()],
+    from_table=users_table
+)
+print(executor.execute(select_stmt))
+
+drop_stmt = DropStatementNode(table=users_table, if_exists=True)
+executor.execute(drop_stmt)
+```
+
+### Oracle Quick Start
+
+```python
+from buildaquery.execution.oracle import OracleExecutor
+from buildaquery.abstract_syntax_tree.models import (
+    CreateStatementNode, TableNode, ColumnDefinitionNode,
+    InsertStatementNode, ColumnNode, LiteralNode,
+    SelectStatementNode, StarNode, DropStatementNode
+)
+
+executor = OracleExecutor(connection_info="oracle://buildaquery:password@127.0.0.1:1521/XEPDB1")
+
+users_table = TableNode(name="users")
+create_stmt = CreateStatementNode(
+    table=users_table,
+    columns=[
+        ColumnDefinitionNode(name="id", data_type="NUMBER", primary_key=True),
+        ColumnDefinitionNode(name="name", data_type="VARCHAR2(255)", not_null=True),
+        ColumnDefinitionNode(name="age", data_type="NUMBER")
+    ]
+)
+executor.execute(create_stmt)
+
+insert_stmt = InsertStatementNode(
+    table=users_table,
+    columns=[ColumnNode(name="id"), ColumnNode(name="name"), ColumnNode(name="age")],
+    values=[LiteralNode(value=1), LiteralNode(value="Alice"), LiteralNode(value=30)]
+)
+executor.execute(insert_stmt)
+
+select_stmt = SelectStatementNode(
+    select_list=[StarNode()],
+    from_table=users_table
+)
+print(executor.execute(select_stmt))
+
+drop_stmt = DropStatementNode(table=users_table, cascade=True)
+executor.execute(drop_stmt)
+```
+
+For more examples, see the `examples/` directory (including `examples/sample_mysql.py` and `examples/sample_oracle.py`).
 
 ## Development Setup
 
@@ -249,7 +346,7 @@ poetry run pytest buildaquery/tests
 
 #### Integration Tests
 
-Integration tests require a PostgreSQL database. Start the test database using Docker:
+Integration tests require PostgreSQL, MySQL, and Oracle databases (and the respective drivers). Start the test databases using Docker:
 
 ```bash
 docker-compose up -d
@@ -283,7 +380,7 @@ poetry run python examples/sample_query.py
 
 - `buildaquery/abstract_syntax_tree/`: Defines query nodes and AST models.
 - `buildaquery/traversal/`: Base classes for AST traversal (Visitor/Transformer pattern).
-- `buildaquery/compiler/`: Dialect-specific SQL generation (PostgreSQL and SQLite).
+- `buildaquery/compiler/`: Dialect-specific SQL generation (PostgreSQL, SQLite, MySQL, Oracle).
 - `buildaquery/execution/`: Database connection and execution logic.
 - `tests/`: Exhaustive unit and integration tests.
 - `examples/`: Practical demonstrations of the library.

{buildaquery-0.2.0 → buildaquery-0.4.0}/README.md

@@ -1,8 +1,8 @@
 # Build-a-Query
 
-A Python-based query builder designed to represent, compile, and execute SQL queries using a dialect-agnostic Abstract Syntax Tree (AST). Supports PostgreSQL and SQLite.
+A Python-based query builder designed to represent, compile, and execute SQL queries using a dialect-agnostic Abstract Syntax Tree (AST). Supports PostgreSQL, SQLite, MySQL, and Oracle.
 
-## Features
+## Features
 
 - **Dialect-Agnostic AST**: Build queries using high-level Python objects.
 - **Full DML Support**: Create `SELECT`, `INSERT`, `UPDATE`, and `DELETE` statements.
@@ -11,7 +11,12 @@ A Python-based query builder designed to represent, compile, and execute SQL que
 - **DDL Support**: Basic schema management with `CREATE TABLE` and `DROP TABLE`.
 - **Visitor Pattern Traversal**: Extensible architecture for analysis and compilation.
 - **Secure Compilation**: Automatic parameterization to prevent SQL injection.
-- **Execution Layer**: Built-in support for executing compiled queries via `psycopg` (PostgreSQL) and the standard library `sqlite3` (SQLite).
+- **Execution Layer**: Built-in support for executing compiled queries via `psycopg` (PostgreSQL), `mysql-connector-python` (MySQL), `oracledb` (Oracle), and the standard library `sqlite3` (SQLite).
+
+## Dialect Notes
+- MySQL does not support `INTERSECT` / `EXCEPT` or `DROP TABLE ... CASCADE` in this implementation (the compiler raises `ValueError`).
+- SQLite does not support `DROP TABLE ... CASCADE` (the compiler raises `ValueError`).
+- Oracle does not support `IF EXISTS` / `IF NOT EXISTS` in `DROP TABLE`/`CREATE TABLE` (the compiler raises `ValueError`), and `EXCEPT` is compiled as `MINUS`.
 
 ## Installation
 
@@ -28,13 +33,19 @@ pip install buildaquery
 - **PostgreSQL database**: A running PostgreSQL instance (version 12+ recommended). You can set this up locally, via Docker, or use a cloud service.
   - Example with Docker: `docker run --name postgres -e POSTGRES_PASSWORD=yourpassword -d -p 5432:5432 postgres:15`
 - `psycopg` (automatically installed as a dependency) - the PostgreSQL adapter for Python.
+- **MySQL database**: A running MySQL instance (version 8.0+ recommended).
+  - Example with Docker: `docker run --name mysql -e MYSQL_ROOT_PASSWORD=yourpassword -e MYSQL_DATABASE=buildaquery -d -p 3306:3306 mysql:8.0`
+- `mysql-connector-python` (automatically installed as a dependency) - the MySQL adapter for Python.
+- **Oracle database**: A running Oracle instance (Oracle XE is suitable for development).
+  - Example with Docker (Oracle XE): `docker run --name oracle-xe -e ORACLE_PASSWORD=yourpassword -e APP_USER=buildaquery -e APP_USER_PASSWORD=yourpassword -d -p 1521:1521 gvenzl/oracle-xe:21-slim`
+- `oracledb` (automatically installed as a dependency) - the Oracle adapter for Python.
 - `python-dotenv` (automatically installed as a dependency) - for loading environment variables from a `.env` file.
 - **SQLite**: Uses Python's standard library `sqlite3` module.
   - **SQLite Version**: SQLite 3.x via Python's `sqlite3` module (the exact SQLite version depends on your Python build; check `sqlite3.sqlite_version` at runtime).
 
 ### Environment Variables
 
-To connect to your PostgreSQL database, set the following environment variables (or use a `.env` file with `python-dotenv`):
+To connect to your PostgreSQL database, set the following environment variables (or use a `.env` file with `python-dotenv`):
 
 - `DB_HOST`: PostgreSQL host (e.g., `localhost`)
 - `DB_PORT`: PostgreSQL port (e.g., `5432`)
@@ -42,14 +53,18 @@ To connect to your PostgreSQL database, set the following environment variables
 - `DB_USER`: Database username (e.g., `postgres`)
 - `DB_PASSWORD`: Database password (e.g., `yourpassword`)
 
-Example `.env` file:
-```
-DB_HOST=localhost
-DB_PORT=5432
-DB_NAME=buildaquery
-DB_USER=postgres
-DB_PASSWORD=yourpassword
-```
+Example `.env` file:
+```
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=buildaquery
+DB_USER=postgres
+DB_PASSWORD=yourpassword
+```
+
+For MySQL, you can use a connection URL directly in code (e.g., `mysql://user:password@host:3306/dbname`) or set your own environment variables and construct the URL similarly.
+
+For Oracle, use a connection URL in the format `oracle://user:password@host:port/service_name` (for example: `oracle://buildaquery:password@127.0.0.1:1521/XEPDB1`).
 
 ### For Developers
 
@@ -72,7 +87,7 @@ Activate the virtual environment:
 poetry shell
 ```
 
-## Quick Start
+## Quick Start
 
 Here's a simple example of creating a table, inserting data, querying it, and dropping the table. This example uses environment variables for database connection (see Environment Variables section above).
 
@@ -176,7 +191,87 @@ drop_stmt = DropStatementNode(table=users_table, if_exists=True)
 executor.execute(drop_stmt)
 ```
 
-For more examples, see the `examples/` directory.
+### MySQL Quick Start
+
+```python
+from buildaquery.execution.mysql import MySqlExecutor
+from buildaquery.abstract_syntax_tree.models import (
+    CreateStatementNode, TableNode, ColumnDefinitionNode,
+    InsertStatementNode, ColumnNode, LiteralNode,
+    SelectStatementNode, StarNode, DropStatementNode
+)
+
+executor = MySqlExecutor(connection_info="mysql://root:password@127.0.0.1:3306/buildaquery")
+
+users_table = TableNode(name="users")
+create_stmt = CreateStatementNode(
+    table=users_table,
+    columns=[
+        ColumnDefinitionNode(name="id", data_type="INT AUTO_INCREMENT", primary_key=True),
+        ColumnDefinitionNode(name="name", data_type="VARCHAR(255)", not_null=True),
+        ColumnDefinitionNode(name="age", data_type="INT")
+    ]
+)
+executor.execute(create_stmt)
+
+insert_stmt = InsertStatementNode(
+    table=users_table,
+    columns=[ColumnNode(name="name"), ColumnNode(name="age")],
+    values=[LiteralNode(value="Alice"), LiteralNode(value=30)]
+)
+executor.execute(insert_stmt)
+
+select_stmt = SelectStatementNode(
+    select_list=[StarNode()],
+    from_table=users_table
+)
+print(executor.execute(select_stmt))
+
+drop_stmt = DropStatementNode(table=users_table, if_exists=True)
+executor.execute(drop_stmt)
+```
+
+### Oracle Quick Start
+
+```python
+from buildaquery.execution.oracle import OracleExecutor
+from buildaquery.abstract_syntax_tree.models import (
+    CreateStatementNode, TableNode, ColumnDefinitionNode,
+    InsertStatementNode, ColumnNode, LiteralNode,
+    SelectStatementNode, StarNode, DropStatementNode
+)
+
+executor = OracleExecutor(connection_info="oracle://buildaquery:password@127.0.0.1:1521/XEPDB1")
+
+users_table = TableNode(name="users")
+create_stmt = CreateStatementNode(
+    table=users_table,
+    columns=[
+        ColumnDefinitionNode(name="id", data_type="NUMBER", primary_key=True),
+        ColumnDefinitionNode(name="name", data_type="VARCHAR2(255)", not_null=True),
+        ColumnDefinitionNode(name="age", data_type="NUMBER")
+    ]
+)
+executor.execute(create_stmt)
+
+insert_stmt = InsertStatementNode(
+    table=users_table,
+    columns=[ColumnNode(name="id"), ColumnNode(name="name"), ColumnNode(name="age")],
+    values=[LiteralNode(value=1), LiteralNode(value="Alice"), LiteralNode(value=30)]
+)
+executor.execute(insert_stmt)
+
+select_stmt = SelectStatementNode(
+    select_list=[StarNode()],
+    from_table=users_table
+)
+print(executor.execute(select_stmt))
+
+drop_stmt = DropStatementNode(table=users_table, cascade=True)
+executor.execute(drop_stmt)
+```
+
+For more examples, see the `examples/` directory (including `examples/sample_mysql.py` and `examples/sample_oracle.py`).
 
 ## Development Setup
 
@@ -214,9 +309,9 @@ Run unit tests for all modules:
 poetry run pytest buildaquery/tests
 ```
 
-#### Integration Tests
-
-Integration tests require a PostgreSQL database. Start the test database using Docker:
+#### Integration Tests
+
+Integration tests require PostgreSQL, MySQL, and Oracle databases (and the respective drivers). Start the test databases using Docker:
 
 ```bash
 docker-compose up -d
@@ -250,9 +345,9 @@ poetry run python examples/sample_query.py
 
 - `buildaquery/abstract_syntax_tree/`: Defines query nodes and AST models.
 - `buildaquery/traversal/`: Base classes for AST traversal (Visitor/Transformer pattern).
-- `buildaquery/compiler/`: Dialect-specific SQL generation (PostgreSQL and SQLite).
+- `buildaquery/compiler/`: Dialect-specific SQL generation (PostgreSQL, SQLite, MySQL, Oracle).
 - `buildaquery/execution/`: Database connection and execution logic.
-- `tests/`: Exhaustive unit and integration tests.
+- `tests/`: Exhaustive unit and integration tests.
 - `examples/`: Practical demonstrations of the library.
 - `scripts/`: Utility scripts for testing and maintenance.
 

{buildaquery-0.2.0 → buildaquery-0.4.0}/buildaquery/abstract_syntax_tree/README.md

@@ -2,7 +2,7 @@
 
 The `abstract_syntax_tree` module defines the data structures used to represent SQL queries as an Abstract Syntax Tree. This representation is agnostic of any specific SQL dialect and serves as the intermediate format that the query builder constructs and the compiler translates into SQL.
 
-**SQLite Version**: SQLite 3.x via Python's `sqlite3` module (the exact SQLite version depends on your Python build; check `sqlite3.sqlite_version` at runtime).
+**Dialect Notes**: The AST is dialect-agnostic and compilers target PostgreSQL, SQLite, and MySQL.
 
 ## Core Concepts
 

{buildaquery-0.2.0 → buildaquery-0.4.0}/buildaquery/compiler/README.md

@@ -44,12 +44,35 @@ The initial implementation supports PostgreSQL.
 - **Core AST Coverage**: Supports the same AST nodes as PostgreSQL where SQLite syntax allows.
 - **TOP Translation**: Maps `TopClauseNode` to `LIMIT`, with optional implicit `ORDER BY`.
 - **CASCADE Handling**: Raises a `ValueError` when `DropStatementNode.cascade=True`, because SQLite does not support `DROP TABLE ... CASCADE`.
+
+### MySQL (`MySqlCompiler`)
+
+#### Key Features:
+- **`%s` Placeholders**: Uses MySQL-compatible parameter style.
+- **Core AST Coverage**: Supports the same AST nodes as PostgreSQL where MySQL syntax allows.
+- **TOP Translation**: Maps `TopClauseNode` to `LIMIT`, with optional implicit `ORDER BY`.
+- **Set Operation Limits**: Raises a `ValueError` for `INTERSECT` and `EXCEPT` (unsupported in MySQL).
+- **CASCADE Handling**: Raises a `ValueError` when `DropStatementNode.cascade=True`, because MySQL does not support `DROP TABLE ... CASCADE`.
+
+### Oracle (`OracleCompiler`)
+
+#### Key Features:
+- **`:1` Placeholders**: Uses Oracle-style positional bind parameters.
+- **LIMIT/OFFSET Translation**: Uses `OFFSET ... ROWS` and `FETCH FIRST ... ROWS ONLY`.
+- **TOP Translation**: Maps `TopClauseNode` to `FETCH FIRST`, with optional implicit `ORDER BY`.
+- **Set Operation Notes**:
+  - `EXCEPT` is translated to `MINUS`.
+  - `INTERSECT ALL` and `MINUS ALL` raise `ValueError`.
+- **Table Aliases**: Emits `table alias` (Oracle does not allow `AS` for table aliases).
+- **IF EXISTS/IF NOT EXISTS**: Raises `ValueError` for `DropStatementNode.if_exists=True` and `CreateStatementNode.if_not_exists=True`.
 
 ## Usage Example
 
 ```python
 from buildaquery.compiler.postgres.postgres_compiler import PostgresCompiler
 from buildaquery.compiler.sqlite.sqlite_compiler import SqliteCompiler
+from buildaquery.compiler.mysql.mysql_compiler import MySqlCompiler
+from buildaquery.compiler.oracle.oracle_compiler import OracleCompiler
 
 compiler = PostgresCompiler()
 compiled = compiler.compile(ast_root)
@@ -61,4 +84,14 @@ sqlite_compiler = SqliteCompiler()
 compiled = sqlite_compiler.compile(ast_root)
 print(compiled.sql)    # "SELECT * FROM users WHERE id = ?"
 print(compiled.params) # [123]
-```
+
+mysql_compiler = MySqlCompiler()
+compiled = mysql_compiler.compile(ast_root)
+print(compiled.sql)    # "SELECT * FROM users WHERE id = %s"
+print(compiled.params) # [123]
+
+oracle_compiler = OracleCompiler()
+compiled = oracle_compiler.compile(ast_root)
+print(compiled.sql)    # "SELECT * FROM users WHERE id = :1"
+print(compiled.params) # [123]
+```

buildaquery-0.4.0/buildaquery/compiler/__init__.py

@@ -0,0 +1,6 @@
+from buildaquery.compiler.postgres.postgres_compiler import PostgresCompiler
+from buildaquery.compiler.sqlite.sqlite_compiler import SqliteCompiler
+from buildaquery.compiler.mysql.mysql_compiler import MySqlCompiler
+from buildaquery.compiler.oracle.oracle_compiler import OracleCompiler
+
+__all__ = ["PostgresCompiler", "SqliteCompiler", "MySqlCompiler", "OracleCompiler"]

buildaquery-0.4.0/buildaquery/compiler/mysql/README.md

@@ -0,0 +1,25 @@
+# MySQL Compiler
+
+The `MySqlCompiler` translates the AST into MySQL-compatible SQL with `%s` placeholders.
+
+## Notes
+
+- **Placeholders**: Uses `%s` for parameters (compatible with `mysql-connector-python`).
+- **TOP Translation**: `TopClauseNode` is translated into `LIMIT`, with optional implicit `ORDER BY`.
+- **Unsupported Operations**:
+  - `INTERSECT` and `EXCEPT` raise `ValueError` (MySQL does not support them).
+  - `DROP TABLE ... CASCADE` raises `ValueError`.
+
+## Example
+
+```python
+from buildaquery.compiler.mysql.mysql_compiler import MySqlCompiler
+from buildaquery.abstract_syntax_tree.models import SelectStatementNode, StarNode, TableNode
+
+compiler = MySqlCompiler()
+query = SelectStatementNode(select_list=[StarNode()], from_table=TableNode(name="users"))
+compiled = compiler.compile(query)
+
+print(compiled.sql)    # SELECT * FROM users
+print(compiled.params) # []
+```

buildaquery-0.4.0/buildaquery/compiler/mysql/__init__.py

@@ -0,0 +1 @@
+# Intentionally left empty to mark mysql as a package.