Name

EXECUTE SCRIPT — Execute SQL/DDL script

Synopsis

EXECUTE SCRIPT (options);

Description

Executes a script containing arbitrary SQL statements on all nodes that are subscribed to a set at a common controlled point within the replication transaction stream.

The specified event origin must be the origin of the set. The script file must not contain any START or COMMIT TRANSACTION calls. (This changes somewhat in PostgreSQL 8.0 once nested transactions, aka savepoints, are supported) In addition, non-deterministic DML statements (like updating a field with CURRENT_TIMESTAMP) must be avoided, since the data changes done by the script are explicitly not replicated.

SET ID = ival

The unique numeric ID number of the set affected by the script

FILENAME = '/path/to/file'

The name of the file containing the SQL script to execute. This might be a relative path, relative to the location of the slonik instance you are running, or, preferably, an absolute path on the system where slonik is to run.

The contents of the file are propagated as part of the event, so the file does not need to be accessible on any of the nodes.

EVENT NODE = ival

(Optional) The ID of the current origin of the set. Default value is 1.

EXECUTE ONLY ON = ival

(Optional) The ID of the only node to actually execute the script. This option causes the script to be propagated by all nodes but executed only by one. The default is to execute the script on all nodes that are subscribed to the set.

See also the warnings in Section 14, “Database Schema Changes (DDL)”.

Note that this is a locking operation, which means that it can get stuck behind other database activity.

At the start of this event, all tables in the specified set are unlocked via the function alterTableRestore(tab_id). After the SQL script has run, they are returned to “replicating state” using alterTableForReplication(tab_id). This means that all of these tables are locked by this slon process for the duration of the SQL script execution.

If a table's columns are modified, it is very important that the triggers be regenerated, otherwise they may be inappropriate for the new form of the table schema.

Note that if you need to make reference to the cluster name, you can use the token @CLUSTERNAME@; if you need to make reference to the Slony-I namespace, you can use the token @NAMESPACE@; both will be expanded into the appropriate replacement tokens.

It generally seems a bad idea to use quotes in DDL scripts. It appears preferable to handle that sort of thing “out of band.

This uses schemadocddlscript( integer, text, integer ).

Example

EXECUTE SCRIPT (
   SET ID = 1,
   FILENAME = '/tmp/changes_2004-05-01.sql',
   EVENT NODE = 1
);
    

Locking Behaviour

Each replicated table receives an exclusive lock, on the origin node, in order to remove the replication triggers; after the DDL script completes, those locks will be cleared.

After the DDL script has run on the origin node, it will then run on subscriber nodes, where replicated tables will be similarly altered to remove replication triggers, therefore requiring that exclusive locks be taken out on each node, in turn.

Version Information

This command was introduced in Slony-I 1.0