clarify documentation and whatsnew

Author: Matt Roeschke

doc/source/io.rst

@@ -4777,7 +4777,7 @@ writes ``data`` to the database in batches of 1000 rows at a time:
     data.to_sql('data_chunked', engine, chunksize=1000)
 
 SQL data types
-''''''''''''''
+++++++++++++++
 
 :func:`~pandas.DataFrame.to_sql` will try to map your data to an appropriate
 SQL data type based on the dtype of the data. When you have columns of dtype
@@ -4809,13 +4809,19 @@ default ``Text`` type for string columns:
     Because of this, reading the database table back in does **not** generate
     a categorical.
 
+.. _io.sql_datetime_data:
+
 Datetime data types
 '''''''''''''''''''
 
 Using SQLAlchemy, :func:`~pandas.DataFrame.to_sql` is capable of writing
 datetime data that is timezone naive or timezone aware. However, the resulting
-data stored in the database ultimately depends on the corresponding,
-supported data type for datetime data.
+data stored in the database ultimately depends on the supported data type
+for datetime data of the database system being used.
+
+The following table lists supported data types for datetime data for some
+common databases. Other database dialects may have different data types for
+datetime data.
 
 ===========   =============================================  ===================
 Database      SQL Datetime Types                             Timezone Support
@@ -4830,7 +4836,7 @@ the data will be written as timezone naive timestamps that are in local time
 with respect to the timezone.
 
 :func:`~pandas.read_sql_table` is also capable of reading datetime data that is
-timezone aware of naive. When reading ``TIMESTAMP WITH TIME ZONE`` types, pandas
+timezone aware or naive. When reading ``TIMESTAMP WITH TIME ZONE`` types, pandas
 will convert the data to UTC.
 
 Reading Tables

doc/source/whatsnew/v0.24.0.txt

@@ -183,7 +183,7 @@ Other Enhancements
 - :class:`IntervalIndex` has gained the :meth:`~IntervalIndex.set_closed` method to change the existing ``closed`` value (:issue:`21670`)
 - :func:`~DataFrame.to_csv`, :func:`~Series.to_csv`, :func:`~DataFrame.to_json`, and :func:`~Series.to_json` now support ``compression='infer'`` to infer compression based on filename extension (:issue:`15008`).
   The default compression for ``to_csv``, ``to_json``, and ``to_pickle`` methods has been updated to ``'infer'`` (:issue:`22004`).
-- :meth:`DataFrame.to_sql` now supports writing ``TIMESTAMP WITH TIME ZONE`` types for supported databases. See the `io reference <https://pandas.pydata.org/pandas-docs/stable/io.html#sql-queries>`__ for implications (:issue:`9086`).
+- :meth:`DataFrame.to_sql` now supports writing ``TIMESTAMP WITH TIME ZONE`` types for supported databases. For databases that don't support timezones, datetime data will be stored as timezone unaware local timestamps. See the :ref:`io.sql_datetime_data` for implications (:issue:`9086`).
 - :func:`to_timedelta` now supports iso-formated timedelta strings (:issue:`21877`)
 - :class:`Series` and :class:`DataFrame` now support :class:`Iterable` in constructor (:issue:`2193`)
 - :class:`DatetimeIndex` gained :attr:`DatetimeIndex.timetz` attribute. Returns local time with timezone information. (:issue:`21358`)

pandas/core/generic.py

@@ -2316,8 +2316,10 @@ def to_sql(self, name, con, schema=None, if_exists='fail', index=True,
         -----
         Timezone aware datetime columns will be written as
         ``Timestamp with timezone`` type with SQLAlchemy if supported by the
-        database. Otherwise, the datetimes will stored in the closest available
-        type as timezone unaware timestamps local to the original timezone.
+        database. Otherwise, the datetimes will be stored as timezone unaware
+        timestamps local to the original timezone.
+
+        .. versionadded:: 0.24.0
 
         References
         ----------