{"id":22106253,"url":"https://github.com/ddc/ddcdatabases","last_synced_at":"2026-01-24T23:17:08.760Z","repository":{"id":244091546,"uuid":"814192689","full_name":"ddc/ddcDatabases","owner":"ddc","description":"Database ORM Connections","archived":false,"fork":false,"pushed_at":"2025-09-18T17:35:38.000Z","size":444,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-10T12:44:43.696Z","etag":null,"topics":["database","databases","ddcdatabases","mssql","mssql-database","postgres","postgresql","postgresql-database","postgressql","python","python-3","python3","sqlite","sqlite3","sqlite3-database"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/ddcDatabases","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"ddc","ko_fi":"ddcsta","custom":"https://www.paypal.com/ncp/payment/6G9Z78QHUD4RJ"}},"created_at":"2024-06-12T14:13:07.000Z","updated_at":"2025-09-18T17:32:04.000Z","dependencies_parsed_at":"2024-12-07T20:17:32.693Z","dependency_job_id":"abfc2873-8b43-48cd-ab59-929192be6feb","html_url":"https://github.com/ddc/ddcDatabases","commit_stats":null,"previous_names":["ddc/ddcdatabases"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/ddc/ddcDatabases","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddc%2FddcDatabases","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddc%2FddcDatabases/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddc%2FddcDatabases/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddc%2FddcDatabases/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddc","download_url":"https://codeload.github.com/ddc/ddcDatabases/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddc%2FddcDatabases/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28642697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T18:04:35.752Z","status":"ssl_error","status_checked_at":"2026-01-21T18:03:55.054Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","databases","ddcdatabases","mssql","mssql-database","postgres","postgresql","postgresql-database","postgressql","python","python-3","python3","sqlite","sqlite3","sqlite3-database"],"created_at":"2024-12-01T07:09:14.143Z","updated_at":"2026-01-21T21:02:46.047Z","avatar_url":"https://github.com/ddc.png","language":"Python","funding_links":["https://github.com/sponsors/ddc","https://ko-fi.com/ddcsta","https://www.paypal.com/ncp/payment/6G9Z78QHUD4RJ"],"categories":[],"sub_categories":[],"readme":"# ddcDatabases\n\n[![Donate](https://img.shields.io/badge/Donate-PayPal-brightgreen.svg?style=plastic)](https://www.paypal.com/ncp/payment/6G9Z78QHUD4RJ)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPi](https://img.shields.io/pypi/v/ddcDatabases.svg)](https://pypi.python.org/pypi/ddcDatabases)\n[![PyPI Downloads](https://static.pepy.tech/badge/ddcDatabases)](https://pepy.tech/projects/ddcDatabases)\n[![codecov](https://codecov.io/gh/ddc/ddcDatabases/graph/badge.svg?token=XWB53034GI)](https://codecov.io/gh/ddc/ddcDatabases)\n[![CI/CD Pipeline](https://github.com/ddc/ddcDatabases/actions/workflows/workflow.yml/badge.svg)](https://github.com/ddc/ddcDatabases/actions/workflows/workflow.yml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ddc_ddcDatabases\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=ddc_ddcDatabases)  \n[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A//actions-badge.atrox.dev/ddc/ddcDatabases/badge?ref=main\u0026label=build\u0026logo=none)](https://actions-badge.atrox.dev/ddc/ddcDatabases/goto?ref=main)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Python](https://img.shields.io/pypi/pyversions/ddcDatabases.svg)](https://www.python.org/downloads)\n\n[![Support me on GitHub](https://img.shields.io/badge/Support_me_on_GitHub-154c79?style=for-the-badge\u0026logo=github)](https://github.com/sponsors/ddc)\n\n\nA Python library for database connections and ORM queries with support for multiple database engines including SQLite, PostgreSQL, MySQL, MSSQL, Oracle, and MongoDB.\n\n## Table of Contents\n\n- [Installation](#installation)\n  - [Basic Installation (SQLite only)](#basic-installation-sqlite-only)\n  - [Database-Specific Installations](#database-specific-installations)\n- [Features](#features)\n  - [Default Session Settings](#default-session-settings)\n- [Database Classes](#database-classes)\n  - [SQLite](#sqlite)\n  - [MSSQL (SQL Server)](#mssql-sql-server)\n  - [PostgreSQL](#postgresql)\n  - [MySQL](#mysql)\n  - [Oracle](#oracle)\n  - [MongoDB](#mongodb)\n- [Database Engines](#database-engines)\n- [Database Utilities](#database-utilities)\n  - [Available Methods](#available-methods)\n- [Logging](#logging)\n- [Development](#development)\n  - [Building from Source](#building-from-source)\n  - [Running Tests](#running-tests)\n- [License](#license)\n- [Support](#support)\n\n\n## Features\n\n- **Multiple Database Support**: SQLite, PostgreSQL, MySQL, MSSQL, Oracle, and MongoDB\n- **Sync and Async Support**: Both synchronous and asynchronous operations\n- **Environment Configuration**: Optional parameters with `.env` file fallback\n- **SQLAlchemy Integration**: Built on top of SQLAlchemy ORM\n- **Connection Pooling**: Configurable connection pooling for better performance\n\n### Default Session Settings\n\n- `autoflush = False`\n- `expire_on_commit = False` \n- `echo = False`\n\n**Note:** All constructor parameters are optional and fall back to [.env](./ddcDatabases/.env.example) file variables.\n\n\n## Installation\n\n### Basic Installation (SQLite only)\n```shell\npip install ddcDatabases\n```\n\n**Note:** The basic installation includes only SQlite. Database-specific drivers are optional extras that you can install as needed.\n\n### Database-Specific Installations\n\nInstall only the database drivers you need:\n\n```shell\n# All database drivers (recommended for development)\npip install ddcDatabases[all]\n\n# SQL Server / MSSQL\npip install ddcDatabases[mssql]\n\n# MySQL / MariaDB\npip install ddcDatabases[mysql]\n\n# PostgreSQL\npip install ddcDatabases[pgsql]\n\n# Oracle Database\npip install ddcDatabases[oracle]\n\n# MongoDB\npip install ddcDatabases[mongodb]\n\n# Multiple databases (example)\npip install ddcDatabases[mysql,pgsql,mongodb]\n```\n\n**Available Database Extras:**\n- `all` - All database drivers\n- `mssql` - Microsoft SQL Server (pyodbc, aioodbc)\n- `mysql` - MySQL/MariaDB (pymysql, aiomysql)\n- `pgsql` - PostgreSQL (psycopg2-binary, asyncpg)\n- `oracle` - Oracle Database (cx-oracle)\n- `mongodb` - MongoDB (pymongo)\n\n**Platform Notes:**\n- SQLite support is included by default (no extra installation required)\n- PostgreSQL extras may have compilation requirements on some systems\n- All extras support both synchronous and asynchronous operations where applicable\n\n\n## Database Classes\n\n### SQLite\n\n**Example:**\n```python\nimport sqlalchemy as sa\nfrom ddcDatabases import DBUtils, Sqlite\nfrom your_models import Model  # Your SQLAlchemy model\n\nwith Sqlite(filepath=\"data.db\") as session:\n    db_utils = DBUtils(session)\n    stmt = sa.select(Model).where(Model.id == 1)\n    results = db_utils.fetchall(stmt)\n    for row in results:\n        print(row)\n```\n\n\n\n\n\n### MSSQL (SQL Server)\n\n**Synchronous Example:**\n```python\nimport sqlalchemy as sa\nfrom ddcDatabases import DBUtils, MSSQL\nfrom your_models import Model\n\nkwargs = {\n    \"host\": \"127.0.0.1\",\n    \"port\": 1433,\n    \"user\": \"sa\",\n    \"password\": \"password\",\n    \"database\": \"master\",\n    \"db_schema\": \"dbo\",\n    \"echo\": True,\n    \"autoflush\": True,\n    \"expire_on_commit\": True,\n    \"autocommit\": True,\n    \"connection_timeout\": 30,\n    \"pool_recycle\": 3600,\n    \"pool_size\": 25,\n    \"max_overflow\": 50,\n}\n\nwith MSSQL(**kwargs) as session:\n    stmt = sa.select(Model).where(Model.id == 1)\n    db_utils = DBUtils(session)\n    results = db_utils.fetchall(stmt)\n    for row in results:\n        print(row)\n```\n\n**Asynchronous Example:**\n```python\nimport asyncio\nimport sqlalchemy as sa\nfrom ddcDatabases import DBUtilsAsync, MSSQL\nfrom your_models import Model\n\nasync def main():\n    async with MSSQL(**kwargs) as session:\n        stmt = sa.select(Model).where(Model.id == 1)\n        db_utils = DBUtilsAsync(session)\n        results = await db_utils.fetchall(stmt)\n        for row in results:\n            print(row)\nasyncio.run(main())\n```\n\n\n\n\n\n\n### PostgreSQL\n\n**Synchronous Example:**\n```python\nimport sqlalchemy as sa\nfrom ddcDatabases import DBUtils, PostgreSQL\nfrom your_models import Model\n\nkwargs = {\n    \"host\": \"127.0.0.1\",\n    \"port\": 5432,\n    \"user\": \"postgres\",\n    \"password\": \"postgres\",\n    \"database\": \"postgres\",\n    \"echo\": True,\n    \"autoflush\": False,\n    \"expire_on_commit\": False,\n    \"autocommit\": True,\n    \"connection_timeout\": 30,\n    \"pool_recycle\": 3600,\n    \"pool_size\": 25,\n    \"max_overflow\": 50,\n}\n\nwith PostgreSQL(**kwargs) as session:\n    stmt = sa.select(Model).where(Model.id == 1)\n    db_utils = DBUtils(session)\n    results = db_utils.fetchall(stmt)\n    for row in results:\n        print(row)\n```\n\n**Asynchronous Example:**\n```python\nimport asyncio\nimport sqlalchemy as sa\nfrom ddcDatabases import DBUtilsAsync, PostgreSQL\nfrom your_models import Model\n\nasync def main():\n    async with PostgreSQL(**kwargs) as session:\n        stmt = sa.select(Model).where(Model.id == 1)\n        db_utils = DBUtilsAsync(session)\n        results = await db_utils.fetchall(stmt)\n        for row in results:\n            print(row)\nasyncio.run(main())\n```\n\n\n\n\n\n\n\n### MySQL\n\n**Synchronous Example:**\n```python\nimport sqlalchemy as sa\nfrom ddcDatabases import DBUtils, MySQL\n\nkwargs = {\n    \"host\": \"127.0.0.1\",\n    \"port\": 3306,\n    \"user\": \"root\",\n    \"password\": \"root\",\n    \"database\": \"dev\",\n    \"echo\": True,\n    \"autoflush\": False,\n    \"expire_on_commit\": False,\n    \"autocommit\": True,\n    \"connection_timeout\": 30,\n    \"pool_recycle\": 3600,\n    \"pool_size\": 25,\n    \"max_overflow\": 50,\n}\n\nwith MySQL(**kwargs) as session:\n    stmt = sa.text(\"SELECT * FROM users WHERE id = 1\")\n    db_utils = DBUtils(session)\n    results = db_utils.fetchall(stmt)\n    for row in results:\n        print(row)\n```\n\n**Asynchronous Example:**\n```python\nimport asyncio\nimport sqlalchemy as sa\nfrom ddcDatabases import DBUtilsAsync, MySQL\nasync def main() -\u003e None:\n    async with MySQL(**kwargs) as session:\n        stmt = sa.text(\"SELECT * FROM users\")\n        db_utils = DBUtilsAsync(session)\n        results = await db_utils.fetchall(stmt)\n        for row in results:\n            print(row)\nasyncio.run(main())\n\n```\n\n\n\n\n\n### Oracle\n\n**Example with explicit credentials:**\n```python\nimport sqlalchemy as sa\nfrom ddcDatabases import DBUtils, Oracle\n\nkwargs = {\n    \"host\": \"127.0.0.1\",\n    \"port\": 1521,\n    \"user\": \"system\",\n    \"password\": \"oracle\",\n    \"servicename\": \"xe\",\n    \"echo\": False,\n    \"autoflush\": False,\n    \"expire_on_commit\": False,\n    \"autocommit\": True,\n    \"connection_timeout\": 30,\n    \"pool_recycle\": 3600,\n    \"pool_size\": 25,\n    \"max_overflow\": 50,\n}\n\nwith Oracle(**kwargs) as session:\n    stmt = sa.text(\"SELECT * FROM dual\")\n    db_utils = DBUtils(session)\n    results = db_utils.fetchall(stmt)\n    for row in results:\n        print(row)\n```\n\n\n\n\n\n\n\n\n### MongoDB\n\n**Example with explicit credentials:**\n```python\nfrom ddcDatabases import MongoDB\nfrom bson.objectid import ObjectId\n\nkwargs = {\n    \"host\": \"127.0.0.1\",\n    \"port\": 27017,\n    \"user\": \"admin\",\n    \"password\": \"admin\",\n    \"database\": \"admin\",\n    \"collection\": \"test_collection\",\n    \"sort_column\": \"_id\",\n    \"sort_order\": \"asc\", # asc or desc\n}\n\nquery = {\"_id\": ObjectId(\"689c9f71dd642a68cfc60477\")}\nwith MongoDB(**kwargs, query=query) as cursor:\n    for each in cursor:\n        print(each)\n```\n\n\n\n\n\n\n\n\n## Database Engines\n\nAccess the underlying SQLAlchemy engine for advanced operations:\n\n**Synchronous Engine:**\n```python\nfrom ddcDatabases import PostgreSQL\n\nwith PostgreSQL() as session:\n    engine = session.bind\n    # Use engine for advanced operations\n```\n\n**Asynchronous Engine:**\n```python\nfrom ddcDatabases import PostgreSQL\n\nasync def main():\n    async with PostgreSQL() as session:\n        engine = session.bind\n        # Use engine for advanced operations\n```\n\n\n\n\n## Database Utilities\n\nThe `DBUtils` and `DBUtilsAsync` classes provide convenient methods for common database operations:\n\n### Available Methods\n\n```python\nfrom ddcDatabases import DBUtils, DBUtilsAsync\n\n# Synchronous utilities\ndb_utils = DBUtils(session)\nresults = db_utils.fetchall(stmt)           # Returns list of RowMapping objects\nvalue = db_utils.fetchvalue(stmt)           # Returns single value as string\ndb_utils.insert(stmt)                       # Insert into model table\ndb_utils.deleteall(model)                   # Delete all records from model\ndb_utils.insertbulk(model, data_list)      # Bulk insert from list of dictionaries\ndb_utils.execute(stmt)                      # Execute any SQLAlchemy statement\n\n# Asynchronous utilities (similar interface with await)\ndb_utils_async = DBUtilsAsync(session)\nresults = await db_utils_async.fetchall(stmt)\n```\n\n\n\n\n## Logging\n```python\nimport logging\nlogging.getLogger('ddcDatabases').setLevel(logging.INFO)\nlogging.getLogger('ddcDatabases').addHandler(logging.StreamHandler())\n```\n\n\n## Development\n\n### Building from Source\n```shell\npoetry build -f wheel\n```\n\n### Running Tests\n```shell\npoetry update --with test\npoe tests\n```\n\n## License\n\nReleased under the [MIT License](LICENSE)\n\n## Support\n\nIf you find this project helpful, consider supporting development:\n\n- [GitHub Sponsor](https://github.com/sponsors/ddc)\n- [ko-fi](https://ko-fi.com/ddcsta)\n- [PayPal](https://www.paypal.com/ncp/payment/6G9Z78QHUD4RJ)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddc%2Fddcdatabases","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddc%2Fddcdatabases","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddc%2Fddcdatabases/lists"}