提示
本页面仅包含st.connections.SQLConnection
类。要深入了解在Streamlit应用程序中创建和管理数据连接,请阅读连接到数据。
使用SQLAlchemy引擎连接到SQL数据库。
使用 st.connection("sql") 或
st.connection("
- url 或关键字参数用于 sqlalchemy.engine.URL.create(),除了 drivername。使用 dialect 和 driver 代替 drivername。
- sqlalchemy.create_engine() 的关键字参数,包括由特定 dialect 或 driver 使用的自定义 connect() 参数。
- autocommit. 如果这是 False(默认值),连接将以手动提交(事务)模式运行。如果这是 True,连接将以自动提交(非事务)模式运行。
如果url作为连接参数存在,Streamlit会将其传递给sqlalchemy.engine.make_url()。否则,Streamlit至少需要dialect、username和host。Streamlit将使用dialect和driver(如果已定义)来推导drivername,然后将相关的连接参数传递给sqlalchemy.engine.URL.create()。
除了sqlalchemy.create_engine()的默认关键字参数外,您的方言可能还接受其他关键字参数。例如,如果您使用Snowflake SQLAlchemy的dialect="snowflake",您可以传递private_key的值以使用密钥对认证。如果您使用Google BigQuery的dialect="bigquery",您可以传递location的值。
SQLConnection 提供了 .query() 便捷方法,可以用于运行简单的只读查询,并具有缓存和简单的错误处理/重试功能。更复杂的数据库交互可以通过使用 .session 属性来获取一个常规的 SQLAlchemy 会话。
重要
必须安装SQLAlchemy在你的环境中才能使用此连接。你还必须安装你的驱动程序,例如pyodbc或psycopg2。
类描述[来源] | |
---|---|
st.connections.SQLConnection(connection_name, **kwargs) | |
方法 | |
connect() | 在底层的SQLAlchemy Engine上调用.connect(),返回一个新的连接对象。 |
query(sql, *, show_spinner="Running `sql.query(...)`.", ttl=None, index_col=None, chunksize=None, params=None, **kwargs) | 运行一个只读查询。 |
reset() | 重置此连接,以便下次使用时重新初始化。 |
属性 | |
底层SQLAlchemy引擎使用的驱动程序的名称。 | |
底层的 SQLAlchemy 引擎。 | |
返回一个SQLAlchemy会话。 |
示例
示例1:使用URL进行配置
您可以使用Streamlit的Secrets management来配置您的SQL连接。以下示例指定了一个SQL连接URL。
.streamlit/secrets.toml:
[connections.sql] url = "xxx+xxx://xxx:xxx@xxx:xxx/xxx"您的应用程序代码:
import streamlit as st conn = st.connection("sql") df = conn.query("SELECT * FROM pet_owners") st.dataframe(df)示例2:使用方言、主机和用户名的配置
如果不指定url,则必须至少指定dialect、host和username。以下示例还包括password。
.streamlit/secrets.toml:
[connections.sql] dialect = "xxx" host = "xxx" username = "xxx" password = "xxx"您的应用程序代码:
import streamlit as st conn = st.connection("sql") df = conn.query("SELECT * FROM pet_owners") st.dataframe(df)示例 3:使用关键字参数进行配置
您可以使用关键字参数(带或不带secrets.toml)配置您的SQL连接。例如,如果您将Microsoft Entra ID与Microsoft Azure SQL服务器一起使用,您可以使用交互式身份验证快速设置本地连接以进行开发。
此示例需要Microsoft ODBC Driver for SQL Server以及Python的sqlalchemy和pyodbc包。
import streamlit as st conn = st.connection( "sql", dialect="mssql", driver="pyodbc", host="xxx.database.windows.net", database="xxx", username="xxx", query={ "driver": "ODBC Driver 18 for SQL Server", "authentication": "ActiveDirectoryInteractive", "encrypt": "yes", }, ) df = conn.query("SELECT * FROM pet_owners") st.dataframe(df)
在底层的SQLAlchemy Engine上调用.connect(),返回一个新的连接对象。
调用此方法等同于调用self._instance.connect()。
注意:此方法不应与用于实现Streamlit连接的内部_connect方法混淆。
函数签名[source] | |
---|---|
SQLConnection.connect() | |
返回 | |
(sqlalchemy.engine.Connection) | 一个新的SQLAlchemy连接对象。 |
运行一个只读查询。
此方法实现了查询结果的缓存和简单的错误处理/重试。缓存行为与使用@st.cache_data时完全相同。
注意
未指定ttl的查询将无限期缓存。
传递给此函数的所有关键字参数都会传递给 pandas.read_sql,除了ttl。
函数签名[source] | |
---|---|
SQLConnection.query(sql, *, show_spinner="正在运行 `sql.query(...)`。", ttl=None, index_col=None, chunksize=None, params=None, **kwargs) | |
参数 | |
sql (str) | 要执行的只读SQL查询。 |
show_spinner (boolean or string) | 启用加载动画。默认情况下,当出现“缓存未命中”并且正在创建缓存资源时,会显示加载动画。如果是一个字符串,show_spinner 参数的值将用作加载动画的文本。 |
ttl (float, int, timedelta or None) | 缓存中保留结果的最大秒数,如果缓存结果不应过期,则为None。默认值为None。 |
index_col (str, list of str, or None) | 要设置为索引(MultiIndex)的列。默认值为None。 |
chunksize (int or None) | 如果指定,返回一个迭代器,其中chunksize是每个块中包含的行数。默认值为None。 |
params (list, tuple, dict or None) | 传递给execute方法的参数列表。传递参数的语法取决于数据库驱动程序。请查阅您的数据库驱动程序文档,了解支持的五种语法风格中的哪一种,这些风格在PEP 249 paramstyle中有描述。 默认值为None。 |
**kwargs (dict) | 额外的关键字参数传递给 pandas.read_sql。 |
返回 | |
(pandas.DataFrame) | 查询结果,格式化为pandas DataFrame。 |
示例
import streamlit as st conn = st.connection("sql") df = conn.query( "SELECT * FROM pet_owners WHERE owner = :owner", ttl=3600, params={"owner": "barbara"}, ) st.dataframe(df)
重置此连接,以便下次使用时重新初始化。
当连接变得陈旧、认证令牌过期或在类似情况下,重新初始化可能会修复断开的连接时,此方法可能很有用。请注意,某些连接方法可能已经在它们的错误处理代码中使用了reset()。
函数签名[source] | |
---|---|
SQLConnection.reset() | |
返回 | |
(None) | 无描述 |
示例
import streamlit as st conn = st.connection("my_conn") # Reset the connection before using it if it isn't healthy # Note: is_healthy() isn't a real method and is just shown for example here. if not conn.is_healthy(): conn.reset() # Do stuff with conn...
函数签名[source] | |
---|---|
SQLConnection.driver | |
返回 | |
(str) | 驱动程序的名称。例如,"pyodbc" 或 "psycopg2"。 |
函数签名[source] | |
---|---|
SQLConnection.engine | |
返回 | |
(sqlalchemy.engine.base.Engine) | 底层的SQLAlchemy引擎。 |
返回一个SQLAlchemy会话。
此连接的用户应使用上下文管理器模式进行写入、事务以及比简单读取查询更复杂的操作。
请参见下面的使用示例,假设我们有一个名为numbers的表,其中包含一个整数列val。SQLAlchemy文档中还包含了更多关于会话使用的信息。
函数签名[source] | |
---|---|
SQLConnection.session | |
返回 | |
(sqlalchemy.orm.Session) | 一个 SQLAlchemy 会话。 |
示例
import streamlit as st conn = st.connection("sql") n = st.slider("Pick a number") if st.button("Add the number!"): with conn.session as session: session.execute("INSERT INTO numbers (val) VALUES (:n);", {"n": n}) session.commit()
还有问题吗?
我们的 论坛 充满了有用的信息和Streamlit专家。