External procedures

• 1: Requirements for external procedures
• 2: Installing external procedure executable files
• 3: Creating external procedures
• 4: Executing external procedures
• 5: Dropping external procedures

1 - Requirements for external procedures

Enterprise Mode only

External procedures have requirements regarding their attributes, where you store them, and how you handle their output. You should also be cognizant of their resource usage.

Procedure file attributes

The procedure file cannot be owned by root. It must have the set-user-ID (SUID), user execute, and group execute attributes set. If it is not readable by the Linux database administrator user, then the owner's password will have to be specified when installing the procedure.

Handling procedure output

Vertica does not provide a facility for handling procedure output. Therefore, you must make your own arrangements for handling procedure output, which should include writing error, logging, and program information directly to files that you manage.

Handling resource usage

The Vertica resource manager is unaware of resources used by external procedures. Additionally, Vertica is intended to be the only major process running on your system. If your external procedure is resource intensive, it could affect the performance and stability of Vertica. Consider the types of external procedures you create and when you run them. For example, you might run a resource-intensive procedure during off hours.

Sample procedure file

#!/bin/bash
echo "hello planet argument: $1" >> /tmp/myprocedure.log

2 - Installing external procedure executable files

Enterprise Mode only

To install an external procedure, use the Administration Tools through either menu or the command line.

Using the admin tools menus

Run the Administration tools.
$ /opt/vertica/bin/adminTools


On the AdminTools Main Menu, click Configuration Menu, and then click OK.


On the Configuration Menu, click Install External Procedure and then click OK.


Select the database on which you want to install the external procedure.


Either select the file to install or manually type the complete file path, and then click OK.


If you are not the superuser, you are prompted to enter your password and click OK.
The Administration Tools automatically create the <database_catalog_path>/procedures directory on each node in the database and installs the external procedure in these directories for you.


Click OK in the dialog that indicates that the installation was successful.

Command line

If you use the command line, be sure to specify the full path to the procedure file and the password of the Linux user who owns the procedure file.

For example:

$ admintools -t install_procedure -d vmartdb -f /scratch/helloworld.sh -p ownerpassword
Installing external procedure...
External procedure installed

Once you have installed an external procedure, you need to make Vertica aware of it. To do so, use the CREATE PROCEDURE statement, but review Creating external procedures first.

3 - Creating external procedures

Enterprise Mode only

After you install an external procedure, you must make Vertica aware of it with CREATE PROCEDURE (external).

Only superusers can create an external procedure, and by default, only they have execute privileges. However, superusers can grant users and roles EXECUTE privilege on the stored procedure.

After you create a procedure, its metadata is stored in system table USER_PROCEDURES. Users can see only those procedures that they have been granted the privilege to execute.

Example

The following example creates a procedure named helloplanet for external procedure file helloplanet.sh. This file accepts one VARCHAR argument. The sample code is provided in Requirements for external procedures.

=> CREATE PROCEDURE helloplanet(arg1 VARCHAR) AS 'helloplanet.sh' LANGUAGE 'external'
   USER 'dbadmin';

The next example creates a procedure named proctest for the script copy_vertica_database.sh. This script copies a database from one cluster to another; it is included in the server RPM located in directory /opt/vertica/scripts.

=> CREATE PROCEDURE proctest(shosts VARCHAR, thosts VARCHAR, dbdir VARCHAR)
   AS 'copy_vertica_database.sh' LANGUAGE 'external' USER 'dbadmin';

Overloading external procedures

You can create multiple external procedures with the same name if they have different signatures—that is, accept a different set of arguments. For example, you can overload the helloplanet external procedure to also accept an integer value:

=> CREATE PROCEDURE helloplanet(arg1 INT) AS 'helloplanet.sh' LANGUAGE 'external'
   USER 'dbadmin';

After executing this statement, the database catalog stores two external procedures named helloplanet—one that accepts a VARCHAR argument and one that accepts an integer. When you call the external procedure, Vertica evaluates the arguments in the procedure call to determine which procedure to call.

See also

• CREATE PROCEDURE (external)
• GRANT (procedure)

4 - Executing external procedures

Enterprise Mode only

After you define a procedure using the CREATE PROCEDURE (external) statement, you can use it as a meta command in a SELECT statement. Vertica does not support using procedures in more complex statements or in expressions.

The following example runs a procedure named helloplanet:

=> SELECT helloplanet('earthlings');
 helloplanet
-------------
           0
(1 row)

The following example runs a procedure named proctest. This procedure references the copy_vertica_database.sh script that copies a database from one cluster to another. It is installed by the server RPM in the /opt/vertica/scripts directory.

=> SELECT proctest(
    '-s qa01',
    '-t rbench1',
    '-D /scratch_b/qa/PROC_TEST' );

Procedures are executed on the initiating node. Vertica runs the procedure by forking and executing the program. Each procedure argument is passed to the executable file as a string. The parent fork process waits until the child process ends.

If the child process exits with status 0, Vertica reports the operation took place by returning one row as shown in the helloplanet example. If the child process exits with any other status, Vertica reports an error like the following:

ERROR 7112: Procedure reported: Procedure execution error: exit status = code

To stop execution, cancel the process by sending a cancel command (for example, CTRL+C) through the client. If the procedure program exits with an error, an error message with the exit status is returned.

Permissions

To execute an external procedure, the user needs:

• EXECUTE privilege on procedure

• USAGE privilege on schema that contains the procedure

5 - Dropping external procedures

Enterprise Mode only

Only a superuser can drop an external procedure. To drop the definition for an external procedure from Vertica, use the DROP PROCEDURE (external) statement. Only the reference to the procedure is removed. The external file remains in the <database>/procedures directory on each node in the database.

Example

=> DROP PROCEDURE helloplanet(arg1 varchar);

See also

• DROP PROCEDURE (external)