DOC: Document existing functionality of pandas.DataFrame.to_sql() #11886

pandas/core/generic.py

@@ -6,7 +6,7 @@
 import operator
 import pickle
 from textwrap import dedent
-from typing import Callable, FrozenSet, List, Set
+from typing import Callable, FrozenSet, List, Optional, Set, Union
 import warnings
 import weakref
 
@@ -2458,8 +2458,12 @@ def to_msgpack(self, path_or_buf=None, encoding='utf-8', **kwargs):
         return packers.to_msgpack(path_or_buf, self, encoding=encoding,
                                   **kwargs)
 
-    def to_sql(self, name, con, schema=None, if_exists='fail', index=True,
-               index_label=None, chunksize=None, dtype=None, method=None):
+    def to_sql(self, name: str, con,
+               schema: Optional[str] = None, if_exists: str = 'fail',
+               index: bool = True,
+               index_label: Optional[Union[str, List[str]]] = None,
+               chunksize: Optional[int] = None, dtype: Union[dict] = None,
+               method: Union[str, Callable] = None):
         """
         Write records stored in a DataFrame to a SQL database.
 
@@ -2493,10 +2497,11 @@ def to_sql(self, name, con, schema=None, if_exists='fail', index=True,
         chunksize : int, optional
             Rows will be written in batches of this size at a time. By default,
             all rows will be written at once.
-        dtype : dict, optional
-            Specifying the datatype for columns. The keys should be the column
-            names and the values should be the SQLAlchemy types or strings for
-            the sqlite3 legacy mode.
+        dtype : dict or scalar, optional
+            Specifying the datatype for columns. If a dictionary is used, the
+            keys should be the column names and the values should be the
+            SQLAlchemy types or strings for the sqlite3 legacy mode. If a
+            scalar is provided, it will be applied to all columns.
         method : {None, 'multi', callable}, default None
             Controls the SQL insertion clause used:
 

pandas/io/sql.py

@@ -419,10 +419,11 @@ def to_sql(frame, name, con, schema=None, if_exists='fail', index=True,
     chunksize : int, default None
         If not None, then rows will be written in batches of this size at a
         time.  If None, all rows will be written at once.
-    dtype : single SQLtype or dict of column name to SQL type, default None
-        Optional specifying the datatype for columns. The SQL type should
-        be a SQLAlchemy type, or a string for sqlite3 fallback connection.
-        If all columns are of the same type, one single value can be used.
+    dtype : dict or scalar, optional
+        Specifying the datatype for columns. If a dictionary is used, the
+        keys should be the column names and the values should be the
+        SQLAlchemy types or strings for the sqlite3 legacy mode. If a
+        scalar is provided, it will be applied to all columns.
     method : {None, 'multi', callable}, default None
         Controls the SQL insertion clause used: