{"id":19147742,"url":"https://github.com/sslivkoff/toolsql","last_synced_at":"2025-07-04T09:04:34.121Z","repository":{"id":40825595,"uuid":"472506054","full_name":"sslivkoff/toolsql","owner":"sslivkoff","description":null,"archived":false,"fork":false,"pushed_at":"2023-12-11T23:54:05.000Z","size":288,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-22T20:17:56.754Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/sslivkoff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2022-03-21T20:44:33.000Z","updated_at":"2023-09-28T00:13:37.000Z","dependencies_parsed_at":"2024-11-09T07:52:01.316Z","dependency_job_id":"e10cc0b4-51a9-45bc-9fe3-3996421ce3a1","html_url":"https://github.com/sslivkoff/toolsql","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/sslivkoff/toolsql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sslivkoff%2Ftoolsql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sslivkoff%2Ftoolsql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sslivkoff%2Ftoolsql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sslivkoff%2Ftoolsql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sslivkoff","download_url":"https://codeload.github.com/sslivkoff/toolsql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sslivkoff%2Ftoolsql/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263480867,"owners_count":23473164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-09T07:51:23.923Z","updated_at":"2025-07-04T09:04:34.059Z","avatar_url":"https://github.com/sslivkoff.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# toolsql\n\ntoolsql makes it easy to build sql queries and execute those queries\n\ntoolsql's goals:\n- provide identical interfaces to sqlite + postgresql\n- provide nearly identical interfaces for synchronous + `async` usage\n- minimize startup import time\n- maximize read / write performance\n- tight integration with connectorx and polars\n- make it easy to drop into raw SQL when needed\n- use basic python datatypes instead of custom objects\n- mypy typing with `strict=True`\n\n## Contents\n- [Installation](#installation)\n- [Example Usage](#example-usage)\n- [Reference](#reference)\n\n## Installation\n- `pip install toolsql`\n- requires python 3.7 - 3.11\n\n\n## Example Usage\n\n1. [Specify Database Configuration](#specify-database-configuration)\n2. [Specify Table Schema](#specify-table-schema)\n3. [DDL Statements](#ddl-statements)\n4. [DML Statements](#dml-statements)\n5. [Transactions](#transactions)\n6. [`async` Functionality](#async-functionality)\n\n#### Specify Database Configuration\n\n```python\n# sqlite\ndb_config = {\n    'dbms': 'sqlite',\n    'path': '/path/to/sqlite/file.db',\n}\n\n# postgresql\ndb_config = {\n    'dbms': 'postgresql',\n    'database': '\u003cdatabase_name\u003e',\n    'hostname': '\u003chostname\u003e',\n    'username': '\u003cusername\u003e',\n    'password': '\u003cpassword\u003e',\n}\n```\n\n#### Specify Table Schema\n\n```python\ntable = {\n    'name': 'weather',\n    'columns': [\n        {'name': 'year', 'type': 'Integer', 'primary': True},\n        {'name': 'month', 'type': 'Integer', 'primary': True},\n        {'name': 'rainfall', 'type': 'Float'},\n        {'name': 'temperature', 'type': 'Float'},\n        {'name': 'country', 'type': 'Float'},\n    ],\n}\n```\n\n#### DDL Statements\n\n```python\n\nwith toolsql.connect(db_config) as conn:\n\n    # CREATE\n    toolsql.create_table(\n        table=table,\n        conn=conn,\n        confirm=True,\n    )\n    \n    # DROP\n    toolsql.drop_table(\n        table=table,\n        conn=conn,\n        confirm=True,\n    )\n```\n\n#### DML Statements\n\n```python\n\nrows = [\n    (2020, 1, 8.2, 90, 'Turkey'),\n    (2020, 5, 1.1, 50, 'Germany'),\n    (2020, 9, 7.4, 60, 'UK'),\n    (2021, 1, 5.2, 72, 'France'),\n    (2021, 5, 2.1, 56, 'Argentina'),\n    (2021, 9, 6.4, 68, 'Sweden'),\n    (2022, 1, 1.2, 70, 'Indonesia'),\n    (2022, 5, 4.1, 56, 'Vietnam'),\n    (2022, 9, 9.4, 60, 'India'),\n]\n\nwith toolsql.connect(db_config) as conn:\n\n    # INSERT\n    toolsql.insert(\n        rows=rows,\n        table=table,\n        conn=conn,\n    )\n    \n    # SELECT\n    toolsql.select(\n        where_equals={'country': 'Turkey'},\n        table=table,\n        conn=conn,\n    )\n    \n    # UPDATE\n    toolsql.update(\n        values={'country': 'Türkiye'},\n        where_equals={'country': 'Turkey'},\n        table=table,\n        conn=conn,\n    )\n    \n    # DELETE\n    toolsql.delete(\n        where_equals={'country': 'Türkiye'},\n        table=table,\n        conn=conn,\n    )\n```\n\n#### Transactions\n\n```python\nwith toolsql.connect(db_config) as conn:\n    with toolsql.transaction(conn)\n        # will commit if context exits error-free\n        # ...\n```\n\n#### `async` Functionality\n```python\nasync with toolsql.async_connect(db_config) as conn:\n\n    await toolsql.async_select(\n        with_equals={'country': 'Turkey'},\n        table=table,\n        conn=conn,\n    )\n\n    async with toolsql.async_transaction():\n\n        await toolsql.async_insert(\n            rows=rows,\n            table=table,\n            conn=conn,\n        )\n        await toolsql.async_update(\n            values={'country': 'Türkiye'},\n            where_equals={'country': 'Turkey'},\n            table=table,\n            conn=conn,\n        )\n        await toolsql.async_delete(\n            where_equals={'country': 'Türkiye'},\n            table=table,\n            conn=conn,\n        )\n```\n\n## Reference\n\n### Supported Executors\n- `sqlite3`: sqlite sync reads\n- `aiosqlite`: sqlite async reads\n- `psycopg`: postgres sync / async reads\n- `connectorx`: simple read queries\n\n### `SELECT` input arguments\n- `distinct`\n- `where_equals`\n- `where_gt`\n- `where_gte`\n- `where_lt`\n- `where_lte`\n- `where_like`\n- `where_ilike`\n- `where_in`\n- `where_or`\n- `order_by`\n- `limit`\n- `offset` \n\n### `SELECT` output formats\n- `'tuple'`: each row is a tuple\n- `'dict'`: each row is a dict\n- `'cursor'`: query cursor\n- `'polars'`: polars dataframe of rows\n- `'pandas'`: pandas dataframe of rows\n- `'single_tuple'`: single row of output as a tuple\n- `'single_tuple_or_none'`: single row of output as a tuple\n- `'single_dict'`: single row of output as a dict\n- `'single_dict_or_none'`: single row of output as a dict\n- `'cell'`: single column of single row\n- `'cell_or_none'`: single column of single row\n- `'single_column'`: single column\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsslivkoff%2Ftoolsql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsslivkoff%2Ftoolsql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsslivkoff%2Ftoolsql/lists"}