External Apache Hive metastore (legacy)

important

Cette documentation a été retirée et pourrait ne pas être mise à jour.

remarque

L’utilisation de métastores externes est un modèle de gouvernance des données hérité. Databricks vous recommande de passer à Unity Catalog. Unity Catalog simplifie la sécurité et la gouvernance de vos données en fournissant un emplacement central pour administrer et auditer l'accès aux données dans plusieurs Workspaces de votre compte. Voir Qu'est-ce que Unity Catalog ?.

Cet article décrit comment configurer les clusters Databricks pour se connecter à des métastores Apache Hive externes existants. Il fournit des informations sur les modes de déploiement des métastores, la configuration réseau recommandée et les exigences de configuration des clusters, suivies des instructions pour configurer les clusters afin de se connecter à un métastore externe. Pour les versions de bibliothèque Hive incluses dans Databricks Runtime, consultez les notes de version Databricks Runtime pertinentes.

important

Si vous utilisez Azure Database pour MySQL comme metastore externe, vous devez modifier la valeur de la propriété lower_case_table_names de 1 (valeur par default) à 2 dans la configuration de la base de données côté serveur. Pour plus de détails, consultez Sensibilité à la casse de l'identifiant.
Si vous utilisez une base de données de metastore en lecture seule, Databricks vous recommande fortement de définir spark.databricks.delta.catalog.update.enabled sur false sur vos clusters pour de meilleures performances.

Modes de déploiement du Hive metastore

Dans un environnement de production, vous pouvez déployer un Hive metastore selon deux modes : local et distant.

Mode local

Le client de métastore exécuté au sein d'un cluster se connecte directement à la base de données de métastore sous-jacente via JDBC.

Mode distant

Au lieu de se connecter directement à la base de données sous-jacente, le client du metastore se connecte à un service de metastore distinct via le protocole Thrift. Le service metastore se connecte à la base de données sous-jacente. Lors de l'exécution d'un metastore en mode distant, DBFS n'est *pas pris en charge*.

Pour plus de détails sur ces modes de déploiement, consultez la documentation Hive.

remarque

Les exemples dans ce document utilisent MySQL comme base de données de metastore sous-jacente.

Configuration réseau

Les clusters Databricks s'exécutent dans un cloud privé virtuel (VPC). Nous vous recommandons de configurer le Hive metastore externe dans un nouveau Virtual Private Cloud (VPC), puis d'appairer ces deux Virtual Private Cloud (VPC) afin que les clusters se connectent au Hive metastore en utilisant une adresse IP privée. L'appairage VPC fournit des instructions détaillées sur la manière d'associer le Virtual Private Cloud (VPC) utilisé par les clusters Databricks et le Virtual Private Cloud (VPC) où réside le metastore. Après avoir appairé les Virtual Private Cloud (VPC), vous pouvez tester la connectivité réseau d'un cluster au Virtual Private Cloud (VPC) du metastore en exécutant la commande suivante dans un Notebook :

Bash
%sh
nc -vz <DNS name or private IP> <port>

où

<DNS name or private IP> est le nom DNS ou l'adresse IP privée de la base de données MySQL (pour le mode local) ou du service metastore (pour le mode distant). Si vous utilisez un nom DNS ici, assurez-vous que l'adresse IP résolue est privée.
<port> est le port de la base de données MySQL ou le port du service de metastore.

Configurations des clusters

Vous devez définir trois ensembles d'options de configuration pour connecter un cluster à un métastore externe :

Les options Spark configurent Spark avec la version du Hive metastore et les JARs pour le client metastore.
Les options Hive configurent le client metastore pour se connecter au metastore externe.
Un ensemble facultatif d'options Hadoop configure les options du système de fichiers.

Options de configuration Spark

Définissez spark.sql.hive.metastore.version sur la version de votre Hive metastore et spark.sql.hive.metastore.jars comme suit :

Hive 0,13 : ne définissez pas spark.sql.hive.metastore.jars.

remarque

Hive 1.2.0 et 1.2.1 ne sont pas le métastore intégré sur Databricks Runtime 7.0 et versions ultérieures. Si vous souhaitez utiliser Hive 1.2.0 ou 1.2.1 avec Databricks Runtime 7.0 et versions ultérieures, suivez la procédure décrite dans download les JAR du métastore et y faire référence.

