How to use JDBC and PSQL to connect to a virtual warehouse instance - Hologres

Si une instance Hologres comporte plusieurs entrepôts virtuels, vous pouvez cibler un entrepôt spécifique lors de la connexion ou changer d'entrepôt en cours de session sans vous reconnecter. Cette rubrique explique comment spécifier un entrepôt virtuel dans les chaînes de connexion JDBC et psql, et comment basculer d'un entrepôt à l'autre via SQL après la connexion.

Connexion via JDBC

Format de la chaîne de connexion

Sans entrepôt virtuel (utilise votre entrepôt virtuel par défaut) :

jdbc:postgresql:<Endpoint>:<Port>/<database_name>

Avec un entrepôt virtuel :

jdbc:postgresql://<Endpoint>:<Port>/<database_name>@<warehouse_name>

Paramètres

Paramètre	Obligatoire	Description
`Endpoint`	Oui	Point de terminaison de l'instance Hologres. Accédez à la console Hologres, cliquez sur Instances dans le volet de navigation de gauche, sélectionnez l'instance cible et repérez le point de terminaison dans la section Network Information de la page Instance Details. Sélectionnez le point de terminaison correspondant à votre environnement réseau ; l'utilisation d'un point de terminaison incorrect entraînera l'échec de la connexion.
`Port`	Oui	Port de l'instance Hologres. Vous le trouverez dans la même section Network Information.
`database_name`	Oui	Nom de la base de données Hologres. Lors de la création d'une instance, le système génère automatiquement la base de données postgres. Les ressources de la base de données postgres étant limitées, nous vous recommandons de créer une base de données dédiée pour vos charges de travail métier. Exemple : `demo`.
`warehouse_name`	Non	Entrepôt virtuel à utiliser pour cette connexion. Si ce paramètre est omis, la connexion s'établit via votre entrepôt virtuel par défaut. Pour changer d'entrepôt après la connexion, utilisez SET current_warehouse.

Exemples

Sans entrepôt virtuel — connexion à la base de données demo via l'entrepôt virtuel par défaut :

jdbc:postgresql://hgpostcn-cn-zz4xxxxxxxxxx-cn-shenzhen-vpc-st.hologres.aliyuncs.com:80/demo

Avec un entrepôt virtuel — connexion à la base de données demo via l'entrepôt warehouse_1 :

jdbc:postgresql://hgpostcn-cn-zz4xxxxxxxxxx-cn-shenzhen-vpc-st.hologres.aliyuncs.com:80/demo@warehouse_1

Priorité de routage vers l'entrepôt virtuel

Si la chaîne de connexion ne précise pas explicitement d'entrepôt virtuel, Hologres détermine l'entrepôt à utiliser selon l'ordre de priorité suivant :

L'entrepôt virtuel indiqué dans la chaîne de connexion, comme illustré dans les exemples précédents.
Votre entrepôt virtuel par défaut au niveau utilisateur, si vous en avez défini un en appelant hg_set_user_default_warehouse.
L'entrepôt virtuel par défaut de l'instance, init_warehouse, utilisé uniquement si aucun des deux paramètres précédents n'est configuré.

Pour vérifier l'entrepôt virtuel effectivement utilisé par la connexion actuelle, exécutez :

SELECT current_warehouse();

Routage automatique des requêtes d'écriture (DML)

Le paramètre Grand Unified Configuration (GUC) hg_experimental_enable_warehouse_dml_auto_routing régit le routage des requêtes d'écriture (DML) entre les entrepôts virtuels. Ce paramètre est on par défaut. Pour confirmer sa valeur actuelle, exécutez SHOW hg_experimental_enable_warehouse_dml_auto_routing;. Tant que le paramètre reste sur on, les requêtes d'écriture sont automatiquement acheminées vers l'entrepôt virtuel leader pour exécution ; les écritures aboutissent donc même si votre connexion utilise un entrepôt non leader.

Si vous désactivez ce paramètre off, les requêtes d'écriture émises depuis un entrepôt virtuel non leader seront rejetées. En revanche, les requêtes d'écriture lancées directement sur l'entrepôt virtuel leader continueront de fonctionner normalement.

