star

提示

本页面仅包含st.connections.SQLConnection类。要深入了解在Streamlit应用程序中创建和管理数据连接,请阅读连接到数据

使用SQLAlchemy引擎连接到SQL数据库。

使用 st.connection("sql")st.connection("", type="sql") 初始化此连接对象。SQLConnection 的连接参数可以使用 secrets.toml 和/或 **kwargs 指定。 可能的连接参数包括:

  • url 或关键字参数用于 sqlalchemy.engine.URL.create(),除了 drivername。使用 dialectdriver 代替 drivername
  • sqlalchemy.create_engine() 的关键字参数,包括由特定 dialectdriver 使用的自定义 connect() 参数。
  • autocommit. 如果这是 False(默认值),连接将以手动提交(事务)模式运行。如果这是 True,连接将以自动提交(非事务)模式运行。

如果url作为连接参数存在,Streamlit会将其传递给sqlalchemy.engine.make_url()。否则,Streamlit至少需要dialectusernamehost。Streamlit将使用dialectdriver(如果已定义)来推导drivername,然后将相关的连接参数传递给sqlalchemy.engine.URL.create()

除了sqlalchemy.create_engine()的默认关键字参数外,您的方言可能还接受其他关键字参数。例如,如果您使用Snowflake SQLAlchemydialect="snowflake",您可以传递private_key的值以使用密钥对认证。如果您使用Google BigQuerydialect="bigquery",您可以传递location的值。

SQLConnection 提供了 .query() 便捷方法,可以用于运行简单的只读查询,并具有缓存和简单的错误处理/重试功能。更复杂的数据库交互可以通过使用 .session 属性来获取一个常规的 SQLAlchemy 会话。

重要

必须安装SQLAlchemy在你的环境中才能使用此连接。你还必须安装你的驱动程序,例如pyodbcpsycopg2

类描述[来源]

st.connections.SQLConnection(connection_name, **kwargs)

方法

在底层的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,则必须至少指定dialecthostusername。以下示例还包括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的sqlalchemypyodbc包。

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...

底层SQLAlchemy引擎使用的驱动程序的名称。

这相当于访问 self._instance.driver

函数签名[source]

SQLConnection.driver

返回

(str)

驱动程序的名称。例如,"pyodbc""psycopg2"

底层的SQLAlchemy引擎。

这相当于访问 self._instance

函数签名[source]

SQLConnection.engine

返回

(sqlalchemy.engine.base.Engine)

底层的SQLAlchemy引擎。

返回一个SQLAlchemy会话。

此连接的用户应使用上下文管理器模式进行写入、事务以及比简单读取查询更复杂的操作。

请参见下面的使用示例,假设我们有一个名为numbers的表,其中包含一个整数列valSQLAlchemy文档中还包含了更多关于会话使用的信息。

函数签名[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()
forum

还有问题吗?

我们的 论坛 充满了有用的信息和Streamlit专家。