{"id":43352164,"url":"https://github.com/dimagi/db-query-fwd","last_synced_at":"2026-02-02T02:32:36.715Z","repository":{"id":327305060,"uuid":"1101417483","full_name":"dimagi/db-query-fwd","owner":"dimagi","description":"Forwards a SQL query result to a web API endpoint","archived":false,"fork":false,"pushed_at":"2025-12-02T23:09:47.000Z","size":146,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-05T22:49:37.196Z","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":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dimagi.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-21T16:36:44.000Z","updated_at":"2025-11-21T17:25:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dimagi/db-query-fwd","commit_stats":null,"previous_names":["dimagi/db-query-fwd"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dimagi/db-query-fwd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fdb-query-fwd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fdb-query-fwd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fdb-query-fwd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fdb-query-fwd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dimagi","download_url":"https://codeload.github.com/dimagi/db-query-fwd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fdb-query-fwd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29001654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T01:32:03.847Z","status":"online","status_checked_at":"2026-02-02T02:00:07.448Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-02-02T02:32:36.065Z","updated_at":"2026-02-02T02:32:36.708Z","avatar_url":"https://github.com/dimagi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Database Query Forwarder\n========================\n\nForwards a SQL query result to a web API endpoint.\n\n\nUse Case\n--------\n\n**DQF** was created to send data, aggregated in PostgreSQL, to the\n[DHIS2 API for data value sets](https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-242/data.html).\n\nIt is generic enough to send data from any database that can return a\nresult as a JSON object (e.g. SQL Server, MySQL, MariaDB, Oracle\nDatabase, IBM Db2) to any API endpoint that accepts JSON data and\nsupports basic authentication.\n\nBased on this use case, **DQF** expects queries to return only one row,\nand only one field, which contains the payload. It will return an error\nif a query returns more than one row and more than one field.\n\n\nInstallation\n------------\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003eLinux/Mac\u003c/b\u003e\u003c/summary\u003e\n\n1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/).\n\n2. Clone this repository and install dependencies:\n   ```shell\n   $ git clone https://github.com/dimagi/db-query-fwd.git\n   $ cd db-query-fwd/\n   $ uv sync --extra postgres\n   ```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindows\u003c/b\u003e\u003c/summary\u003e\n\nDownload the Windows executable:\n\n1. Open https://github.com/dimagi/db-query-fwd in your browser.\n2. Navigate to the \"Actions\" tab.\n3. Open the latest workflow run, or select \"Build Windows executable\"\n   and click \"Run workflow\" if no workflow runs are listed.\n4. Download the `dqf-exe` artifact.\n5. Unzip `dqf-exe.zip` and extract `dqf.exe`.\n\nNo Python installation required.\n\n\u003c/details\u003e\n\n\nUsage\n-----\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003eLinux/Mac\u003c/b\u003e\u003c/summary\u003e\n\n```shell\n$ dqf \\\n    --log-level [none,info,debug] \\\n    --log-file \u003cfilename\u003e \\\n    --config-file \u003cfilename\u003e \\\n    query_name \\\n    [query_param] [query_param] etc.\n```\n\nThe log level given on the command line overrides the value set in the\nconfig file. If not specified, the default value is \"info\".\n\nThe log file given on the command line overrides the value set in the\nconfig file. If not specified, the default value is \"dqf.log\".\n\nThe config file defaults to \"dqf.toml\".\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindows\u003c/b\u003e\u003c/summary\u003e\n\nUsing the Windows executable, `dqf.exe`:\n\n```shell\n\u003e dqf.exe query_name [query_param] [query_param] etc.\n```\n\n\u003c/details\u003e\n\n\nEnvironment Variables\n---------------------\n\nThe use of environment variables is optional. The following are\navailable:\n\n`DB_FWD_DB_URL` stores the URL of the database to query for all queries.\n\n`DB_FWD_API_USERNAME` stores the username to use for API authentication.\nCurrently basic auth is the only API authentication method that **DQF**\nsupports.\n\n`DB_FWD_API_PASSWORD` stores the password to use for API authentication.\n\n\nConfiguration File\n------------------\n\n**DQF** looks for a configuration file named \"dqf.toml\" by default.\nThe configuration file is given in TOML format. This file can contain\npasswords, and should only be readable by the user that **DQF** will\nrun as.\n\nThe `dqf.toml.example` file includes detailed examples. It can be\ncopied to `dqf.toml`and customized.\n\nThe following is an example configuration:\n\n```toml\n[dqf]\nlog_level = 'info'\nlog_file = 'dqf.log'\nlog_db_url = 'postgresql://username:Passw0rd1@pg.example.com:5432/dbname'\n\n[queries]\ndb_url = 'postgresql://username:Passw0rd1@pg.example.com:5432/dbname'\napi_username = 'admin@example.com'\napi_password = 'Password!'\n\n[queries.queryname1]\nquery = \"SELECT json_payload FROM queryname1_view WHERE period = :param1;\"\napi_url = 'https://dhis2.example.com/api/dataset/abcd1234/'\n\n[queries.queryname2]\nquery = \"SELECT json_payload FROM queryname2_view WHERE category_id = :param1 AND period = :param2;\"\napi_url = 'https://dhis2.example.com/api/dataset/efgh5678/'\n```\n\n\n### `dqf` Section\n\n#### Logging\n\nIf not specified, `log_level` defaults to \"info\". Valid values are\n\"none\", \"info\" and \"debug\". The log level applies to both the log file\nand the log database.\n\nIf not specified, `log_file` defaults to \"dqf.log\".\n\n`log_db_url` is optional. It stores a database URL. If it is specified\nthen logs will be stored in the \"dqf_logs\" table.\n\n\n### `queries` Section\n\n`db_url` is the URL of the database to query for all queries. This\nsetting overrides the environment variable \"DB_FWD_DB_URL\". A query can\noverride this value by specifying `db_url` in its section.\n\n`api_url` can be used to specify the URL that all query results are\nforwarded to. This setting is optional. A query can override this value\nby specifying `api_url` in its section.\n\n`api_username` sets the username, and `api_password` override the\nenvironment variables \"DB_FWD_API_USERNAME\" and \"DB_FWD_API_PASSWORD\".\n\n\n### `queries.queryname` Sections\n\nEach query has a section, where \"queryname\" is the name of the query as\nit will be given on the command line.\n\n`query` is the SQL query that will be executed. It must return a single\nfield. Query parameters should use named placeholders (`:param1`,\n`:param2`, etc.). Parameters passed on the command line are mapped to\nthese placeholders in order (first command line parameter becomes\n`:param1`, second becomes `:param2`, etc.).\n\n`api_url` is the API endpoint that the value of the field returned by\n`query` will be forwarded to. If `api_url` was given in the `queries`\nsection then this setting is optional. If both are given then this value\noverrides the value given in the `queries` section.\n\n`api_username` and `api_password` can optionally be set here to override\nthe values given in the `queries` section.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimagi%2Fdb-query-fwd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimagi%2Fdb-query-fwd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimagi%2Fdb-query-fwd/lists"}