duckgate

Interactive SQL shell over S3 data (Parquet, Iceberg, CSV) using DuckDB.

Install

duckgate is a CLI tool, so an isolated install is recommended over a bare pip install:

uv tool install duckgate
# or
pipx install duckgate

Quick start

duckgate init          # prompts for a config path (default: ~/.duckgate/config.toml)
duckgate tables        # list available tables
duckgate               # open interactive shell
duckgate -q "SELECT COUNT(*) FROM my_table"  # one-shot query

duckgate init accepts Enter to take the suggested default, or a path you type (e.g. a local duckgate.toml for a per-project override). Pass -p/--path to skip the prompt entirely — handy in scripts: duckgate init --path duckgate.toml.

Configuration

duckgate.toml in the current directory, falling back to ~/.duckgate/config.toml:

[aws]
profile = "my-aws-profile"
region  = "eu-central-1"

[glue]
enabled   = true
databases = []  # empty = all databases

[[tables]]
name   = "fis_location"
path   = "s3://my-bucket/structured/sqlserver/dev/fis/location/**/*.parquet"
format = "parquet"  # parquet | iceberg | csv

Table resolution

• Glue tables are discovered automatically from the configured databases. A bare Glue table location (no wildcard) is read as location/**/*.<format>.
• Local [[tables]] entries override Glue tables with the same name — use this to point to a specific environment prefix.
• If two Glue tables from different databases share a name, they are registered as database__table_name.

AWS credentials

Uses the AWS profile from [aws] profile. Works with SSO (aws sso login, Granted assume) and static credentials alike.

Supported formats

Development

uv sync
uv run pytest
uv run ruff check --fix .
uv run ruff format .

Release

Pushing a v* tag (e.g. v0.1.0) builds and publishes to PyPI via GitHub Actions, using PyPI Trusted Publishing (see .github/workflows/publish.yml). Bump __version__ in duckgate/__init__.py to match before tagging.

License

Apache License 2.0 — see LICENSE.