From: Mike Bayer Date: Tue, 2 Aug 2022 13:33:51 +0000 (-0400) Subject: document @ sign in issue template, docs X-Git-Tag: rel_2_0_0b1~144 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7f45bcd114c797105921e06789b3753e7d8f6daa;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git document @ sign in issue template, docs Fixes: #8328 Change-Id: I69a48c4499fe7e57aad242403186e69c4452b84b --- diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 92f04ae33b..4f692f3663 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -26,6 +26,13 @@ If your issue is actually a bug, we will open a new bug report with what we need [START A NEW USAGE QUESTIONS DISCUSSION HERE](https://github.com/sqlalchemy/sqlalchemy/discussions/new?category=Usage-Questions) " + - type: markdown + attributes: + value: "**IF YOUR ISSUE RELATES TO AN @ SIGN IN YOUR PASSWORD. THIS IS NOT A BUG.** + +Please URL escape @ signs in passwords using `%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: " diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index 6edd01090a..c8af6626a3 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -60,7 +60,9 @@ on a URL. These URLs follow `RFC-1738 `_, and usually can include username, password, hostname, database name as well as optional keyword arguments for additional configuration. In some cases a file path is accepted, and in others a "data source name" replaces -the "host" and "database" portions. The typical form of a database URL is:: +the "host" and "database" portions. The typical form of a database URL is: + +.. sourcecode:: plain dialect+driver://username:password@host:port/database @@ -71,31 +73,47 @@ the database using all lowercase letters. If not specified, a "default" DBAPI will be imported if available - this default is typically the most widely known driver available for that backend. +Escaping Special Characters such as @ signs in Passwords +---------------------------------------------------------- + As the URL is like any other URL, **special characters such as those that may be used in the user and password need to be URL encoded to be parsed correctly.**. -Below is an example of a URL that includes the password ``"kx%jj5/g"``, where the -percent sign and slash characters are represented as ``%25`` and ``%2F``, -respectively:: +**This includes the @ sign**. + +Below is an example of a URL that includes the password ``"kx@jj5/g"``, where the +"at" sign and slash characters are represented as ``%40`` and ``%2F``, +respectively: + +.. sourcecode:: plain - postgresql+pg8000://dbuser:kx%25jj5%2Fg@pghost10/appdb + postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb The encoding for the above password can be generated using `urllib.parse `_:: >>> import urllib.parse - >>> urllib.parse.quote_plus("kx%jj5/g") - 'kx%25jj5%2Fg' + >>> urllib.parse.quote_plus("kx@jj5/g") + 'kx%40jj5%2Fg' + +.. versionchanged:: 1.4 + + Support for ``@`` signs in hostnames and database names has been + fixed. As a side effect of this fix, ``@`` signs in passwords must be + escaped. + +Backend-Specific URLs +---------------------- Examples for common connection styles follow below. For a full index of detailed information on all included dialects as well as links to third-party dialects, see :ref:`dialect_toplevel`. PostgreSQL ----------- +^^^^^^^^^^ -The PostgreSQL dialect uses psycopg2 as the default DBAPI. pg8000 is -also available as a pure-Python substitute:: +The PostgreSQL dialect uses psycopg2 as the default DBAPI. Other +PostgreSQL DBAPIs include pg8000 and asyncpg:: # default engine = create_engine('postgresql://scott:tiger@localhost/mydatabase') @@ -109,10 +127,10 @@ also available as a pure-Python substitute:: More notes on connecting to PostgreSQL at :ref:`postgresql_toplevel`. MySQL ------ +^^^^^^^^^^ -The MySQL dialect uses mysql-python as the default DBAPI. There are many -MySQL DBAPIs available, including MySQL-connector-python and OurSQL:: +The MySQL dialect uses mysqlclient as the default DBAPI. There are other +MySQL DBAPIs available, including PyMySQL:: # default engine = create_engine('mysql://scott:tiger@localhost/foo') @@ -126,7 +144,7 @@ MySQL DBAPIs available, including MySQL-connector-python and OurSQL:: More notes on connecting to MySQL at :ref:`mysql_toplevel`. Oracle ------- +^^^^^^^^^^ The Oracle dialect uses cx_oracle as the default DBAPI:: @@ -137,7 +155,7 @@ The Oracle dialect uses cx_oracle as the default DBAPI:: More notes on connecting to Oracle at :ref:`oracle_toplevel`. Microsoft SQL Server --------------------- +^^^^^^^^^^^^^^^^^^^^ The SQL Server dialect uses pyodbc as the default DBAPI. pymssql is also available:: @@ -151,7 +169,7 @@ also available:: More notes on connecting to SQL Server at :ref:`mssql_toplevel`. SQLite ------- +^^^^^^^ SQLite connects to file-based databases, using the Python built-in module ``sqlite3`` by default. @@ -182,7 +200,7 @@ To use a SQLite ``:memory:`` database, specify an empty URL:: More notes on connecting to SQLite at :ref:`sqlite_toplevel`. Others ------- +^^^^^^ See :ref:`dialect_toplevel`, the top-level page for all additional dialect documentation.