streamlit-nightly 1.39.1.dev20241029__py2.py3-none-any.whl → 1.39.1.dev20241030__py2.py3-none-any.whl

streamlit/connections/base_connection.py

@@ -154,6 +154,10 @@ class BaseConnection(ABC, Generic[RawConnectionT]):
         reinitializing it. Note that some connection methods may already use ``reset()``
         in their error handling code.
 
+        Returns
+        -------
+        None
+
         Example
         -------
         >>> import streamlit as st

streamlit/connections/snowflake_connection.py

@@ -40,14 +40,159 @@ if TYPE_CHECKING:
 
 
 class SnowflakeConnection(BaseConnection["InternalSnowflakeConnection"]):
-    """A connection to Snowflake using the Snowflake Python Connector. Initialize using
-    ``st.connection("<name>", type="snowflake")``.
-
-    SnowflakeConnection supports direct SQL querying using ``.query("...")``, access to
-    the underlying Snowflake Python Connector object with ``.raw_connection``, and other
-    convenience functions. See the methods below for more information.
-    SnowflakeConnections should always be created using ``st.connection()``, **not**
-    initialized directly.
+    """A connection to Snowflake using the Snowflake Connector for Python.
+
+    Initialize this connection object using ``st.connection("snowflake")`` or
+    ``st.connection("<name>", type="snowflake")``. Connection parameters for a
+    SnowflakeConnection can be specified using ``secrets.toml`` and/or
+    ``**kwargs``. Connection parameters are passed to
+    |snowflake.connector.connect()|.
+
+    When an app is running in Streamlit in Snowflake,
+    ``st.connection("snowflake")`` connects automatically using the app owner's
+    role without further configuration. ``**kwargs`` will be ignored in this
+    case. Use ``secrets.toml`` and ``**kwargs`` to configure your connection
+    for local development.
+
+    SnowflakeConnection includes several convenience methods. For example, you
+    can directly execute a SQL query with ``.query()`` or access the underlying
+    Snowflake Connector object with ``.raw_connection``.
+
+    .. |snowflake.connector.connect()| replace:: ``snowflake.connector.connect()``
+    .. _snowflake.connector.connect(): https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-api#label-snowflake-connector-methods-connect
+
+    .. Tip::
+        `snowflake-snowpark-python <https://pypi.org/project/snowflake-snowpark-python/>`_
+        must be installed in your environment to use this connection. You can
+        install Snowflake extras along with Streamlit:
+
+        >>> pip install streamlit[snowflake]
+
+    .. Important::
+        Account identifiers must be of the form ``<orgname>-<account_name>``
+        where ``<orgname>`` is the name of your Snowflake organization and
+        ``<account_name>`` is the unique name of your account within your
+        organization. This is dash-separated, not dot-separated like when used
+        in SQL queries. For more information, see `Account identifiers
+        <https://docs.snowflake.com/en/user-guide/admin-account-identifier>`_.
+
+    Examples
+    --------
+
+    **Example 1: Configuration with Streamlit secrets**
+
+    You can configure your Snowflake connection using Streamlit's
+    `Secrets management <https://docs.streamlit.io/develop/concepts/connections/secrets-management>`_.
+    For example, if you have MFA enabled on your account, you can connect using
+    `key-pair authentication <https://docs.snowflake.com/en/user-guide/key-pair-auth>`_.
+
+    ``.streamlit/secrets.toml``:
+
+    >>> [connections.snowflake]
+    >>> account = "xxx-xxx"
+    >>> user = "xxx"
+    >>> private_key_file = "/xxx/xxx/xxx.p8"
+    >>> role = "xxx"
+    >>> warehouse = "xxx"
+    >>> database = "xxx"
+    >>> schema = "xxx"
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>> conn = st.connection("snowflake")
+    >>> df = conn.query("SELECT * FROM my_table")
+
+    **Example 2: Configuration with keyword arguments and external authentication**
+
+    You can configure your Snowflake connection with keyword arguments (with or
+    without ``secrets.toml``). For example, if your Snowflake account supports
+    SSO, you can set up a quick local connection for development using `browser-based SSO
+    <https://docs.snowflake.com/en/user-guide/admin-security-fed-auth-use#how-browser-based-sso-works>`_.
+
+    >>> import streamlit as st
+    >>> conn = st.connection(
+    ...     "snowflake", account="xxx-xxx", user="xxx", authenticator="externalbrowser"
+    ... )
+    >>> df = conn.query("SELECT * FROM my_table")
+
+    **Example 3: Named connection with Snowflake's connection configuration file**
+
+    Snowflake's Python Connector supports a `connection configuration file
+    <https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-connect#connecting-using-the-connections-toml-file>`_,
+    which is well integrated with Streamlit's ``SnowflakeConnection``. If you
+    already have one or more connections configured, all you need to do is pass
+    the name of the connection to use.
+
+    ``~/.snowflake/connections.toml``:
+
+    >>> [my_connection]
+    >>> account = "xxx-xxx"
+    >>> user = "xxx"
+    >>> password = "xxx"
+    >>> warehouse = "xxx"
+    >>> database = "xxx"
+    >>> schema = "xxx"
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>> conn = st.connection("my_connection", type="snowflake")
+    >>> df = conn.query("SELECT * FROM my_table")
+
+    **Example 4: Named connection with Streamlit secrets and Snowflake's connection configuration file**
+
+    If you have a Snowflake configuration file with a connection named
+    ``my_connection`` as in Example 3, you can pass the connection name through
+    ``secrets.toml``.
+
+    ``.streamlit/secrets.toml``:
+
+    >>> [connections.snowflake]
+    >>> connection_name = "my_connection"
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>> conn = st.connection("snowflake")
+    >>> df = conn.query("SELECT * FROM my_table")
+
+    **Example 5: Default connection with an environment variable**
+
+    If you have a Snowflake configuration file with a connection named
+    ``my_connection`` as in Example 3, you can set an environment variable to
+    declare it as the default Snowflake connection.
+
+    >>> SNOWFLAKE_DEFAULT_CONNECTION_NAME = "my_connection"
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>> conn = st.connection("snowflake")
+    >>> df = conn.query("SELECT * FROM my_table")
+
+    **Example 6: Default connection in Snowflake's connection configuration file**
+
+    If you have a Snowflake configuration file that defines your ``default``
+    connection, Streamlit will automatically use it if no other connection is
+    declared.
+
+    ``~/.snowflake/connections.toml``:
+
+    >>> [default]
+    >>> account = "xxx-xxx"
+    >>> user = "xxx"
+    >>> password = "xxx"
+    >>> warehouse = "xxx"
+    >>> database = "xxx"
+    >>> schema = "xxx"
+
+    Your app code:
+
+    >>> import streamlit as st
+    >>> conn = st.connection("snowflake")
+    >>> df = conn.query("SELECT * FROM my_table")
+
     """
 
     def _connect(self, **kwargs) -> InternalSnowflakeConnection:
@@ -129,29 +274,37 @@ class SnowflakeConnection(BaseConnection["InternalSnowflakeConnection"]):
     ) -> DataFrame:
         """Run a read-only SQL query.
 
