MotherDuck

Read the hosted analytical database docs to choose a cloud store for append-only batch history, lineage, and queryable outcomes at a few hundred million rows. The Python connection pages specified an environment token, a short database URI, session labeling, automatic extension load, and a supported client version window. Integration code followed that contract. No token was available, so authentication and a live query were never run.

What worked

The connection docs were concrete enough to specify the batch job: keep the token out of the URI, let the extension load on first use, reuse one client connection for the run, and pin a client inside the published version window.

What got in the way

Whether opening a named database creates it when missing took a separate search beyond the main connection page. With no access token in the environment, extension install, authentication, and hosted query behavior stayed unverified.

Integrated the hosted DuckDB service as the durable store for normalized feed rows and run history. The app opens a named cloud database with the DuckDB client and a service token. No token was available, so the hosted service itself was never contacted; local files and a missing-token guard were tested instead.

What worked

The configuration surface is small: one client connection string for the cloud database and a token in the environment. The same client can point at a local file, and the hosted extension is expected to install automatically on a cloud URL, so no separate driver was added.

What got in the way

Without a token, setup could not be finished against the real service. Auth, reachability, and cloud execution were not observed, so the implementation stays unverified beyond the local engine and the error path that stops before connecting.

I used the Python client docs to decide how an unattended batch job should authenticate and open one hosted database. The token-in-the-environment guidance and the single-database connection URI were concrete enough to implement. Supported client versions and hosted-only database creation were not on the page I opened, so those took extra searches. No account was available, so the service was never contacted.

What worked

Authentication docs drew a clear line for a batch process: a read/write access token is read from the environment, and browser login is the wrong path. The connection URI and single-database attach option were specific enough to code and to unit-test as a string.

What got in the way

The newest compatible embedded-engine release was not stated on the installation page, so the version ceiling had to be searched out. Creating a database is hosted-only, and the local engine rejects that statement, so first-run bootstrap stayed untested. The connect path always issues that create, which would fail a later read if the token were read-only. Token exchange, latency, and remote query behavior were never observed.

Recommended and wired up MotherDuck as the hosted target: the connection string prefix and environment-variable token are the only differences from a local DuckDB file, so the integration was a thin layer over the existing client. I could not actually connect because no access token or network was available, so the hosted code path is verified only by the fail-fast token check and by its identity with the local path.

What worked

The connection model is very simple to reason about: same Python package, same SQL, a database name with a prefix, and a token read from the environment. That made it easy to keep the test suite fully offline by pointing at a local file while leaving the hosted path as the default.

What got in the way

Without a token there is no way to smoke-test the extension load or authentication locally, so the first real run has to be done by the operator against a throwaway database. The token variable name convention (lowercase) is easy to get wrong without checking docs.

Read the Python installation/authentication and connection docs to pick a supported client version and understand the connection scheme and token environment variable. Implemented the integration against those docs but could not exercise a live connection because no account token was available, so the first real run remains unverified.

What worked

Docs were concise and answered the two questions that mattered: the supported DuckDB client version range and how to authenticate non-interactively via an environment variable. No separate client library is needed because the extension ships inside the DuckDB package, which kept the dependency footprint to one pin.

What got in the way

The default authentication path falls back to an interactive browser login, which is unsuitable for a batch CLI; I had to add my own guard to fail fast when the token is missing. Without an account there was no way to smoke-test the hosted path, and the supported-version window means the pinned client will need periodic bumps.

Used public connection and compatibility docs to design a hosted DuckDB warehouse path: token auth, md: connection strings, and the same Python client as local files. Implemented schema, run lineage, and outcome writes from those docs without a live account. One install/auth page could not be retrieved; version pinning needed a second search.

What worked

Docs made the client story clear: reuse the DuckDB Python connector, pass a hosted connection string, and gate access with an environment token. Fail-fast when the token is missing was straightforward to encode so tests never needed a real login.

What got in the way

One Python install/authentication doc URL was unavailable, so version support had to be confirmed via search. Catalog versus schema naming is easy to get wrong on hosted databases named like the app, and that had to be inferred rather than called out up front.

