| Name | databricks-sql-handler JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | A comprehensive Databricks SQL handler with Pydantic models, OAuth authentication, and connection management |
| upload_time | 2025-08-08 09:36:37 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
database
databricks
oauth
pydantic
sql
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Databricks SQL Handler
A comprehensive Python package for interacting with Databricks SQL warehouses using Pydantic models, OAuth authentication, and robust connection management.
## Features
- **OAuth Authentication**: Secure client credentials flow authentication
- **Pydantic Models**: Type-safe data models for query results
- **Connection Management**: Robust connection handling with automatic retry logic
- **Query Execution**: Execute single or multiple queries with structured results
- **Built-in Models**: Pre-defined models for common Databricks operations
- **Extensible**: Easy to extend with custom data models
- **CLI Interface**: Interactive command-line interface for testing and development
## Installation
```bash
pip install databricks-sql-handler
```
## Quick Start
### Basic Usage
```python
from databricks_sql_handler import QueryHandler, DatabricksSettings, NexsysRecord
# Configure settings (or use environment variables)
settings = DatabricksSettings(
client_id="your_client_id",
client_secret="your_client_secret",
server_hostname="your_databricks_hostname",
http_path="/sql/1.0/warehouses/your_warehouse_id"
)
# Use as context manager
with QueryHandler(settings) as handler:
# Execute a simple query
result = handler.execute_query("SELECT * FROM my_table LIMIT 10")
# Execute with Pydantic model parsing
result = handler.execute_query(
"SELECT * FROM nexsys_table LIMIT 10",
NexsysRecord
)
# Access structured data
for record in result.data:
print(f"ID: {record.id}, Name: {record.name}")
```
### Environment Variables
Create a `.env` file:
```env
DATABRICKS_CLIENT_ID=your_client_id
DATABRICKS_CLIENT_SECRET=your_client_secret
DATABRICKS_SERVER_HOSTNAME=your_hostname.databricks.com
DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/warehouse_id
DATABRICKS_LOG_LEVEL=INFO
```
### CLI Usage
```bash
# Interactive mode
databricks-sql-handler --interactive
# Run example queries
databricks-sql-handler --examples
# Execute a single query
databricks-sql-handler --query "SELECT current_timestamp()"
```
## Custom Models
Create your own Pydantic models:
```python
from pydantic import BaseModel
from datetime import datetime
from typing import Optional
class MyCustomModel(BaseModel):
id: int
name: str
created_at: datetime
amount: Optional[float] = None
# Register the model
from databricks_sql_handler import register_model
register_model("my_custom", MyCustomModel)
# Use it in queries
result = handler.execute_query("SELECT * FROM my_table", MyCustomModel)
```
## Configuration
All configuration can be done via environment variables with the `DATABRICKS_` prefix or programmatically:
| Setting | Environment Variable | Default | Description |
|---------|---------------------|---------|-------------|
| client_id | DATABRICKS_CLIENT_ID | Required | OAuth client ID |
| client_secret | DATABRICKS_CLIENT_SECRET | Required | OAuth client secret |
| server_hostname | DATABRICKS_SERVER_HOSTNAME | Required | Databricks hostname |
| http_path | DATABRICKS_HTTP_PATH | Required | SQL warehouse HTTP path |
| log_level | DATABRICKS_LOG_LEVEL | INFO | Logging level |
| max_retries | DATABRICKS_MAX_RETRIES | 3 | Query retry attempts |
| query_timeout | DATABRICKS_QUERY_TIMEOUT | 300 | Query timeout (seconds) |
## API Reference
### QueryHandler
Main class for executing queries and managing connections.
#### Methods
- `execute_query(query, model_class=None)`: Execute single query
- `execute_multiple_queries(queries, model_classes=None)`: Execute multiple queries
- `execute_query_with_retry(query, model_class=None)`: Execute with automatic retry
- `list_files(path)`: List files in Databricks path
- `show_tables(database=None)`: Show tables in database
- `test_connection()`: Test database connectivity
### Built-in Models
- `NexsysRecord`: For NEXSYS system data
- `SalesRecord`: For sales transaction data
- `FileInfo`: For file listing results
- `TableInfo`: For table information
- `GenericRecord`: For unknown data structures
## Error Handling
The package provides specific exceptions:
```python
from databricks_sql_handler import (
AuthenticationError,
ConnectionError,
QueryExecutionError,
SyntaxError,
TimeoutError,
DataParsingError
)
try:
result = handler.execute_query("SELECT * FROM table")
except AuthenticationError:
print("Authentication failed")
except QueryExecutionError as e:
print(f"Query failed: {e}")
```
## License
MIT License
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "databricks-sql-handler",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Andras Gyacsok <atti.dyachok@gmail.com>",
"keywords": "database, databricks, oauth, pydantic, sql",
"author": null,
"author_email": "Andras Gyacsok <atti.dyachok@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/28/61/1eeb70cbd7dafcea1f6faec17b04b79c10defc48e9ef03258aa026152756/databricks_sql_handler-1.0.0.tar.gz",
"platform": null,
"description": "# Databricks SQL Handler\n\nA comprehensive Python package for interacting with Databricks SQL warehouses using Pydantic models, OAuth authentication, and robust connection management.\n\n## Features\n\n- **OAuth Authentication**: Secure client credentials flow authentication\n- **Pydantic Models**: Type-safe data models for query results\n- **Connection Management**: Robust connection handling with automatic retry logic\n- **Query Execution**: Execute single or multiple queries with structured results\n- **Built-in Models**: Pre-defined models for common Databricks operations\n- **Extensible**: Easy to extend with custom data models\n- **CLI Interface**: Interactive command-line interface for testing and development\n\n## Installation\n\n```bash\npip install databricks-sql-handler\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom databricks_sql_handler import QueryHandler, DatabricksSettings, NexsysRecord\n\n# Configure settings (or use environment variables)\nsettings = DatabricksSettings(\n client_id=\"your_client_id\",\n client_secret=\"your_client_secret\", \n server_hostname=\"your_databricks_hostname\",\n http_path=\"/sql/1.0/warehouses/your_warehouse_id\"\n)\n\n# Use as context manager\nwith QueryHandler(settings) as handler:\n # Execute a simple query\n result = handler.execute_query(\"SELECT * FROM my_table LIMIT 10\")\n \n # Execute with Pydantic model parsing\n result = handler.execute_query(\n \"SELECT * FROM nexsys_table LIMIT 10\", \n NexsysRecord\n )\n \n # Access structured data\n for record in result.data:\n print(f\"ID: {record.id}, Name: {record.name}\")\n```\n\n### Environment Variables\n\nCreate a `.env` file:\n\n```env\nDATABRICKS_CLIENT_ID=your_client_id\nDATABRICKS_CLIENT_SECRET=your_client_secret\nDATABRICKS_SERVER_HOSTNAME=your_hostname.databricks.com\nDATABRICKS_HTTP_PATH=/sql/1.0/warehouses/warehouse_id\nDATABRICKS_LOG_LEVEL=INFO\n```\n\n### CLI Usage\n\n```bash\n# Interactive mode\ndatabricks-sql-handler --interactive\n\n# Run example queries\ndatabricks-sql-handler --examples\n\n# Execute a single query\ndatabricks-sql-handler --query \"SELECT current_timestamp()\"\n```\n\n## Custom Models\n\nCreate your own Pydantic models:\n\n```python\nfrom pydantic import BaseModel\nfrom datetime import datetime\nfrom typing import Optional\n\nclass MyCustomModel(BaseModel):\n id: int\n name: str\n created_at: datetime\n amount: Optional[float] = None\n\n# Register the model\nfrom databricks_sql_handler import register_model\nregister_model(\"my_custom\", MyCustomModel)\n\n# Use it in queries\nresult = handler.execute_query(\"SELECT * FROM my_table\", MyCustomModel)\n```\n\n## Configuration\n\nAll configuration can be done via environment variables with the `DATABRICKS_` prefix or programmatically:\n\n| Setting | Environment Variable | Default | Description |\n|---------|---------------------|---------|-------------|\n| client_id | DATABRICKS_CLIENT_ID | Required | OAuth client ID |\n| client_secret | DATABRICKS_CLIENT_SECRET | Required | OAuth client secret |\n| server_hostname | DATABRICKS_SERVER_HOSTNAME | Required | Databricks hostname |\n| http_path | DATABRICKS_HTTP_PATH | Required | SQL warehouse HTTP path |\n| log_level | DATABRICKS_LOG_LEVEL | INFO | Logging level |\n| max_retries | DATABRICKS_MAX_RETRIES | 3 | Query retry attempts |\n| query_timeout | DATABRICKS_QUERY_TIMEOUT | 300 | Query timeout (seconds) |\n\n## API Reference\n\n### QueryHandler\n\nMain class for executing queries and managing connections.\n\n#### Methods\n\n- `execute_query(query, model_class=None)`: Execute single query\n- `execute_multiple_queries(queries, model_classes=None)`: Execute multiple queries \n- `execute_query_with_retry(query, model_class=None)`: Execute with automatic retry\n- `list_files(path)`: List files in Databricks path\n- `show_tables(database=None)`: Show tables in database\n- `test_connection()`: Test database connectivity\n\n### Built-in Models\n\n- `NexsysRecord`: For NEXSYS system data\n- `SalesRecord`: For sales transaction data \n- `FileInfo`: For file listing results\n- `TableInfo`: For table information\n- `GenericRecord`: For unknown data structures\n\n## Error Handling\n\nThe package provides specific exceptions:\n\n```python\nfrom databricks_sql_handler import (\n AuthenticationError,\n ConnectionError, \n QueryExecutionError,\n SyntaxError,\n TimeoutError,\n DataParsingError\n)\n\ntry:\n result = handler.execute_query(\"SELECT * FROM table\")\nexcept AuthenticationError:\n print(\"Authentication failed\")\nexcept QueryExecutionError as e:\n print(f\"Query failed: {e}\")\n```\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive Databricks SQL handler with Pydantic models, OAuth authentication, and connection management",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/yourusername/databricks-sql-handler#readme",
"Homepage": "https://github.com/yourusername/databricks-sql-handler",
"Issues": "https://github.com/yourusername/databricks-sql-handler/issues",
"Repository": "https://github.com/yourusername/databricks-sql-handler.git"
},
"split_keywords": [
"database",
" databricks",
" oauth",
" pydantic",
" sql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2efed8180e9ce50c379243eee8e6dbb83fda65b5c483fefdb59864c532514e0d",
"md5": "564d76c01bbae5af696072f95c3b061b",
"sha256": "b0251a95da8b33913d94ca580574ef8c5f09ea64c7bd90d3bb5a2f71ceb6849b"
},
"downloads": -1,
"filename": "databricks_sql_handler-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "564d76c01bbae5af696072f95c3b061b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19556,
"upload_time": "2025-08-08T09:36:36",
"upload_time_iso_8601": "2025-08-08T09:36:36.592487Z",
"url": "https://files.pythonhosted.org/packages/2e/fe/d8180e9ce50c379243eee8e6dbb83fda65b5c483fefdb59864c532514e0d/databricks_sql_handler-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "28611eeb70cbd7dafcea1f6faec17b04b79c10defc48e9ef03258aa026152756",
"md5": "9af3053a05fb238bcfafc7aa559fe50d",
"sha256": "6fb64115b1aa64219dc8b1889a139068685bc45da04c03e307c19c7bca4ef1ed"
},
"downloads": -1,
"filename": "databricks_sql_handler-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "9af3053a05fb238bcfafc7aa559fe50d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15116,
"upload_time": "2025-08-08T09:36:37",
"upload_time_iso_8601": "2025-08-08T09:36:37.853898Z",
"url": "https://files.pythonhosted.org/packages/28/61/1eeb70cbd7dafcea1f6faec17b04b79c10defc48e9ef03258aa026152756/databricks_sql_handler-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 09:36:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "databricks-sql-handler#readme",
"github_not_found": true,
"lcname": "databricks-sql-handler"
}
