depr(python): Rename write_database parameter if_exists to if_table_exists

[alexander-beedie]

Closes #12779.

Deprecates if_exists in favour of if_table_exists, clarifying what it is that exists.

As per the linked Issue, it's not unreasonable that somebody may think they are replacing some existing data in a table. Given that the downside of getting this wrong is potentially deleting an entire table, it's good to remove the potential for ambiguity...

---

@stinodego: as a follow-up we should probably make the write_database "if_table_exists" and write_delta "mode" parameters consistent, given that they have the same options/behaviour, but use different param/value names 🤔 (Can be left to a subsequent PR).

[stinodego]

@stinodego: as a follow-up we should probably make the write_database "if_table_exists" and write_delta "mode" parameters consistent, given that they have the same options/behaviour, but use different param/value names 🤔 (Can be left to a subsequent PR).

I'm not sure about that. mode is pretty well established in Spark/Delta Lake docs. I don't want to change that.
https://docs.delta.io/latest/delta-batch.html

[alexander-beedie]

I'm not sure about that. mode is pretty well established in Spark/Delta Lake docs. I don't want to change that. https://docs.delta.io/latest/delta-batch.html

If it's well established already then that's fair, but it does seem prone to the same ambiguity that this PR addresses - and if you're going to write via polars then there is a reasonable argument that we should line these up on our side (as a consistent API is one of our selling points ;))

Parameter correspondence:

write_database ("if_table_exists")	write_delta ("mode")
replace	overwrite
append	append
fail	error
<n/a>	ignore

You can see that the parameters line-up exactly in terms of what they do and how they behave (with an extra "ignore" option for write_delta). Anyway, let's have a think and come back to it later 👌