# docs https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema

name: Create a bug report regarding SQLAlchemy runtime behavior
description: Errors and regression reports with complete reproducing test cases and/or stack traces.
labels: [requires triage]
body:
  - type: markdown
    attributes:
      value: "

**If you are writing new SQLAlchemy code and are observing a behavior that you did not expect,
or if you are new to SQLAlchemy overall, please open a
[discussion](https://github.com/sqlalchemy/sqlalchemy/discussions/new?category=Usage-Questions)
instead of an issue report.  The VAST MAJORITY of issues are converted to discussions
as they are not bugs.**

[START A NEW USAGE QUESTIONS DISCUSSION HERE](https://github.com/sqlalchemy/sqlalchemy/discussions/new?category=Usage-Questions)

"
  - type: markdown
    attributes:
      value: "**If your issue is you have upgraded SQLAlchemy and now can't connect to the database, please READ THIS FIRST:**

URL escape **@ signs and any other non-alphanumeric characters** in passwords;  **@ signs
must be escaped in modern versions of SQLAlchemy which was not the case with older versions**.

For the ``@`` sign for example, the escape is `%40`.
See [Engine URLs](https://docs.sqlalchemy.org/en/stable/core/engines.html#escaping-special-characters-such-as-signs-in-passwords)
    "
  - type: markdown
    attributes:
      value: "

**GUIDELINES FOR REPORTING BUGS**

IF YOU DO NOT HAVE A COMPLETE, RUNNABLE TEST CASE WRITTEN DIRECTLY IN THE TEXTAREA BELOW,
YOUR ISSUE WILL BE CLOSED.   PLEASE OPEN A
[DISCUSSION](https://github.com/sqlalchemy/sqlalchemy/discussions/new?category=Usage-Questions)
IF YOU DON'T HAVE A COMPLETE TEST CASE!


If you are new to SQLAlchemy bug reports, please review our many examples
of [well written bug reports](https://github.com/sqlalchemy/sqlalchemy/issues?q=is%3Aissue+label%3A%22great+mcve%22).   Each of these reports include the following features:

1. a **succinct description of the problem** - typically a line or two at most

2. **succinct, dependency-free code which reproduces the problem**, otherwise known as a [Minimal, Complete, and Verifiable](https://stackoverflow.com/help/mcve) example.

3. **complete stack traces for all errors - please avoid screenshots, use formatted text inside issues**

4. Other things as applicable:   **SQL log output**, **database backend and DBAPI driver**,
   **operating system**, **comparative performance timings** for performance issues.
"
  - type: textarea
    attributes:
      label: Describe the bug
      description: A clear and concise description of what the bug is.
    validations:
      required: true

  - type: input
    id: relevant_documentation
    attributes:
      label: Optional link from https://docs.sqlalchemy.org which documents the behavior that is expected
      description:  "
Please make sure the behavior you are seeing is definitely in contradiction
to what's documented as the correct behavior.  If unsure, open a
[discussion](https://github.com/sqlalchemy/sqlalchemy/discussions/new?category=Usage-Questions)
instead.
"
    validations:
      required: false

  - type: input
    id: sqlalchemy_version
    attributes:
      label: SQLAlchemy Version in Use
      description: e.g. 1.4.42, 2.0.2, etc
    validations:
      required: true

  - type: input
    id: dbapi_version
    attributes:
      label: DBAPI (i.e. the database driver)
      description: examples include psycopg2, pyodbc, pysqlite, mysqlclient, asyncpg
    validations:
      required: true

  - type: input
    id: database_version
    attributes:
      label: Database Vendor and Major Version
      description: e.g. SQLite, PostgreSQL 12, MySQL 8, MariaDB 10.10, etc
    validations:
      required: true

  - type: input
    id: python_version
    attributes:
      label: Python Version
      description: assumes cpython unless otherwise stated, e.g. 3.10, 3.11, pypy
    validations:
      required: true

  - type: input
    id: os
    attributes:
      label: Operating system
      description: Linux, Windows, OSX
    validations:
      required: true

  - type: textarea
    attributes:
      label: To Reproduce
      description: "
Provide your [Minimal, Complete, and Verifiable](https://stackoverflow.com/help/mcve) example here.
If you need help creating one, you can model yours after the MCV code shared in one of our previous
[well written bug reports](https://github.com/sqlalchemy/sqlalchemy/issues?q=is%3Aissue+label%3A%22great+mcve%22)"
      placeholder: "# Insert code here (text area already python formatted)"
      render: python
    validations:
      required: true

  - type: textarea
    attributes:
      label: Error
      description: "
Provide the complete text of any errors received **including the complete stack trace**.
If the message is a warning, run your program with the ``-Werror`` flag:   ``python -Werror myprogram.py``
"
      placeholder: "# Copy the complete stack trace and error message here, including SQL log output if applicable."
      value: "\
```

# Copy the complete stack trace and error message here, including SQL log output if applicable.

```
"
    validations:
      required: true

  - type: textarea
    attributes:
      label: Additional context
      description: Add any other context about the problem here.
    validations:
      required: false

  - type: markdown
    attributes:
      value: "**Have a nice day!**"