dbt-hotdata 0.2.1__tar.gz

dbt_hotdata-0.2.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @hotdata-dev/engineers

dbt_hotdata-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync
+      - name: Lint
+        run: uv run ruff check dbt tests
+      - name: Format
+        run: uv run ruff format --check dbt tests
+      - name: Type-check
+        run: uv run mypy
+      - name: Test (offline)
+        run: uv run pytest -q
+
+  wheel-contents:
+    # The adapter ships as PEP 420 namespace packages (dbt/adapters/hotdata +
+    # dbt/include/hotdata). A packaging change that drops the macros or config
+    # files produces a wheel that imports fine but cannot run a single model —
+    # so assert the contents explicitly.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Assert wheel contents
+        run: |
+          python3 - <<'EOF'
+          import glob, sys, zipfile
+
+          wheel = glob.glob("dist/*.whl")[0]
+          names = set(zipfile.ZipFile(wheel).namelist())
+          required = [
+              "dbt/adapters/hotdata/__init__.py",
+              "dbt/adapters/hotdata/__version__.py",
+              "dbt/adapters/hotdata/client.py",
+              "dbt/adapters/hotdata/column.py",
+              "dbt/adapters/hotdata/connections.py",
+              "dbt/adapters/hotdata/credentials.py",
+              "dbt/adapters/hotdata/impl.py",
+              "dbt/adapters/hotdata/relation.py",
+              "dbt/adapters/hotdata/seeds.py",
+              "dbt/include/hotdata/__init__.py",
+              "dbt/include/hotdata/dbt_project.yml",
+              "dbt/include/hotdata/profile_template.yml",
+              "dbt/include/hotdata/macros/adapters.sql",
+              "dbt/include/hotdata/macros/materializations/table.sql",
+              "dbt/include/hotdata/macros/materializations/incremental.sql",
+              "dbt/include/hotdata/macros/materializations/seed.sql",
+              "dbt/include/hotdata/macros/materializations/view.sql",
+              "dbt/include/hotdata/macros/materializations/snapshot.sql",
+          ]
+          missing = [name for name in required if name not in names]
+          if missing:
+              sys.exit(f"wheel {wheel} is missing: {missing}")
+          print(f"ok: {wheel} contains all {len(required)} required files")
+          EOF

dbt_hotdata-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Assert tag matches pyproject version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "Tag v$TAG does not match pyproject version $VERSION" >&2
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: Assert wheel contents
+        # Same guard as CI: a packaging change that drops the macros or config
+        # files produces a wheel that imports fine but cannot run a model.
+        run: |
+          python3 - <<'EOF'
+          import glob, sys, zipfile
+
+          wheel = glob.glob("dist/*.whl")[0]
+          names = set(zipfile.ZipFile(wheel).namelist())
+          required = [
+              "dbt/adapters/hotdata/__init__.py",
+              "dbt/adapters/hotdata/__version__.py",
+              "dbt/adapters/hotdata/client.py",
+              "dbt/adapters/hotdata/column.py",
+              "dbt/adapters/hotdata/connections.py",
+              "dbt/adapters/hotdata/credentials.py",
+              "dbt/adapters/hotdata/impl.py",
+              "dbt/adapters/hotdata/relation.py",
+              "dbt/adapters/hotdata/seeds.py",
+              "dbt/include/hotdata/__init__.py",
+              "dbt/include/hotdata/dbt_project.yml",
+              "dbt/include/hotdata/profile_template.yml",
+              "dbt/include/hotdata/macros/adapters.sql",
+              "dbt/include/hotdata/macros/materializations/table.sql",
+              "dbt/include/hotdata/macros/materializations/incremental.sql",
+              "dbt/include/hotdata/macros/materializations/seed.sql",
+              "dbt/include/hotdata/macros/materializations/view.sql",
+              "dbt/include/hotdata/macros/materializations/snapshot.sql",
+          ]
+          missing = [name for name in required if name not in names]
+          if missing:
+              sys.exit(f"wheel {wheel} is missing: {missing}")
+          print(f"ok: {wheel} contains all {len(required)} required files")
+          EOF
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/dbt-hotdata/
+    permissions:
+      # Required for PyPI trusted publishing (OIDC) — no API token needed.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

dbt_hotdata-0.2.1/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments
+.venv/
+.env
+
+# macOS
+.DS_Store
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+
+# dbt artifacts from local test projects
+**/target/
+**/dbt_packages/
+logs/

