# firebirdsql-run
> [Firebirdsql](https://github.com/nakagami/pyfirebirdsql/) wrapper inspired by [subprocess.run](https://docs.python.org/3/library/subprocess.html#subprocess.run)
[![PyPI version](https://img.shields.io/pypi/v/firebirdsql-run)](https://pypi.org/project/firebirdsql-run)
[![Documentation](https://img.shields.io/badge/docs-github-blue.svg)](https://deadnews.github.io/firebirdsql-run)
[![Main](https://github.com/DeadNews/firebirdsql-run/actions/workflows/main.yml/badge.svg)](https://github.com/DeadNews/firebirdsql-run/actions/workflows/main.yml)
[![pre-commit.ci](https://results.pre-commit.ci/badge/github/DeadNews/firebirdsql-run/main.svg)](https://results.pre-commit.ci/latest/github/DeadNews/firebirdsql-run/main)
[![codecov](https://codecov.io/gh/DeadNews/firebirdsql-run/branch/main/graph/badge.svg?token=OCZDZIYPMC)](https://codecov.io/gh/DeadNews/firebirdsql-run)
## Table of contents
- [Installation](#installation)
- [Examples](#examples)
- [Env variables](#env-variables)
- [API reference](https://deadnews.github.io/firebirdsql-run/reference)
## Installation
```sh
pip install firebirdsql-run
```
## Examples
Execute a query with read-only access:
```py
from firebirdsql_run import DBAccess, execute
# Execute a query with read-only access.
result = execute(query="SELECT * FROM table", db="database", access=DBAccess.READ_ONLY)
# Output: List of dictionaries containing the query results.
print(result.data)
```
Execute a query with parameters and log the result:
```py
# Execute a query with parameters.
result = execute(query="INSERT INTO customers (name, age) VALUES (?, ?)", params=("John", 25))
# Log the result.
if result.returncode != 0:
logger.error(result)
else:
logger.info(result)
```
Execute a query using the existing connection:
```py
# Create a connection object.
conn = connection(db="database", access=DBAccess.READ_ONLY)
# Execute a query using the existing connection.
result = execute(query="SELECT * FROM table", use_conn=conn)
# Close the connection.
conn.close()
# Output: Named tuple representing the completed transaction.
print(result)
```
An example of a successful transaction:
```py
>>> print(result)
CompletedTransaction(
host="127.0.0.1",
db="database",
user="TWUSER",
access="READ_ONLY",
returncode=0,
exception="",
query="SELECT * FROM table",
params=(),
time=0.001,
data=[
{'id': 1, 'name': 'John Doe', 'department': 'Sales'},
{'id': 2, 'name': 'Jane Smith', 'department': 'Sales'},
],
)
```
An example of a failed transaction:
```py
>>> print(result)
CompletedTransaction(
host="127.0.0.1",
db="database",
user="TWUSER",
access="READ_ONLY",
returncode=1,
exception="Dynamic SQL Error\nSQL error code = -204\nTable unknown\ntable\nAt line 1, column 15\n",
query="SELECT * FROM table",
params=(),
time=0.001,
data=[],
)
```
## Env variables
```ini
FIREBIRD_KEY=
```
The `FIREBIRD_KEY` environment variable can be overridden with the functions argument `passwd`.
Raw data
{
"_id": null,
"home_page": "https://github.com/deadnews/firebirdsql-run",
"name": "firebirdsql-run",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "firebird,sql,api",
"author": "DeadNews",
"author_email": "aurczpbgr@mozmail.com",
"download_url": "https://files.pythonhosted.org/packages/86/57/39414cea97ae1c84b2f02ed90e168429105f3de93f3eed5926eaff89d16a/firebirdsql_run-1.1.1.tar.gz",
"platform": null,
"description": "# firebirdsql-run\n\n> [Firebirdsql](https://github.com/nakagami/pyfirebirdsql/) wrapper inspired by [subprocess.run](https://docs.python.org/3/library/subprocess.html#subprocess.run)\n\n[![PyPI version](https://img.shields.io/pypi/v/firebirdsql-run)](https://pypi.org/project/firebirdsql-run)\n[![Documentation](https://img.shields.io/badge/docs-github-blue.svg)](https://deadnews.github.io/firebirdsql-run)\n[![Main](https://github.com/DeadNews/firebirdsql-run/actions/workflows/main.yml/badge.svg)](https://github.com/DeadNews/firebirdsql-run/actions/workflows/main.yml)\n[![pre-commit.ci](https://results.pre-commit.ci/badge/github/DeadNews/firebirdsql-run/main.svg)](https://results.pre-commit.ci/latest/github/DeadNews/firebirdsql-run/main)\n[![codecov](https://codecov.io/gh/DeadNews/firebirdsql-run/branch/main/graph/badge.svg?token=OCZDZIYPMC)](https://codecov.io/gh/DeadNews/firebirdsql-run)\n\n## Table of contents\n\n- [Installation](#installation)\n- [Examples](#examples)\n- [Env variables](#env-variables)\n- [API reference](https://deadnews.github.io/firebirdsql-run/reference)\n\n## Installation\n\n```sh\npip install firebirdsql-run\n```\n\n## Examples\n\nExecute a query with read-only access:\n\n```py\nfrom firebirdsql_run import DBAccess, execute\n\n# Execute a query with read-only access.\nresult = execute(query=\"SELECT * FROM table\", db=\"database\", access=DBAccess.READ_ONLY)\n\n# Output: List of dictionaries containing the query results.\nprint(result.data)\n```\n\nExecute a query with parameters and log the result:\n\n```py\n# Execute a query with parameters.\nresult = execute(query=\"INSERT INTO customers (name, age) VALUES (?, ?)\", params=(\"John\", 25))\n\n# Log the result.\nif result.returncode != 0:\n logger.error(result)\nelse:\n logger.info(result)\n```\n\nExecute a query using the existing connection:\n\n```py\n# Create a connection object.\nconn = connection(db=\"database\", access=DBAccess.READ_ONLY)\n# Execute a query using the existing connection.\nresult = execute(query=\"SELECT * FROM table\", use_conn=conn)\n# Close the connection.\nconn.close()\n\n# Output: Named tuple representing the completed transaction.\nprint(result)\n```\n\nAn example of a successful transaction:\n\n```py\n>>> print(result)\nCompletedTransaction(\n host=\"127.0.0.1\",\n db=\"database\",\n user=\"TWUSER\",\n access=\"READ_ONLY\",\n returncode=0,\n exception=\"\",\n query=\"SELECT * FROM table\",\n params=(),\n time=0.001,\n data=[\n {'id': 1, 'name': 'John Doe', 'department': 'Sales'},\n {'id': 2, 'name': 'Jane Smith', 'department': 'Sales'},\n ],\n)\n```\n\nAn example of a failed transaction:\n\n```py\n>>> print(result)\nCompletedTransaction(\n host=\"127.0.0.1\",\n db=\"database\",\n user=\"TWUSER\",\n access=\"READ_ONLY\",\n returncode=1,\n exception=\"Dynamic SQL Error\\nSQL error code = -204\\nTable unknown\\ntable\\nAt line 1, column 15\\n\",\n query=\"SELECT * FROM table\",\n params=(),\n time=0.001,\n data=[],\n)\n```\n\n## Env variables\n\n```ini\nFIREBIRD_KEY=\n```\n\nThe `FIREBIRD_KEY` environment variable can be overridden with the functions argument `passwd`.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Firebirdsql wrapper inspired by subprocess.run",
"version": "1.1.1",
"project_urls": {
"Documentation": "https://deadnews.github.io/firebirdsql-run",
"Homepage": "https://github.com/deadnews/firebirdsql-run",
"Repository": "https://github.com/deadnews/firebirdsql-run"
},
"split_keywords": [
"firebird",
"sql",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "58d3d3f6fb074b4694aaf23bd0b943d89ef1ea8446fdd06377393b825e8b7c44",
"md5": "74b3ea429df51fe428a6dcb2545bddf3",
"sha256": "937a3dbea159607c9443ca879da829b115c95728c2134a88b0d4fdedc8dc79a7"
},
"downloads": -1,
"filename": "firebirdsql_run-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74b3ea429df51fe428a6dcb2545bddf3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 6458,
"upload_time": "2024-02-26T02:29:18",
"upload_time_iso_8601": "2024-02-26T02:29:18.560348Z",
"url": "https://files.pythonhosted.org/packages/58/d3/d3f6fb074b4694aaf23bd0b943d89ef1ea8446fdd06377393b825e8b7c44/firebirdsql_run-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "865739414cea97ae1c84b2f02ed90e168429105f3de93f3eed5926eaff89d16a",
"md5": "576082476f81d6f0dcfa0077e1323066",
"sha256": "5173e0a234ca4decf993f56e2493c4966e4c8c6f83921ad60eed55fd0792e226"
},
"downloads": -1,
"filename": "firebirdsql_run-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "576082476f81d6f0dcfa0077e1323066",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 5992,
"upload_time": "2024-02-26T02:29:19",
"upload_time_iso_8601": "2024-02-26T02:29:19.704121Z",
"url": "https://files.pythonhosted.org/packages/86/57/39414cea97ae1c84b2f02ed90e168429105f3de93f3eed5926eaff89d16a/firebirdsql_run-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 02:29:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deadnews",
"github_project": "firebirdsql-run",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "firebirdsql-run"
}