CREATE_PROTOCOL.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1">
    <title id="bv20941">CREATE PROTOCOL</title>
    <body>
        <p id="sql_command_desc">Registers a custom data access protocol that can be specified when
            defining a Greenplum Database external table.</p>
        <section id="section2">
            <title>Synopsis</title>
            <codeblock id="sql_command_synopsis">CREATE [TRUSTED] PROTOCOL <varname>name</varname> (
   [readfunc='<varname>read_call_handler</varname>'] [, writefunc='<varname>write_call_handler</varname>']
   [, validatorfunc='<varname>validate_handler</varname>' ])</codeblock>
        </section>
        <section id="section3">
            <title>Description</title>
            <p><codeph>CREATE PROTOCOL</codeph> associates a data access protocol name with call
                handlers that are responsible for reading from and writing data to an external data
                source. You must be a superuser to create a protocol.</p>
            <p>The <codeph>CREATE PROTOCOL</codeph> command must specify either a read call handler
                or a write call handler. The call handlers specified in the <codeph>CREATE
                    PROTOCOL</codeph> command must be defined in the database.</p>
            <p>The protocol name can be specified in a <codeph>CREATE EXTERNAL TABLE</codeph>
                command. </p>
            <p> For information about creating and enabling a custom data access protocol, see
                "Example Custom Data Access Protocol" in the <cite>Greenplum Database Administrator
                    Guide</cite>.</p>
        </section>
        <section id="section4">
            <title>Parameters</title>
            <parml>
                <plentry>
                    <pt>TRUSTED</pt>
                    <pd>If not specified, only superusers and the protocol owner can create external
                        tables using the protocol. If specified, superusers and the protocol owner
                        can <codeph>GRANT</codeph> permissions on the protocol to other database
                        roles.</pd>
                </plentry>
                <plentry>
                    <pt>
                        <varname>name</varname>
                    </pt>
                    <pd>The name of the data access protocol. The protocol name is case sensitive.
                        The name must be unique among the protocols in the database. </pd>
                </plentry>
                <plentry>
                    <pt>readfunc= '<varname>read_call_handler</varname>'</pt>
                    <pd>The name of a previously registered function that Greenplum Database calls
                        to read data from an external data source. The command must specify either a
                        read call handler or a write call handler.</pd>
                </plentry>
                <plentry>
                    <pt>writefunc= '<varname>write_call_handler</varname>'</pt>
                    <pd>The name of a previously registered function that Greenplum Database calls
                        to write data to an external data source. The command must specify either a
                        read call handler or a write call handler.</pd>
                </plentry>
                <plentry>
                    <pt>validatorfunc='<varname>validate_handler</varname>'</pt>
                    <pd>An optional validator function that validates the URL specified in the
                            <codeph>CREATE EXTERNAL TABLE</codeph> command.</pd>
                </plentry>
            </parml>
        </section>
        <section id="section5">
            <title>Notes</title>
            <p>Greenplum Database handles external tables of type <codeph>file</codeph>,
                    <codeph>gpfdist</codeph>, and <codeph>gpfdists</codeph> internally. 
                See
                    <xref href="../../admin_guide/external/g-s3-protocol.xml#amazon-emr/s3_prereq"/>
                for information about enabling the <codeph>S3</codeph> protocol. Refer to <xref
                    href="../../admin_guide/external/g-pxf-protocol.xml" type="topic"></xref> for
                information about using the <codeph>pxf</codeph> protocol.</p>
            <p>Any shared library that implements a data access protocol must be located in the same
                location on all Greenplum Database segment hosts. For example, the shared library
                can be in a location specified by the operating system environment variable
                    <codeph>LD_LIBRARY_PATH</codeph> on all hosts. You can also specify the location
                when you define the handler function. For example, when you define the
                    <codeph>s3</codeph> protocol in the <codeph>CREATE PROTOCOL</codeph> command,
                you specify <codeph>$libdir/gps3ext.so</codeph> as the location of the shared
                object, where <codeph>$libdir</codeph> is located at
                <codeph>$GPHOME/lib</codeph>.</p>
        </section>
        <section id="section7">
            <title>Compatibility</title>
            <p><codeph>CREATE PROTOCOL</codeph> is a Greenplum Database extension. </p>
        </section>
        <section id="section8">
            <title>See Also</title>
            <p><codeph><xref href="ALTER_PROTOCOL.xml#topic1"/></codeph>, <codeph><xref
                        href="CREATE_EXTERNAL_TABLE.xml#topic1"/></codeph>, <codeph><xref
                        href="DROP_PROTOCOL.xml#topic1"/></codeph>, <xref href="GRANT.xml#topic1"
                /></p>
        </section>
    </body>
</topic>