--single-transaction doc clarification

"Simon Riggs" <simon@2ndquadrant.com> writes:

Clarification of when it's not appropriate to use this option.

I think it's a fairly bad idea to try to enumerate the commands that
can't be used in a transaction block here, because there is no way
that we will remember to keep such a list up-to-date. Why not just
say "It won't work for commands that can't be used in a transaction
block"?

regards, tom lane

On Mon, 2006-10-30 at 17:32 -0500, Tom Lane wrote:

"Simon Riggs" <simon@2ndquadrant.com> writes:

Clarification of when it's not appropriate to use this option.

I think it's a fairly bad idea to try to enumerate the commands that
can't be used in a transaction block here, because there is no way
that we will remember to keep such a list up-to-date. Why not just
say "It won't work for commands that can't be used in a transaction
block"?

I agree, but such a comment immediately begs the question: What is the
list of commands this applies to? I was surprised how long a list it was
myself, hence the patch.

(Checks)...The man pages for VACUUM, CREATE TABLESPACE, CLUSTER and
REINDEX DATABASE don't mention they are not allowed inside a transaction
block at all, so I'm not sure if doing it the other way around helps
with maintaining docs...

I prefer useful info rather than hidden gotchas, even if the list might
possibly be < 100% exactly correct. At least we can say we tried.

--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com

On Mon, 2006-10-30 at 22:56 +0000, Simon Riggs wrote:

The man pages for VACUUM, CREATE TABLESPACE, CLUSTER and
REINDEX DATABASE don't mention they are not allowed inside a transaction
block at all

That should be fixed, I think. Once that is done, I think it's
sufficient to just say that --single-transaction won't work for commands
that can't be executed in a transaction block.

-Neil

Neil Conway <neilc@samurai.com> writes:

On Mon, 2006-10-30 at 22:56 +0000, Simon Riggs wrote:

The man pages for VACUUM, CREATE TABLESPACE, CLUSTER and
REINDEX DATABASE don't mention they are not allowed inside a transaction
block at all

That should be fixed, I think. Once that is done, I think it's
sufficient to just say that --single-transaction won't work for commands
that can't be executed in a transaction block.

That's what makes sense to me, too.

regards, tom lane

On Mon, 2006-10-30 at 19:28 -0500, Tom Lane wrote:

Neil Conway <neilc@samurai.com> writes:

On Mon, 2006-10-30 at 22:56 +0000, Simon Riggs wrote:

The man pages for VACUUM, CREATE TABLESPACE, CLUSTER and
REINDEX DATABASE don't mention they are not allowed inside a transaction
block at all

That should be fixed, I think. Once that is done, I think it's
sufficient to just say that --single-transaction won't work for commands
that can't be executed in a transaction block.

That's what makes sense to me, too.

As requested.

--
Simon Riggs
EnterpriseDB http://www.enterprisedb.com

On Tue, 2006-10-31 at 01:07 +0000, Simon Riggs wrote:

As requested.

Applied, thanks for the patch.

I didn't apply the ON_ERROR_STOP addition: IMHO it's not very useful to
say that doing something is "advised" without explaining why it is
wise/useful/necessary. If we want to include this point, can you add
some elaboration on why/when ON_ERROR_STOP should be used with
--single-transaction?

-Neil

Neil Conway <neilc@samurai.com> writes:

On Tue, 2006-10-31 at 01:07 +0000, Simon Riggs wrote:

As requested.

Applied, thanks for the patch.

This patch converted a correct statement into a lie: there is not
anything that will cause begin/commit in a script file to fail just
because you wrapped begin/commit around them. I rewrote the text to

If the script itself uses <command>BEGIN</>, <command>COMMIT</>,
or <command>ROLLBACK</>, this option will not have the desired
effects.
Also, if the script contains any command that cannot be executed
inside a transaction block, specifying this option will cause that
command (and hence the whole transaction) to fail.

regards, tom lane

On Mon, Oct 30, 2006 at 07:18:04PM -0500, Neil Conway wrote:

On Mon, 2006-10-30 at 22:56 +0000, Simon Riggs wrote:

The man pages for VACUUM, CREATE TABLESPACE, CLUSTER and
REINDEX DATABASE don't mention they are not allowed inside a transaction
block at all

That should be fixed, I think. Once that is done, I think it's
sufficient to just say that --single-transaction won't work for commands
that can't be executed in a transaction block.

"What commands aren't allowed in a transaction?" is still a logical
question to ask though, so it would be nice if we had such a list
hanging around.

Is there a standard way these commands test to see if they're in a
transaction block? If there is, perhaps something could be created that
would pull that info out of the code so that we didn't have to maintain
the list by hand. It might also be possible to do this with some SGML
magic.
--
Jim Nasby jim@nasby.net
EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)