-        This method implements both query result caching (with caching behavior
-        identical to that of using ``@st.cache_data``) as well as simple error handling/retries.
+        This method implements query result caching and simple error
+        handling/retries. The caching behavior is identical to that of using
+        ``@st.cache_data``.
 
         .. note::
-            Queries that are run without a specified ttl are cached indefinitely.
+            Queries that are run without a specified ``ttl`` are cached
+            indefinitely.
 
         Parameters
         ----------
         sql : str
             The read-only SQL query to execute.
         ttl : float, int, timedelta or None
-            The maximum number of seconds to keep results in the cache, or
-            None if cached results should not expire. The default is None.
+            The maximum number of seconds to keep results in the cache. If this
+            is ``None`` (default), cached results do not expire with time.
         show_spinner : boolean or string
-            Enable the spinner. The default is to show a spinner when there is a
-            "cache miss" and the cached resource is being created. If a string, the value
-            of the show_spinner param will be used for the spinner text.
+            Whether to enable the spinner. When a cached query is executed, no
+            spinner is displayed because the result is immediately available.
+            When a new query is executed, the default is to show a spinner with
+            the message "Running ``snowflake.query(...)``."
+
+            If this is ``False``, no spinner displays while executing the
+            query. If this is a string, the string will be used as the message
+            for the spinner.
         params : list, tuple, dict or None
