DOC: update the pandas.DataFrame.to_sql docstring

pandas/core/generic.py

@@ -1865,17 +1865,22 @@ def to_sql(self, name, con, schema=None, if_exists='fail', index=True,
         """
         Write records stored in a DataFrame to a SQL database.
 
+        This function inserts all rows of the dataframe into the given
+         table and recreates it if if_exists='replace'. Databases supported by
+         SQLAlchemy or DBAPI2 are also supported.
+
         Parameters
         ----------
         name : string
-            Name of SQL table
+            Name of SQL table.
         con : SQLAlchemy engine or DBAPI2 connection (legacy mode)
             Using SQLAlchemy makes it possible to use any DB supported by that
             library. If a DBAPI2 object, only sqlite3 is supported.
         schema : string, default None
             Specify the schema (if database flavor supports this). If None, use
             default schema.
         if_exists : {'fail', 'replace', 'append'}, default 'fail'
+            Accepted values:
             - fail: If table exists, do nothing.
             - replace: If table exists, drop it, recreate it, and insert data.
             - append: If table exists, insert data. Create if does not exist.
@@ -1892,6 +1897,34 @@ def to_sql(self, name, con, schema=None, if_exists='fail', index=True,
             Optional specifying the datatype for columns. The SQL type should
             be a SQLAlchemy type, or a string for sqlite3 fallback connection.
 
+        Returns
+        --------
+            None
+
+        See Also
+        --------
+        pandas.read_sql_query : read a DataFrame from a table
+
+        Examples
+        --------
+        >>> from sqlalchemy import create_engine
+        >>> engine = create_engine('sqlite://', echo=False)
+        >>> df = pd.DataFrame({'name' : ['User 1', 'User 2', 'User 3']})
+        >>> # create a table from scratch with 3 rows
+        >>> df.to_sql('users', con=engine, if_exists='replace')
+        >>> df1 = pd.DataFrame({'name' : ['User 4', 'User 5']})
+        >>> # 2 new rows inserted
+        >>> df1.to_sql('users', con=engine, if_exists='append')
+        >>> # table will be recreated and 5 rows inserted
+        >>> df = pd.concat([df, df1], ignore_index=True)
+        >>> df.to_sql('users', con=engine, if_exists='replace')
+        >>> pd.read_sql_query("select * from users",con=engine)
+           index    name
+        0      0  User 1
+        1      1  User 2
+        2      2  User 3
+        3      3  User 4
+        4      4  User 5
         """
         from pandas.io import sql
         sql.to_sql(self, name, con, schema=schema, if_exists=if_exists,