Hive 2.3.7 (Databricks Runtime 7.0 à 9.x) ou Hive 2.3.9 (Databricks Runtime 10.0 et versions supérieures) : définissez spark.sql.hive.metastore.jars sur builtin.
Pour toutes les autres versions de Hive, Databricks vous recommande de download les JAR du metastore et de définir la configuration spark.sql.hive.metastore.jars pour qu’elle pointe vers les JAR downloaded à l’aide de la procédure décrite dans download les JAR du metastore et pointez-les.

download les JAR du metastore et pointez vers eux.

Créez un cluster avec spark.sql.hive.metastore.jars défini sur maven et spark.sql.hive.metastore.version pour correspondre à la version de votre métastore.
Lorsque le cluster est en cours d'exécution, recherchez dans le log du driver une ligne similaire à la suivante :
```
17/11/18 22:41:19 INFO IsolatedClientLoader: Downloaded metastore jars to <path>
```
Le répertoire <path> est l'emplacement des JAR téléchargés sur le nœud driver du cluster.

Vous pouvez également exécuter le code suivant dans un notebook Scala pour afficher l'emplacement des JAR :
Scala
```
import com.typesafe.config.ConfigFactory
val path = ConfigFactory.load().getString("java.io.tmpdir")

println(s"\nHive JARs are downloaded to the path: $path \n")
```
Exécutez %sh cp -r <path> /dbfs/hive_metastore_jar (en remplaçant <path> par les informations de votre cluster) pour copier ce répertoire dans un répertoire de la racine DBFS appelé hive_metastore_jar via le client DBFS sur le nœud du Driver.
Créez un script d'initialisation qui copie /dbfs/hive_metastore_jar dans le système de fichiers local du nœud, en veillant à ce que le script d'initialisation se mette en veille quelques secondes avant d'accéder au client DBFS. Cela garantit que le client est prêt.
Définissez spark.sql.hive.metastore.jars pour utiliser ce répertoire. Si votre script d'initialisation copie /dbfs/hive_metastore_jar vers /databricks/hive_metastore_jars/, définissez spark.sql.hive.metastore.jars sur /databricks/hive_metastore_jars/*. L'emplacement doit inclure le /* final.
Redémarrez le cluster.

Options de configuration Hive

Cette section décrit les options spécifiques à Hive.

Options de configuration pour le mode local

Pour vous connecter à un métastore externe en mode local, définissez les options de configuration Hive suivantes :

ini
# JDBC connect string for a JDBC metastore
javax.jdo.option.ConnectionURL jdbc:mysql://<metastore-host>:<metastore-port>/<metastore-db>

# Username to use against metastore database
javax.jdo.option.ConnectionUserName <mysql-username>

# Password to use against metastore database
javax.jdo.option.ConnectionPassword <mysql-password>

# Driver class name for a JDBC metastore (Runtime 3.4 and later)
javax.jdo.option.ConnectionDriverName org.mariadb.jdbc.Driver

# Driver class name for a JDBC metastore (prior to Runtime 3.4)
# javax.jdo.option.ConnectionDriverName com.mysql.jdbc.Driver

où

<metastore-host> et <metastore-port> sont l'hôte et le port d'écoute de votre instance MySQL.
<metastore-db> est le nom de la base de données MySQL qui contient toutes les tables du metastore.
<mysql-username> et <mysql-password> spécifient le nom d'utilisateur et le mot de passe de votre compte MySQL qui a un accès en lecture/écriture à <metastore-db>.

remarque

Utilisez le Driver MariaDB pour communiquer avec les bases de données MySQL.
Pour les environnements de production, nous vous recommandons de définir hive.metastore.schema.verification sur true. Cela empêche le client Hive metastore de modifier implicitement le schéma de la base de données metastore lorsque la version du client metastore ne correspond pas à la version de la base de données metastore. Lorsque vous activez ce paramètre pour les versions de client Metastore inférieures à Hive 1.2.0, assurez-vous que le client Metastore dispose de l'autorisation d'écriture dans la base de données Metastore (afin d'éviter le problème décrit dans HIVE-9749).
- Pour Hive metastore 1.2.0 et supérieur, définissez hive.metastore.schema.verification.record.version sur true pour activer hive.metastore.schema.verification.
- Pour Hive metastore 2.1.1 et supérieur, définissez hive.metastore.schema.verification.record.version sur true car il est défini sur false par default.

Options de configuration pour le mode distant

Pour vous connecter à un métastore externe en mode distant, définissez l'option de configuration Hive suivante :

ini
# Thrift URI for the remote metastore. Used by metastore client to connect to remote metastore.
hive.metastore.uris thrift://<metastore-host>:<metastore-port>

où <metastore-host> et <metastore-port> sont l'hôte et le port d'écoute de votre service Hive metastore.

Options du système de fichiers

Si vous souhaitez utiliser un profil d'instance et définir AssumeRole, vous devez définir :

fs.s3a.credentialsType à la AssumeRole
fs.s3a.stsAssumeRole.arn à l'Amazon Resource Name (ARN) du rôle à assumer

Configurer un métastore externe à l’aide de l’interface utilisateur

Pour configurer un métastore externe à l'aide de l'interface utilisateur de Databricks :

Cliquez sur le bouton Clusters dans la barre latérale.
Cliquez sur Créer un cluster .

Saisissez les options de configuration Spark suivantes :

Mode local

ini
# Hive specific configuration options.
# spark.hadoop prefix is added to make sure these Hive specific options will propagate to the metastore client.
spark.hadoop.javax.jdo.option.ConnectionURL jdbc:mysql://<mysql-host>:<mysql-port>/<metastore-db>

# Driver class name for a JDBC metastore (Runtime 3.4 and later)
spark.hadoop.javax.jdo.option.ConnectionDriverName org.mariadb.jdbc.Driver

# Driver class name for a JDBC metastore (prior to Runtime 3.4)
# spark.hadoop.javax.jdo.option.ConnectionDriverName com.mysql.jdbc.Driver

spark.hadoop.javax.jdo.option.ConnectionUserName <mysql-username>
spark.hadoop.javax.jdo.option.ConnectionPassword <mysql-password>

# Spark specific configuration options
spark.sql.hive.metastore.version <hive-version>
# Skip this one if <hive-version> is 0.13.x.
spark.sql.hive.metastore.jars <hive-jar-source>

# If you need to use AssumeRole, uncomment the following settings.
# spark.hadoop.fs.s3a.credentialsType AssumeRole
# spark.hadoop.fs.s3a.stsAssumeRole.arn <sts-arn>

Mode distant

ini
# Hive specific configuration option
# spark.hadoop prefix is added to make sure these Hive specific options will propagate to the metastore client.
spark.hadoop.hive.metastore.uris thrift://<metastore-host>:<metastore-port>

# Spark specific configuration options
spark.sql.hive.metastore.version <hive-version>
# Skip this one if <hive-version> is 0.13.x.
spark.sql.hive.metastore.jars <hive-jar-source>

# If you need to use AssumeRole, uncomment the following settings.
# spark.hadoop.fs.s3a.credentialsType AssumeRole
# spark.hadoop.fs.s3a.stsAssumeRole.arn <sts-arn>

Poursuivez la configuration de votre cluster, en suivant les instructions de la référence de configuration de compute.
Cliquez sur Créer un cluster pour créer le cluster.

Configurez un metastore externe à l'aide d'un script d'initialisation

Les scripts d'initialisation vous permettent de vous connecter à un Hive metastore existant sans avoir à configurer manuellement les configurations requises.

Mode local

Créez le répertoire de base dans lequel vous souhaitez stocker le script d'initialisation s'il n'existe pas. L'exemple suivant utilise dbfs:/databricks/scripts.
Exécutez l'extrait de code suivant dans un Notebook. L'extrait crée le script d'initialisation /databricks/scripts/external-metastore.sh dans le système de fichiers Databricks (DBFS). Alternativement, vous pouvez utiliser l'Opération put de l'API REST DBFS pour créer le script d'initialisation. Ce script d'initialisation écrit les options de configuration requises dans un fichier de configuration nommé 00-custom-spark.conf dans un format de type JSON sous /databricks/driver/conf/ à l'intérieur de chaque nœud du cluster. Databricks fournit des configurations Spark default dans le fichier /databricks/driver/conf/spark-branch.conf. Les fichiers de configuration du répertoire /databricks/driver/conf s'appliquent dans l'ordre alphabétique inverse. Si vous souhaitez modifier le nom du fichier 00-custom-spark.conf, assurez-vous qu'il continue à s'appliquer avant le fichier spark-branch.conf.

Scala
Python

Scala
dbutils.fs.put(
    "/databricks/scripts/external-metastore.sh",
    """#!/bin/sh
      |# Loads environment variables to determine the correct JDBC driver to use.
      |source /etc/environment
      |# Quoting the label (i.e. EOF) with single quotes to disable variable interpolation.
      |cat << 'EOF' > /databricks/driver/conf/00-custom-spark.conf
      |[driver] {
      |    # Hive specific configuration options for metastores in local mode.
      |    # spark.hadoop prefix is added to make sure these Hive specific options will propagate to the metastore client.
      |    "spark.hadoop.javax.jdo.option.ConnectionURL" = "jdbc:mysql://<mysql-host>:<mysql-port>/<metastore-db>"
      |    "spark.hadoop.javax.jdo.option.ConnectionUserName" = "<mysql-username>"
      |    "spark.hadoop.javax.jdo.option.ConnectionPassword" = "<mysql-password>"
      |
      |    # Spark specific configuration options
      |    "spark.sql.hive.metastore.version" = "<hive-version>"
      |    # Skip this one if <hive-version> is 0.13.x.
      |    "spark.sql.hive.metastore.jars" = "<hive-jar-source>"
      |
      |    # If you need to use AssumeRole, uncomment the following settings.
      |    # "spark.hadoop.fs.s3a.credentialsType" = "AssumeRole"
      |    # "spark.hadoop.fs.s3a.stsAssumeRole.arn" = "<sts-arn>"
      |EOF
      |
      |case "$DATABRICKS_RUNTIME_VERSION" in
      |  "")
      |     DRIVER="com.mysql.jdbc.Driver"
      |     ;;
      |  *)
      |     DRIVER="org.mariadb.jdbc.Driver"
      |     ;;
      |esac
      |# Add the JDBC driver separately since must use variable expansion to choose the correct
      |# driver version.
      |cat << EOF >> /databricks/driver/conf/00-custom-spark.conf
      |    "spark.hadoop.javax.jdo.option.ConnectionDriverName" = "$DRIVER"
      |}
      |EOF
      |""".stripMargin,
    overwrite = true
)

Python
contents = """#!/bin/sh
# Loads environment variables to determine the correct JDBC driver to use.
source /etc/environment
# Quoting the label (i.e. EOF) with single quotes to disable variable interpolation.
cat << 'EOF' > /databricks/driver/conf/00-custom-spark.conf
[driver] {
    # Hive specific configuration options for metastores in local mode.
    # spark.hadoop prefix is added to make sure these Hive specific options will propagate to the metastore client.
    "spark.hadoop.javax.jdo.option.ConnectionURL" = "jdbc:mysql://<mysql-host>:<mysql-port>/<metastore-db>"
    "spark.hadoop.javax.jdo.option.ConnectionUserName" = "<mysql-username>"
    "spark.hadoop.javax.jdo.option.ConnectionPassword" = "<mysql-password>"

    # Spark specific configuration options
    "spark.sql.hive.metastore.version" = "<hive-version>"
    # Skip this one if <hive-version> is 0.13.x.
    "spark.sql.hive.metastore.jars" = "<hive-jar-source>"

    # If you need to use AssumeRole, uncomment the following settings.
    # "spark.hadoop.fs.s3a.credentialsType" = "AssumeRole"
    # "spark.hadoop.fs.s3a.stsAssumeRole.arn" = "<sts-arn>"
EOF

case "$DATABRICKS_RUNTIME_VERSION" in
  "")
    DRIVER="com.mysql.jdbc.Driver"
    ;;
  *)
    DRIVER="org.mariadb.jdbc.Driver"
    ;;
esac
# Add the JDBC driver separately since must use variable expansion to choose the correct
# driver version.
cat << EOF >> /databricks/driver/conf/00-custom-spark.conf
    "spark.hadoop.javax.jdo.option.ConnectionDriverName" = "$DRIVER"
}
EOF"""

dbutils.fs.put(
    file = "/databricks/scripts/external-metastore.sh",
    contents = contents,
    overwrite = True
)

Configurez votre cluster avec le script d'initialisation.
Redémarrez le cluster.

Mode distant

Créez le répertoire de base dans lequel vous souhaitez stocker le script d'initialisation s'il n'existe pas. L'exemple suivant utilise dbfs:/databricks/scripts.
Exécutez l'extrait de code suivant dans un notebook :

Scala
Python

Scala
dbutils.fs.put(
    "/databricks/scripts/external-metastore.sh",
    """#!/bin/sh
      |
      |# Quoting the label (i.e. EOF) with single quotes to disable variable interpolation.
      |cat << 'EOF' > /databricks/driver/conf/00-custom-spark.conf
      |[driver] {
      |    # Hive specific configuration options for metastores in remote mode.
      |    # spark.hadoop prefix is added to make sure these Hive specific options will propagate to the metastore client.
      |    "spark.hadoop.hive.metastore.uris" = "thrift://<metastore-host>:<metastore-port>"
      |
      |    # Spark specific configuration options
      |    "spark.sql.hive.metastore.version" = "<hive-version>"
      |    # Skip this one if <hive-version> is 0.13.x.
      |    "spark.sql.hive.metastore.jars" = "<hive-jar-source>"
      |
      |    # If you need to use AssumeRole, uncomment the following settings.
      |    # "spark.hadoop.fs.s3a.credentialsType" = "AssumeRole"
      |    # "spark.hadoop.fs.s3a.stsAssumeRole.arn" = "<sts-arn>"
      |}
      |EOF
      |""".stripMargin,
    overwrite = true
)

Python
contents = """#!/bin/sh

# Quoting the label (i.e. EOF) with single quotes to disable variable interpolation.
cat << 'EOF' > /databricks/driver/conf/00-custom-spark.conf
[driver] {
    # Hive specific configuration options for metastores in remote mode.
    # spark.hadoop prefix is added to make sure these Hive specific options will propagate to the metastore client.
    "spark.hadoop.hive.metastore.uris" = "thrift://<metastore-host>:<metastore-port>"

    # Spark specific configuration options
    "spark.sql.hive.metastore.version" = "<hive-version>"
    # Skip this one if <hive-version> is 0.13.x.
    "spark.sql.hive.metastore.jars" = "<hive-jar-source>"

    # If you need to use AssumeRole, uncomment the following settings.
    # "spark.hadoop.fs.s3a.credentialsType" = "AssumeRole"
    # "spark.hadoop.fs.s3a.stsAssumeRole.arn" = "<sts-arn>"
}
EOF"""

dbutils.fs.put(
  file = "/databricks/scripts/external-metastore.sh",
  contents = contents,
  overwrite = True
)

Configurez votre cluster avec le script d'initialisation.
Redémarrez le cluster.

Dépannage

Les clusters ne start pas (en raison de paramètres de script d'initialisation incorrects).

Si un script d'initialisation pour la configuration du metastore externe entraîne l'échec de la création du cluster, configurez le script d'initialisation pour consigner, et déboguez le script d'initialisation à l'aide des Logs.

Erreur dans l'instruction SQL : InvocationTargetException

Modèle de message d'erreur dans la trace de pile complète de l'exception :
```
Caused by: javax.jdo.JDOFatalDataStoreException: Unable to open a test connection to the given database. JDBC url = [...]
```
Les informations de connexion JDBC du métastore externe sont mal configurées. Vérifiez le Hostname, le port, le nom d’utilisateur, le mot de passe et le nom de la classe du Driver JDBC configurés. De plus, assurez-vous que le nom d'utilisateur dispose du privilège nécessaire pour accéder à la base de données du métastore.
Modèle de message d'erreur dans la trace de pile complète de l'exception :
```
Required table missing : "`DBS`" in Catalog "" Schema "". DataNucleus requires this table to perform its persistence operations. [...]
```
Base de données du métastore externe non correctement initialisée. Vérifiez que vous avez créé la base de données du metastore et que vous avez inséré le nom de base de données correct dans la chaîne de connexion JDBC. Ensuite, start un nouveau cluster avec les deux options de configuration Spark suivantes :
ini
```
datanucleus.schema.autoCreateTables true
datanucleus.fixedDatastore false
```
Ainsi, la bibliothèque cliente Hive tentera de créer et d’initialiser automatiquement des tables dans la base de données du metastore lorsqu’elle tentera d’y accéder, mais les trouvera absentes.

Erreur dans l'instruction SQL : AnalysisException : Impossible d'instancier org.apache.hadoop.hive.metastore.HiveMetastoreClient

Message d'erreur dans la pile d'exception complète :

The specified datastore driver (driver name) was not found in the CLASSPATH

Le cluster est configuré pour utiliser un driver JDBC incorrect.

Cette erreur peut se produire si un cluster utilisant le Runtime 3.4 ou une version ultérieure est configuré pour utiliser le Driver MySQL plutôt que le Driver MariaDB.

Paramètre datanucleus.autoCreateSchema sur true ne fonctionne pas comme prévu

By default, Databricks définit également datanucleus.fixedDatastore sur true, ce qui empêche toute modification structurelle accidentelle des bases de données du metastore. Par conséquent, la bibliothèque cliente Hive ne peut pas créer de tables de métastore même si vous définissez datanucleus.autoCreateSchema sur true. Cette stratégie est, en général, plus sûre pour les environnements de production, car elle empêche la mise à niveau accidentelle de la base de données du metastore.

Si vous souhaitez utiliser datanucleus.autoCreateSchema pour aider à initialiser la base de données du metastore, assurez-vous de définir datanucleus.fixedDatastore sur false. De plus, vous pouvez souhaiter activer les deux indicateurs après avoir initialisé la base de données du metastore afin d'offrir une meilleure protection à votre environnement de production.

com.amazonaws.AmazonClientException: Impossible d'initialiser un Driver SAX pour créer un lecteur XML

Cette exception peut être levée si la version du cluster est 2.1.1-db5. Ce problème a été corrigé dans la version 2.1.1-db6. Pour 2.1.1-db5, vous pouvez résoudre ce problème en définissant les propriétés JVM suivantes dans les paramètres de spark.driver.extraJavaOptions et spark.executor.extraJavaOptions:

ini
-Djavax.xml.datatype.DatatypeFactory=com.sun.org.apache.xerces.internal.jaxp.datatype.DatatypeFactoryImpl
-Djavax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl
-Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
-Djavax.xml.validation.SchemaFactory:https://www.w3.org/2001/XMLSchema=com.sun.org.apache.xerces.internal.jaxp.validation.XMLSchemaFactory
-Dorg.xml.sax.driver=com.sun.org.apache.xerces.internal.parsers.SAXParser
-Dorg.w3c.dom.DOMImplementationSourceList=com.sun.org.apache.xerces.internal.dom.DOMXSImplementationSourceImpl

Modes de déploiement du Hive metastore​

Configuration réseau​

Configurations des clusters​

Options de configuration Spark​

download les JAR du metastore et pointez vers eux.​

Options de configuration Hive​

Options de configuration pour le mode local​

Options de configuration pour le mode distant​

Options du système de fichiers​

Configurer un métastore externe à l’aide de l’interface utilisateur​

Configurez un metastore externe à l'aide d'un script d'initialisation​

Mode local​

Mode distant​

Dépannage​

Modes de déploiement du Hive metastore

Configuration réseau

Configurations des clusters

Options de configuration Spark

download les JAR du metastore et pointez vers eux.

Options de configuration Hive

Options de configuration pour le mode local

Options de configuration pour le mode distant

Options du système de fichiers

Configurer un métastore externe à l’aide de l’interface utilisateur

Configurez un metastore externe à l'aide d'un script d'initialisation

Mode local

Mode distant

Dépannage