docs: Acquire examples and alternative

[stoically]

Tried to summarize my findings around Acquire from

• Using a connection retrieved from Acquire more than once not possible because of lifetimes #1635
• Acquire lifetime errors in axum handlers #1686
• Implementation of sqlx::Acquire is not general enough for MySqlConnection #1015 (comment)

as doc examples so others might have an easier start.

[abonander]

@stoically looks like your examples aren't compiling in CI: https://github.com/launchbadge/sqlx/runs/5211089701?check_suite_focus=true

[stoically]

@abonander Yeah, since every workflow run needs another approval, debugging takes a while. First reason it failed CI was missing postgres feature. Now it doesn't have a DATABASE_URL for the doc tests, so it probably required adding running of a postgres db to the unit test job.

[abonander]

I don't like the requirement of a Postgres database for unit testing. Kinda defeats the purpose of having a separate pass just for unit tests.

Coincidentally, however, I did just add a way for tests to know if they're meant only for (a certain version of) Postgres, which could be useful here.

Try removing the changes you made to .github/workflows/sqlx.yaml and instead wrapping the code in the examples with

#[cfg(any(postgres_9_6, postgres_14))]

[stoically]

I don't like the requirement of a Postgres database for unit testing. Kinda defeats the purpose of having a separate pass just for unit tests.

While I agree that unit tests should have no external dependencies, I'd argue that doc tests are (or should be) feature/integration tests, not unit tests. Since they are executed from the same point of view than integration tests, where they have to explicitly use things from the crates and aren't able to just use what's in scope of the file. So I guess it's a question of how the workflow jobs are structured.

Coincidentally, however, I did just add a way for tests to know if they're meant only for (a certain version of) Postgres, which could be useful here.

Sounds good, adjusted accordingly.

[abonander]

While I agree that unit tests should have no external dependencies, I'd argue that doc tests are (or should be) feature/integration tests, not unit tests.

I'm not arguing there, I agree. The context of my comment was your modifications to the "Unit Test" pass of CI.

I think technically we could restrict that pass to just unit tests without having cfg hacks in the doctests by doing cargo test --lib, but to my understanding, that only works for one package at a time so we'd have to duplicate the command for every crate (although sqlx-core I think is the only one that actually has unit tests anyway).

[stoically]

Seems like cargo test --lib --workspace would do the trick and run only unit tests for the whole workspace, which could be used for the unit test job. But I guess that would still require the cfg as the doc tests are postgres specific?

[abonander]

Yeah, this seems to work fine though so we'll probably just go with it.