add params to rds data api

Author: kukushking

awswrangler/data_api/rds.py

@@ -256,7 +256,9 @@ def connect(
     return RdsDataApi(resource_arn, database, secret_arn=secret_arn, boto3_session=boto3_session, **kwargs)
 
 
-def read_sql_query(sql: str, con: RdsDataApi, database: str | None = None, parameters: list[dict[str, Any]] | None = None) -> pd.DataFrame:
+def read_sql_query(
+    sql: str, con: RdsDataApi, database: str | None = None, parameters: list[dict[str, Any]] | None = None
+) -> pd.DataFrame:
     """Run an SQL query on an RdsDataApi connection and return the result as a DataFrame.
 
     Parameters
@@ -268,11 +270,28 @@ def read_sql_query(sql: str, con: RdsDataApi, database: str | None = None, param
     database
         Database to run query on - defaults to the database specified by `con`.
     parameters
-        A list of named parameters e.g. [{"name": "id", "value": "42"}].
+        A list of named parameters e.g. [{"name": "col", "value": {"stringValue": "val1"}}].
 
     Returns
     -------
         A Pandas DataFrame containing the query results.
+
+    Examples
+    --------
+    >>> import awswrangler as wr
+    >>> df = wr.data_api.rds.read_sql_query(
+    >>>     sql="SELECT * FROM public.my_table",
+    >>>     con=con,
+    >>> )
+
+    >>> import awswrangler as wr
+    >>> df = wr.data_api.rds.read_sql_query(
+    >>>     sql="SELECT * FROM public.my_table WHERE col = :name",
+    >>>     con=con,
+    >>>     parameters=[
+    >>>        {"name": "col1", "value": {"stringValue": "val1"}}
+    >>>     ],
+    >>> )
     """
     return con.execute(sql, database=database, parameters=parameters)
 

tests/unit/test_data_api.py

@@ -131,7 +131,7 @@ def test_data_api_redshift_parameters(redshift_connector: "RedshiftDataApi", red
     wr.data_api.redshift.read_sql_query(
         f"INSERT INTO public.{redshift_table} VALUES (41, 'test1'), (42, 'test2')", con=redshift_connector
     )
-    expected_dataframe = pd.DataFrame([[42, "test"]], columns=["id", "name"])
+    expected_dataframe = pd.DataFrame([[42, "test2"]], columns=["id", "name"])
 
     dataframe = wr.data_api.redshift.read_sql_query(
         f"SELECT * FROM  public.{redshift_table} WHERE id >= :id",
@@ -319,3 +319,25 @@ def test_data_api_postgresql(postgresql_serverless_connector: "RdsDataApi", post
     )
     expected_dataframe = pd.DataFrame([["test"]], columns=["name"])
     assert_pandas_equals(out_frame, expected_dataframe)
+
+
+def test_data_api_mysql_parameters(
+    mysql_serverless_connector: "RdsDataApi",
+    mysql_serverless_table: str,
+) -> None:
+    database = "test"
+    df = pd.DataFrame([[42, "test"]], columns=["id", "name"])
+
+    wr.data_api.rds.to_sql(
+        df=df,
+        con=mysql_serverless_connector,
+        table=mysql_serverless_table,
+        database=database,
+    )
+
+    out_df = wr.data_api.rds.read_sql_query(
+        f"SELECT * FROM {database}.{mysql_serverless_table} WHERE name = :name",
+        con=mysql_serverless_connector,
+        parameters=[{"name": "name", "value": {"stringValue": "test"}}],
+    )
+    assert_pandas_equals(out_df, df)