stackabletech · maltesander · Aug 5, 2026 · Aug 5, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,140 @@
+name: Bug report
+description: The driver behaves differently from the ODBC spec, from its own documentation, or from what Trino answers.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This repository holds the Trino-specific half of the driver: the
+        connection string, the SQL and type mapping, the catalog functions and
+        the error mapping. Everything generic about being an ODBC driver
+        (handle management, UTF-16 marshalling, diagnostic records, the
+        exported C entry points) lives in
+        [`stackable-odbc-core`](https://github.com/stackabletech/stackable-odbc-core).
+
+        If you are not sure which side a problem falls on, file it here and say
+        so. Please do not report security vulnerabilities in an issue, see
+        [SECURITY.md](https://github.com/stackabletech/stackable-odbc-trino/blob/main/SECURITY.md).
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      options:
+        - The ODBC driver
+        - The Power BI custom connector (.mez)
+        - The Windows installer or the DSN dialog
+        - The Linux installer
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What the driver did, and what you expected instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: >
+        The ODBC calls or the application steps that lead to it, in order, with
+        the arguments that matter. If a statement is involved, include the SQL
+        as the application sends it, and what Trino answers when the same
+        statement is run through the Trino CLI. That comparison separates a
+        driver defect from Trino's own behaviour faster than anything else.
+      placeholder: |
+        SQLExecDirectW(stmt, L"SELECT * FROM tpch.tiny.nation", SQL_NTS)  -> SQL_SUCCESS
+        SQLFetch(stmt)                                                   -> SQL_ERROR, expected SQL_SUCCESS
+    validations:
+      required: true
+
+  - type: input
+    id: sqlstate
+    attributes:
+      label: SQLSTATE and message
+      description: >
+        From `SQLGetDiagRecW`, if the call returned `SQL_ERROR` or
+        `SQL_SUCCESS_WITH_INFO`. A wrong SQLSTATE is itself a bug worth
+        reporting, even when the call otherwise does the right thing.
+      placeholder: "42S02, Table 'tpch.tiny.nations' does not exist"
+
+  - type: textarea
+    id: connection-string
+    attributes:
+      label: Connection string or DSN
+      description: >
+        With the password and any token removed. Several defects turn out to be
+        one key, so the keys in use are usually part of the answer. For example
+        `Driver=stackable_odbc_trino;Host=trino.example.com;Port=8443;User=me;TlsVerify=ca`.
+      render: text
+
+  - type: input
+    id: version
+    attributes:
+      label: Driver version
+      description: The release you installed, or the commit if you built from source.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: trino-version
+    attributes:
+      label: Trino version
+      description: >
+        The coordinator version, from `SELECT version()`. Also say which
+        catalog and connector the failing query touches, if it touches one.
+      placeholder: "476, iceberg catalog"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: driver-manager
+    attributes:
+      label: Driver Manager
+      description: >
+        The Windows Driver Manager is considerably stricter than unixODBC, and
+        several behaviours differ between them.
+      options:
+        - unixODBC
+        - Windows Driver Manager
+        - Other / not sure
+    validations:
+      required: true
+
+  - type: input
+    id: platform
+    attributes:
+      label: Platform and application
+      description: OS and architecture, and the tool that drives the driver.
+      placeholder: "Windows 11 x86_64, Power BI Desktop 2.14 / Ubuntu 24.04 x86_64, pyodbc 5.1"
+    validations:
+      required: true
+
+  - type: input
+    id: spec-reference
+    attributes:
+      label: Spec reference
+      description: >
+        Link to the function's page on Microsoft Learn, and quote the row or
+        sentence you think is not being honoured. Optional, but it is what
+        makes a report immediately actionable. Pay attention to whether the row
+        carries a `(DM)` marker, which means the Driver Manager owes it rather
+        than the driver.
+      placeholder: "https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlgetinfo-function"
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Driver log
+      description: >
+        Set `ODBC_LOG_LEVEL=debug` and `ODBC_LOG_FILE=/path/to/log`, reproduce,
+        and attach the relevant part. **Check it before posting.** The
+        connection string appears in it: passwords are redacted, but hostnames,
+        usernames and every other parameter are not.
+      render: text
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/orgs/stackabletech/discussions
+    about: For usage questions and anything that is not yet a specific defect.
+  - name: Community chat
+    url: https://discord.gg/7kZ3BNnCAF
+    about: Stackable's Discord, for a faster back-and-forth.
+  - name: Report a security vulnerability
+    url: https://github.com/stackabletech/stackable-odbc-trino/security/advisories/new
+    about: Please report vulnerabilities privately rather than in an issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,84 @@
+name: Feature request
+description: A connection-string key, a type mapping, a metadata function or a connector capability the driver does not offer yet.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Most additions here are driven by something that already exists
+        elsewhere: a key Trino's JDBC driver accepts, a session property the
+        coordinator honours, a spec-defined info type answered with a default.
+        Saying which one it is usually settles the design.
+
+        Some limits are Trino's rather than the driver's. Trino publishes no
+        primary keys, foreign keys, indexes or stored procedures, so those
+        lookups cannot return rows. The
+        [Limits section of the README](https://github.com/stackabletech/stackable-odbc-trino#limits)
+        lists the rest.
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What is missing
+      description: What you need the driver to do that it does not do today.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: What it unblocks
+      description: >
+        The application that needs it, and what you do instead today. A
+        concrete blocked case is the strongest argument.
+      placeholder: "Power BI cannot refresh a dataset because ..."
+    validations:
+      required: true
+
+  - type: input
+    id: prior-art
+    attributes:
+      label: Prior art
+      description: >
+        If Trino's JDBC driver, the Trino CLI or the REST API already exposes
+        this, name the property or header. Keys shared with JDBC take the same
+        name and format here on purpose, so an existing name is usually the one
+        we adopt.
+      placeholder: "JDBC connection property `assumeLiteralNamesInMetadataCallsForNonConformingClients`"
+
+  - type: input
+    id: spec-reference
+    attributes:
+      label: Spec reference
+      description: >
+        The relevant page on Microsoft Learn, if there is one. For an info type
+        or a statement attribute, quote its description: the stated *purpose*
+        often decides the design.
+      placeholder: "https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlgetinfo-function"
+
+  - type: dropdown
+    id: layer
+    attributes:
+      label: Which side should own it
+      description: >
+        This repository holds only the Trino-specific half. Anything generic to
+        being an ODBC driver belongs in
+        [`stackable-odbc-core`](https://github.com/stackabletech/stackable-odbc-core),
+        and anything about speaking Trino's protocol belongs in the client
+        library underneath it. Answer "not sure" if the split is not obvious,
+        which is often.
+      options:
+        - This driver (a Trino-specific answer, key or mapping)
+        - The Power BI custom connector
+        - stackable-odbc-core (the same for every driver)
+        - The Trino client library or Trino itself
+        - Not sure
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: compatibility
+    attributes:
+      label: Compatibility
+      options:
+        - label: This would change an existing connection-string key, SQLSTATE, type mapping or `SQLGetInfo` value, so an application relying on today's behaviour would see the difference
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,60 @@
+<!-- markdownlint-disable-file MD041 -->
+<!--
+MD041 wants a top-level heading first. This file is not a document: its
+content is pasted into a pull request body, where GitHub supplies the title,
+so an H1 here would only duplicate it. The rule stays on everywhere else.
+
+Delete any section that does not apply. The checklist is a reminder, not a
+gate. CI enforces what it can, and the rest is what a reviewer would otherwise
+have to ask for.
+-->
+
+## What this changes
+
+<!-- What an ODBC application sees differently after this, and why. -->
+
+## Spec basis
+
+<!--
+For anything an application can observe (a SQLSTATE, a `SQLGetInfo` value, a
+catalog result set, a type conversion), link the relevant page on Microsoft
+Learn and quote the row or sentence this implements.
+
+Two things worth stating explicitly, because both have caused rework here:
+- whether a SQLSTATE's row carries a **(DM)** marker, which means the Driver
+  Manager owes it and the driver must not return it; and
+- what the info type's or attribute's description says its *purpose* is, which
+  has decided the design more than once.
+-->
+
+## Trino behaviour
+
+<!--
+What the coordinator actually does, if this depends on it. Paste the response,
+the `DESCRIBE OUTPUT` row or the error Trino returns, rather than describing
+it. A measured answer is what the next reader needs, and Trino's behaviour is
+not always what its documentation implies.
+-->
+
+## Checklist
+
+- [ ] `pre-commit run --all-files` passes. It is the single source of truth for what must pass.
+- [ ] `CHANGELOG.md` has an entry under `## [Unreleased]`, if an ODBC application can observe the difference. A changed SQLSTATE, a changed `SQLGetInfo` value, a new connection-string key or a different type mapping all count.
+- [ ] Every client error added or moved goes through `map_trino_error`, which is the single place that decides the SQLSTATE and carries Trino's own error code through to `SQLGetDiagRec`.
+- [ ] New tests were checked by breaking the line they cover and watching them fail. A test that cannot fail reports coverage that does not exist.
+
+### If it applies
+
+- [ ] A new connection-string key is two edits: the parser in `src/backend/types/connect_params.rs` and the table in `README.md`. The Windows dialog is generated from the parser, and a test in `src/lib.rs` fails if the two disagree.
+- [ ] The integration suite was run against a live Trino: `./integration-tests/setup.sh` then `./integration-tests/run-tests.sh`. CI runs the Linux suites, so this is about anything you added to them.
+- [ ] The Windows suites were run in the VM, for anything touching the Windows Driver Manager, the installer or the DSN dialog. They do not run in CI. See `integration-tests/windows/WINDOWS.md`.
+- [ ] A defect found in `stackable-odbc-core` or in the Trino client was fixed where it lives, not worked around here, and this pull request says which version it needs.
+- [ ] The Power BI connector was rebuilt and loaded in Power BI Desktop, for anything under `connector/`.
+
+## Notes for the reviewer
+
+<!--
+Anything you decided rather than derived: a spec sentence you read two ways, a
+case left unhandled on purpose, a Trino version whose behaviour you could not
+test against.
+-->