dbt_hotdata-0.2.1/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-08
+
+### Added
+
+- Ambient-environment fallbacks for profile fields from the platform's own
+  `HOTDATA_*` variables (explicit profile values always win): the API key
+  from `HOTDATA_API_KEY`, `workspace_id` from `HOTDATA_WORKSPACE`,
+  `database_id` from `HOTDATA_DATABASE`, and `api_base_url` from
+  `HOTDATA_API_URL`. Resolution reuses the `hotdata_framework.env` helpers,
+  so URLs are normalized the same way as every other SDK consumer. A dbt
+  project runs with no profile fields beyond `type: hotdata` when the
+  environment provides the rest, and orchestrator bridges (e.g.
+  hotdata-dlt-destination's dbt bridge) drive the adapter through the same
+  contract. A `database_id` adopted from the environment is logged, since it
+  retargets the whole build.
+
+### Fixed
+
+- `convert_timezone` returned the UTC instant unshifted; it now converts via
+  `to_local_time()` (DST-aware, non-UTC sources verified) and defaults a
+  falsy `source_tz` to UTC.
+
+### Changed
+
+- Docs and comments now use the product branding — HotSQL for the SQL
+  surface, Hotdata for engine behavior — and the README documents the
+  cross-database macros and the SQL dialect story.
+- Dev lockfile resolves dbt-core 1.12.3 (sqlparse 0.6.0), clearing the
+  open Dependabot alerts; the supported floor stays dbt-core 1.10.
+
+## [0.1.0] - 2026-07-27
+
+### Added
+
+- Initial dbt adapter for Hotdata managed databases (`type: hotdata`). Models
+  run server-side and the results load back with native modes — no local
+  engine, no DDL, pure HTTPS.
+- Materializations: `table`, `incremental` (`append`, or `merge` as a native
+  upsert by `unique_key`), `seed` (numbers stay exact), `ephemeral`. Views and
+  snapshots fail up front with actionable errors.
+- dbt unit tests, data tests, `dbt show`, source freshness, and
+  `dbt docs generate`.
+- Id-first database addressing: pin `database_id` in the profile, or let the
+  first run create a database and print its id.
+- Cross-database macros for HotSQL: `dateadd`, `datediff`,
+  `convert_timezone`.
+- Transient API errors (409/429/5xx) retry for ~42s via the shared
+  `hotdata-framework` client; terminal errors fail the node immediately.
+- CI: lint, format, type-check, offline tests (Python 3.11/3.12), and a
+  wheel-contents check.

dbt_hotdata-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hotdata Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dbt_hotdata-0.2.1/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: dbt-hotdata
+Version: 0.2.1
+Summary: dbt adapter for Hotdata instant databases.
+Project-URL: Homepage, https://hotdata.dev
+Project-URL: Repository, https://github.com/hotdata-dev/dbt-hotdata
+Project-URL: Changelog, https://github.com/hotdata-dev/dbt-hotdata/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/hotdata-dev/dbt-hotdata/issues
+Author-email: 669988+eddietejeda@users.noreply.github.com
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: dbt-adapters<2,>=1.16
+Requires-Dist: dbt-common<2,>=1.14
+Requires-Dist: dbt-core<2,>=1.10
+Requires-Dist: hotdata-framework<0.10,>=0.9.0
+Requires-Dist: hotdata<0.9,>=0.8.0
+Requires-Dist: pyarrow>=14
+Description-Content-Type: text/markdown
+
+# dbt-hotdata
+
+[![Python versions](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://pypi.org/project/dbt-hotdata/)
+[![dbt](https://img.shields.io/badge/dbt-1.10%2B-orange.svg)](https://www.getdbt.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Transform data in [Hotdata](https://hotdata.dev) instant databases with [dbt](https://www.getdbt.com).
+
+Hotdata is a managed analytics engine speaking [HotSQL](https://www.hotdata.dev/docs/sql) (standard SQL with analytics extensions — if you know Postgres, you already know most of it) with **no DDL surface**: tables are created by loading data, not by `CREATE TABLE`. This adapter embraces that. Every model runs as the Chain pattern, entirely against the API:
+
+1. the model's compiled `SELECT` executes **server-side**,
+2. the result streams back as Arrow,
+3. a native load (`replace` / `append` / `upsert`) applies it to the managed table.
+
+No local database engine, no driver, no version matching — pure Python over HTTPS. The same project runs unchanged on a laptop, in CI, or in a serverless function.
+
+## Contents
+
+- [Requirements](#requirements)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [How materializations work](#how-materializations-work)
+- [Feature support](#feature-support)
+- [Configuration](#configuration)
+- [How it relates to hotdata-dlt-destination](#how-it-relates-to-hotdata-dlt-destination)
+- [Development](#development)
+- [License](#license)
+
+## Requirements
+
+- Python **3.11+**, dbt-core **1.10+** (tested through 1.12)
+- A [Hotdata](https://hotdata.dev) workspace, an API key, and its workspace ID — from your Hotdata dashboard or the [Hotdata CLI](https://github.com/hotdata-dev/sdk-python).
+
+## Install
+
+```bash
+pip install dbt-hotdata
+# or
+uv add dbt-hotdata
+```
+
+## Quickstart
+
+**profiles.yml**
+
+```yaml
+my_project:
+  target: dev
+  outputs:
+    dev:
+      type: hotdata
+      workspace_id: your_workspace_id
+      # database_id: db_abc123   # pin after the first run — see below
+      schema: public
+      threads: 1
+```
+
+Set your API key in the environment (it's a secret; the workspace ID is routing, not a credential):
+
+```bash
+export HOTDATA_API_KEY=your_api_key
+```
+
+**dbt_project.yml** — Hotdata has no views, and dbt's default materialization is `view`, so set the project default to `table`:
+
+```yaml
+models:
+  my_project:
+    +materialized: table
+```
+
+Then:
+
+```bash
+dbt run
+```
+
+On first run, an instant database labelled `dbt` is created automatically and its **id** is printed:
+
+```
+hotdata: created instant database db_abc123 (name='dbt'). Pin it for future runs by
+setting database_id: db_abc123 in profiles.yml.
+```
+
+Instant databases are addressed by id — Hotdata database names are not unique, so a name can't identify one. Pin `database_id` in the profile to keep building into the same database; without it, each run creates a fresh one (useful for CI or per-branch runs — databases can be set to expire).
+
+### An incremental model
+
+```sql
+-- models/events_rollup.sql
+{{ config(
+    materialized='incremental',
+    incremental_strategy='merge',
+    unique_key='event_id'
+) }}
+
+select event_id, user_id, count(*) as touches, max(occurred_at) as last_seen
+from {{ source('app', 'events') }}
+{% if is_incremental() %}
+where occurred_at > (select max(last_seen) from {{ this }})
+{% endif %}
+group by event_id, user_id
+```
+
+`merge` runs as a **native server-side upsert** matched on `unique_key` — updates matches, inserts the rest, no full-table read. `append` (the default strategy) adds the new rows. First runs and `--full-refresh` load with `replace`.
+
+## How materializations work
+
+| Materialization | What happens |
+|---|---|
+| `table` | Model SQL runs server-side → result loads with native `replace`. No temp table, no rename swap (there is no rename). |
+| `incremental` | Same, with `append` (default) or `upsert` (`incremental_strategy: merge` + `unique_key`, composite keys supported). |
+| `seed` | The CSV becomes Arrow (numbers stay exact — integers and decimals, never silently floats), then a `replace` load. `column_types:` are applied as Arrow casts. |
+| `ephemeral` | Standard dbt — inlined into consumers, nothing built. |
+| `view` | ❌ Fails up front: Hotdata has no views. The error tells you to set `+materialized: table`. |
+| `snapshot` | ❌ Fails up front: merges update rows in place, so past versions aren't kept. Keep history with an `append` incremental model. |
+
+Tests, `dbt show`, analyses, and source freshness all run as plain SELECTs on the server. `dbt docs generate` builds the catalog from the managed-table API plus Arrow schema probes.
+
+Schema evolution is additive and automatic: a model that starts producing a new column just includes it in the next load — existing data is never touched, and types can widen but never silently shrink. (`on_schema_change` is therefore ignored.)
+
+### SQL dialect
+
+Write models in [HotSQL](https://www.hotdata.dev/docs/sql). It is Postgres-familiar, so SQL written for Postgres mostly runs unchanged, and the adapter overrides the cross-database macros (`dateadd`, `datediff`, `convert_timezone`) where HotSQL differs. Hotdata's query API also accepts the Postgres, DuckDB, and Snowflake dialects (translated to HotSQL server-side), but this adapter always submits model SQL as native HotSQL.
+
+## Feature support
+
+| Feature | Support | Notes |
+|---|:-:|---|
+| `table`, `incremental`, `seed`, `ephemeral` | ✅ | See above |
+| Incremental strategies | ⚠️ | `append`, `merge` (native upsert by `unique_key`). No `delete+insert`, no `microbatch` |
+| `view`, `snapshot` | ❌ | Clear error up front |
+| Tests (generic + singular) | ✅ | Run server-side; `store_failures` supported |
+| `dbt docs generate` | ✅ | Catalog from the managed-table API |
+| Source freshness | ✅ | `loaded_at_field` queries run server-side |
+| Cross-database macros | ✅ | `dateadd`, `datediff`, `convert_timezone` implemented for [HotSQL](https://www.hotdata.dev/docs/sql) (`convert_timezone` is DST-aware) |
+| Hooks (`pre-hook`/`post-hook`, `on-run-*`) | ⚠️ | Run server-side — SELECT-shaped SQL only (no DDL exists) |
+| Python models | ❌ | |
+| Model contracts / constraints | ❌ | No DDL; dbt warns they are unenforced |
+| Grants | ❌ | Ignored with a warning — access is governed by workspace API keys |
+| Transactions | ❌ | `begin`/`commit` are no-ops (Hotdata has no transactions) |
+| Query cancellation | ❌ | An in-flight HTTPS query can't be interrupted client-side |
+
+## Configuration
+
+| Profile field | Env variable | Default | Description |
+|---|---|---|---|
+| `api_key` | `HOTDATA_API_KEY` | required | API key (a secret — prefer the env var or `"{{ env_var('HOTDATA_API_KEY') }}"`) |
+| `workspace_id` | `HOTDATA_WORKSPACE` | required | Workspace ID (routing, not a secret) |
+| `database_id` | `HOTDATA_DATABASE` | — | Id of the instant database to build into. **This is how a database is targeted** — names aren't unique. Printed on first-run create; pin it to reuse |
+| `database_name` | — | `dbt` | Display label used **only when creating** a new database (never to look one up) |
+| `schema` | — | `public` | Schema inside the instant database |
+| `create_database_if_missing` | — | `true` | Create a database on first run when no `database_id` is pinned |
+| `api_base_url` | `HOTDATA_API_URL` | `https://api.hotdata.dev` | API endpoint |
+| `max_retries` | — | `8` | Retry budget for transient errors (409/429/5xx). Loads take a catalog-level lock per database; ~42s of linear backoff outlasts a concurrent writer |
+| `retry_backoff_seconds` | — | `1.5` | Initial retry wait (grows linearly) |
+| `threads` | — | `1` | Loads into one database serialize server-side (contention is retried); more threads still help when models spend most of their time in query execution |
+
+`database:` stays unset — inside an instant database the SQL catalog is always literally `default` (relations render as `"default"."schema"."table"`), and the adapter rejects any other value up front.
+
+Fields left unset in the profile resolve from the platform's own `HOTDATA_*` environment variables (explicit profile values always win). These are the Hotdata CLI conventions — under any orchestrator that sets them, the adapter needs no profile fields at all beyond `type: hotdata`. A `database_id` adopted from the environment is logged, since it retargets the whole build.
+
+## How it relates to hotdata-dlt-destination
+
+[hotdata-dlt-destination](https://github.com/hotdata-dev/hotdata-dlt-destination) loads external data **into** Hotdata (the EL); this adapter transforms it **inside** Hotdata (the T). They share the same conventions — `HOTDATA_API_KEY` from the environment, `workspace_id` as a plain parameter, id-first `database_id` addressing, the same retry classification — and the same underlying SDK (`hotdata` + `hotdata-framework`). Point dbt at the `database_id` your dlt pipeline prints, add sources for the loaded tables, and build models on top.
+
+### Running after a dlt load
+
+[hotdata-dlt-destination](https://github.com/hotdata-dev/hotdata-dlt-destination) ships a dbt bridge: after a pipeline run, one helper call executes a dbt package against the exact instant database the load just wrote — no profiles.yml to author, credentials and routing reused from the pipeline. See “Transform with dbt” in that repo's README. This adapter itself knows nothing about dlt; the bridge drives it through the `HOTDATA_*` environment contract above.
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+git clone https://github.com/hotdata-dev/dbt-hotdata.git
+cd dbt-hotdata
+
+uv sync                 # install deps (including dev group)
+
+uv run pytest           # run the test suite (offline — no credentials needed)
+uv run ruff check       # lint
+uv run ruff format      # format
+uv run mypy             # type-check
+```
+
+The test suite runs entirely offline: adapter logic is exercised against an in-memory fake client, and a real `dbt parse` verifies plugin registration and every macro.
+
+## License
+
+[MIT](LICENSE) © Hotdata Inc.
+
+## Resources
+
+- [Hotdata Python SDK](https://github.com/hotdata-dev/sdk-python) · [hotdata-framework](https://github.com/hotdata-dev/sdk-python-framework)
+- [hotdata-dlt-destination](https://github.com/hotdata-dev/hotdata-dlt-destination)
+- [dbt adapter documentation](https://docs.getdbt.com/docs/connect-adapters)
+- [Changelog](CHANGELOG.md) · [Architecture](docs/architecture.md)