diff --git a/presto-docs/src/main/sphinx/connector/googlesheets.rst b/presto-docs/src/main/sphinx/connector/googlesheets.rst index 94869d0640a1c..73d54dac5932c 100644 --- a/presto-docs/src/main/sphinx/connector/googlesheets.rst +++ b/presto-docs/src/main/sphinx/connector/googlesheets.rst @@ -4,6 +4,13 @@ Google Sheets connector The Google Sheets connector allows reading `Google Sheets `_ spreadsheets as tables in Presto. +.. note:: + + Before configuring this connector, verify that the Google Sheets connector + plugin has been deployed to the Presto plugin directory. If the plugin is + not deployed, Presto will fail to start when this catalog is configured. + See :doc:`/installation/deploy-custom-plugins` for more information. + Configuration ------------- diff --git a/presto-docs/src/main/sphinx/develop/spi-overview.rst b/presto-docs/src/main/sphinx/develop/spi-overview.rst index c34968607f176..cda3505cf3f7b 100644 --- a/presto-docs/src/main/sphinx/develop/spi-overview.rst +++ b/presto-docs/src/main/sphinx/develop/spi-overview.rst @@ -83,17 +83,13 @@ Deploying a Custom Plugin ------------------------- In order to add a custom plugin to a Presto installation, create a directory -for that plugin in the Presto plugin directory and add all the necessary jars -for the plugin to that directory. For example, for a plugin called -``my-functions``, you would create a directory ``my-functions`` in the Presto -plugin directory and add the relevant jars to that directory. +for that plugin in the Presto plugin directory and add all the necessary JAR +files to that directory. Plugins must be installed on all nodes in the Presto +cluster (coordinator and workers). -By default, the plugin directory is the ``plugin`` directory relative to the -directory in which Presto is installed, but it is configurable using the -configuration variable ``catalog.config-dir``. In order for Presto to pick up -the new plugin, you must restart Presto. - -Plugins must be installed on all nodes in the Presto cluster (coordinator and workers). +For detailed step-by-step instructions on deploying custom plugins, +including how to verify that a plugin has been loaded and troubleshoot common +errors, see :doc:`/installation/deploy-custom-plugins`. Coordinator Plugin ------------------ diff --git a/presto-docs/src/main/sphinx/installation.rst b/presto-docs/src/main/sphinx/installation.rst index daef03acb5288..157ddd86780cf 100644 --- a/presto-docs/src/main/sphinx/installation.rst +++ b/presto-docs/src/main/sphinx/installation.rst @@ -6,6 +6,7 @@ Installation :maxdepth: 1 installation/deployment + installation/deploy-custom-plugins installation/deploy-brew installation/deploy-docker installation/deploy-helm diff --git a/presto-docs/src/main/sphinx/installation/deploy-custom-plugins.rst b/presto-docs/src/main/sphinx/installation/deploy-custom-plugins.rst new file mode 100644 index 0000000000000..728fc573ffecc --- /dev/null +++ b/presto-docs/src/main/sphinx/installation/deploy-custom-plugins.rst @@ -0,0 +1,124 @@ +======================== +Deploying Custom Plugins +======================== + +Presto has a plugin-based architecture. Connectors, functions, access control +implementations, and other features are provided by plugins that are loaded at +server startup. Many plugins are bundled with a Presto installation, but +additional plugins can be deployed manually. + +This topic explains how to deploy a custom or additional plugin to a Presto +installation. + +.. contents:: + :local: + :backlinks: none + :depth: 1 + +Overview +-------- + +When Presto starts, it scans the plugin directory for subdirectories. Each +subdirectory is treated as a separate plugin and must contain all of the +Java Archive (JAR) files required by that plugin. Presto loads each plugin +into a separate class loader to ensure that plugins are isolated from each +other. + +If a catalog configuration file (in ``etc/catalog``) references a connector +whose corresponding plugin has not been deployed, Presto will fail to start. + +Plugin Directory +---------------- + +By default, the plugin directory is the ``plugin`` directory relative to the +Presto installation directory. This can be changed using the ``plugin.dir`` +configuration property. + +The plugin directory is structured as follows, where each subdirectory +contains the JAR files for a single plugin: + +.. code-block:: none + + plugin/ + ├── hive-hadoop2/ + │ ├── presto-hive-hadoop2-0.296.jar + │ └── ... (dependency JARs) + ├── tpch/ + │ ├── presto-tpch-0.296.jar + │ └── ... (dependency JARs) + └── gsheets/ + ├── presto-google-sheets-0.296.jar + └── ... (dependency JARs) + +Deploying a Plugin +------------------ + +To deploy a plugin: + +1. Obtain the plugin directory for the plugin you want to deploy. This + directory should contain the plugin JAR file and all of its required + dependencies. Plugin directories can be obtained by building the plugin + from source or from a Presto distribution that includes the plugin. + +2. Copy the plugin directory into the Presto plugin directory. The name of the + subdirectory does not need to match the connector name, but using a matching + name is recommended for clarity. + + For example, to deploy the Google Sheets connector plugin on a Presto + installation located at ``/opt/presto-server``: + + .. code-block:: none + + cp -r presto-google-sheets-0.296/ /opt/presto-server/plugin/gsheets + +3. Deploy the plugin on all nodes in the Presto cluster (coordinator and + workers). Every node must have the same set of plugins installed. + +4. Restart Presto. A plugin is loaded only at server startup. + +Verifying a Plugin +------------------ + +After restarting Presto, check the server log file (``var/log/server.log``) +for entries showing that the plugin was loaded and its connector was +registered. For example: + +.. code-block:: none + + INFO main com.facebook.presto.server.PluginManagerUtil -- Loading plugin /opt/presto-server/plugin/gsheets -- + INFO main com.facebook.presto.server.PluginManagerUtil Installing com.facebook.presto.google.sheets.SheetsPlugin + INFO main com.facebook.presto.server.PluginManager Registering connector gsheets + INFO main com.facebook.presto.server.PluginManagerUtil -- Finished loading plugin /opt/presto-server/plugin/gsheets -- + +If the server log shows ``======== SERVER STARTED ========``, the plugin was +loaded successfully. + +Troubleshooting +--------------- + +**Server fails to start with "No factory for connector"** + +.. code-block:: none + + ERROR main com.facebook.presto.server.PrestoServer No factory for connector gsheets + java.lang.IllegalArgumentException: No factory for connector gsheets + +This error indicates that the connector plugin has not been deployed. Verify +that: + +* The plugin directory exists in the Presto plugin directory. +* The plugin directory contains the required JAR files. +* Presto has been restarted after deploying the plugin. + +**Plugin directory is empty or contains incorrect JARs** + +Each plugin directory must contain the plugin JAR file and all of its +transitive dependencies. If a required JAR file is missing, the plugin may +fail to load or the connector may produce errors at runtime. + +See Also +-------- + +* :doc:`deployment` -- Deploying Presto +* :doc:`/develop/spi-overview` -- SPI Overview, including information about + building plugins from source