DOC: update the pandas.DataFrame.to_sql docstring
Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```

################################################################################
##################### Docstring (pandas.DataFrame.to_sql)  #####################
################################################################################

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.
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.
index : boolean, default True
    Write DataFrame index as a column.
index_label : string or sequence, default None
    Column label for index column(s). If None is given (default) and
    `index` is True, then the index names are used.
    A sequence should be given if the DataFrame uses MultiIndex.
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 : 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.

Returns
--------
    None

See Also
--------
pandas.read_sql_query : read a DataFrame from a table

Examples
--------
>>> from sqlalchemy import create_engine
>>> engine = create_engine('sqlite:///example.db', 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

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.to_sql" correct. :)

```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.