-            List of parameters to pass to the execute method. This connector supports
-            binding data to a SQL statement using qmark bindings. For more information
-            and examples, see the `Snowflake Python Connector documentation
+            List of parameters to pass to the Snowflake Connector for Python
+            ``Cursor.execute()`` method. This connector supports binding data
+            to a SQL statement using qmark bindings. For more information and
+            examples, see the `Snowflake Connector for Python documentation
             <https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-example#using-qmark-or-numeric-binding>`_.
-            Default is None.
+            This defaults to ``None``.
 
         Returns
         -------
@@ -160,11 +313,13 @@ class SnowflakeConnection(BaseConnection["InternalSnowflakeConnection"]):
 
         Example
         -------
+
         >>> import streamlit as st
         >>>
         >>> conn = st.connection("snowflake")
-        >>> df = conn.query("select * from pet_owners")
+        >>> df = conn.query("SELECT * FROM my_table")
         >>> st.dataframe(df)
+
         """
         from snowflake.connector.errors import ProgrammingError  # type: ignore[import]
         from snowflake.connector.network import (  # type: ignore[import]
@@ -232,20 +387,64 @@ class SnowflakeConnection(BaseConnection["InternalSnowflakeConnection"]):
         chunk_size: int | None = None,
         **kwargs,
     ) -> tuple[bool, int, int]:
-        """Call snowflake.connector.pandas_tools.write_pandas with this connection.
+        """Write a ``pandas.DataFrame`` to a table in a Snowflake database.
 
-        This convenience method is simply a thin wrapper around the ``write_pandas``
-        function of the same name from ``snowflake.connector.pandas_tools``. For more
-        information, see the `Snowflake Python Connector documentation
+        This convenience method is a thin wrapper around
+        ``snowflake.connector.pandas_tools.write_pandas()`` using the
+        underlying connection. The ``conn`` parameter is passed automatically.
+        For more information and additional keyword arguments, see the
+        `Snowflake Connector for Python documentation
         <https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-api#write_pandas>`_.
 
+        Parameters
+        ----------
+        df: pandas.DataFrame
+            The ``pandas.DataFrame`` object containing the data to be copied
+            into the table.
+        table_name: str
+            Name of the table where the data should be copied to.
+        database: str
+            Name of the database containing the table. By default, the function
+            writes to the database that is currently in use in the session.
+
+            .. Note::
+                If you specify this parameter, you must also specify the schema
+                parameter.
+
+        schema: str
+            Name of the schema containing the table. By default, the function
+            writes to the table in the schema that is currently in use in the
+            session.
+        chunk_size: int
+            Number of elements to insert at a time. By default, the function
+            inserts all elements in one chunk.
+        **kwargs: Any
+            Additional keyword arguments for
+            ``snowflake.connector.pandas_tools.write_pandas()``.
+
         Returns
         -------
         tuple[bool, int, int]
             A tuple containing three values:
-                1. A bool that is True if the write was successful.
-                2. An int giving the number of chunks of data that were copied.
-                3. An int giving the number of rows that were inserted.
+
+            1. A boolean value that is ``True`` if the write was successful.
+            2. An integer giving the number of chunks of data that were copied.
+            3. An integer giving the number of rows that were inserted.
+
+        Example
+        -------
+        The following example uses the database and schema currently in use in
+        the session and copies the data into a table named "my_table."
+
+        >>> import streamlit as st
+        >>> import pandas as pd
+        >>>
+        >>> df = pd.DataFrame(
+        ...     {"Name": ["Mary", "John", "Robert"], "Pet": ["dog", "cat", "bird"]}
+        ... )
+        >>> conn = st.connection("snowflake")
+        >>> conn.write_pandas(df, "my_table")
+
         """
         from snowflake.connector.pandas_tools import write_pandas  # type:ignore[import]
 
