DOC: pandas.DataFrame.to_sql does not document that it creates a table index for index columns

[mattatark]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.to_sql.html#pandas.DataFrame.to_sql

Documentation problem

As far as I can tell, pandas.DataFrame.to_sql creates a table index when creating a table and including the index of the dataframe. This is unexpected, and undocumented. See this line that I believe is responsible for this. Here's a link to the relevant SQLAlchemy docs for that constructor input.

Suggested fix for documentation

I'd recommend updating the text field for the index input:

Write DataFrame index as a column. Uses index_label as the column name in the table. Creates a table index for this column.

Or something like that. I DO think that this behavior is generally undesired and should be removed, or have an input that should default to False, but at least documenting it will save others from hours of time looking through the code base to figure this out.

[pauluhlenbruck]

take

[pauluhlenbruck]

I will start working on this issue during the upcoming weekend.