{"id":20351798,"url":"https://github.com/tobilg/duckdb-api","last_synced_at":"2025-07-31T19:02:09.909Z","repository":{"id":262900036,"uuid":"885875644","full_name":"tobilg/duckdb-api","owner":"tobilg","description":"Running DuckDB behind a Hono.js API","archived":false,"fork":false,"pushed_at":"2024-11-10T16:47:54.000Z","size":37,"stargazers_count":39,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-14T23:02:54.747Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/tobilg.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":"2024-11-09T16:15:26.000Z","updated_at":"2024-11-13T19:43:27.000Z","dependencies_parsed_at":"2024-11-14T23:02:56.946Z","dependency_job_id":"8c2f3ec8-e3ed-4d88-856e-f8beb28e2625","html_url":"https://github.com/tobilg/duckdb-api","commit_stats":null,"previous_names":["tobilg/duckdb-api"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobilg","download_url":"https://codeload.github.com/tobilg/duckdb-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236464833,"owners_count":19152979,"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-14T23:00:46.751Z","updated_at":"2025-07-31T19:02:09.869Z","avatar_url":"https://github.com/tobilg.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Backends"],"sub_categories":[],"readme":"# duckdb-api\nRunning [DuckDB](https://duckdb.org/) behind a [Hono.js](https://hono.dev/) API in a Docker container.\n\n## Building the Docker image\n\n```bash\nnpm run build:docker\n```\n\n## Usage\nTo build and run the Docker container, use the following commands:\n\n```bash\nnpm run dev:docker\n```\n\nThis will expose the DuckDB API on port `3000`.\n\n### Environment Variables\nYou can set the port:\n- `PORT`: The port to run the API on. Defaults to `3000`. (optional)\n\nIf you want to use Bearer Auth, set the following:\n- `API_TOKEN`: The API Token to be used for bearer auth. (optional)\n\nIf you want to activate basic auth for the API, set both the `USERNAME` and the `PASSWORD` environment variables:\n- `USERNAME`: The username to be used for basic auth. (optional)\n- `PASSWORD`: The password to be used for basic auth. (optional)\n\nIn case you want to use AWS S3, set the `AWS_REGION`, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables with the appropriate values (you need to have set up the appropriate credentials beforehand in your AWS account):\n- `AWS_REGION`: The AWS region to be used for S3 access (optional)\n- `AWS_ACCESS_KEY_ID`: The AWS access key ID to be used for S3 access (optional)\n- `AWS_SECRET_ACCESS_KEY`: The AWS secret access key to be used for S3 access (optional)\n\nWhen you want to use the [R2 Data Catalog](https://developers.cloudflare.com/r2/data-catalog/get-started/) (i.e. your data resides in R2) for Apache Iceberg tables, you need to add the following environment variables:\n- `R2_CATALOG`: The catalog name\n- `R2_ENDPOINT`: The catalog endpoint URI\n- `R2_TOKEN`: The Cloudflare API Token for R2 (see [docs](https://developers.cloudflare.com/r2/data-catalog/get-started/#3-create-an-api-token))\n\n### API Documentation\nThere are two endpoints available:\n\n- `POST /query`: Executes a SQL query and returns the result as a JSON object.\n- `POST /streaming-query`: Executes a SQL query and streams the Arrow data to the client.\n\nThe request body of both endpoints is a JSON object with a `query` property, which contains the SQL query to execute.\n\n### Examples\n\nSimple query to the JSON endpoint\n```bash\ncurl -X POST http://localhost:3000/query -H \"Content-Type: application/json\" -d '{\"query\": \"SELECT 1;\"}'\n```\nStreaming query from a remote Parquet file\n```bash\ncurl --location 'localhost:3000/streaming-query' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"query\": \"SELECT * FROM '\\''https://shell.duckdb.org/data/tpch/0_01/parquet/orders.parquet'\\'' LIMIT 100\"\n  }' \\\n  --output /tmp/result.arrow\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Fduckdb-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobilg%2Fduckdb-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Fduckdb-api/lists"}