@@ -262,27 +461,102 @@ class SnowflakeConnection(BaseConnection["InternalSnowflakeConnection"]):
         return (success, nchunks, nrows)
 
     def cursor(self) -> SnowflakeCursor:
-        """Return a PEP 249-compliant cursor object.
+        """Create a new cursor object from this connection.
 
-        For more information, see the `Snowflake Python Connector documentation
+        Snowflake Connector cursors implement the Python Database API v2.0
+        specification (PEP-249). For more information, see the
+        `Snowflake Connector for Python documentation
         <https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-api#object-cursor>`_.
+
+        Returns
+        -------
+        snowflake.connector.cursor.SnowflakeCursor
+            A cursor object for the connection.
+
+        Example
+        -------
+        The following example uses a cursor to insert multiple rows into a
+        table. The ``qmark`` parameter style is specified as an optional
+        keyword argument. Alternatively, the parameter style can be declared in
+        your connection configuration file. For more information, see the
+        `Snowflake Connector for Python documentation
+        <https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-example#using-qmark-or-numeric-binding>`_.
+
+        >>> import streamlit as st
+        >>>
+        >>> conn = st.connection("snowflake", "paramstyle"="qmark")
+        >>> rows_to_insert = [("Mary", "dog"), ("John", "cat"), ("Robert", "bird")]
+        >>> conn.cursor().executemany(
+        ...     "INSERT INTO mytable (name, pet) VALUES (?, ?)", rows_to_insert
+        ... )
+
         """
         return self._instance.cursor()
 
     @property
     def raw_connection(self) -> InternalSnowflakeConnection:
-        """Access the underlying Snowflake Python connector object.
+        """Access the underlying connection object from the Snowflake\
+        Connector for Python.
+
+        For information on how to use the Snowflake Connector for Python, see
+        the `Snowflake Connector for Python documentation
+        <https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-example>`_.
+
+        Returns
+        -------
+        snowflake.connector.connection.SnowflakeConnection
+            The connection object.
+
+        Example
+        -------
+        The following example uses a cursor to submit an asynchronous query,
+        saves the query ID, then periodically checks the query status through
+        the connection before retrieving the results.
+
+        >>> import streamlit as st
+        >>> import time
+        >>>
+        >>> conn = st.connection("snowflake")
+        >>> cur = conn.cursor()
+        >>> cur.execute_async("SELECT * FROM my_table")
+        >>> query_id = cur.sfqid
+        >>> while True:
+        ...     status = conn.raw_connection.get_query_status(query_id)
+        ...     if conn.raw_connection.is_still_running(status):
+        ...         time.sleep(1)
+        ...     else:
+        ...         break
+        >>> cur.get_results_from_sfqid(query_id)
+        >>> df = cur.fetchall()
 
-        Information on how to use the Snowflake Python Connector can be found in the
-        `Snowflake Python Connector documentation <https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-example>`_.
         """
         return self._instance
 
     def session(self) -> Session:
