SqlAlchemy 2.0 中文文档（四十三）（3）https://developer.aliyun.com/article/1563061
隐藏参数
Engine发出的日志还指示了特定语句中存在的 SQL 参数的摘录。为了防止出于隐私目的记录这些参数，启用create_engine.hide_parameters标志：
>>> e = create_engine("sqlite://", echo=True, hide_parameters=True) >>> with e.connect() as conn: ... conn.execute(text("select :some_private_name"), {"some_private_name": "pii"}) 2020-10-24 12:48:32,808 INFO sqlalchemy.engine.Engine select ? 2020-10-24 12:48:32,808 INFO sqlalchemy.engine.Engine [SQL parameters hidden due to hide_parameters=True] ```## 支持的数据库 SQLAlchemy 包括许多用于各种后端的`Dialect`实现。SQLAlchemy 包含最常见数据库的方言；另外一些需要额外安装单独的方言。 查看 Dialects 部分，了解可用的各种后端信息。 ## 数据库 URL `create_engine()`函数基于 URL 生成一个`Engine`对象。URL 的格式通常遵循[RFC-1738](https://www.ietf.org/rfc/rfc1738.txt)，但也有一些例外，包括“scheme”部分接受下划线而不是破折号或句点。URL 通常包括用户名、密码、主机名、数据库名字段，以及用于额外配置的可选关键字参数。在某些情况下，接受文件路径，而在其他情况下，“数据源名称”取代“主机”和“数据库”部分。数据库 URL 的典型形式为： ```py dialect+driver://username:password@host:port/database
方言名称包括 SQLAlchemy 方言的标识名称，如sqlite、mysql、postgresql、oracle或mssql。驱动程序名称是用于使用所有小写字母连接到数据库的 DBAPI 的名称。如果未指定，将导入“默认”DBAPI（如果可用）- 这个默认通常是该后端可用的最广为人知的驱动程序。
转义特殊字符，如密码中的@符号
在构建完整的 URL 字符串以传递给create_engine()时，特殊字符（如用户和密码中可能使用的字符）需要进行 URL 编码以正确解析。。这包括@符号。
以下是包含密码 "kx@jj5/g" 的 URL 的示例，其中“at” 符号和斜杠字符分别表示为 %40 和 %2F：
postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb
上述密码的编码可以使用 urllib.parse 生成：
>>> import urllib.parse >>> urllib.parse.quote_plus("kx@jj5/g") 'kx%40jj5%2Fg'
然后 URL 可以作为字符串传递给 create_engine()：
from sqlalchemy import create_engine engine = create_engine("postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb")
作为在创建完整 URL 字符串时替代转义特殊字符的选择，传递给 create_engine() 的对象可以是 URL 对象的实例，它绕过了解析阶段，可以直接容纳未转义的字符串。查看下一节以获取示例。
1.4 版本中的变化：已修复主机名和数据库名中 @ 符号的支持。作为此修复的副作用，密码中的 @ 符号必须转义。
以编程方式创建 URL
传递给 create_engine() 的值可以是 URL 的实例，而不是简单的字符串，这样可以绕过使用字符串解析的需要，因此不需要提供转义的 URL 字符串。
使用 URL.create() 构造方法创建 URL 对象，逐个传递所有字段。密码中的特殊字符可以不作任何修改地传递：
from sqlalchemy import URL url_object = URL.create( "postgresql+pg8000", username="dbuser", password="kx@jj5/g", # plain (unescaped) text host="pghost10", database="appdb", )
构造的 URL 对象然后可以直接传递给 create_engine() 代替字符串参数：
from sqlalchemy import create_engine engine = create_engine(url_object)
另请参阅
URL
URL.create()
特定后端的 URL
下面是常见连接样式的示例。有关所有包含方言的详细信息以及第三方方言的链接的完整索引，请参见 方言。
PostgreSQL
PostgreSQL 方言使用 psycopg2 作为默认的 DBAPI。其他 PostgreSQL DBAPI 包括 pg8000 和 asyncpg：
# default engine = create_engine("postgresql://scott:tiger@localhost/mydatabase") # psycopg2 engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/mydatabase") # pg8000 engine = create_engine("postgresql+pg8000://scott:tiger@localhost/mydatabase")
关于连接到 PostgreSQL 的更多说明请参见 PostgreSQL。
MySQL
MySQL 方言使用 mysqlclient 作为默认的 DBAPI。还有其他可用的 MySQL DBAPI，包括 PyMySQL：
# default engine = create_engine("mysql://scott:tiger@localhost/foo") # mysqlclient (a maintained fork of MySQL-Python) engine = create_engine("mysql+mysqldb://scott:tiger@localhost/foo") # PyMySQL engine = create_engine("mysql+pymysql://scott:tiger@localhost/foo")
关于连接到 MySQL 的更多说明请参见 MySQL 和 MariaDB。
Oracle
Oracle 方言使用 cx_oracle 作为默认的 DBAPI：
engine = create_engine("oracle://scott:tiger@127.0.0.1:1521/sidname") engine = create_engine("oracle+cx_oracle://scott:tiger@tnsname")
关于连接到 Oracle 的更多说明请参见 Oracle。
Microsoft SQL Server
SQL Server 方言使用 pyodbc 作为默认的 DBAPI。pymssql 也可用：
# pyodbc engine = create_engine("mssql+pyodbc://scott:tiger@mydsn") # pymssql engine = create_engine("mssql+pymssql://scott:tiger@hostname:port/dbname")
关于连接到 SQL Server 的更多说明请参见 Microsoft SQL Server。
SQLite
SQLite 连接到基于文件的数据库，默认使用 Python 内置模块sqlite3。
由于 SQLite 连接到本地文件，URL 格式略有不同。URL 的“file”部分是数据库的文件名。对于相对文件路径，这需要三个斜杠：
# sqlite://<nohostname>/<path> # where <path> is relative: engine = create_engine("sqlite:///foo.db")
对于绝对文件路径，三个斜杠后跟绝对路径：
# Unix/Mac - 4 initial slashes in total engine = create_engine("sqlite:absolute/path/to/foo.db") # Windows engine = create_engine("sqlite:///C:\\path\\to\\foo.db") # Windows alternative using raw string engine = create_engine(r"sqlite:///C:\path\to\foo.db")
要使用 SQLite :memory:数据库，请指定空 URL：
engine = create_engine("sqlite://")
关于连接到 SQLite 的更多说明请参见 SQLite。
其他
请参阅 Dialects，所有其他方言文档的顶级页面。
转义密码中的特殊字符，例如@符号
在构造完整的 URL 字符串以传递给create_engine()时，需要对特殊字符进行 URL 编码才能正确解析。这包括@符号。
下面是一个包含密码"kx@jj5/g"的 URL 示例，其中“at”符号和斜杠字符分别表示为%40和%2F：
postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb
上述密码的编码可以使用urllib.parse生成：
>>> import urllib.parse >>> urllib.parse.quote_plus("kx@jj5/g") 'kx%40jj5%2Fg'
然后 URL 可以作为字符串传递给create_engine()：
from sqlalchemy import create_engine engine = create_engine("postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb")
作为在创建完整 URL 字符串时转义特殊字符的替代方法，传递给create_engine()的对象可以是URL对象的实例，它会绕过解析阶段并可以直接适应未转义的字符串。请参阅下一节的示例。
从版本 1.4 开始更改：修复了对主机名和数据库名中的@符号的支持。由于此修复的副作用，密码中的@符号必须转义。
以编程方式创建 URL
传递给create_engine()的值可以是URL的实例，而不是简单的字符串，这将绕过使用字符串解析的需要，因此不需要提供已转义的 URL 字符串。
URL对象是使用URL.create()构造方法创建的，分别传递所有字段。例如密码中的特殊字符可以直接传递而无需任何修改：
from sqlalchemy import URL url_object = URL.create( "postgresql+pg8000", username="dbuser", password="kx@jj5/g", # plain (unescaped) text host="pghost10", database="appdb", )
然后构造的URL对象可以直接传递给create_engine()以替代字符串参数：
from sqlalchemy import create_engine engine = create_engine(url_object)
另请参阅
URL
URL.create()
后端特定的 URL
下面是常见连接样式的示例。有关所有包含方言的详细信息以及链接到第三方方言的链接的完整索引，请参阅方言。
PostgreSQL
PostgreSQL 方言默认使用 psycopg2 作为默认的 DBAPI。其他 PostgreSQL DBAPI 包括 pg8000 和 asyncpg：
# default engine = create_engine("postgresql://scott:tiger@localhost/mydatabase") # psycopg2 engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/mydatabase") # pg8000 engine = create_engine("postgresql+pg8000://scott:tiger@localhost/mydatabase")
在 PostgreSQL 中有关连接到 PostgreSQL 的更多注意事项。
MySQL
MySQL 方言默认使用 mysqlclient 作为默认的 DBAPI。还有其他可用的 MySQL DBAPI，包括 PyMySQL：
# default engine = create_engine("mysql://scott:tiger@localhost/foo") # mysqlclient (a maintained fork of MySQL-Python) engine = create_engine("mysql+mysqldb://scott:tiger@localhost/foo") # PyMySQL engine = create_engine("mysql+pymysql://scott:tiger@localhost/foo")
在 MySQL 和 MariaDB 中有关连接到 MySQL 的更多注意事项。
Oracle
Oracle 方言默认使用 cx_oracle 作为默认的 DBAPI：
engine = create_engine("oracle://scott:tiger@127.0.0.1:1521/sidname") engine = create_engine("oracle+cx_oracle://scott:tiger@tnsname")
在 Oracle 中有关连接到 Oracle 的更多注意事项。
Microsoft SQL Server
SQL Server 方言默认使用 pyodbc 作为默认的 DBAPI。pymssql 也可用：
# pyodbc engine = create_engine("mssql+pyodbc://scott:tiger@mydsn") # pymssql engine = create_engine("mssql+pymssql://scott:tiger@hostname:port/dbname")
在 Microsoft SQL Server 中有关连接到 SQL Server 的更多注意事项。
SQLite
SQLite 连接到基于文件的数据库，默认情况下使用 Python 内置模块sqlite3。
由于 SQLite 连接到本地文件，URL 格式略有不同。 URL 的“file”部分是数据库的文件名。对于相对文件路径，这需要三个斜杠：
# sqlite://<nohostname>/<path> # where <path> is relative: engine = create_engine("sqlite:///foo.db")
对于绝对文件路径，三个斜杠后跟绝对路径：
# Unix/Mac - 4 initial slashes in total engine = create_engine("sqlite:absolute/path/to/foo.db") # Windows engine = create_engine("sqlite:///C:\\path\\to\\foo.db") # Windows alternative using raw string engine = create_engine(r"sqlite:///C:\path\to\foo.db")
要使用 SQLite :memory: 数据库，请指定一个空 URL：
engine = create_engine("sqlite://")
在 SQLite 中有关连接到 SQLite 的更多注意事项。
其他
请参阅方言，这是所有额外方言文档的顶级页面。
PostgreSQL
PostgreSQL 方言默认使用 psycopg2 作为默认的 DBAPI。其他 PostgreSQL DBAPI 包括 pg8000 和 asyncpg：
# default engine = create_engine("postgresql://scott:tiger@localhost/mydatabase") # psycopg2 engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/mydatabase") # pg8000 engine = create_engine("postgresql+pg8000://scott:tiger@localhost/mydatabase")
在 PostgreSQL 中有关连接到 PostgreSQL 的更多注意事项。
MySQL
MySQL 方言默认使用 mysqlclient 作为默认的 DBAPI。还有其他可用的 MySQL DBAPI，包括 PyMySQL：
# default engine = create_engine("mysql://scott:tiger@localhost/foo") # mysqlclient (a maintained fork of MySQL-Python) engine = create_engine("mysql+mysqldb://scott:tiger@localhost/foo") # PyMySQL engine = create_engine("mysql+pymysql://scott:tiger@localhost/foo")
在 MySQL 和 MariaDB 中有关连接到 MySQL 的更多注意事项。
Oracle
Oracle 方言默认使用 cx_oracle 作为默认的 DBAPI：
engine = create_engine("oracle://scott:tiger@127.0.0.1:1521/sidname") engine = create_engine("oracle+cx_oracle://scott:tiger@tnsname")
在 Oracle 中有关连接到 Oracle 的更多注意事项。
Microsoft SQL Server
SQL Server 方言默认使用 pyodbc 作为默认的 DBAPI。pymssql 也可用：
# pyodbc engine = create_engine("mssql+pyodbc://scott:tiger@mydsn") # pymssql engine = create_engine("mssql+pymssql://scott:tiger@hostname:port/dbname")
在 Microsoft SQL Server 中有关连接到 SQL Server 的更多注意事项。
SQLite
SQLite 连接到基于文件的数据库，默认情况下使用 Python 内置模块sqlite3。
由于 SQLite 连接到本地文件，URL 格式略有不同。 URL 的“file”部分是数据库的文件名。对于相对文件路径，这需要三个斜杠：
# sqlite://<nohostname>/<path> # where <path> is relative: engine = create_engine("sqlite:///foo.db")
对于绝对文件路径，三个斜杠后跟绝对路径：
# Unix/Mac - 4 initial slashes in total engine = create_engine("sqlite:absolute/path/to/foo.db") # Windows engine = create_engine("sqlite:///C:\\path\\to\\foo.db") # Windows alternative using raw string engine = create_engine(r"sqlite:///C:\path\to\foo.db")
要使用 SQLite :memory: 数据库，请指定一个空 URL：
engine = create_engine("sqlite://")
在 SQLite 中有关连接到 SQLite 的更多注意事项。
其他
请参阅方言，这是所有额外方言文档的顶级页面。
SqlAlchemy 2.0 中文文档（四十三）（5）https://developer.aliyun.com/article/1563064