Connexion via psql

Format de la chaîne de connexion

Sans entrepôt virtuel (utilise votre entrepôt virtuel par défaut) :

PGUSER="<AccessKey_ID>" PGPASSWORD="<AccessKey_Secret>" psql -h <Endpoint> -p <Port> -d <database_name>

Avec un entrepôt virtuel :

PGUSER="<AccessKey_ID>" PGPASSWORD="<AccessKey_Secret>" psql -h <Endpoint> -p <Port> -d <database_name>@<warehouse_name>

Remarque

L'indicateur -d accepte <database_name>@<warehouse_name> comme une seule valeur. La partie @<warehouse_name> ne constitue pas un indicateur distinct ; elle est simplement ajoutée au nom de la base de données.

Paramètres

Paramètre	Obligatoire	Description
`AccessKey_ID`	Oui	Compte Alibaba Cloud : votre AccessKey ID. Obtenez-le depuis la page AccessKey Management. Compte personnalisé : votre nom d'utilisateur, par exemple `BASIC$abc`.
`AccessKey_Secret`	Oui	Compte Alibaba Cloud : votre AccessKey Secret. Compte personnalisé : votre mot de passe.
`Endpoint`	Oui	Point de terminaison de l'instance Hologres. Disponible sur la page Instance Details de la console Hologres.
`Port`	Oui	Port de l'instance Hologres. Visible sur la même page Instance Details.
`database_name`	Oui	Nom de la base de données Hologres. Lors de la création d'une instance, le système génère automatiquement la base de données postgres. Les ressources de la base de données postgres étant limitées, nous vous recommandons de créer une base de données dédiée pour vos charges de travail métier. Exemple : `demo`.
`warehouse_name`	Non	Entrepôt virtuel à utiliser pour cette connexion. Ajoutez-le au paramètre `database_name` sous la forme `<database_name>@<warehouse_name>`. Si ce paramètre est omis, la connexion s'établit via votre entrepôt virtuel par défaut.

Exemples

Ligne de commande — sans entrepôt virtuel :

PGUSER="xxx" PGPASSWORD="xxx" psql -h hgpostcn-cn-zz4xxxxxxxxxx-cn-shenzhen-vpc-st.hologres.aliyuncs.com -p 80 -d demo

Ligne de commande — avec un entrepôt virtuel :

PGUSER="xxx" PGPASSWORD="xxx" psql -h hgpostcn-cn-zz4xxxxxxxxxx-cn-shenzhen-vpc-st.hologres.aliyuncs.com -p 80 -d demo@warehouse_1

Changer d'entrepôt virtuel via SQL

Disponible à partir de Hologres V4.0.

Utilisez SET current_warehouse pour basculer vers un autre entrepôt virtuel sur la connexion active sans vous reconnecter. Pour connaître l'entrepôt actif à tout moment, exécutez SHOW current_warehouse.

Utilisation de base :

-- Switch to a different virtual warehouse
SET current_warehouse = <warehouse_name>;

-- Verify the active virtual warehouse
SHOW current_warehouse;

Basculer puis revenir à l'entrepôt initial — utile lorsque vous devez utiliser temporairement un autre entrepôt avant de reprendre le précédent :

-- Record the current warehouse
SHOW current_warehouse;

-- Switch to a different warehouse
SET current_warehouse = warehouse_2;

-- Verify the switch
SHOW current_warehouse;

-- Restore the original warehouse when done
SET current_warehouse = <original_warehouse_name>;

Remarques d'utilisation

Le changement d'entrepôt préserve l'intégralité de l'état de la session, y compris les variables Grand Unified Configuration (GUC) et les instructions préparées.
Ce paramètre s'applique uniquement au niveau de la session. Toute tentative de définition au niveau de la base de données ou de l'utilisateur renvoie l'erreur suivante : This can only be set at session level.
L'utilisateur actuel doit disposer des autorisations nécessaires sur l'entrepôt virtuel cible. En l'absence des permissions requises, la commande renvoie : Permission denied for warehouse "xxx".
Le basculement n'est pas pris en charge pour les connexions associées à une table temporaire active (TEMP TABLE).