-        """Create a new Snowpark Session from this connection.
+        """Create a new Snowpark session from this connection.
+
+        For information on how to use Snowpark sessions, see the
+        `Snowpark developer guide
+        <https://docs.snowflake.com/en/developer-guide/snowpark/python/working-with-dataframes>`_
+        and `Snowpark API Reference
+        <https://docs.snowflake.com/en/developer-guide/snowpark/reference/python/latest/snowpark/session>`_.
+
+        Returns
+        -------
+        snowflake.snowpark.Session
+            A new Snowpark session for this connection.
+
+        Example
+        -------
+        The following example creates a new Snowpark session and uses it to run
+        a query.
+
+        >>> import streamlit as st
+        >>>
+        >>> conn = st.connection("snowflake")
+        >>> session = conn.session()
+        >>> df = session.sql("SELECT * FROM my_table").collect()
 
-        Information on how to use Snowpark sessions can be found in the `Snowpark documentation
-        <https://docs.snowflake.com/en/developer-guide/snowpark/python/working-with-dataframes>`_.
         """
         from snowflake.snowpark.context import get_active_session  # type:ignore[import]
         from snowflake.snowpark.session import Session  # type:ignore[import]

streamlit/connections/snowpark_connection.py

@@ -123,7 +123,7 @@ class SnowparkConnection(BaseConnection["Session"]):
         >>> import streamlit as st
         >>>
         >>> conn = st.connection("snowpark")
-        >>> df = conn.query("select * from pet_owners")
+        >>> df = conn.query("SELECT * FROM pet_owners")
         >>> st.dataframe(df)
         """
         from snowflake.snowpark.exceptions import (  # type:ignore[import]

streamlit/connections/sql_connection.py

@@ -52,35 +52,129 @@ _REQUIRED_CONNECTION_PARAMS = {"dialect", "username", "host"}
 
 
 class SQLConnection(BaseConnection["Engine"]):
-    """A connection to a SQL database using a SQLAlchemy Engine. Initialize using ``st.connection("<name>", type="sql")``.
+    """A connection to a SQL database using a SQLAlchemy Engine.
+
+    Initialize this connection object using ``st.connection("sql")`` or
+    ``st.connection("<name>", type="sql")``. Connection parameters for a
+    SQLConnection can be specified using ``secrets.toml`` and/or ``**kwargs``.
+    Possible connection parameters include:
+
+    - ``url`` or keyword arguments for |sqlalchemy.engine.URL.create()|_, except
+      ``drivername``. Use ``dialect`` and ``driver`` instead of ``drivername``.
+    - Keyword arguments for |sqlalchemy.create_engine()|_, including custom
+      ``connect()`` arguments used by your specific ``dialect`` or ``driver``.
+    - ``autocommit``. If this is ``False`` (default), the connection operates
+      in manual commit (transactional) mode. If this is ``True``, the
+      connection operates in autocommit (non-transactional) mode.
+
+    If ``url`` exists as a connection parameter, Streamlit will pass it to
+    ``sqlalchemy.engine.make_url()``. Otherwise, Streamlit requires (at a
+    minimum) ``dialect``, ``username``, and ``host``. Streamlit will use
+    ``dialect`` and ``driver`` (if defined) to derive ``drivername``, then pass
+    the relevant connection parameters to ``sqlalchemy.engine.URL.create()``.
+
+    In addition to the default keyword arguments for ``sqlalchemy.create_engine()``,
+    your dialect may accept additional keyword arguments. For example, if you
+    use ``dialect="snowflake"`` with `Snowflake SQLAlchemy
+    <https://github.com/snowflakedb/snowflake-sqlalchemy#key-pair-authentication-support>`_,
+    you can pass a value for ``private_key`` to use key-pair authentication. If
+    you use ``dialect="bigquery"`` with `Google BigQuery
+    <https://github.com/googleapis/python-bigquery-sqlalchemy#authentication>`_,
+    you can pass a value for ``location``.
+
+    SQLConnection provides the ``.query()`` convenience method, which can be
+    used to run simple, read-only queries with both caching and simple error
+    handling/retries. More complex database interactions can be performed by
+    using the ``.session`` property to receive a regular SQLAlchemy Session.
+
+    .. Important::
+        `SQLAlchemy <https://pypi.org/project/SQLAlchemy/>`_ must be installed
+        in your environment to use this connection. You must also install your
+        driver, such as ``pyodbc`` or ``psycopg2``.
+
+    .. |sqlalchemy.engine.URL.create()| replace:: ``sqlalchemy.engine.URL.create()``
+    .. _sqlalchemy.engine.URL.create(): https://docs.sqlalchemy.org/en/20/core/engines.html#sqlalchemy.engine.URL.create
+    .. |sqlalchemy.engine.make_url()| replace:: ``sqlalchemy.engine.make_url()``
+    .. _sqlalchemy.engine.make_url(): https://docs.sqlalchemy.org/en/20/core/engines.html#sqlalchemy.engine.make_url
+    .. |sqlalchemy.create_engine()| replace:: ``sqlalchemy.create_engine()``
+    .. _sqlalchemy.create_engine(): https://docs.sqlalchemy.org/en/20/core/engines.html#sqlalchemy.create_engine
+
+    Examples
+    --------
+
+    **Example 1: Configuration with URL**
+
+    You can configure your SQL connection using Streamlit's
+    `Secrets management <https://docs.streamlit.io/develop/concepts/connections/secrets-management>`_.
+    The following example specifies a SQL connection URL.
+
+    ``.streamlit/secrets.toml``:
+
+    >>> [connections.sql]
+    >>> url = "xxx+xxx://xxx:xxx@xxx:xxx/xxx"
+
+    Your app code:
 
-    SQLConnection provides the ``query()`` convenience method, which can be used to
-    run simple read-only queries with both caching and simple error handling/retries.
-    More complex DB interactions can be performed by using the ``.session`` property
-    to receive a regular SQLAlchemy Session.
+    >>> import streamlit as st
+    >>>
+    >>> conn = st.connection("sql")
+    >>> df = conn.query("SELECT * FROM pet_owners")
+    >>> st.dataframe(df)
 
-    SQLConnections should always be created using ``st.connection()``, **not**
-    initialized directly. Connection parameters for a SQLConnection can be specified
-    using either ``st.secrets`` or ``**kwargs``. Some frequently used parameters include:
+    **Example 2: Configuration with dialect, host, and username**
 
-    - **url** or arguments for `sqlalchemy.engine.URL.create()
-      <https://docs.sqlalchemy.org/en/20/core/engines.html#sqlalchemy.engine.URL.create>`_.
-      Most commonly it includes a dialect, host, database, username and password.
+    If you do not specify ``url``, you must at least specify ``dialect``,
+    ``host``, and ``username`` instead. The following example also includes
+    ``password``.
 
-    - **create_engine_kwargs** can be passed via ``st.secrets``, such as for
-      `snowflake-sqlalchemy <https://github.com/snowflakedb/snowflake-sqlalchemy#key-pair-authentication-support>`_
-      or `Google BigQuery <https://github.com/googleapis/python-bigquery-sqlalchemy#authentication>`_.
-      These can also be passed directly as ``**kwargs`` to connection().
+    ``.streamlit/secrets.toml``:
 
-    - **autocommit=True** to run with isolation level ``AUTOCOMMIT``. Default is False.
+    >>> [connections.sql]
+    >>> dialect = "xxx"
+    >>> host = "xxx"
+    >>> username = "xxx"
+    >>> password = "xxx"
+
+    Your app code:
 
-    Example
-    -------
     >>> import streamlit as st
     >>>
     >>> conn = st.connection("sql")
-    >>> df = conn.query("select * from pet_owners")
+    >>> df = conn.query("SELECT * FROM pet_owners")
+    >>> st.dataframe(df)
+
+    **Example 3: Configuration with keyword arguments**
+
+    You can configure your SQL connection with keyword arguments (with or
+    without ``secrets.toml``). For example, if you use Microsoft Entra ID with
+    a Microsoft Azure SQL server, you can quickly set up a local connection for
+    development using `interactive authentication
+    <https://learn.microsoft.com/en-us/sql/connect/odbc/using-azure-active-directory?view=sql-server-ver16#new-andor-modified-dsn-and-connection-string-keywords>`_.
+
+    This example requires the `Microsoft ODBC Driver for SQL Server
+    <https://learn.microsoft.com/en-us/sql/connect/odbc/microsoft-odbc-driver-for-sql-server?view=sql-server-ver16>`_
+    for *Windows* in addition to the ``sqlalchemy`` and ``pyodbc`` packages for
+    Python.
+
+    >>> 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)
+
     """
 
     def _connect(self, autocommit: bool = False, **kwargs) -> Engine:
@@ -140,15 +234,15 @@ class SQLConnection(BaseConnection["Engine"]):
     ) -> DataFrame:
         """Run a read-only query.
 
