dbt-opteryx 0.1.0__tar.gz

dbt_opteryx-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Justin Joyce (@joocer)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

dbt_opteryx-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: dbt-opteryx
+Version: 0.1.0
+Summary: dbt adapter for Opteryx Cloud (https://opteryx.app)
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dbt-core<2,>=1.10
+Requires-Dist: dbt-adapters<2,>=1.7
+Requires-Dist: dbt-common<2,>=1.10
+Requires-Dist: opteryx-sqlalchemy>=0.0.13
+Dynamic: license-file
+
+# dbt-opteryx
+
+dbt adapter for [Opteryx Cloud](https://opteryx.app). It runs dbt Core 1.x against
+Opteryx's HTTP jobs API, using the DBAPI from
+[`opteryx-sqlalchemy`](https://pypi.org/project/opteryx-sqlalchemy/).
+
+## Install
+
+```bash
+pip install dbt-opteryx
+```
+
+## Profile
+
+dbt's `database` is an Opteryx **workspace** and `schema` is a **collection**
+(`workspace` / `collection` are accepted as aliases). Every account has a personal
+space, `personal.<your user>`, which needs no setup:
+
+```yaml
+my_project:
+  target: cloud
+  outputs:
+    cloud:
+      type: opteryx
+      host: opteryx.app
+      port: 443
+      ssl: true
+      user: "{{ env_var('OPTERYX_USER') }}"
+      token: "{{ env_var('OPTERYX_TOKEN') }}"
+      database: personal            # workspace
+      schema: "{{ env_var('OPTERYX_USER') }}"  # collection
+      threads: 1
+```
+
+Put this in `dbt_project.yml` until the leading-comment issue below is fixed:
+
+```yaml
+query-comment:
+  append: true
+```
+
+## Behaviour to know about
+
+- **No transactions.** Opteryx has none; every statement commits on its own. The
+  adapter sends nothing for dbt's BEGIN/COMMIT.
+- **No temporary tables.** dbt's `__dbt_tmp` intermediates are real tables, which
+  dbt drops when the model succeeds. A failed model can leave one behind.
+- **Views** are built with `CREATE OR REPLACE VIEW`, not dbt's rename swap.
+- **Seeds** are inserted as typed literals (`CAST('…' AS <type>)`), not bind
+  parameters: parameters reach Opteryx as JSON, which has no DATE or TIMESTAMP.
+- **Incremental strategies:** `append`, `merge` and `delete+insert`.
+- **Model contracts are refused**, with an error naming the model: the adapter does
+  not enforce them yet, and ignoring one silently would claim a guarantee it does not keep.
+- **Queries cannot be cancelled** from dbt.
+
+## Integration tests
+
+`tests/integration/project` is a dbt project covering seeds, sources (including
+freshness), view, table, ephemeral and incremental models (all three strategies),
+snapshots, hooks, contracts, generic, singular and unit tests, `show`,
+`run-operation`, `--empty` and docs generation. Run it against opteryx.app:
+
+```bash
+CLIENT_ID=… CLIENT_SECRET=… python tests/integration/run.py
+```
+
+Every step runs, and every node must pass except those listed in
+`EXPECTED_FAILURES` in `run.py`, which must fail. The run fails on an unexpected
+failure and also on an expected failure that passes, so the list is pruned as
+Opteryx gaps close.
+
+It writes into `personal.$CLIENT_ID` (override with `OPTERYX_WORKSPACE` /
+`OPTERYX_COLLECTION`). CI runs it on push (`.github/workflows/integration.yaml`),
+reading `CLIENT_ID` / `CLIENT_SECRET` from the `OPTERYX_TEST_CLIENT` /
+`OPTERYX_TEST_TOKEN` repository secrets. That is a service account, which has no
+personal space, so CI writes into `opteryx_ci.dbt`.
+
+Offline checks (no connection) run with `python -m pytest tests/unit`.
+
+## CI
+
+| Workflow | Runs on | Does |
+|---|---|---|
+| `regression-tests.yaml` | push | `tests/unit` on Python 3.10–3.14 × dbt-core 1.10 (floor) and latest; 1.10 is skipped on 3.14, where it cannot import |
+| `integration.yaml` | push | `tests/integration/run.py` against opteryx.app; known gaps are expected failures |
+| `semgrep_scan.yaml` | push | Semgrep scan, findings uploaded to `opteryx.ops.sast_findings` |
+| `release.yaml` | `v*` tag | Builds and publishes to PyPI by trusted publishing |
+
+Repository secrets: `OPTERYX_TEST_CLIENT`, `OPTERYX_TEST_TOKEN` (integration),
+`UPLOAD_CLIENT`, `UPLOAD_TOKEN` (Semgrep upload).
+
+## Releasing
+
+Bump `version` in `dbt/adapters/opteryx/__version__.py` (the package version is read
+from it), then push a matching `vX.Y.Z` tag. PyPI must list this repository's
+`release.yaml` as a trusted publisher for `dbt-opteryx`; for the first release that
+is a pending publisher, set up on PyPI before the tag is pushed.
+
+## Verification against opteryx.app (2026-11-09)
+
+dbt-core 1.12.6, dbt-adapters 1.24.5, opteryx-sqlalchemy 0.0.13.
+
+| Feature | Result | Notes |
+|---|---|---|
+| `dbt debug` | PASS | |
+| Seeds, first load | PASS | Needs the typed-literal loader in this adapter |
+| Seeds, reload over an existing table | **FAIL (silent)** | Reports OK but doubles the rows: TRUNCATE is a no-op (issue 1) |
+| Seeds, `--full-refresh` | PASS | Drops and recreates |
+| Sources: `source()` reads | PASS | `samples.tpch_sf001.nation` |
+| Sources: tests | PASS | not_null, unique |
+| Sources: `dbt source freshness` | PASS | |
+| View materialization | PASS | Created and replaced |
+| Table materialization | PASS | Created; rebuilt through the rename swap |
+| Incremental, `append` | PASS | Second run appends only new rows (checked 4 → 5) |
+| Incremental, `merge`, first build | PASS | |
+| Incremental, `merge`, incremental run | **FAIL** | Issue 3 |
+| Tests: not_null, unique, singular | PASS | |
+| Tests: accepted_values, relationships | **FAIL** | Issue 4 |
+| `dbt docs generate` | PARTIAL | Catalog written; views have no columns (issue 5) |
+| Schema creation (`CREATE COLLECTION`) | PASS with workaround | Issue 2 |
+| Incremental, `delete+insert`, first build | PASS | |
+| Incremental, `delete+insert`, incremental run | **FAIL** | Issues 11 and 12 |
+| Ephemeral models | **FAIL** | Issue 13 |
+| Snapshots (timestamp and check strategies) | **FAIL** | Issue 14; would then hit issue 3 |
+| Unit tests | **FAIL** | Issue 5: fixtures need the input view's columns |
+| `--empty` | **FAIL** | Issue 15 |
+| Model contracts | **Refused** | The adapter raises (see above) |
+| Pre/post hooks | PASS | Hook statements ran, checked in `hook_log` |
+| `dbt show` | PASS | |
+| `dbt run-operation` with `run_query` | PASS | |
+
+## Issues found
+
+| # | Issue | Class | Proposed fix |
+|---|---|---|---|
+| 1 | `TRUNCATE TABLE` reports OK and removes nothing. `OpteryxConnector.truncate_relation` calls `Dataset.truncate()`, whose default `commit_truncation=False` never moves `current-snapshot-id`. | Opteryx correctness bug | **Fixed in opteryx-core (2026-11-09, not yet released or deployed):** the connector now passes `commit_truncation=True`. Re-run the matrix after deploy. |
+| 2 | `CREATE/DROP COLLECTION` and `ALTER/DROP WORKSPACE` fail to parse after a leading comment. dbt puts a comment in front of every statement. | Opteryx SQL gap | Have the `^\s*` anchors in `opteryx/planner/sql_rewriter/__init__.py:240-251` skip leading comments. Docs workaround: `query-comment: {append: true}`. |
+| 3 | `MERGE … WHEN NOT MATCHED THEN INSERT (…) VALUES ("id", …)` raises "Column id is ambiguous". Only the source is in scope there; qualified `S."id"` works. | Opteryx SQL gap | Bind WHEN NOT MATCHED value expressions against the source relation only. |
+| 4 | A CTE inside a derived table is not found: `SELECT … FROM (WITH a AS (…) SELECT * FROM a) t` gives "Dataset `a` cannot be found". dbt wraps every test in such a subquery. | Opteryx SQL gap | Scope CTEs declared inside a subquery to that subquery. |
+| 5 | `information_schema.columns` has no rows for views, so dbt cannot see view columns. | Opteryx SQL gap | List view columns there as well; it currently iterates `list_datasets()` only. |
+| 6 | `personal.information_schema.schemata` is empty although `personal.<user>` exists. dbt then always issues `CREATE COLLECTION IF NOT EXISTS`, which succeeds. | Opteryx catalog gap (not blocking) | List the caller's personal collection. |
+| 7 | CAST refuses `DOUBLE`, `BIGINT` and `TEXT` ("not a type CAST can produce") although `reference/types.json` lists them as accepted spellings. dbt's default seed types are `text` / `float8`. | Opteryx SQL gap | Accept the listed spellings in CAST. The adapter maps seed types itself meanwhile. |
+| 8 | INSERT type errors print the enum repr, e.g. "target LogicalCategory.FLOAT". | Opteryx message bug | Render the type name. |
+| 9 | Bind parameters of type `Decimal`, `date` or `datetime` fail with "not JSON serializable" in the DBAPI. | Adapter/protocol gap (opteryx-sqlalchemy) | Encode them in `_submit_statement`. Even then, the server will not coerce a string into DATE/TIMESTAMP, so this adapter's seeds use literals. |
+| 10 | `ALTER TABLE x RENAME TO y` with a bare target is read as a move to another workspace. | Behaviour (documented) | None needed: the adapter always passes the qualified name. |
+| 11 | `WHERE (id) IN (SELECT …)` with one parenthesised column fails: "A correlated EXISTS/IN subquery correlates on `(id)`…". Without the parentheses it works. dbt's delete+insert always parenthesises. | Opteryx SQL gap | Treat a one-element parenthesised expression as the expression itself. |
+| 12 | **INSERT fails after a DELETE that removed every row** of the table's files: "concat: all inputs must share one type for 'column_uncompressed_sizes_in_bytes' - found INT64, ARRAY". Root cause is in rugo: a zero-row `array<…>` column reads back as INT64. The delete-all writes a manifest with one zero-row row group, INSERT appends a row group to it, and `read_manifest_columns` cannot combine the two. Three-line reproducer: write an empty ARRAY vector with `rugo.parquet.write_parquet`; `read_parquet` returns it as INT64. Not dbt-specific. | Opteryx correctness bug (rugo reader) | **Fixed in opteryx-core (2026-11-09, not yet released or deployed):** the reader routes list columns on the schema's `max_rep_level`, not on whether repetition levels were decoded. Manifests already written this way need no rewrite; they read correctly once the fix is deployed. |
+| 13 | `CREATE TABLE … AS WITH a AS (…) SELECT … FROM a` gives "Dataset `a` cannot be found". The same query without CREATE works. dbt inlines ephemeral models this way. | Opteryx SQL gap | Resolve CTEs in a CTAS body. |
+| 14 | `SELECT *, x` is refused by design ("`SELECT *` cannot coexist with additional columns"); `SELECT t.*, x` works. dbt's snapshot SQL uses `SELECT *, …`. | Opteryx dialect rule | Either allow `*` with other columns, or override dbt's snapshot macros in the adapter to qualify the star. Architect's call. |
+| 15 | `WHERE false` is refused by design ("WHERE clause cannot be a bare literal"); `WHERE 1 = 0` works. dbt's `--empty` renders refs as `(SELECT * FROM x WHERE false LIMIT 0)`, and contract enforcement uses the same pattern. | Opteryx dialect rule | Either accept a bare boolean literal, or override the relation's limited render in the adapter. Architect's call. |

dbt_opteryx-0.1.0/README.md

@@ -0,0 +1,150 @@
+# dbt-opteryx
+
+dbt adapter for [Opteryx Cloud](https://opteryx.app). It runs dbt Core 1.x against
+Opteryx's HTTP jobs API, using the DBAPI from
+[`opteryx-sqlalchemy`](https://pypi.org/project/opteryx-sqlalchemy/).
+
+## Install
+
+```bash
+pip install dbt-opteryx
+```
+
+## Profile
+
+dbt's `database` is an Opteryx **workspace** and `schema` is a **collection**
+(`workspace` / `collection` are accepted as aliases). Every account has a personal
+space, `personal.<your user>`, which needs no setup:
+
+```yaml
+my_project:
+  target: cloud
+  outputs:
+    cloud:
+      type: opteryx
+      host: opteryx.app
+      port: 443
+      ssl: true
+      user: "{{ env_var('OPTERYX_USER') }}"
+      token: "{{ env_var('OPTERYX_TOKEN') }}"
+      database: personal            # workspace
+      schema: "{{ env_var('OPTERYX_USER') }}"  # collection
+      threads: 1
+```
+
+Put this in `dbt_project.yml` until the leading-comment issue below is fixed:
+
+```yaml
+query-comment:
+  append: true
+```
+
+## Behaviour to know about
+
+- **No transactions.** Opteryx has none; every statement commits on its own. The
+  adapter sends nothing for dbt's BEGIN/COMMIT.
+- **No temporary tables.** dbt's `__dbt_tmp` intermediates are real tables, which
+  dbt drops when the model succeeds. A failed model can leave one behind.
+- **Views** are built with `CREATE OR REPLACE VIEW`, not dbt's rename swap.
+- **Seeds** are inserted as typed literals (`CAST('…' AS <type>)`), not bind
+  parameters: parameters reach Opteryx as JSON, which has no DATE or TIMESTAMP.
+- **Incremental strategies:** `append`, `merge` and `delete+insert`.
+- **Model contracts are refused**, with an error naming the model: the adapter does
+  not enforce them yet, and ignoring one silently would claim a guarantee it does not keep.
+- **Queries cannot be cancelled** from dbt.
+
+## Integration tests
+
+`tests/integration/project` is a dbt project covering seeds, sources (including
+freshness), view, table, ephemeral and incremental models (all three strategies),
+snapshots, hooks, contracts, generic, singular and unit tests, `show`,
+`run-operation`, `--empty` and docs generation. Run it against opteryx.app:
+
+```bash
+CLIENT_ID=… CLIENT_SECRET=… python tests/integration/run.py
+```
+
+Every step runs, and every node must pass except those listed in
+`EXPECTED_FAILURES` in `run.py`, which must fail. The run fails on an unexpected
+failure and also on an expected failure that passes, so the list is pruned as
+Opteryx gaps close.
+
+It writes into `personal.$CLIENT_ID` (override with `OPTERYX_WORKSPACE` /
+`OPTERYX_COLLECTION`). CI runs it on push (`.github/workflows/integration.yaml`),
+reading `CLIENT_ID` / `CLIENT_SECRET` from the `OPTERYX_TEST_CLIENT` /
+`OPTERYX_TEST_TOKEN` repository secrets. That is a service account, which has no
+personal space, so CI writes into `opteryx_ci.dbt`.
+
+Offline checks (no connection) run with `python -m pytest tests/unit`.
+
+## CI
+
+| Workflow | Runs on | Does |
+|---|---|---|
+| `regression-tests.yaml` | push | `tests/unit` on Python 3.10–3.14 × dbt-core 1.10 (floor) and latest; 1.10 is skipped on 3.14, where it cannot import |
+| `integration.yaml` | push | `tests/integration/run.py` against opteryx.app; known gaps are expected failures |
+| `semgrep_scan.yaml` | push | Semgrep scan, findings uploaded to `opteryx.ops.sast_findings` |
+| `release.yaml` | `v*` tag | Builds and publishes to PyPI by trusted publishing |
+
+Repository secrets: `OPTERYX_TEST_CLIENT`, `OPTERYX_TEST_TOKEN` (integration),
+`UPLOAD_CLIENT`, `UPLOAD_TOKEN` (Semgrep upload).
+
+## Releasing
+
+Bump `version` in `dbt/adapters/opteryx/__version__.py` (the package version is read
+from it), then push a matching `vX.Y.Z` tag. PyPI must list this repository's
+`release.yaml` as a trusted publisher for `dbt-opteryx`; for the first release that
+is a pending publisher, set up on PyPI before the tag is pushed.
+
+## Verification against opteryx.app (2026-11-09)
+
+dbt-core 1.12.6, dbt-adapters 1.24.5, opteryx-sqlalchemy 0.0.13.
+
+| Feature | Result | Notes |
+|---|---|---|
+| `dbt debug` | PASS | |
+| Seeds, first load | PASS | Needs the typed-literal loader in this adapter |
+| Seeds, reload over an existing table | **FAIL (silent)** | Reports OK but doubles the rows: TRUNCATE is a no-op (issue 1) |
+| Seeds, `--full-refresh` | PASS | Drops and recreates |
+| Sources: `source()` reads | PASS | `samples.tpch_sf001.nation` |
+| Sources: tests | PASS | not_null, unique |
+| Sources: `dbt source freshness` | PASS | |
+| View materialization | PASS | Created and replaced |
+| Table materialization | PASS | Created; rebuilt through the rename swap |
+| Incremental, `append` | PASS | Second run appends only new rows (checked 4 → 5) |
+| Incremental, `merge`, first build | PASS | |
+| Incremental, `merge`, incremental run | **FAIL** | Issue 3 |
+| Tests: not_null, unique, singular | PASS | |
+| Tests: accepted_values, relationships | **FAIL** | Issue 4 |
+| `dbt docs generate` | PARTIAL | Catalog written; views have no columns (issue 5) |
+| Schema creation (`CREATE COLLECTION`) | PASS with workaround | Issue 2 |
+| Incremental, `delete+insert`, first build | PASS | |
+| Incremental, `delete+insert`, incremental run | **FAIL** | Issues 11 and 12 |
+| Ephemeral models | **FAIL** | Issue 13 |
+| Snapshots (timestamp and check strategies) | **FAIL** | Issue 14; would then hit issue 3 |
+| Unit tests | **FAIL** | Issue 5: fixtures need the input view's columns |
+| `--empty` | **FAIL** | Issue 15 |
+| Model contracts | **Refused** | The adapter raises (see above) |
+| Pre/post hooks | PASS | Hook statements ran, checked in `hook_log` |
+| `dbt show` | PASS | |
+| `dbt run-operation` with `run_query` | PASS | |
+
+## Issues found
+
+| # | Issue | Class | Proposed fix |
+|---|---|---|---|
+| 1 | `TRUNCATE TABLE` reports OK and removes nothing. `OpteryxConnector.truncate_relation` calls `Dataset.truncate()`, whose default `commit_truncation=False` never moves `current-snapshot-id`. | Opteryx correctness bug | **Fixed in opteryx-core (2026-11-09, not yet released or deployed):** the connector now passes `commit_truncation=True`. Re-run the matrix after deploy. |
+| 2 | `CREATE/DROP COLLECTION` and `ALTER/DROP WORKSPACE` fail to parse after a leading comment. dbt puts a comment in front of every statement. | Opteryx SQL gap | Have the `^\s*` anchors in `opteryx/planner/sql_rewriter/__init__.py:240-251` skip leading comments. Docs workaround: `query-comment: {append: true}`. |
+| 3 | `MERGE … WHEN NOT MATCHED THEN INSERT (…) VALUES ("id", …)` raises "Column id is ambiguous". Only the source is in scope there; qualified `S."id"` works. | Opteryx SQL gap | Bind WHEN NOT MATCHED value expressions against the source relation only. |
+| 4 | A CTE inside a derived table is not found: `SELECT … FROM (WITH a AS (…) SELECT * FROM a) t` gives "Dataset `a` cannot be found". dbt wraps every test in such a subquery. | Opteryx SQL gap | Scope CTEs declared inside a subquery to that subquery. |
+| 5 | `information_schema.columns` has no rows for views, so dbt cannot see view columns. | Opteryx SQL gap | List view columns there as well; it currently iterates `list_datasets()` only. |
+| 6 | `personal.information_schema.schemata` is empty although `personal.<user>` exists. dbt then always issues `CREATE COLLECTION IF NOT EXISTS`, which succeeds. | Opteryx catalog gap (not blocking) | List the caller's personal collection. |
+| 7 | CAST refuses `DOUBLE`, `BIGINT` and `TEXT` ("not a type CAST can produce") although `reference/types.json` lists them as accepted spellings. dbt's default seed types are `text` / `float8`. | Opteryx SQL gap | Accept the listed spellings in CAST. The adapter maps seed types itself meanwhile. |
+| 8 | INSERT type errors print the enum repr, e.g. "target LogicalCategory.FLOAT". | Opteryx message bug | Render the type name. |
+| 9 | Bind parameters of type `Decimal`, `date` or `datetime` fail with "not JSON serializable" in the DBAPI. | Adapter/protocol gap (opteryx-sqlalchemy) | Encode them in `_submit_statement`. Even then, the server will not coerce a string into DATE/TIMESTAMP, so this adapter's seeds use literals. |
+| 10 | `ALTER TABLE x RENAME TO y` with a bare target is read as a move to another workspace. | Behaviour (documented) | None needed: the adapter always passes the qualified name. |
+| 11 | `WHERE (id) IN (SELECT …)` with one parenthesised column fails: "A correlated EXISTS/IN subquery correlates on `(id)`…". Without the parentheses it works. dbt's delete+insert always parenthesises. | Opteryx SQL gap | Treat a one-element parenthesised expression as the expression itself. |
+| 12 | **INSERT fails after a DELETE that removed every row** of the table's files: "concat: all inputs must share one type for 'column_uncompressed_sizes_in_bytes' - found INT64, ARRAY". Root cause is in rugo: a zero-row `array<…>` column reads back as INT64. The delete-all writes a manifest with one zero-row row group, INSERT appends a row group to it, and `read_manifest_columns` cannot combine the two. Three-line reproducer: write an empty ARRAY vector with `rugo.parquet.write_parquet`; `read_parquet` returns it as INT64. Not dbt-specific. | Opteryx correctness bug (rugo reader) | **Fixed in opteryx-core (2026-11-09, not yet released or deployed):** the reader routes list columns on the schema's `max_rep_level`, not on whether repetition levels were decoded. Manifests already written this way need no rewrite; they read correctly once the fix is deployed. |
+| 13 | `CREATE TABLE … AS WITH a AS (…) SELECT … FROM a` gives "Dataset `a` cannot be found". The same query without CREATE works. dbt inlines ephemeral models this way. | Opteryx SQL gap | Resolve CTEs in a CTAS body. |
+| 14 | `SELECT *, x` is refused by design ("`SELECT *` cannot coexist with additional columns"); `SELECT t.*, x` works. dbt's snapshot SQL uses `SELECT *, …`. | Opteryx dialect rule | Either allow `*` with other columns, or override dbt's snapshot macros in the adapter to qualify the star. Architect's call. |
+| 15 | `WHERE false` is refused by design ("WHERE clause cannot be a bare literal"); `WHERE 1 = 0` works. dbt's `--empty` renders refs as `(SELECT * FROM x WHERE false LIMIT 0)`, and contract enforcement uses the same pattern. | Opteryx dialect rule | Either accept a bare boolean literal, or override the relation's limited render in the adapter. Architect's call. |

dbt_opteryx-0.1.0/dbt/adapters/opteryx/__init__.py

@@ -0,0 +1,12 @@
+from dbt.adapters.base import AdapterPlugin
+
+from dbt.adapters.opteryx.connections import OpteryxConnectionManager  # noqa: F401
+from dbt.adapters.opteryx.connections import OpteryxCredentials
+from dbt.adapters.opteryx.impl import OpteryxAdapter
+from dbt.include import opteryx
+
+Plugin = AdapterPlugin(
+    adapter=OpteryxAdapter,
+    credentials=OpteryxCredentials,
+    include_path=opteryx.PACKAGE_PATH,
+)

dbt_opteryx-0.1.0/dbt/adapters/opteryx/__version__.py

@@ -0,0 +1 @@
+version = "0.1.0"

dbt_opteryx-0.1.0/dbt/adapters/opteryx/connections.py

@@ -0,0 +1,80 @@
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Optional
+from typing import Tuple
+
+from dbt.adapters.contracts.connection import AdapterResponse
+from dbt.adapters.contracts.connection import Connection
+from dbt.adapters.contracts.connection import Credentials
+from dbt.adapters.sql import SQLConnectionManager
+from dbt_common.exceptions import DbtDatabaseError
+from sqlalchemy_dialect import dbapi
+
+
+@dataclass
+class OpteryxCredentials(Credentials):
+    # database = Opteryx workspace, schema = collection
+    host: str = "opteryx.app"
+    port: int = 443
+    ssl: bool = True
+    user: Optional[str] = None
+    token: Optional[str] = None
+    timeout: float = 300.0
+
+    _ALIASES = {"workspace": "database", "collection": "schema"}
+
+    @property
+    def type(self) -> str:
+        return "opteryx"
+
+    @property
+    def unique_field(self) -> str:
+        return self.host
+
+    def _connection_keys(self) -> Tuple[str, ...]:
+        return ("host", "port", "ssl", "user", "database", "schema", "timeout")
+
+
+class OpteryxConnectionManager(SQLConnectionManager):
+    TYPE = "opteryx"
+
+    @contextmanager
+    def exception_handler(self, sql: str):
+        try:
+            yield
+        except dbapi.Error as e:
+            raise DbtDatabaseError(str(e)) from e
+
+    @classmethod
+    def open(cls, connection: Connection) -> Connection:
+        if connection.state == "open":
+            return connection
+        creds = connection.credentials
+        connection.handle = dbapi.connect(
+            host=creds.host,
+            port=creds.port,
+            username=creds.user,
+            token=creds.token,
+            ssl=creds.ssl,
+            timeout=creds.timeout,
+        )
+        connection.state = "open"
+        return connection
+
+    def cancel(self, connection: Connection) -> None:
+        # OpteryxAdapter.is_cancelable() is False, so dbt never calls this.
+        raise NotImplementedError("dbt-opteryx does not cancel in-flight queries")
+
+    @classmethod
+    def get_response(cls, cursor) -> AdapterResponse:
+        return AdapterResponse(
+            _message="OK", rows_affected=cursor.rowcount, query_id=cursor.statement_handle
+        )
+
+    # Opteryx has no transactions: every statement commits on its own. dbt still
+    # brackets work in begin/commit, so these send nothing to the server.
+    def add_begin_query(self):
+        pass
+
+    def add_commit_query(self):
+        pass

dbt_opteryx-0.1.0/dbt/adapters/opteryx/impl.py

@@ -0,0 +1,50 @@
+from dbt.adapters.sql import SQLAdapter
+
+from dbt.adapters.opteryx.connections import OpteryxConnectionManager
+
+
+class OpteryxAdapter(SQLAdapter):
+    ConnectionManager = OpteryxConnectionManager
+
+    @classmethod
+    def date_function(cls) -> str:
+        return "now()"
+
+    @classmethod
+    def is_cancelable(cls) -> bool:
+        return False
+
+    def valid_incremental_strategies(self):
+        return ["append", "merge", "delete+insert"]
+
+    # Seed column types. Opteryx CAST refuses dbt's defaults (`text`, `float8`).
+    @classmethod
+    def convert_text_type(cls, agate_table, col_idx) -> str:
+        return "VARCHAR"
+
+    @classmethod
+    def convert_number_type(cls, agate_table, col_idx) -> str:
+        import agate  # dbt imports agate lazily; follow suit
+
+        decimals = agate_table.aggregate(agate.MaxPrecision(col_idx))
+        return "FLOAT" if decimals else "INTEGER"
+
+    @classmethod
+    def convert_integer_type(cls, agate_table, col_idx) -> str:
+        return "INTEGER"
+
+    @classmethod
+    def convert_boolean_type(cls, agate_table, col_idx) -> str:
+        return "BOOLEAN"
+
+    @classmethod
+    def convert_datetime_type(cls, agate_table, col_idx) -> str:
+        return "TIMESTAMP"
+
+    @classmethod
+    def convert_date_type(cls, agate_table, col_idx) -> str:
+        return "DATE"
+
+    @classmethod
+    def convert_time_type(cls, agate_table, col_idx) -> str:
+        return "TIME"

dbt_opteryx-0.1.0/dbt/include/opteryx/__init__.py

@@ -0,0 +1,3 @@
+import os
+
+PACKAGE_PATH = os.path.dirname(__file__)

dbt_opteryx-0.1.0/dbt/include/opteryx/dbt_project.yml

@@ -0,0 +1,5 @@
+name: dbt_opteryx
+version: 1.0
+config-version: 2
+
+macro-paths: ["macros"]

dbt_opteryx-0.1.0/dbt/include/opteryx/macros/adapters.sql

@@ -0,0 +1,81 @@
+{# database = workspace, schema = collection, identifier = dataset #}
+
+{% macro opteryx__get_binding_char() %}?{% endmacro %}
+
+{% macro opteryx__current_timestamp() %}now(){% endmacro %}
+
+{% macro opteryx__create_schema(relation) -%}
+  {% call statement('create_schema') -%}
+    CREATE COLLECTION IF NOT EXISTS {{ relation.without_identifier() }}
+  {%- endcall %}
+{% endmacro %}
+
+{% macro opteryx__list_schemas(database) -%}
+  {% call statement('list_schemas', fetch_result=True, auto_begin=False) %}
+    SELECT schema_name FROM {{ database }}.information_schema.schemata
+  {% endcall %}
+  {{ return(load_result('list_schemas').table) }}
+{% endmacro %}
+
+{% macro opteryx__check_schema_exists(information_schema, schema) -%}
+  {% call statement('check_schema_exists', fetch_result=True, auto_begin=False) -%}
+    SELECT COUNT(*) FROM {{ information_schema.database }}.information_schema.schemata
+    WHERE schema_name = '{{ schema }}'
+  {%- endcall %}
+  {{ return(load_result('check_schema_exists').table) }}
+{% endmacro %}
+
+{% macro opteryx__list_relations_without_caching(schema_relation) %}
+  {% call statement('list_relations_without_caching', fetch_result=True) -%}
+    SELECT
+      table_catalog AS database,
+      table_name AS name,
+      table_schema AS schema,
+      CASE WHEN table_type = 'VIEW' THEN 'view' ELSE 'table' END AS type
+    FROM {{ schema_relation.database }}.information_schema.tables
+    WHERE table_schema = '{{ schema_relation.schema }}'
+  {%- endcall %}
+  {{ return(load_result('list_relations_without_caching').table) }}
+{% endmacro %}
+
+{% macro opteryx__get_columns_in_relation(relation) -%}
+  {% call statement('get_columns_in_relation', fetch_result=True) %}
+    SELECT
+      column_name,
+      data_type,
+      NULL AS character_maximum_length,
+      NULL AS numeric_precision,
+      NULL AS numeric_scale
+    FROM {{ relation.database }}.information_schema.columns
+    WHERE table_schema = '{{ relation.schema }}'
+      AND table_name = '{{ relation.identifier }}'
+    ORDER BY ordinal_position
+  {% endcall %}
+  {% set table = load_result('get_columns_in_relation').table %}
+  {{ return(sql_convert_columns_in_relation(table)) }}
+{% endmacro %}
+
+{% macro opteryx__create_table_as(temporary, relation, sql) -%}
+  {#- Opteryx has no temporary tables; dbt drops its intermediates itself. -#}
+  {%- if config.get('contract').enforced -%}
+    {{ exceptions.raise_compiler_error("dbt-opteryx does not enforce model contracts; remove `contract: {enforced: true}` from " ~ relation) }}
+  {%- endif -%}
+  CREATE TABLE {{ relation }} AS {{ sql }}
+{%- endmacro %}
+
+{% macro opteryx__create_view_as(relation, sql) -%}
+  CREATE OR REPLACE VIEW {{ relation }} AS {{ sql }}
+{%- endmacro %}
+
+{% macro opteryx__drop_relation(relation) -%}
+  {% call statement('drop_relation', auto_begin=False) -%}
+    DROP {{ relation.type }} IF EXISTS {{ relation }}
+  {%- endcall %}
+{% endmacro %}
+
+{% macro opteryx__rename_relation(from_relation, to_relation) -%}
+  {#- Opteryx requires the fully qualified target name. -#}
+  {% call statement('rename_relation') -%}
+    ALTER {{ from_relation.type }} {{ from_relation }} RENAME TO {{ to_relation }}
+  {%- endcall %}
+{% endmacro %}

dbt_opteryx-0.1.0/dbt/include/opteryx/macros/catalog.sql

@@ -0,0 +1,23 @@
+{% macro opteryx__get_catalog(information_schema, schemas) -%}
+  {% set query %}
+    SELECT
+      t.table_catalog AS table_database,
+      t.table_schema AS table_schema,
+      t.table_name AS table_name,
+      CASE WHEN t.table_type = 'VIEW' THEN 'VIEW' ELSE 'BASE TABLE' END AS table_type,
+      NULL AS table_comment,
+      c.column_name AS column_name,
+      c.ordinal_position AS column_index,
+      c.data_type AS column_type,
+      NULL AS column_comment,
+      NULL AS table_owner
+    FROM {{ information_schema.database }}.information_schema.tables AS t
+    INNER JOIN {{ information_schema.database }}.information_schema.columns AS c
+      ON t.table_schema = c.table_schema AND t.table_name = c.table_name
+    WHERE t.table_schema IN (
+      {%- for schema in schemas -%}'{{ schema }}'{%- if not loop.last %}, {% endif -%}{%- endfor -%}
+    )
+    ORDER BY t.table_schema, t.table_name, c.ordinal_position
+  {% endset %}
+  {{ return(run_query(query)) }}
+{%- endmacro %}

dbt_opteryx-0.1.0/dbt/include/opteryx/macros/materializations/seed.sql

@@ -0,0 +1,33 @@
+{#-
+  Seed rows are rendered as typed literals, not bind parameters: parameters reach
+  Opteryx as JSON values, JSON has no DATE/TIMESTAMP, and INSERT will not coerce a
+  VARCHAR into a typed column.
+-#}
+{% macro opteryx__load_csv_rows(model, agate_table) %}
+  {% set column_override = model['config'].get('column_types', {}) %}
+  {% set types = [] %}
+  {% for col_name in agate_table.column_names %}
+    {% do types.append(column_override.get(col_name, adapter.convert_type(agate_table, loop.index0))) %}
+  {% endfor %}
+  {% set cols_sql = get_seed_column_quoted_csv(model, agate_table.column_names) %}
+  {% set statements = [] %}
+
+  {% for chunk in agate_table.rows | batch(get_batch_size()) %}
+    {% set sql %}
+      INSERT INTO {{ this.render() }} ({{ cols_sql }}) VALUES
+      {% for row in chunk -%}
+        ({%- for value in row -%}
+          {%- if value is none -%}NULL{%- else -%}CAST('{{ (value | string) | replace("'", "''") }}' AS {{ types[loop.index0] }}){%- endif -%}
+          {%- if not loop.last %}, {% endif -%}
+        {%- endfor -%})
+        {%- if not loop.last %},{% endif %}
+      {% endfor %}
+    {% endset %}
+    {% do adapter.add_query(sql, abridge_sql_log=True) %}
+    {% if loop.index0 == 0 %}
+      {% do statements.append(sql) %}
+    {% endif %}
+  {% endfor %}
+
+  {{ return(statements[0]) }}
+{% endmacro %}

dbt_opteryx-0.1.0/dbt/include/opteryx/macros/materializations/view.sql

@@ -0,0 +1,4 @@
+{#- Opteryx has CREATE OR REPLACE VIEW and no view rename, so skip dbt's tmp/rename swap. -#}
+{% materialization view, adapter='opteryx' -%}
+  {{ return(create_or_replace_view()) }}
+{%- endmaterialization %}

dbt_opteryx-0.1.0/dbt_opteryx.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: dbt-opteryx
+Version: 0.1.0
+Summary: dbt adapter for Opteryx Cloud (https://opteryx.app)
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dbt-core<2,>=1.10
+Requires-Dist: dbt-adapters<2,>=1.7
+Requires-Dist: dbt-common<2,>=1.10
+Requires-Dist: opteryx-sqlalchemy>=0.0.13
+Dynamic: license-file
+
+# dbt-opteryx
+
+dbt adapter for [Opteryx Cloud](https://opteryx.app). It runs dbt Core 1.x against
+Opteryx's HTTP jobs API, using the DBAPI from
+[`opteryx-sqlalchemy`](https://pypi.org/project/opteryx-sqlalchemy/).
+
+## Install
+
+```bash
+pip install dbt-opteryx
+```
+
+## Profile
+
+dbt's `database` is an Opteryx **workspace** and `schema` is a **collection**
+(`workspace` / `collection` are accepted as aliases). Every account has a personal
+space, `personal.<your user>`, which needs no setup:
+
+```yaml
+my_project:
+  target: cloud
+  outputs:
+    cloud:
+      type: opteryx
+      host: opteryx.app
+      port: 443
+      ssl: true
+      user: "{{ env_var('OPTERYX_USER') }}"
+      token: "{{ env_var('OPTERYX_TOKEN') }}"
+      database: personal            # workspace
+      schema: "{{ env_var('OPTERYX_USER') }}"  # collection
+      threads: 1
+```
+
+Put this in `dbt_project.yml` until the leading-comment issue below is fixed:
+
+```yaml
+query-comment:
+  append: true
+```
+
+## Behaviour to know about
+
+- **No transactions.** Opteryx has none; every statement commits on its own. The
+  adapter sends nothing for dbt's BEGIN/COMMIT.
+- **No temporary tables.** dbt's `__dbt_tmp` intermediates are real tables, which
+  dbt drops when the model succeeds. A failed model can leave one behind.
+- **Views** are built with `CREATE OR REPLACE VIEW`, not dbt's rename swap.
+- **Seeds** are inserted as typed literals (`CAST('…' AS <type>)`), not bind
+  parameters: parameters reach Opteryx as JSON, which has no DATE or TIMESTAMP.
+- **Incremental strategies:** `append`, `merge` and `delete+insert`.
+- **Model contracts are refused**, with an error naming the model: the adapter does
+  not enforce them yet, and ignoring one silently would claim a guarantee it does not keep.
+- **Queries cannot be cancelled** from dbt.
+
+## Integration tests
+
+`tests/integration/project` is a dbt project covering seeds, sources (including
+freshness), view, table, ephemeral and incremental models (all three strategies),
+snapshots, hooks, contracts, generic, singular and unit tests, `show`,
+`run-operation`, `--empty` and docs generation. Run it against opteryx.app:
+
+```bash
+CLIENT_ID=… CLIENT_SECRET=… python tests/integration/run.py
+```
+
+Every step runs, and every node must pass except those listed in
+`EXPECTED_FAILURES` in `run.py`, which must fail. The run fails on an unexpected
+failure and also on an expected failure that passes, so the list is pruned as
+Opteryx gaps close.
+
+It writes into `personal.$CLIENT_ID` (override with `OPTERYX_WORKSPACE` /
+`OPTERYX_COLLECTION`). CI runs it on push (`.github/workflows/integration.yaml`),
+reading `CLIENT_ID` / `CLIENT_SECRET` from the `OPTERYX_TEST_CLIENT` /
+`OPTERYX_TEST_TOKEN` repository secrets. That is a service account, which has no
+personal space, so CI writes into `opteryx_ci.dbt`.
+
+Offline checks (no connection) run with `python -m pytest tests/unit`.
+
+## CI
+
+| Workflow | Runs on | Does |
+|---|---|---|
+| `regression-tests.yaml` | push | `tests/unit` on Python 3.10–3.14 × dbt-core 1.10 (floor) and latest; 1.10 is skipped on 3.14, where it cannot import |
+| `integration.yaml` | push | `tests/integration/run.py` against opteryx.app; known gaps are expected failures |
+| `semgrep_scan.yaml` | push | Semgrep scan, findings uploaded to `opteryx.ops.sast_findings` |
+| `release.yaml` | `v*` tag | Builds and publishes to PyPI by trusted publishing |
+
+Repository secrets: `OPTERYX_TEST_CLIENT`, `OPTERYX_TEST_TOKEN` (integration),
+`UPLOAD_CLIENT`, `UPLOAD_TOKEN` (Semgrep upload).
+
+## Releasing
+
+Bump `version` in `dbt/adapters/opteryx/__version__.py` (the package version is read
+from it), then push a matching `vX.Y.Z` tag. PyPI must list this repository's
+`release.yaml` as a trusted publisher for `dbt-opteryx`; for the first release that
+is a pending publisher, set up on PyPI before the tag is pushed.
+
+## Verification against opteryx.app (2026-11-09)
+
+dbt-core 1.12.6, dbt-adapters 1.24.5, opteryx-sqlalchemy 0.0.13.
+
+| Feature | Result | Notes |
+|---|---|---|
+| `dbt debug` | PASS | |
+| Seeds, first load | PASS | Needs the typed-literal loader in this adapter |
+| Seeds, reload over an existing table | **FAIL (silent)** | Reports OK but doubles the rows: TRUNCATE is a no-op (issue 1) |
+| Seeds, `--full-refresh` | PASS | Drops and recreates |
+| Sources: `source()` reads | PASS | `samples.tpch_sf001.nation` |
+| Sources: tests | PASS | not_null, unique |
+| Sources: `dbt source freshness` | PASS | |
+| View materialization | PASS | Created and replaced |
+| Table materialization | PASS | Created; rebuilt through the rename swap |
+| Incremental, `append` | PASS | Second run appends only new rows (checked 4 → 5) |
+| Incremental, `merge`, first build | PASS | |
+| Incremental, `merge`, incremental run | **FAIL** | Issue 3 |
+| Tests: not_null, unique, singular | PASS | |
+| Tests: accepted_values, relationships | **FAIL** | Issue 4 |
+| `dbt docs generate` | PARTIAL | Catalog written; views have no columns (issue 5) |
+| Schema creation (`CREATE COLLECTION`) | PASS with workaround | Issue 2 |
+| Incremental, `delete+insert`, first build | PASS | |
+| Incremental, `delete+insert`, incremental run | **FAIL** | Issues 11 and 12 |
+| Ephemeral models | **FAIL** | Issue 13 |
+| Snapshots (timestamp and check strategies) | **FAIL** | Issue 14; would then hit issue 3 |
+| Unit tests | **FAIL** | Issue 5: fixtures need the input view's columns |
+| `--empty` | **FAIL** | Issue 15 |
+| Model contracts | **Refused** | The adapter raises (see above) |
+| Pre/post hooks | PASS | Hook statements ran, checked in `hook_log` |
+| `dbt show` | PASS | |
+| `dbt run-operation` with `run_query` | PASS | |
+
+## Issues found
+
+| # | Issue | Class | Proposed fix |
+|---|---|---|---|
+| 1 | `TRUNCATE TABLE` reports OK and removes nothing. `OpteryxConnector.truncate_relation` calls `Dataset.truncate()`, whose default `commit_truncation=False` never moves `current-snapshot-id`. | Opteryx correctness bug | **Fixed in opteryx-core (2026-11-09, not yet released or deployed):** the connector now passes `commit_truncation=True`. Re-run the matrix after deploy. |
+| 2 | `CREATE/DROP COLLECTION` and `ALTER/DROP WORKSPACE` fail to parse after a leading comment. dbt puts a comment in front of every statement. | Opteryx SQL gap | Have the `^\s*` anchors in `opteryx/planner/sql_rewriter/__init__.py:240-251` skip leading comments. Docs workaround: `query-comment: {append: true}`. |
+| 3 | `MERGE … WHEN NOT MATCHED THEN INSERT (…) VALUES ("id", …)` raises "Column id is ambiguous". Only the source is in scope there; qualified `S."id"` works. | Opteryx SQL gap | Bind WHEN NOT MATCHED value expressions against the source relation only. |
+| 4 | A CTE inside a derived table is not found: `SELECT … FROM (WITH a AS (…) SELECT * FROM a) t` gives "Dataset `a` cannot be found". dbt wraps every test in such a subquery. | Opteryx SQL gap | Scope CTEs declared inside a subquery to that subquery. |
+| 5 | `information_schema.columns` has no rows for views, so dbt cannot see view columns. | Opteryx SQL gap | List view columns there as well; it currently iterates `list_datasets()` only. |
+| 6 | `personal.information_schema.schemata` is empty although `personal.<user>` exists. dbt then always issues `CREATE COLLECTION IF NOT EXISTS`, which succeeds. | Opteryx catalog gap (not blocking) | List the caller's personal collection. |
+| 7 | CAST refuses `DOUBLE`, `BIGINT` and `TEXT` ("not a type CAST can produce") although `reference/types.json` lists them as accepted spellings. dbt's default seed types are `text` / `float8`. | Opteryx SQL gap | Accept the listed spellings in CAST. The adapter maps seed types itself meanwhile. |
+| 8 | INSERT type errors print the enum repr, e.g. "target LogicalCategory.FLOAT". | Opteryx message bug | Render the type name. |
+| 9 | Bind parameters of type `Decimal`, `date` or `datetime` fail with "not JSON serializable" in the DBAPI. | Adapter/protocol gap (opteryx-sqlalchemy) | Encode them in `_submit_statement`. Even then, the server will not coerce a string into DATE/TIMESTAMP, so this adapter's seeds use literals. |
+| 10 | `ALTER TABLE x RENAME TO y` with a bare target is read as a move to another workspace. | Behaviour (documented) | None needed: the adapter always passes the qualified name. |
+| 11 | `WHERE (id) IN (SELECT …)` with one parenthesised column fails: "A correlated EXISTS/IN subquery correlates on `(id)`…". Without the parentheses it works. dbt's delete+insert always parenthesises. | Opteryx SQL gap | Treat a one-element parenthesised expression as the expression itself. |
+| 12 | **INSERT fails after a DELETE that removed every row** of the table's files: "concat: all inputs must share one type for 'column_uncompressed_sizes_in_bytes' - found INT64, ARRAY". Root cause is in rugo: a zero-row `array<…>` column reads back as INT64. The delete-all writes a manifest with one zero-row row group, INSERT appends a row group to it, and `read_manifest_columns` cannot combine the two. Three-line reproducer: write an empty ARRAY vector with `rugo.parquet.write_parquet`; `read_parquet` returns it as INT64. Not dbt-specific. | Opteryx correctness bug (rugo reader) | **Fixed in opteryx-core (2026-11-09, not yet released or deployed):** the reader routes list columns on the schema's `max_rep_level`, not on whether repetition levels were decoded. Manifests already written this way need no rewrite; they read correctly once the fix is deployed. |
+| 13 | `CREATE TABLE … AS WITH a AS (…) SELECT … FROM a` gives "Dataset `a` cannot be found". The same query without CREATE works. dbt inlines ephemeral models this way. | Opteryx SQL gap | Resolve CTEs in a CTAS body. |
+| 14 | `SELECT *, x` is refused by design ("`SELECT *` cannot coexist with additional columns"); `SELECT t.*, x` works. dbt's snapshot SQL uses `SELECT *, …`. | Opteryx dialect rule | Either allow `*` with other columns, or override dbt's snapshot macros in the adapter to qualify the star. Architect's call. |
+| 15 | `WHERE false` is refused by design ("WHERE clause cannot be a bare literal"); `WHERE 1 = 0` works. dbt's `--empty` renders refs as `(SELECT * FROM x WHERE false LIMIT 0)`, and contract enforcement uses the same pattern. | Opteryx dialect rule | Either accept a bare boolean literal, or override the relation's limited render in the adapter. Architect's call. |

dbt_opteryx-0.1.0/dbt_opteryx.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+dbt/adapters/opteryx/__init__.py
+dbt/adapters/opteryx/__version__.py
+dbt/adapters/opteryx/connections.py
+dbt/adapters/opteryx/impl.py
+dbt/include/opteryx/__init__.py
+dbt/include/opteryx/dbt_project.yml
+dbt/include/opteryx/macros/adapters.sql
+dbt/include/opteryx/macros/catalog.sql
+dbt/include/opteryx/macros/materializations/seed.sql
+dbt/include/opteryx/macros/materializations/view.sql
+dbt_opteryx.egg-info/PKG-INFO
+dbt_opteryx.egg-info/SOURCES.txt
+dbt_opteryx.egg-info/dependency_links.txt
+dbt_opteryx.egg-info/requires.txt
+dbt_opteryx.egg-info/top_level.txt

dbt_opteryx-0.1.0/dbt_opteryx.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dbt_opteryx-0.1.0/dbt_opteryx.egg-info/requires.txt

@@ -0,0 +1,4 @@
+dbt-core<2,>=1.10
+dbt-adapters<2,>=1.7
+dbt-common<2,>=1.10
+opteryx-sqlalchemy>=0.0.13

dbt_opteryx-0.1.0/dbt_opteryx.egg-info/top_level.txt

@@ -0,0 +1 @@
+dbt

dbt_opteryx-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dbt-opteryx"
+dynamic = ["version"]
+description = "dbt adapter for Opteryx Cloud (https://opteryx.app)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+dependencies = [
+    "dbt-core>=1.10,<2",  # the integration project uses 1.10 test `arguments:` syntax
+    "dbt-adapters>=1.7,<2",
+    "dbt-common>=1.10,<2",
+    "opteryx-sqlalchemy>=0.0.13",
+]
+
+[tool.setuptools.packages.find]
+include = ["dbt*"]
+namespaces = true
+
+[tool.setuptools.dynamic]
+version = { attr = "dbt.adapters.opteryx.__version__.version" }
+
+[tool.setuptools.package-data]
+"dbt.include.opteryx" = ["dbt_project.yml", "macros/*.sql", "macros/**/*.sql"]

dbt_opteryx-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+