Remove #[doc(hidden)] from pub trait TransactionManager

[cfkaran2]

I've been thinking about implementing the Database trait on a database engine that I've been planning out for a while now¹. The Database trait requires the use of the TransactionManager trait. I've noticed that while the TransactionManager trait is public, its documentation is hidden via #[doc(hidden)]. This makes it a little confusing for those of us that would like to implement Database on our own database engines because it feels like we're being discouraged from implementing TransactionManager. I don't want to try to implement Database on anything I write unless I know that doing so is actively encouraged by the sqlx project.

So let me ask directly, are we actively encouraged to implement Database, and therefore actively encouraged to implement TransactionManager) within our own crates on our own database engines? If we are actively encouraged to do so, would you be willing to remove the #[doc(hidden)] attribute and flesh out the documentation for what is required of all implementations of TransactionManager?

Once I know what the sqlx project intends for external crates to do, I'll be able to decide how to proceed.

Thank you in advance for any advice you can give me regarding this!

Footnotes

1. Full disclaimer - I don't have any code for a crate yet, just a pile of notes and thoughts on how to implement what I want. However, one sticking point is whether I go for an embedded database engine, or go write a full server that understands SQL. The former is faster and easier to whip up, but will be non-standard, with all that implies. The latter will require significant time and effort on my part to do well, but will mean that anyone that knows how to write SQL will be able to use my engine, and I will be able to use the wide variety of testing tools that are out there for SQL to validate my engine's performance. Yay for tradeoffs... ↩

[abonander]

I thought it was documented somewhere but I guess not.

#[doc(hidden)] APIs are not strictly forbidden, but they are considered sever-exempt. Our interpretation of what that means is discussed with the SQLite driver: https://docs.rs/sqlx/latest/sqlx/sqlite/index.html

In short, you're welcome to use hidden APIs, we just reserve the right to change them without notice so you should link to SQLx using a pinned version.

[cfkaran2]

That makes sense, and I can pin my crate to a given version easily. In that case, can I make two requests?

First, would you be willing to add some additional documentation explaining about hidden APIs being semver-exempt, possibly in lib.md?

And second, would you consider making some of those APIs public at some point in the future? It'd be pretty handy for anyone that wants to develop a new database engine as we could just reuse sqlx as our front end.

[abonander]

The TransactionManager trait should never be part of the sqlx facade. It'd be too easy for someone to use it to place their connection into a transaction and forget to commit it or roll it back.

Honestly, I don't see why it should be hidden in sqlx-core though.