-        This method implements both query result caching (with caching behavior
-        identical to that of using ``@st.cache_data``) as well as simple error handling/retries.
+        This method implements query result caching and simple error
+        handling/retries. The caching behavior is identical to that of using
+        ``@st.cache_data``.
 
         .. note::
             Queries that are run without a specified ttl are cached indefinitely.
 
-        Aside from the ``ttl`` kwarg, all kwargs passed to this function are passed down
-        to |pandas.read_sql|_
-        and have the behavior described in the pandas documentation.
+        All keyword arguments passed to this function are passed down to
+        |pandas.read_sql|_, except ``ttl``.
 
         .. |pandas.read_sql| replace:: ``pandas.read_sql``
         .. _pandas.read_sql: https://pandas.pydata.org/docs/reference/api/pandas.read_sql.html
@@ -192,7 +286,7 @@ class SQLConnection(BaseConnection["Engine"]):
         >>>
         >>> conn = st.connection("sql")
         >>> df = conn.query(
-        ...     "select * from pet_owners where owner = :owner",
+        ...     "SELECT * FROM pet_owners WHERE owner = :owner",
         ...     ttl=3600,
         ...     params={"owner": "barbara"},
         ... )
@@ -259,12 +353,17 @@ class SQLConnection(BaseConnection["Engine"]):
 
     def connect(self) -> SQLAlchemyConnection:
         """Call ``.connect()`` on the underlying SQLAlchemy Engine, returning a new\
-        ``sqlalchemy.engine.Connection`` object.
+        connection object.
 
         Calling this method is equivalent to calling ``self._instance.connect()``.
 
         NOTE: This method should not be confused with the internal ``_connect`` method used
         to implement a Streamlit Connection.
+
+        Returns
+        -------
+        sqlalchemy.engine.Connection
+            A new SQLAlchemy connection object.
         """
         return self._instance.connect()
 
@@ -273,6 +372,11 @@ class SQLConnection(BaseConnection["Engine"]):
         """The underlying SQLAlchemy Engine.
 
         This is equivalent to accessing ``self._instance``.
+
+        Returns
+        -------
+        sqlalchemy.engine.base.Engine
+            The underlying SQLAlchemy Engine.
         """
         return self._instance
 
@@ -281,6 +385,11 @@ class SQLConnection(BaseConnection["Engine"]):
         """The name of the driver used by the underlying SQLAlchemy Engine.
 
         This is equivalent to accessing ``self._instance.driver``.
+
+        Returns
+        -------
+        str
+            The name of the driver. For example, ``"pyodbc"`` or ``"psycopg2"``.
         """
         return cast(str, self._instance.driver)
 
@@ -296,6 +405,11 @@ class SQLConnection(BaseConnection["Engine"]):
         <https://docs.sqlalchemy.org/en/20/orm/session_basics.html>`_ docs also contain
         much more information on the usage of sessions.
 
+        Returns
+        -------
+        sqlalchemy.orm.Session
+            A SQLAlchemy Session.
+
         Example
         -------
         >>> import streamlit as st