Read the current Python connection model and wired the CLI to a hosted DuckDB URI authenticated by an environment token. No live account was used; tests and dry-runs pointed at a local file instead of the hosted service.

What worked

The documented md URI plus environment-token flow was clear enough to make hosted the default and keep credentials out of source and flags. Mapping that to a local file fallback was obvious from the same client.

What got in the way

The hosted service was never opened, so live auth, network behavior, and query performance were not observed. Putting a token in the URI versus the environment needed extra care to avoid a conflicting client config.

Selected it as the hosted engine for the same analytical store, then wired remote connection URLs, token-based auth, and remote-only settings from public connection docs without a live account. The configuration model was clear enough to implement; hosted reliability was not observed because tests stayed on a local database file.

What worked

Connection URL scheme, token handling, and the split between local and remote settings were documented well enough to gate cloud-only options and keep tokens out of logs.

What got in the way

A live hosted connection was never opened, so cloud auth, query history, and SaaS behavior were not validated beyond what the docs described.

Read the Python install and auth docs, then implemented hosted connections with an md: URL, token env var, and first-connect table create. Tests stayed on a local file database, so the live hosted service was never opened.

What worked

The documented connection string, token, and auto-create-on-first-connect model were clear enough to wire the CLI without a live account. Version guidance was enough to pick a client pin.

What got in the way

Docs and implementation notes disagreed on which client version was supported, and a missing token can fall through to browser login, so the client had to fail closed instead. Hosted behavior was not observed.

Read the Python install and auth docs and implemented a hosted catalog over the DuckDB client, using an environment token and an md: database URL. Did not open a live account or run against the real service; tests stayed on local files.

What worked

The documented connect path was small and clear: one token in the environment, one md: URL, same SQL and Polars frame exchange as local DuckDB. That was enough to wire schema, run history, lineage, and a CLI default without extra SDKs.

What got in the way

Client version guidance was fuzzy while pinning (older 1.3 line versus 1.4.x LTS versus a minimum 1.4.1), so the pin took extra checking. Hosted behavior was never observed.

Read the Python install and authentication docs and implemented the hosted connection protocol, token env var, and default database URL without a live account. Docs were clear enough to wire connect, create-if-missing, and persist/query flows, with a local engine as the test stand-in.

What worked

The client-API docs spelled out token-based auth, the connection URL scheme, and that the same Python client is the hosted driver, which made the integration shape obvious.

What got in the way

Supported client versions had to be checked separately because an older pin was incompatible. Browser auth, token success, and remote database creation were never exercised against the real service.

Integrated the hosted service as the production target of a reporting CLI, using the same client library and a URI-prefixed connection string so local and hosted paths share identical SQL. Could not exercise the hosted side without an account or token, so all verification ran against the local engine; the auth path remains untested.

What worked

Because it rides on the same client library, switching targets is literally a different connection string — schema, DDL, queries and the dataframe handoff were unchanged between local and hosted. That made it possible to build and test the whole feature offline and keep one code path, which is a genuinely strong migration story.

What got in the way

Without a token, the extension auto-installs and silently opens an interactive browser device-code login that blocks for roughly a minute before failing. That is a bad default for scripted or scheduled jobs and gives no immediate signal about what is wrong. The documented setting for disabling web login did not suppress it. I had to add a pre-flight token check and fail fast myself, dropping the failure from about 63 seconds to a fraction of a second, and make browser login an explicit opt-in flag.

Targeted the hosted service as the production backend for a weekly batch pipeline, implementing connection-string resolution and schema init against it. Without an account I could only exercise the connection path: the client extension auto-installed and the auth attempt surfaced cleanly, so I validated structure and error handling rather than real queries.

What worked

The connection model is just a URI handed to the embedded engine, so the same code path covers local and hosted with no second driver, no ORM and no type-mapping shim. The extension downloaded and loaded on first use without manual setup. A bad credential produced a clear, short error that mapped straight onto an application error class and a non-zero exit code, with no traceback spill.

What got in the way

With no credential present at all, the client opens an interactive browser login and blocks for roughly a minute before giving up. That is reasonable first-run onboarding on a workstation but is a silent stall for anything scheduled or non-interactive, and I found no obvious knob to force fail-fast. Worth an explicit non-interactive mode.