# polars_mssql
`polars_mssql` is a Python package designed to simplify working with Microsoft SQL Server databases using the high-performance `polars` DataFrame library. It provides an intuitive and efficient interface for running SQL queries, reading tables, and writing data to SQL Server.
## Features
- **Seamless SQL Server Integration**: Easily connect to SQL Server with options for Windows Authentication or SQL Authentication.
- **Query Execution**: Execute SQL queries and retrieve results as `polars.DataFrame` objects.
- **Table Operations**: Read and write tables with flexibility and performance.
- **Context Management**: Supports Python's context manager for automatic connection handling.
- **Customizable Options**: Configure schema inference, batch sizes, and execution options.
## Installation
Install the package using pip:
```bash
pip install polars_mssql
```
Ensure the following dependencies are installed:
- `polars` for high-performance DataFrame operations.
- `sqlalchemy` for database connectivity.
- An appropriate ODBC driver for SQL Server (e.g., ODBC Driver 17 or 18).
## Usage
Here is an example of how to use `polars_mssql` to connect to SQL Server and perform various operations:
### 1. Connecting to SQL Server
```python
from polars_mssql import Connection
# Initialize a connection
conn = Connection(
database="my_database",
server="my_server",
driver = 'ODBC Driver 17 for SQL Server'
)
```
### 2. Running Queries
#### Execute a SQL Query and Get Results as a DataFrame
```python
query = "SELECT * FROM my_table WHERE col1 = 'a'"
df = conn.read_query(query)
```
#### Read an Entire Table
```python
df = conn.read_table("my_table")
```
### 3. Writing Data to SQL Server
#### Write a Polars DataFrame to a Table
```python
import polars as pl
# Example DataFrame
data = pl.DataFrame({"col1": [1, 2, 3], "col2": ["a", "b", "c"]})
conn.write_table(data, name="my_table", if_exists="replace")
```
### 4. Using Context Management
```python
with Connection(database="my_database", server="my_server") as conn:
df = conn.read_query("SELECT * FROM my_table")
print(df)
```
### 5. Closing the Connection
```python
conn.close()
```
## API Reference
### `Connection` Class
#### Constructor
```python
Connection(database: Optional[str] = None, server: Optional[str] = None, driver: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None)
```
#### Methods
- **`read_query(query: str, ...) -> pl.DataFrame`**: Execute a query and return results as a Polars DataFrame.
- **`read_table(name: str) -> pl.DataFrame`**: Read all rows from a table.
- **`write_table(df: pl.DataFrame, name: str, ...)`**: Write a Polars DataFrame to a table.
- **`close()`**: Close the database connection.
- **Context Management (`__enter__` and `__exit__`)**: Automatically manage connections.
## Requirements
- Python 3.8 or higher
- ODBC Driver for SQL Server (17 or 18 recommended)
### Installing the ODBC Driver
#### Windows
Download and install the ODBC Driver from [Microsoft's website](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server).
#### macOS
Install via Homebrew:
```bash
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install --no-sandbox msodbcsql18
```
#### Linux
Install using the following commands:
```bash
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list
sudo apt-get update
sudo apt-get install -y mssql-tools unixodbc-dev
```
## Contributing
Contributions are welcome! If you encounter issues or have feature requests, please open an issue or submit a pull request on [GitHub](https://github.com/drosenman/polars_mssql).
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Acknowledgments
This package integrates the efficiency of polars with the versatility of SQL Server, inspired by real-world data engineering needs. As a data engineer, I often need to pull data from SQL Server into polars and export data from polars back to SQL Server. I created this package to streamline these workflows and make the process more efficient.
Raw data
{
"_id": null,
"home_page": "https://github.com/drosenman/py_mssql",
"name": "polars-mssql",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "sql server polars sqlalchemy database",
"author": "Dave Rosenman",
"author_email": "daverosenman@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5e/0c/7144d06710e8a24868b0722ea4e2945c894755ebf3b7c68f63c445cb671e/polars_mssql-0.2.tar.gz",
"platform": null,
"description": "# polars_mssql\r\n\r\n`polars_mssql` is a Python package designed to simplify working with Microsoft SQL Server databases using the high-performance `polars` DataFrame library. It provides an intuitive and efficient interface for running SQL queries, reading tables, and writing data to SQL Server.\r\n\r\n## Features\r\n\r\n- **Seamless SQL Server Integration**: Easily connect to SQL Server with options for Windows Authentication or SQL Authentication.\r\n- **Query Execution**: Execute SQL queries and retrieve results as `polars.DataFrame` objects.\r\n- **Table Operations**: Read and write tables with flexibility and performance.\r\n- **Context Management**: Supports Python's context manager for automatic connection handling.\r\n- **Customizable Options**: Configure schema inference, batch sizes, and execution options.\r\n\r\n## Installation\r\n\r\nInstall the package using pip:\r\n\r\n```bash\r\npip install polars_mssql\r\n```\r\n\r\nEnsure the following dependencies are installed:\r\n\r\n- `polars` for high-performance DataFrame operations.\r\n- `sqlalchemy` for database connectivity.\r\n- An appropriate ODBC driver for SQL Server (e.g., ODBC Driver 17 or 18).\r\n\r\n## Usage\r\n\r\nHere is an example of how to use `polars_mssql` to connect to SQL Server and perform various operations:\r\n\r\n### 1. Connecting to SQL Server\r\n\r\n```python\r\nfrom polars_mssql import Connection\r\n\r\n# Initialize a connection\r\nconn = Connection(\r\n database=\"my_database\",\r\n server=\"my_server\",\r\n driver = 'ODBC Driver 17 for SQL Server'\r\n)\r\n```\r\n\r\n### 2. Running Queries\r\n\r\n#### Execute a SQL Query and Get Results as a DataFrame\r\n\r\n```python\r\nquery = \"SELECT * FROM my_table WHERE col1 = 'a'\"\r\ndf = conn.read_query(query)\r\n```\r\n\r\n#### Read an Entire Table\r\n\r\n```python\r\ndf = conn.read_table(\"my_table\")\r\n```\r\n\r\n### 3. Writing Data to SQL Server\r\n\r\n#### Write a Polars DataFrame to a Table\r\n\r\n```python\r\nimport polars as pl\r\n\r\n# Example DataFrame\r\ndata = pl.DataFrame({\"col1\": [1, 2, 3], \"col2\": [\"a\", \"b\", \"c\"]})\r\nconn.write_table(data, name=\"my_table\", if_exists=\"replace\")\r\n```\r\n\r\n### 4. Using Context Management\r\n\r\n```python\r\nwith Connection(database=\"my_database\", server=\"my_server\") as conn:\r\n df = conn.read_query(\"SELECT * FROM my_table\")\r\n print(df)\r\n```\r\n\r\n### 5. Closing the Connection\r\n\r\n```python\r\nconn.close()\r\n```\r\n\r\n## API Reference\r\n\r\n### `Connection` Class\r\n\r\n#### Constructor\r\n```python\r\nConnection(database: Optional[str] = None, server: Optional[str] = None, driver: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None)\r\n```\r\n\r\n#### Methods\r\n\r\n- **`read_query(query: str, ...) -> pl.DataFrame`**: Execute a query and return results as a Polars DataFrame.\r\n- **`read_table(name: str) -> pl.DataFrame`**: Read all rows from a table.\r\n- **`write_table(df: pl.DataFrame, name: str, ...)`**: Write a Polars DataFrame to a table.\r\n- **`close()`**: Close the database connection.\r\n- **Context Management (`__enter__` and `__exit__`)**: Automatically manage connections.\r\n\r\n## Requirements\r\n\r\n- Python 3.8 or higher\r\n- ODBC Driver for SQL Server (17 or 18 recommended)\r\n\r\n### Installing the ODBC Driver\r\n\r\n#### Windows\r\nDownload and install the ODBC Driver from [Microsoft's website](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server).\r\n\r\n#### macOS\r\nInstall via Homebrew:\r\n```bash\r\nbrew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release\r\nbrew update\r\nbrew install --no-sandbox msodbcsql18\r\n```\r\n\r\n#### Linux\r\nInstall using the following commands:\r\n```bash\r\ncurl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -\r\ncurl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list\r\nsudo apt-get update\r\nsudo apt-get install -y mssql-tools unixodbc-dev\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! If you encounter issues or have feature requests, please open an issue or submit a pull request on [GitHub](https://github.com/drosenman/polars_mssql).\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\r\n\r\n## Acknowledgments\r\n\r\nThis package integrates the efficiency of polars with the versatility of SQL Server, inspired by real-world data engineering needs. As a data engineer, I often need to pull data from SQL Server into polars and export data from polars back to SQL Server. I created this package to streamline these workflows and make the process more efficient.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Effortlessly connect to SQL Server to import data into Polars DataFrames and export data back to SQL Server.",
"version": "0.2",
"project_urls": {
"Bug Reports": "https://github.com/drosenman/py_mssql/issues",
"Homepage": "https://github.com/drosenman/py_mssql",
"Source": "https://github.com/drosenman/py_mssql"
},
"split_keywords": [
"sql",
"server",
"polars",
"sqlalchemy",
"database"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d592c2317a879ba4bca85dd040e4e7652ad9e40823283d27c2370cb41e8c6c63",
"md5": "b5df5c69ead2325fe925f4c8c341ec2d",
"sha256": "22be5b8e43cbc00a86a7da569047b4c70e6acbe0d72b1a344267af4a7af0e05d"
},
"downloads": -1,
"filename": "polars_mssql-0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5df5c69ead2325fe925f4c8c341ec2d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6579,
"upload_time": "2024-12-26T21:37:23",
"upload_time_iso_8601": "2024-12-26T21:37:23.185991Z",
"url": "https://files.pythonhosted.org/packages/d5/92/c2317a879ba4bca85dd040e4e7652ad9e40823283d27c2370cb41e8c6c63/polars_mssql-0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e0c7144d06710e8a24868b0722ea4e2945c894755ebf3b7c68f63c445cb671e",
"md5": "be9f5365ccad0be95ddf5a22086bef48",
"sha256": "0a4173b64c5c68e4c6107bd892fc70f60434ade0f7f58f3de311f4582c1af771"
},
"downloads": -1,
"filename": "polars_mssql-0.2.tar.gz",
"has_sig": false,
"md5_digest": "be9f5365ccad0be95ddf5a22086bef48",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6263,
"upload_time": "2024-12-26T21:37:24",
"upload_time_iso_8601": "2024-12-26T21:37:24.123893Z",
"url": "https://files.pythonhosted.org/packages/5e/0c/7144d06710e8a24868b0722ea4e2945c894755ebf3b7c68f63c445cb671e/polars_mssql-0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-26 21:37:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "drosenman",
"github_project": "py_mssql",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "polars",
"specs": []
},
{
"name": "sqlalchemy",
"specs": []
},
{
"name": "pyodbc",
"specs": []
}
],
"lcname": "polars-mssql"
}
JSON
