文章目录一、密钥分组SECRETS1. st.secrets密钥读取对象功能说明两种取值语法等效优先级规则代码示例2. secrets.toml密钥配置文件功能说明文件存放路径文件格式示例读取对应关系二、数据库连接分组CONNECTIONS1. st.connection通用数据库连接创建器1.1 核心功能1.2 函数入参说明1.3 返回值1.4 代码示例示例1自动推断类型最简写法示例2自定义连接名称显式指定类型示例3直接传入连接类静态类型友好示例4运行时覆盖密钥文件参数1.5 核心特性2. SnowflakeConnectionSnowflake 云数据仓库专用连接类2.1 类基础介绍2.1.1 类定位与继承关系2.1.2 实例化创建方式2.1.3 底层依赖与安装2.1.4 连接缓存机制2.1.5 账号格式强制要求2.2 连接配置四大来源优先级从高至低2.2.1 代码传入关键字参数最高优先级代码示例2.2.2 项目 secrets.toml 密钥文件生产推荐配置文件示例读取代码2.2.3 Snowflake 原生本地配置文件本地配置文件示例调用代码2.2.4 系统环境变量全局默认连接2.3 核心内置方法与属性2.3.1 .query()只读SQL查询方法2.3.1.1 核心参数2.3.1.2 代码示例2.3.2 .write_pandas()DataFrame批量写入数仓2.3.2.1 核心参数2.3.2.2 代码示例2.3.3 .session()创建Snowpark分布式计算会话代码示例2.3.4 .cursor()获取原生数据库游标对象代码示例2.3.5 .raw_connection底层原生连接只读属性代码示例2.3.6 .reset()重置连接实例方法代码示例2.4 六大典型使用场景2.5 核心特性总结3. SQLConnection通用SQL数据库连接基类3.1 类基础介绍3.1.1 类定位与继承关系3.1.2 实例化创建方式3.1.3 底层依赖安装3.1.4 连接缓存机制3.1.5 事务模式说明3.2 连接配置三种写法优先级代码传参 secrets.toml3.2.1 完整URL配置写法配置文件示例调用代码3.2.2 拆分字段配置写法配置文件示例3.2.3 代码运行时传入参数最高优先级Azure SQL交互式认证示例3.3 核心内置方法与属性3.3.1 .query()只读查询快捷方法3.3.1.1 核心参数3.3.1.2 代码示例带参数防注入3.3.2 .connect()获取原生SQLAlchemy连接3.3.3 .reset()重置数据库连接池3.3.4 三大只读属性3.3.4.1 .driver3.3.4.2 .engine3.3.4.3 .session事务写入示例3.4 核心特性总结4. BaseConnection所有数据源连接的抽象基础父类4.1 类基础介绍4.1.1 类定位与作用4.1.2 强制抽象方法 _connect()4.1.3 与 st.connection() 工厂函数的关联4.2 内置通用方法reset()4.2.1 方法功能4.2.2 适用业务场景4.2.3 代码示例4.3 版本兼容说明4.3.1 不存在的方法v1.40.04.4 类设计核心价值一、密钥分组SECRETS1.st.secrets密钥读取对象功能说明字典风格的只读密钥读取对象用来读取secrets.toml内存储的账号、密码、API密钥、数据库凭证等敏感信息避免硬编码密码到代码文件。两种取值语法等效importstreamlitasst# 下标取值api_keyst.secrets[OpenAI_key]db_userst.secrets[database][user]# 属性点取值api_keyst.secrets.OpenAI_key db_pwdst.secrets.database.password优先级规则同时存在全局密钥文件和项目本地密钥文件时同名键优先读取项目本地配置。代码示例importstreamlitasst# 读取API密钥openai_keyst.secrets.OpenAI_key# 读取数据库分组账号密码db_userst.secrets.database.user db_pwdst.secrets.database.password st.write(API密钥已加载)2.secrets.toml密钥配置文件功能说明TOML格式密钥配置文件存放项目所有敏感凭证分项目本地文件、全局用户文件两种存放位置。文件存放路径项目本地优先级更高项目根目录.streamlit/secrets.toml全局用户目录Mac/Linux~/.streamlit/secrets.tomlWindows%userprofile%\.streamlit\secrets.toml文件格式示例# 单层密钥 OpenAI_key sk-xxxxxxx whitelist [user1, user2] # 分组数据库密钥 [database] user root password 123456 host 127.0.0.1读取对应关系# 单层键st.secrets.OpenAI_key# 分组内键st.secrets.database.password二、数据库连接分组CONNECTIONS1.st.connection通用数据库连接创建器1.1 核心功能st.connection是 Streamlit 统一数据源连接工厂函数用于创建 SQL、Snowflake、自定义数据源连接。内部通过st.cache_resource缓存连接实例全应用多会话共享同一个连接减少重复创建连接的开销连接配置自动合并三处来源优先级从高到低函数传入**kwargssecrets.toml连接配置块 数据源专属配置文件返回BaseConnection的子类实例SQLConnection / SnowflakeConnection / 自定义连接。1.2 函数入参说明st.connection(name,typeNone,max_entriesNone,ttlNone,**kwargs)name (str)连接名称程序会读取secrets.toml里[connections.{name}]的配置块若名称为sql/snowflake/snowpark会自动推断连接类型无需手动传type。type (str | 连接类 | None)指定连接类型支持四种写法None根据name自动推断内置字符串sql/snowflakesnowpark已废弃类路径字符串streamlit.connections.SQLConnection直接导入连接类对象from streamlit.connections import SQLConnection。max_entries (int | None)连接缓存池最大存储数量None代表无上限缓存满时自动淘汰最久未使用的连接。ttl (float | timedelta | None)连接缓存有效期单位秒超时后下次调用会重新创建连接None永久缓存。kwargs覆盖密钥文件的临时连接参数会直接传入连接底层_connect()方法优先级最高。1.3 返回值BaseConnection的子类实例SQLConnection / SnowflakeConnection / 自定义连接可调用.query()、.reset()等连接专属方法。1.4 代码示例示例1自动推断类型最简写法secrets.toml 配置[connections.sql] dialect mysqlpymysql host 127.0.0.1 username root password 123456 database test_db业务代码importstreamlitasst# namesql 自动识别为SQLConnectionconnst.connection(sql)dfconn.query(SELECT * FROM user LIMIT 10)示例2自定义连接名称显式指定类型secrets.toml[connections.mysql_test] dialect mysqlpymysql host 127.0.0.1 username root password 123456 database test_db代码importstreamlitasst# 自定义名称无法自动推断手动指定typesqlconnst.connection(mysql_test,typesql)示例3直接传入连接类静态类型友好importstreamlitasstfromstreamlit.connectionsimportSQLConnection connst.connection(mysql_test,typeSQLConnection)示例4运行时覆盖密钥文件参数importstreamlitasst# 临时覆盖host与database优先级高于secrets.tomlconnst.connection(sql,host192.168.1.100,databaseonline_db)1.5 核心特性全局连接缓存同一个name多次调用只会创建一次连接跨浏览器标签页共享多配置源合并函数参数临时覆盖密钥配置适合本地开发与线上环境切换支持自定义数据源继承BaseConnection实现私有数据库/API连接通过type参数加载生命周期控制通过ttl设置连接过期调用conn.reset()手动重置失效连接。2. SnowflakeConnectionSnowflake 云数据仓库专用连接类2.1 类基础介绍2.1.1 类定位与继承关系SnowflakeConnection是 Streamlit 官方内置数据源连接类继承顶层抽象父类BaseConnection专门用于对接 Snowflake 云数据仓库。2.1.2 实例化创建方式统一通过工厂函数st.connection()创建实例connst.connection(连接名称,typesnowflake)2.1.3 底层依赖与安装底层封装官方snowflake-connector-python需要安装 Streamlit Snowflake 扩展包pipinstallstreamlit[snowflake]2.1.4 连接缓存机制内部使用st.cache_resource缓存连接实例全应用、多浏览器会话共享同一个连接避免频繁创建销毁连接节省资源开销。2.1.5 账号格式强制要求Snowflake 账号标识必须采用组织名-账号ID的横杠分隔格式不支持点分隔格式。2.2 连接配置四大来源优先级从高至低2.2.1 代码传入关键字参数最高优先级调用st.connection()时通过**kwargs直接传入认证、库信息会临时覆盖所有配置文件内参数适合本地调试、浏览器SSO免密登录场景。代码示例importstreamlitasst connst.connection(snowflake,accountorgdemo-abc123,userdev_user,authenticatorexternalbrowser)2.2.2 项目secrets.toml密钥文件生产推荐在项目目录.streamlit/secrets.toml中编写[connections.连接名]配置块统一存放账号、密钥等敏感信息杜绝代码硬编码密码。配置文件示例[connections.snowflake] account orgdemo-abc123 user admin private_key_file ./rsa_key.p8 warehouse COMPUTE_WH database DATA_DB schema PUBLIC读取代码# namesnowflake 自动匹配secrets中的配置块connst.connection(snowflake)2.2.3 Snowflake 原生本地配置文件本地文件路径~/.snowflake/connections.toml可预先维护多套 Snowflake 连接配置在 Streamlit 中直接引用配置名称。本地配置文件示例# ~/.snowflake/connections.toml [my_snow_conn] account orgdemo-abc123 user admin password xxxxxx warehouse COMPUTE_WH调用代码connst.connection(my_snow_conn,typesnowflake)2.2.4 系统环境变量全局默认连接设置环境变量SNOWFLAKE_DEFAULT_CONNECTION_NAME指定本地 Snowflake 配置文件内的默认连接名称调用时无需额外传参即可读取。2.3 核心内置方法与属性2.3.1.query()只读SQL查询方法执行SELECT等只读SQL语句内置查询缓存缓存逻辑等同于st.cache_data执行完成自动返回 Pandas DataFrame。2.3.1.1 核心参数sql待执行SQL语句ttl查询缓存有效期单位秒None代表永久缓存paramsSQL预编译参数用于防止SQL注入show_spinner布尔/字符串控制查询时的加载动画与提示文字。2.3.1.2 代码示例# 查询数据缓存结果1小时dfconn.query(SELECT * FROM SALES_DATA LIMIT 200,ttl3600)st.dataframe(df)2.3.2.write_pandas()DataFrame批量写入数仓将 Pandas DataFrame 批量写入 Snowflake 数据表内置自动分块上传逻辑适配大批量数据落地场景。2.3.2.1 核心参数df待入库的 Pandas DataFrametable_name目标数据表名称database/schema可选指定目标数据库与模式chunk_size自定义数据分块大小。2.3.2.2 代码示例importpandasaspd dfpd.DataFrame({NAME:[张三,李四],SALE:[1200,2500]})# 将DataFrame写入SALE_LOG数据表conn.write_pandas(df,SALE_LOG,databaseDATA_DB,schemaPUBLIC)2.3.3.session()创建Snowpark分布式计算会话生成 Snowpark Session 对象是官方替代已废弃SnowparkConnection的方案用于编写类Spark的DataFrame分布式计算代码完成复杂数据加工、ETL逻辑。代码示例# 获取Snowpark计算会话snow_sessionconn.session()# Snowpark语法过滤、加工数据表snow_dfsnow_session.table(SALES).filter(AMOUNT 1000).collect()2.3.4.cursor()获取原生数据库游标对象返回 Snowflake 原生 Cursor 游标实例支持INSERT / UPDATE / DELETE、批量插入、异步长查询等复杂DML数据操作。代码示例# 创建游标指定参数占位符格式curconn.cursor(paramstyleqmark)# 批量插入多条数据rows[(苹果,100),(香蕉,200)]cur.executemany(INSERT INTO FRUIT(NAME, PRICE) VALUES (?, ?),rows)2.3.5.raw_connection底层原生连接只读属性只读属性获取底层snowflake.connector.Connection原生连接实例用于调用官方连接器提供的各类高级底层接口。代码示例native_connconn.raw_connection2.3.6.reset()重置连接实例方法清空当前缓存的连接会话下一次调用该连接时会重新创建全新连接适用于登录令牌过期、会话异常、连接失效等场景。代码示例# 重置失效的连接conn.reset()2.4 六大典型使用场景读取项目secrets配置线上生产标准用法敏感信息统一托管代码传入SSO浏览器认证本地开发调试免密码一键登录读取本地Snowflake配置文件本地多套数仓环境统一管理secrets文件引用本地Snowflake连接配置线上环境兼容本地配置系统环境变量指定全局默认连接服务器统一默认数仓配置读取本地Snowflake配置文件内[default]默认连接极简本地开发2.5 核心特性总结全局单例连接缓存同一连接名称全局复用连接降低连接创建资源开销内置查询结果缓存.query()自带结果缓存重复查询无需重复访问数仓一站式数据读写能力同时支持原生SQL查询、DataFrame批量入库、Snowpark分布式计算全类型认证兼容支持账号密码、RSA密钥对、浏览器SSO、MFA多因素认证连接自愈机制.reset()一键重建失效连接适配长期运行的线上可视化应用四层灵活配置源支持代码临时传参、项目密钥文件、本地Snowflake配置、系统环境变量完美适配开发/测试/生产多环境切换。## 3.SQLConnection通用SQL数据库连接基类3. SQLConnection通用SQL数据库连接基类3.1 类基础介绍3.1.1 类定位与继承关系SQLConnection继承抽象父类BaseConnection是 Streamlit 内置的通用SQL数据库连接实现底层基于SQLAlchemy引擎兼容MySQL、PostgreSQL、SQL Server、BigQuery等绝大多数关系型数据库。3.1.2 实例化创建方式通过工厂函数st.connection()初始化两种写法# 名称为sql自动识别类型connst.connection(sql)# 自定义连接名显式指定typeconnst.connection(mysql_conn,typesql)3.1.3 底层依赖安装必须提前安装SQLAlchemy同时按需安装对应数据库驱动如pymysql、psycopg2、pyodbc# 基础依赖pipinstallsqlalchemy# 示例MySQL驱动pipinstallpymysql3.1.4 连接缓存机制依托st.cache_resource全局缓存Engine引擎实例多浏览器会话共享数据库连接池减少重复创建连接池的开销。3.1.5 事务模式说明默认autocommitFalse手动事务提交模式设置autocommitTrue则自动提交每条DML语句。3.2 连接配置三种写法优先级代码传参 secrets.toml3.2.1 完整URL配置写法在secrets.toml中直接填写SQLAlchemy标准连接URL无需拆分host、账号等字段。配置文件示例[connections.sql] url mysqlpymysql://root:123456127.0.0.1:3306/test_db调用代码importstreamlitasst connst.connection(sql)dfconn.query(SELECT * FROM pet_owners)3.2.2 拆分字段配置写法不填写完整url拆分dialect、host、username、password、database字段配置可读性更强。配置文件示例[connections.sql] dialect mysqlpymysql host 127.0.0.1 username root password 123456 database test_db3.2.3 代码运行时传入参数最高优先级调用st.connection时直接传入数据库参数临时覆盖secrets配置适合本地调试、特殊认证场景如Azure SQL交互式AD登录。Azure SQL交互式认证示例importstreamlitasst connst.connection(sql,dialectmssql,driverpyodbc,hostxxx.database.windows.net,databasedemo_db,usernameadmin,query{driver:ODBC Driver 18 for SQL Server,authentication:ActiveDirectoryInteractive,encrypt:yes,})3.3 核心内置方法与属性3.3.1 .query()只读查询快捷方法执行SELECT只读SQL内置查询缓存缓存逻辑等价st.cache_data自动返回Pandas DataFrame自带重试、异常捕获。3.3.1.1 核心参数sql待执行SQL语句ttl查询缓存有效期单位秒None永久缓存paramsSQL预编译参数防SQL注入show_spinner控制加载提示动画index_col/chunksize适配pandas读取的索引、分块参数。3.3.1.2 代码示例带参数防注入# 缓存1小时传入查询参数dfconn.query(SELECT * FROM pet_owners WHERE owner :owner,ttl3600,params{owner:barbara})st.dataframe(df)3.3.2 .connect()获取原生SQLAlchemy连接从底层Engine获取原生数据库连接对象用于底层原生SQL执行。native_connconn.connect()3.3.3 .reset()重置数据库连接池清空当前缓存的Engine连接池下次调用自动重建全新连接池用于令牌过期、连接池失效、数据库切换场景。conn.reset()3.3.4 三大只读属性3.3.4.1 .driver获取当前数据库使用的驱动名称如pymysql、pyodbcprint(conn.driver)3.3.4.2 .engine获取底层完整的SQLAlchemy Engine引擎实例可调用原生Engine接口engineconn.engine3.3.4.3 .session获取SQLAlchemy ORM会话对象用于事务、增删改、ORM复杂操作推荐使用with上下文管理事务。事务写入示例# 新增数据手动提交事务withconn.sessionassess:sess.execute(INSERT INTO numbers(val) VALUES(:n),{n:10})sess.commit()3.4 核心特性总结全数据库兼容基于SQLAlchemy支持MySQL、PostgreSQL、SQL Server、Oracle、BigQuery等几乎所有主流SQL数据库两种使用模式简单查询用.query()自带缓存复杂事务/ORM操作使用.session会话三层配置方案支持URL完整字符串、拆分字段、代码动态传参三种配置方式适配开发/生产环境内置查询缓存.query()自动缓存结果大幅降低重复查询的数据库压力标准化事务管理通过session上下文实现安全事务提交、回滚适配批量写入业务连接池全局复用Engine全局缓存复用连接池减少频繁创建销毁连接的性能损耗连接自愈重置.reset()一键重建连接池解决长时间运行应用的连接失效问题。4. BaseConnection所有数据源连接的抽象基础父类4.1 类基础介绍4.1.1 类定位与作用BaseConnection是 Streamlit 所有数据库/数据源连接的抽象父类规定了统一的连接开发规范内置通用连接能力。官方内置的SQLConnection、SnowflakeConnection都直接继承该类用户自定义私有数据库、API数据源连接也必须继承此类。4.1.2 强制抽象方法_connect()所有子类必须重写实现_connect()抽象方法该方法负责读取配置参数secrets、函数入参创建底层数据源原生连接/引擎实例返回封装后的连接对象。仅实现_connect()即可完成合法连接类的基础定义在此之上可拓展查询、写入等业务方法。4.1.3 与st.connection()工厂函数的关联st.connection()是统一创建连接的入口函数底层依赖BaseConnection的标准化规范自动缓存连接实例、合并多源配置参数。4.2 内置通用方法reset()4.2.1 方法功能重置当前缓存的连接实例下次调用连接相关方法时会自动重新执行子类的_connect()方法生成全新连接。4.2.2 适用业务场景连接会话过期、认证令牌失效长时运行应用连接池/底层连接失效切换数据库环境、刷新凭证捕获SQL异常后重建损坏连接。4.2.3 代码示例importstreamlitasst# 获取任意继承BaseConnection的连接connst.connection(my_conn,typesql)# 模拟检测连接异常执行重置ifnotconn.is_healthy():# is_healthy仅为示例伪方法conn.reset()# 重置后正常执行查询dfconn.query(SELECT * FROM table)4.3 版本兼容说明4.3.1 不存在的方法v1.40.0在当前主流版本 1.40.0 中以下两个接口尚未实现无法调用.close()关闭连接方法.scope()连接作用域管理方法。4.4 类设计核心价值统一开发标准统一内置、自定义连接的开发规范降低多数据源维护成本通用连接自愈能力所有子类自动继承reset()重置方法统一实现连接失效修复兼容工厂函数配合st.connection()实现全局缓存、多配置源自动合并拓展性极强仅需实现_connect()即可对接任意数据库、API、数仓等数据源。
Streamlit（二十一）- API 参考文档（十四）- 连接与密钥管理
发布时间：2026/6/1 16:16:15
文章目录一、密钥分组SECRETS1. st.secrets密钥读取对象功能说明两种取值语法等效优先级规则代码示例2. secrets.toml密钥配置文件功能说明文件存放路径文件格式示例读取对应关系二、数据库连接分组CONNECTIONS1. st.connection通用数据库连接创建器1.1 核心功能1.2 函数入参说明1.3 返回值1.4 代码示例示例1自动推断类型最简写法示例2自定义连接名称显式指定类型示例3直接传入连接类静态类型友好示例4运行时覆盖密钥文件参数1.5 核心特性2. SnowflakeConnectionSnowflake 云数据仓库专用连接类2.1 类基础介绍2.1.1 类定位与继承关系2.1.2 实例化创建方式2.1.3 底层依赖与安装2.1.4 连接缓存机制2.1.5 账号格式强制要求2.2 连接配置四大来源优先级从高至低2.2.1 代码传入关键字参数最高优先级代码示例2.2.2 项目 secrets.toml 密钥文件生产推荐配置文件示例读取代码2.2.3 Snowflake 原生本地配置文件本地配置文件示例调用代码2.2.4 系统环境变量全局默认连接2.3 核心内置方法与属性2.3.1 .query()只读SQL查询方法2.3.1.1 核心参数2.3.1.2 代码示例2.3.2 .write_pandas()DataFrame批量写入数仓2.3.2.1 核心参数2.3.2.2 代码示例2.3.3 .session()创建Snowpark分布式计算会话代码示例2.3.4 .cursor()获取原生数据库游标对象代码示例2.3.5 .raw_connection底层原生连接只读属性代码示例2.3.6 .reset()重置连接实例方法代码示例2.4 六大典型使用场景2.5 核心特性总结3. SQLConnection通用SQL数据库连接基类3.1 类基础介绍3.1.1 类定位与继承关系3.1.2 实例化创建方式3.1.3 底层依赖安装3.1.4 连接缓存机制3.1.5 事务模式说明3.2 连接配置三种写法优先级代码传参 secrets.toml3.2.1 完整URL配置写法配置文件示例调用代码3.2.2 拆分字段配置写法配置文件示例3.2.3 代码运行时传入参数最高优先级Azure SQL交互式认证示例3.3 核心内置方法与属性3.3.1 .query()只读查询快捷方法3.3.1.1 核心参数3.3.1.2 代码示例带参数防注入3.3.2 .connect()获取原生SQLAlchemy连接3.3.3 .reset()重置数据库连接池3.3.4 三大只读属性3.3.4.1 .driver3.3.4.2 .engine3.3.4.3 .session事务写入示例3.4 核心特性总结4. BaseConnection所有数据源连接的抽象基础父类4.1 类基础介绍4.1.1 类定位与作用4.1.2 强制抽象方法 _connect()4.1.3 与 st.connection() 工厂函数的关联4.2 内置通用方法reset()4.2.1 方法功能4.2.2 适用业务场景4.2.3 代码示例4.3 版本兼容说明4.3.1 不存在的方法v1.40.04.4 类设计核心价值一、密钥分组SECRETS1.st.secrets密钥读取对象功能说明字典风格的只读密钥读取对象用来读取secrets.toml内存储的账号、密码、API密钥、数据库凭证等敏感信息避免硬编码密码到代码文件。两种取值语法等效importstreamlitasst# 下标取值api_keyst.secrets[OpenAI_key]db_userst.secrets[database][user]# 属性点取值api_keyst.secrets.OpenAI_key db_pwdst.secrets.database.password优先级规则同时存在全局密钥文件和项目本地密钥文件时同名键优先读取项目本地配置。代码示例importstreamlitasst# 读取API密钥openai_keyst.secrets.OpenAI_key# 读取数据库分组账号密码db_userst.secrets.database.user db_pwdst.secrets.database.password st.write(API密钥已加载)2.secrets.toml密钥配置文件功能说明TOML格式密钥配置文件存放项目所有敏感凭证分项目本地文件、全局用户文件两种存放位置。文件存放路径项目本地优先级更高项目根目录.streamlit/secrets.toml全局用户目录Mac/Linux~/.streamlit/secrets.tomlWindows%userprofile%\.streamlit\secrets.toml文件格式示例# 单层密钥 OpenAI_key sk-xxxxxxx whitelist [user1, user2] # 分组数据库密钥 [database] user root password 123456 host 127.0.0.1读取对应关系# 单层键st.secrets.OpenAI_key# 分组内键st.secrets.database.password二、数据库连接分组CONNECTIONS1.st.connection通用数据库连接创建器1.1 核心功能st.connection是 Streamlit 统一数据源连接工厂函数用于创建 SQL、Snowflake、自定义数据源连接。内部通过st.cache_resource缓存连接实例全应用多会话共享同一个连接减少重复创建连接的开销连接配置自动合并三处来源优先级从高到低函数传入**kwargssecrets.toml连接配置块 数据源专属配置文件返回BaseConnection的子类实例SQLConnection / SnowflakeConnection / 自定义连接。1.2 函数入参说明st.connection(name,typeNone,max_entriesNone,ttlNone,**kwargs)name (str)连接名称程序会读取secrets.toml里[connections.{name}]的配置块若名称为sql/snowflake/snowpark会自动推断连接类型无需手动传type。type (str | 连接类 | None)指定连接类型支持四种写法None根据name自动推断内置字符串sql/snowflakesnowpark已废弃类路径字符串streamlit.connections.SQLConnection直接导入连接类对象from streamlit.connections import SQLConnection。max_entries (int | None)连接缓存池最大存储数量None代表无上限缓存满时自动淘汰最久未使用的连接。ttl (float | timedelta | None)连接缓存有效期单位秒超时后下次调用会重新创建连接None永久缓存。kwargs覆盖密钥文件的临时连接参数会直接传入连接底层_connect()方法优先级最高。1.3 返回值BaseConnection的子类实例SQLConnection / SnowflakeConnection / 自定义连接可调用.query()、.reset()等连接专属方法。1.4 代码示例示例1自动推断类型最简写法secrets.toml 配置[connections.sql] dialect mysqlpymysql host 127.0.0.1 username root password 123456 database test_db业务代码importstreamlitasst# namesql 自动识别为SQLConnectionconnst.connection(sql)dfconn.query(SELECT * FROM user LIMIT 10)示例2自定义连接名称显式指定类型secrets.toml[connections.mysql_test] dialect mysqlpymysql host 127.0.0.1 username root password 123456 database test_db代码importstreamlitasst# 自定义名称无法自动推断手动指定typesqlconnst.connection(mysql_test,typesql)示例3直接传入连接类静态类型友好importstreamlitasstfromstreamlit.connectionsimportSQLConnection connst.connection(mysql_test,typeSQLConnection)示例4运行时覆盖密钥文件参数importstreamlitasst# 临时覆盖host与database优先级高于secrets.tomlconnst.connection(sql,host192.168.1.100,databaseonline_db)1.5 核心特性全局连接缓存同一个name多次调用只会创建一次连接跨浏览器标签页共享多配置源合并函数参数临时覆盖密钥配置适合本地开发与线上环境切换支持自定义数据源继承BaseConnection实现私有数据库/API连接通过type参数加载生命周期控制通过ttl设置连接过期调用conn.reset()手动重置失效连接。2. SnowflakeConnectionSnowflake 云数据仓库专用连接类2.1 类基础介绍2.1.1 类定位与继承关系SnowflakeConnection是 Streamlit 官方内置数据源连接类继承顶层抽象父类BaseConnection专门用于对接 Snowflake 云数据仓库。2.1.2 实例化创建方式统一通过工厂函数st.connection()创建实例connst.connection(连接名称,typesnowflake)2.1.3 底层依赖与安装底层封装官方snowflake-connector-python需要安装 Streamlit Snowflake 扩展包pipinstallstreamlit[snowflake]2.1.4 连接缓存机制内部使用st.cache_resource缓存连接实例全应用、多浏览器会话共享同一个连接避免频繁创建销毁连接节省资源开销。2.1.5 账号格式强制要求Snowflake 账号标识必须采用组织名-账号ID的横杠分隔格式不支持点分隔格式。2.2 连接配置四大来源优先级从高至低2.2.1 代码传入关键字参数最高优先级调用st.connection()时通过**kwargs直接传入认证、库信息会临时覆盖所有配置文件内参数适合本地调试、浏览器SSO免密登录场景。代码示例importstreamlitasst connst.connection(snowflake,accountorgdemo-abc123,userdev_user,authenticatorexternalbrowser)2.2.2 项目secrets.toml密钥文件生产推荐在项目目录.streamlit/secrets.toml中编写[connections.连接名]配置块统一存放账号、密钥等敏感信息杜绝代码硬编码密码。配置文件示例[connections.snowflake] account orgdemo-abc123 user admin private_key_file ./rsa_key.p8 warehouse COMPUTE_WH database DATA_DB schema PUBLIC读取代码# namesnowflake 自动匹配secrets中的配置块connst.connection(snowflake)2.2.3 Snowflake 原生本地配置文件本地文件路径~/.snowflake/connections.toml可预先维护多套 Snowflake 连接配置在 Streamlit 中直接引用配置名称。本地配置文件示例# ~/.snowflake/connections.toml [my_snow_conn] account orgdemo-abc123 user admin password xxxxxx warehouse COMPUTE_WH调用代码connst.connection(my_snow_conn,typesnowflake)2.2.4 系统环境变量全局默认连接设置环境变量SNOWFLAKE_DEFAULT_CONNECTION_NAME指定本地 Snowflake 配置文件内的默认连接名称调用时无需额外传参即可读取。2.3 核心内置方法与属性2.3.1.query()只读SQL查询方法执行SELECT等只读SQL语句内置查询缓存缓存逻辑等同于st.cache_data执行完成自动返回 Pandas DataFrame。2.3.1.1 核心参数sql待执行SQL语句ttl查询缓存有效期单位秒None代表永久缓存paramsSQL预编译参数用于防止SQL注入show_spinner布尔/字符串控制查询时的加载动画与提示文字。2.3.1.2 代码示例# 查询数据缓存结果1小时dfconn.query(SELECT * FROM SALES_DATA LIMIT 200,ttl3600)st.dataframe(df)2.3.2.write_pandas()DataFrame批量写入数仓将 Pandas DataFrame 批量写入 Snowflake 数据表内置自动分块上传逻辑适配大批量数据落地场景。2.3.2.1 核心参数df待入库的 Pandas DataFrametable_name目标数据表名称database/schema可选指定目标数据库与模式chunk_size自定义数据分块大小。2.3.2.2 代码示例importpandasaspd dfpd.DataFrame({NAME:[张三,李四],SALE:[1200,2500]})# 将DataFrame写入SALE_LOG数据表conn.write_pandas(df,SALE_LOG,databaseDATA_DB,schemaPUBLIC)2.3.3.session()创建Snowpark分布式计算会话生成 Snowpark Session 对象是官方替代已废弃SnowparkConnection的方案用于编写类Spark的DataFrame分布式计算代码完成复杂数据加工、ETL逻辑。代码示例# 获取Snowpark计算会话snow_sessionconn.session()# Snowpark语法过滤、加工数据表snow_dfsnow_session.table(SALES).filter(AMOUNT 1000).collect()2.3.4.cursor()获取原生数据库游标对象返回 Snowflake 原生 Cursor 游标实例支持INSERT / UPDATE / DELETE、批量插入、异步长查询等复杂DML数据操作。代码示例# 创建游标指定参数占位符格式curconn.cursor(paramstyleqmark)# 批量插入多条数据rows[(苹果,100),(香蕉,200)]cur.executemany(INSERT INTO FRUIT(NAME, PRICE) VALUES (?, ?),rows)2.3.5.raw_connection底层原生连接只读属性只读属性获取底层snowflake.connector.Connection原生连接实例用于调用官方连接器提供的各类高级底层接口。代码示例native_connconn.raw_connection2.3.6.reset()重置连接实例方法清空当前缓存的连接会话下一次调用该连接时会重新创建全新连接适用于登录令牌过期、会话异常、连接失效等场景。代码示例# 重置失效的连接conn.reset()2.4 六大典型使用场景读取项目secrets配置线上生产标准用法敏感信息统一托管代码传入SSO浏览器认证本地开发调试免密码一键登录读取本地Snowflake配置文件本地多套数仓环境统一管理secrets文件引用本地Snowflake连接配置线上环境兼容本地配置系统环境变量指定全局默认连接服务器统一默认数仓配置读取本地Snowflake配置文件内[default]默认连接极简本地开发2.5 核心特性总结全局单例连接缓存同一连接名称全局复用连接降低连接创建资源开销内置查询结果缓存.query()自带结果缓存重复查询无需重复访问数仓一站式数据读写能力同时支持原生SQL查询、DataFrame批量入库、Snowpark分布式计算全类型认证兼容支持账号密码、RSA密钥对、浏览器SSO、MFA多因素认证连接自愈机制.reset()一键重建失效连接适配长期运行的线上可视化应用四层灵活配置源支持代码临时传参、项目密钥文件、本地Snowflake配置、系统环境变量完美适配开发/测试/生产多环境切换。## 3.SQLConnection通用SQL数据库连接基类3. SQLConnection通用SQL数据库连接基类3.1 类基础介绍3.1.1 类定位与继承关系SQLConnection继承抽象父类BaseConnection是 Streamlit 内置的通用SQL数据库连接实现底层基于SQLAlchemy引擎兼容MySQL、PostgreSQL、SQL Server、BigQuery等绝大多数关系型数据库。3.1.2 实例化创建方式通过工厂函数st.connection()初始化两种写法# 名称为sql自动识别类型connst.connection(sql)# 自定义连接名显式指定typeconnst.connection(mysql_conn,typesql)3.1.3 底层依赖安装必须提前安装SQLAlchemy同时按需安装对应数据库驱动如pymysql、psycopg2、pyodbc# 基础依赖pipinstallsqlalchemy# 示例MySQL驱动pipinstallpymysql3.1.4 连接缓存机制依托st.cache_resource全局缓存Engine引擎实例多浏览器会话共享数据库连接池减少重复创建连接池的开销。3.1.5 事务模式说明默认autocommitFalse手动事务提交模式设置autocommitTrue则自动提交每条DML语句。3.2 连接配置三种写法优先级代码传参 secrets.toml3.2.1 完整URL配置写法在secrets.toml中直接填写SQLAlchemy标准连接URL无需拆分host、账号等字段。配置文件示例[connections.sql] url mysqlpymysql://root:123456127.0.0.1:3306/test_db调用代码importstreamlitasst connst.connection(sql)dfconn.query(SELECT * FROM pet_owners)3.2.2 拆分字段配置写法不填写完整url拆分dialect、host、username、password、database字段配置可读性更强。配置文件示例[connections.sql] dialect mysqlpymysql host 127.0.0.1 username root password 123456 database test_db3.2.3 代码运行时传入参数最高优先级调用st.connection时直接传入数据库参数临时覆盖secrets配置适合本地调试、特殊认证场景如Azure SQL交互式AD登录。Azure SQL交互式认证示例importstreamlitasst connst.connection(sql,dialectmssql,driverpyodbc,hostxxx.database.windows.net,databasedemo_db,usernameadmin,query{driver:ODBC Driver 18 for SQL Server,authentication:ActiveDirectoryInteractive,encrypt:yes,})3.3 核心内置方法与属性3.3.1 .query()只读查询快捷方法执行SELECT只读SQL内置查询缓存缓存逻辑等价st.cache_data自动返回Pandas DataFrame自带重试、异常捕获。3.3.1.1 核心参数sql待执行SQL语句ttl查询缓存有效期单位秒None永久缓存paramsSQL预编译参数防SQL注入show_spinner控制加载提示动画index_col/chunksize适配pandas读取的索引、分块参数。3.3.1.2 代码示例带参数防注入# 缓存1小时传入查询参数dfconn.query(SELECT * FROM pet_owners WHERE owner :owner,ttl3600,params{owner:barbara})st.dataframe(df)3.3.2 .connect()获取原生SQLAlchemy连接从底层Engine获取原生数据库连接对象用于底层原生SQL执行。native_connconn.connect()3.3.3 .reset()重置数据库连接池清空当前缓存的Engine连接池下次调用自动重建全新连接池用于令牌过期、连接池失效、数据库切换场景。conn.reset()3.3.4 三大只读属性3.3.4.1 .driver获取当前数据库使用的驱动名称如pymysql、pyodbcprint(conn.driver)3.3.4.2 .engine获取底层完整的SQLAlchemy Engine引擎实例可调用原生Engine接口engineconn.engine3.3.4.3 .session获取SQLAlchemy ORM会话对象用于事务、增删改、ORM复杂操作推荐使用with上下文管理事务。事务写入示例# 新增数据手动提交事务withconn.sessionassess:sess.execute(INSERT INTO numbers(val) VALUES(:n),{n:10})sess.commit()3.4 核心特性总结全数据库兼容基于SQLAlchemy支持MySQL、PostgreSQL、SQL Server、Oracle、BigQuery等几乎所有主流SQL数据库两种使用模式简单查询用.query()自带缓存复杂事务/ORM操作使用.session会话三层配置方案支持URL完整字符串、拆分字段、代码动态传参三种配置方式适配开发/生产环境内置查询缓存.query()自动缓存结果大幅降低重复查询的数据库压力标准化事务管理通过session上下文实现安全事务提交、回滚适配批量写入业务连接池全局复用Engine全局缓存复用连接池减少频繁创建销毁连接的性能损耗连接自愈重置.reset()一键重建连接池解决长时间运行应用的连接失效问题。4. BaseConnection所有数据源连接的抽象基础父类4.1 类基础介绍4.1.1 类定位与作用BaseConnection是 Streamlit 所有数据库/数据源连接的抽象父类规定了统一的连接开发规范内置通用连接能力。官方内置的SQLConnection、SnowflakeConnection都直接继承该类用户自定义私有数据库、API数据源连接也必须继承此类。4.1.2 强制抽象方法_connect()所有子类必须重写实现_connect()抽象方法该方法负责读取配置参数secrets、函数入参创建底层数据源原生连接/引擎实例返回封装后的连接对象。仅实现_connect()即可完成合法连接类的基础定义在此之上可拓展查询、写入等业务方法。4.1.3 与st.connection()工厂函数的关联st.connection()是统一创建连接的入口函数底层依赖BaseConnection的标准化规范自动缓存连接实例、合并多源配置参数。4.2 内置通用方法reset()4.2.1 方法功能重置当前缓存的连接实例下次调用连接相关方法时会自动重新执行子类的_connect()方法生成全新连接。4.2.2 适用业务场景连接会话过期、认证令牌失效长时运行应用连接池/底层连接失效切换数据库环境、刷新凭证捕获SQL异常后重建损坏连接。4.2.3 代码示例importstreamlitasst# 获取任意继承BaseConnection的连接connst.connection(my_conn,typesql)# 模拟检测连接异常执行重置ifnotconn.is_healthy():# is_healthy仅为示例伪方法conn.reset()# 重置后正常执行查询dfconn.query(SELECT * FROM table)4.3 版本兼容说明4.3.1 不存在的方法v1.40.0在当前主流版本 1.40.0 中以下两个接口尚未实现无法调用.close()关闭连接方法.scope()连接作用域管理方法。4.4 类设计核心价值统一开发标准统一内置、自定义连接的开发规范降低多数据源维护成本通用连接自愈能力所有子类自动继承reset()重置方法统一实现连接失效修复兼容工厂函数配合st.connection()实现全局缓存、多配置源自动合并拓展性极强仅需实现_connect()即可对接任意数据库、API、数仓等数据源。
相关文章
从Arduino到3D打印：手把手教你制作可编程RGB智能灯
1. 项目概述：从创意到实物的智能灯制作之旅几年前，当我第一次接触Arduino和3D打印时，就被这种“数字到物理”的创造力深深吸引。一个想法，可以通过代码赋予逻辑，再通过建模软件塑造成型，最终成为手中一个会…
三步完成QQ空间完整备份：永久保存你的数字青春记忆
三步完成QQ空间完整备份：永久保存你的数字青春记忆 【免费下载链接】GetQzonehistory 获取QQ空间发布的历史说说 项目地址: https://gitcode.com/GitHub_Trending/ge/GetQzonehistory 你是否曾想找回那些年发过的QQ空间说说，那些承载着青春记忆的…
ComfyUI IPAdapter plus 完整安装配置指南：5分钟解决模型加载问题
ComfyUI IPAdapter plus 完整安装配置指南：5分钟解决模型加载问题 【免费下载链接】ComfyUI_IPAdapter_plus 项目地址: https://gitcode.com/gh_mirrors/co/ComfyUI_IPAdapter_plus 想在ComfyUI中体验强大的图像风格迁移功能，却总是被"模型…
别再为CKKS自举精度发愁了：OpenFHE里这个Meta-BTS迭代技巧，实测精度翻倍
突破CKKS自举精度瓶颈：OpenFHE中Meta-BTS的工程实践指南在同态加密的实际应用中，CKKS方案因其对浮点数的原生支持而备受青睐。然而，自举过程中的精度损失一直是困扰开发者的核心难题。传统解决方案往往需要大幅提升安全参数（如将环…
别再死记硬背了！用eNSP模拟器亲手抓包，5分钟搞懂IP网络通信全过程
用eNSP实战解析IP网络通信：从抓包看协议交互本质当我在第一次接触计算机网络课程时，那些抽象的协议栈和报文格式让我头疼不已。直到导师让我在模拟器中实际搭建网络并抓包观察，那些枯燥的概念突然变得鲜活起来。这就是我想分享的可视化学习方…
数据可视化进阶：手把手教你调优小提琴图的KDE带宽，告别失真与误导
数据可视化进阶：手把手教你调优小提琴图的KDE带宽，告别失真与误导第一次用Python绘制小提琴图时，我盯着屏幕上那些诡异的"负值区域"愣住了——明明销售数据全是正数，图表底部却莫名其妙出现了延伸至负轴的曲线。这种视觉…
动态算子序列内存优化技术解析与Chameleon系统设计
1. 动态算子序列内存优化技术解析在大型语言模型（LLM）训练过程中，内存管理始终是制约模型规模扩展的关键瓶颈。传统的内存优化技术如交换（swap）通常基于静态算子序列的假设，但在PyTorch等动态图框架&#x…
QQ群数据自动化采集：3步实现批量社群信息获取
QQ群数据自动化采集：3步实现批量社群信息获取 【免费下载链接】QQ-Groups-Spider QQ Groups Spider（QQ 群爬虫） 项目地址: https://gitcode.com/gh_mirrors/qq/QQ-Groups-Spider 还在为手动收集QQ群信息而效率低下烦恼吗？Q…
保姆级教程：用YOLOv8和WIDER Face数据集，从零训练一个高精度人脸检测模型
从零构建高精度人脸检测模型：YOLOv8与WIDER Face实战指南 人脸检测作为计算机视觉的基础任务，在安防监控、智能门锁、移动支付等领域有着广泛应用。本文将手把手教你如何利用YOLOv8这一前沿目标检测框架，结合WIDER Face这一权威人脸数据集&a…
从 Prompt 到生产闭环：Spring AI Tool Calling 深度拆解与企业级落地
从 Prompt 到生产闭环：Spring AI Tool Calling 深度拆解与企业级落地 摘要 Tool Calling 是大模型系统从“会回答”走向“会执行”的关键能力。很多文章只停留在 @Tool 注解和 Hello World 级别示例，但一旦进入生产环境，问题很快从“怎么调用”升级为“怎么控延迟、怎么控风…
解耦安防碎片化：基于 Docker 与边缘计算的 AI 视频中台架构设计（支持 GB28181/RTSP 与源码交付）
在智能视频分析（IVA）与产业物联网（IoT）大行其道的今天，政企级安防项目的落地依然面临着严重的碎片化挑战。对于系统集成商和独立软件开发商（ISV）而言，传统的流媒体研发存在两大核心痛…
解耦品牌壁垒：基于 Docker 与边缘计算的高并发视频中台架构（支持 GB28181/RTSP 统一接入与源码交付）
在泛安防与产业物联网（IoT）工程落地中，系统集成商与技术团队往往深陷于底层流媒体对接的碎片化泥潭。一方面，前端摄像机、IPC、NVR 品牌林立（如海康、大华、宇视等），其 GB28181 国标协议的信令交…
Win10/Win11下Realtek 8188GU网卡驱动感叹号？别急着扔，试试这个手动安装的野路子
Realtek 8188GU网卡驱动故障深度修复指南：从原理到实战当设备管理器里那个顽固的黄色感叹号挥之不去，而你已经尝试了所有"标准操作"——Windows自动更新、第三方驱动工具、甚至重启大法——却依然无济于事时，是时候换个思路了。这篇…
AnolisOS 8.8安装源配置踩坑实录：从‘设置基础软件仓库时出错’到成功联网的保姆级指南
AnolisOS 8.8安装源配置实战指南：从诊断到解决方案的全流程解析当你在安装AnolisOS 8.8时遇到"设置基础软件仓库时出错"的提示，这通常意味着系统无法访问或识别安装源。这个问题看似简单，但背后可能涉及网络配置、镜像选择、启动参…
基于树莓派Pico的反应速度测试游戏：从GPIO编程到状态机实战
1. 项目概述与核心思路最近在整理工作室的电子元件，翻出来几个闲置的街机按钮和一块树莓派Pico，灵机一动，决定做个简单又有趣的反应速度测试游戏。这个项目非常适合想入门嵌入式开发的朋友，它不涉及复杂的传感器和通信协议&#x…
Zotero Duplicates Merger：5步彻底清理文献库重复条目
Zotero Duplicates Merger：5步彻底清理文献库重复条目 【免费下载链接】ZoteroDuplicatesMerger A zotero plugin to automatically merge duplicate items 项目地址: https://gitcode.com/gh_mirrors/zo/ZoteroDuplicatesMerger 还在为文献库中堆积如山的重…
利用随机有限集理论对蜂群的ILQR和MPC控制研究附Matlab代码
✅作者简介：热爱科研的Matlab仿真开发者，擅长数据处理、建模仿真、程序设计、完整代码获取、论文复现及科研仿真。🍎 往期回顾关注个人主页：Matlab科研工作室🍊个人信条：格物致知,完整Matlab代码及仿真咨询…
为什么你的Gemini邮件CTE低于行业均值2.8倍？：从Prompt架构到发送时序的深度归因
更多请点击： https://intelliparadigm.com 第一章：为什么你的Gemini邮件CTE低于行业均值2.8倍？：从Prompt架构到发送时序的深度归因 Gemini邮件的客户转化效率（CTE）显著偏低，根本原因常被误判为…