diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..e4f2cc8 --- /dev/null +++ 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 new file mode 100644 index 0000000..414672c --- /dev/null +++ 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 new file mode 100644 index 0000000..928e74c --- /dev/null +++ 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 new file mode 100644 index 0000000..2987105 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,60 @@ + + + +## What this changes + + + +## Spec basis + + + +## Trino behaviour + + + +## 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 + +