Metadata-Version: 2.5
Name: wherobots-dbt
Version: 0.1.3
Summary: The Wherobots adapter plugin for dbt
Project-URL: Homepage, https://wherobots.com
Project-URL: Documentation, https://docs.wherobots.com/develop/dbt
Author-email: Wherobots <support@wherobots.com>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: dbt-adapters<2.0,>=1.9.0
Requires-Dist: dbt-common<2.0,>=1.12.0
Requires-Dist: dbt-core<2.0,>=1.9.0
Requires-Dist: wherobots-python-dbapi>=0.30.1
Description-Content-Type: text/markdown

# wherobots-dbt

The Wherobots adapter for [dbt](https://www.getdbt.com/). Write spatial models as SQL, run them on
Wherobots Cloud, and keep them version-controlled, tested, and documented like the rest of your dbt
project.

## Install

```bash
pip install wherobots-dbt
```

Requires Python 3.10 or later and dbt Core 1.9 or later (below 2.0).

## Configure

Add a Wherobots target to `~/.dbt/profiles.yml`. Read the API key from an environment variable so no
secret is written to disk.

```yaml
my_project:
  target: dev
  outputs:
    dev:
      type: wherobots
      host: api.cloud.wherobots.com
      catalog: my_catalog          # a catalog you can write to (dbt's `database`)
      schema: my_namespace
      api_token: "{{ env_var('WHEROBOTS_API_KEY') }}"
      runtime: micro               # optional
      region: aws-us-west-2        # optional
      threads: 1
```

```bash
export WHEROBOTS_API_KEY="<your-api-key>"
dbt debug
```

## Sessions and billing

dbt runs on a Wherobots SQL session. During one dbt invocation, the adapter reuses its connections
for every model and holds at most `threads` + 1 at a time, and dbt closes them when it exits. With
the defaults (`session_type: multi`, `force_new: false`), they all use one runtime.

Billing starts when the session is ready, not while its runtime starts. After the session's last
connection closes, which is when dbt exits if no other run uses the session, the session keeps
running, and billing, for `shutdown_after_inactive_seconds` (about 5 minutes when unset), plus up
to about 3 minutes until the server's idle check stops it. A run with `force_new: false` that
starts in that window attaches to it in seconds.

You can change this with three optional profile keys:

```yaml
      session_type: multi                   # single: never share a runtime with another open connection
      force_new: false                      # true: every connection starts a new runtime
      shutdown_after_inactive_seconds: 60   # stops 1–4 minutes after the last run exits
```

A connection with `force_new: false` attaches to a running session that has the same Wherobots user
(through the API key), region, `runtime`, `session_type` and `shutdown_after_inactive_seconds`,
even one started by a different dbt project. An unset `runtime` or `session_type` matches its
default, but an unset `shutdown_after_inactive_seconds` matches only another unset one.
`force_new: true` doesn't keep runs apart, because other runs can still attach to the session it
starts; use `session_type: single` for that. See
[Sessions and billing](https://github.com/wherobots/wherobots-dbt#sessions-and-billing) for the rules,
how to keep runs apart, and an example for scheduled runs.

## What works

- `dbt debug`, `seed`, `run`, `test`, `snapshot`, `docs generate`, `show`, and `source freshness`.
- Materializations: `view`, `table`, `ephemeral`, `incremental` (`append`, `merge`,
  `delete+insert`, `insert_overwrite`), and `snapshot`. Persisted models are Havasu (Apache Iceberg)
  tables.
- Spatial columns: `geometry` seeds load from WKT, EWKT, GeoJSON, or WKB with a real SRID, and models
  can materialize `geometry`, `geography`, and `raster` columns.

## Documentation

See [Wherobots dbt Adapter](https://docs.wherobots.com/develop/dbt) for the profile reference,
materializations, and working with spatial data.

## License

Apache-2.0
