Skip to content

Make base API URL configurable via env var and kwarg#23

Merged
CollierKing merged 4 commits into
mainfrom
feature/issue-22-configurable-base-url
Apr 17, 2026
Merged

Make base API URL configurable via env var and kwarg#23
CollierKing merged 4 commits into
mainfrom
feature/issue-22-configurable-base-url

Conversation

@CollierKing

@CollierKing CollierKing commented Apr 16, 2026

Copy link
Copy Markdown
Owner

Summary

  • Connection and AsyncConnection now accept a base_url kwarg to override the hard-coded Cloudflare endpoint
  • Falls back to the CF_D1_BASE_URL environment variable, then the default Cloudflare URL

Usage

# Recommended: env var (affects all connections in the process)
CF_D1_BASE_URL=http://localhost:8787

# Recommended: connect_args (clean, no URL encoding needed)
create_engine(
    "cloudflare_d1://acct:token@db",
    connect_args={"base_url": "http://localhost:8787"},
)

# Also works: direct kwarg on Connection
Connection(..., base_url="http://localhost:8787")

# Also works: URL query param (requires percent-encoding)
create_engine("cloudflare_d1://acct:token@db?base_url=http%3A%2F%2Flocalhost%3A8787")

Closes #22

Test plan

  • 4 new unit tests in tests/unit/test_dialect.py covering kwarg, env var, default fallback, and query-param passthrough
  • 5 new integration tests in tests/integration/test_base_url_integration.py — spin up a local HTTP server mimicking the D1 /raw response format and verify all override mechanisms route requests there (no Cloudflare credentials required)
  • make test passes (20 unit tests)
  • uv run pytest tests/integration/test_base_url_integration.py -v passes (5 integration tests)

Resolves the hard-coded Cloudflare endpoint in Connection and AsyncConnection
by accepting a `base_url` keyword argument (highest priority), falling back to
the CF_D1_BASE_URL environment variable, and finally the default Cloudflare URL.

Users running a local D1 proxy (e.g. `wrangler dev`) can now point the dialect
at it without patching source code:

  - env var: CF_D1_BASE_URL=http://localhost:8787
  - engine URL query param: cloudflare_d1://acct:token@db?base_url=http%3A%2F%2Flocalhost%3A8787
  - direct kwarg: Connection(..., base_url="http://localhost:8787")
Spins up a minimal in-process HTTP server that mimics the D1 /raw
response envelope to verify that base_url kwarg, CF_D1_BASE_URL env
var, and ?base_url= connection string query param all correctly
redirect requests away from the hard-coded Cloudflare endpoint.
No Cloudflare credentials required.
@CollierKing CollierKing merged commit e85855e into main Apr 17, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Change hard-coded base api url to config or env variable

1 participant