Updated on 2026-11-12 GMT+08:00

Creating a Foreign Server

To create a foreign server for HDFS, you need to create a user and database and provide the necessary permissions for the foreign table.

Creating a User and a Database and Granting the User Foreign Table Permissions

In the following example, a common user dbuser and a database mydatabase are created. Then, an administrator is used to grant foreign table permissions to user dbuser.

  1. Connect to the default database gaussdb as a database administrator through the database client tool provided by DWS.

    For example, use the gsql client to connect to the database by running the following command:

    1
    gsql -d gaussdb -h 192.168.2.30 -U dbadmin -p 8000 -W password -r
    

  2. Create a common user and use it to create a database.

    Create a user named dbuser that has the permission to create databases.

    1
    CREATE USER dbuser WITH CREATEDB PASSWORD 'password';
    
    Switch to the created user.
    1
    SET ROLE dbuser PASSWORD 'password';
    
    Run the following command to create a database:
    1
    CREATE DATABASE mydatabase;
    

    Query the database.

    1
    SELECT * FROM pg_database;
    

    The database is successfully created if the returned result contains information about mydatabase.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    datname   | datdba | encoding | datcollate | datctype | datistemplate | datallowconn | datconnlimit | datlastsysoid | datfrozenxid | dattablespace | datcompatibility |                       datacl
    
    ------------+--------+----------+------------+----------+---------------+--------------+--------------+---------------+--------------+---------------+------------------+--------------------------------------
    --------------
     template1  |     10 |        0 | C          | C        | t             | t            |           -1 |         14146 |         1351 |          1663 | ORA              | {=c/Ruby,Ruby=CTc/Ruby}
     template0  |     10 |        0 | C          | C        | t             | f            |           -1 |         14146 |         1350 |          1663 | ORA              | {=c/Ruby,Ruby=CTc/Ruby}
     gaussdb   |     10 |        0 | C          | C        | f             | t            |           -1 |         14146 |         1352 |          1663 | ORA              | {=Tc/Ruby,Ruby=CTc/Ruby,chaojun=C/Ruby,hu
    obinru=C/Ruby}
     mydatabase |  17000 |        0 | C          | C        | f             | t            |           -1 |         14146 |         1351 |          1663 | ORA              |
    (4 rows)
    

  3. Grant the permissions for creating foreign servers and using foreign tables to a common user as the administrator.

    Use the connection to create a database as a database administrator.

    You can use the gsql client to run the following command, switching to an administrator user, and connect to the new database:
    1
    \c mydatabase dbadmin;
    

    Enter the password as prompted.

    Note that you must use the administrator account to connect to the database where a foreign server is to be created and foreign tables are used; and then grant permissions to the common user.

    By default, only system administrators can create foreign servers. Common users can create foreign servers only after being authorized. Run the following command to grant the permission:
    1
    GRANT ALL ON FOREIGN DATA WRAPPER hdfs_fdw TO dbuser;
    

    The name of FOREIGN DATA WRAPPER must be hdfs_fdw. dbuser is the username for creating SERVER.

    Run the following command to grant the user the permission to use foreign tables:

    1
    ALTER USER dbuser USEFT;
    

    Query for the user.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    SELECT r.rolname, r.rolsuper, r.rolinherit,
      r.rolcreaterole, r.rolcreatedb, r.rolcanlogin,
      r.rolconnlimit, r.rolvalidbegin, r.rolvaliduntil,
      ARRAY(SELECT b.rolname
            FROM pg_catalog.pg_auth_members m
            JOIN pg_catalog.pg_roles b ON (m.roleid = b.oid)
            WHERE m.member = r.oid) as memberof
    , r.rolreplication
    , r.rolauditadmin
    , r.rolsystemadmin
    , r.roluseft
    FROM pg_catalog.pg_roles r
    ORDER BY 1;
    

    The authorization is successful if the dbuser information in the returned result contains the UseFT permission.

    1
    2
    3
    4
    5
     rolname  | rolsuper | rolinherit | rolcreaterole | rolcreatedb | rolcanlogin | rolconnlimit | rolvalidbegin | rolvaliduntil | memberof | rolreplication | rolauditadmin | rolsystemadmin | roluseft
    -----------+----------+------------+---------------+-------------+-------------+--------------+---------------+---------------+----------+----------------+---------------+----------------+----------
     dbuser    | f        | t          | f             | t           | t           |           -1 |               |               | {}       | f              | f             | f              | t
     lily      | f        | t          | f             | f           | t           |           -1 |               |               | {}       | f              | f             | f              | f
     Ruby       | t        | t          | t             | t           | t           |           -1 |               |               | {}       | t              | t             | t              | t
    

Manually Creating a Foreign Server

  1. Connect to the default database postgres as a database administrator through the database client tool provided by DWS.

    You can use the gsql client to log in to the database in either of the following ways:

    You can use either of the following methods to create the connection:

    • If you have logged in to the gsql client, run the following command to switch the database and user:
      1
      \c postgres dbadmin;
      

      Enter the password as prompted.

    • If you have not logged in to the gsql client or have exited the gsql client by running the \q command, run the following command to reconnect to it:
      1
      gsql -d postgres -h 192.168.2.30 -U dbadmin -p 8000 -W password -r
      

  2. Run the following command to query the information about the foreign server that is automatically created:

    1
    SELECT * FROM pg_foreign_server;
    

    The returned result is as follows:

    1
    2
    3
    4
    5
                         srvname                      | srvowner | srvfdw | srvtype | srvversion | srvacl |                                                     srvoptions
    --------------------------------------------------+----------+--------+---------+------------+--------+---------------------------------------------------------------------------------------------------------------------
     gsmpp_server                                     |       10 |  13673 |         |            |        |
     hdfs_server_8f79ada0_d998_4026_9020_80d6de2692ca |    16476 |  13685 |         |            |        | {"address=192.168.1.245:25000,192.168.1.218:25000",hdfscfgpath=/MRS/8f79ada0-d998-4026-9020-80d6de2692ca,type=hdfs}
    (2 rows)
    

    In the query result, each row contains the information about a foreign server. The foreign server associated with the MRS data source connection contains the following information:

    • The value of srvname contains hdfs_server and the ID of the MRS cluster, which is the same as the MRS ID in the cluster list on the MRS management console.
    • The address parameter in the srvoptions field contains the IP addresses and ports of the primary and standby nodes in the MRS cluster.

    You can find the foreign server you want based on the above information and record the values of its srvname and srvoptions.

  3. Switch to the user who is about to create a foreign server to connect to the corresponding database.

    In this example, run the following command to use common user dbuser created in Creating a User and a Database and Granting the User Foreign Table Permissions to connect to mydatabase created by the user:
    1
    \c mydatabase dbuser;
    

  4. Create a foreign server.

    For details about the syntax for creating an external server, see "CREATE SERVER" in Data Warehouse Service (DWS) SQL Syntax Reference. For example:

    1
    2
    3
    4
    5
    6
    7
    CREATE SERVER hdfs_server_8f79ada0_d998_4026_9020_80d6de2692cahdfs_server FOREIGN DATA WRAPPER HDFS_FDW 
    OPTIONS 
    (
    address '192.168.1.245:25000,192.168.1.218:25000', 
    hdfscfgpath '/MRS/8f79ada0-d998-4026-9020-80d6de2692ca',
    type 'hdfs'
    );
    

    Mandatory parameters are described as follows:

    Table 1 Parameters for creating a server

    Parameter

    Description

    Example

    SERVER

    Specifies the name of the foreign server. You can configure the name as required.

    In this example, specify the name to the value of the srvname field recorded in 2, such as hdfs_server_8f79ada0_d998_4026_9020_80d6de2692ca.

    Resources in different databases are isolated. Therefore, the names of foreign servers in different databases can be the same.

    hdfs_server

    FOREIGN DATA WRAPPER

    Specifies the name of the foreign data wrapper. The value can only be HDFS_FDW, which already exists in the database.

    hdfs_fdw

    OPTIONS

    Sets the following parameters to the values under srvoptions recorded in 2.
    • address

      Specifies the IP address and port number of the primary and standby nodes of the HDFS cluster.

    • hdfscfgpath

      Specifies the configuration file path of the HDFS cluster. This parameter is available only when type is HDFS. You can set only one path.

    • type

      Its value is hdfs, which indicates that HDFS_FDW connects to HDFS.

    -

  5. View the foreign server.

    1
    SELECT * FROM pg_foreign_server WHERE srvname='hdfs_server_8f79ada0_d998_4026_9020_80d6de2692ca';
    

    The server is successfully created if the returned result is as follows:

    1
    2
    3
    4
                         srvname                      | srvowner | srvfdw | srvtype | srvversion | srvacl |                                                     srvoptions
    --------------------------------------------------+----------+--------+---------+------------+--------+---------------------------------------------------------------------------------------------------------------------
     hdfs_server_8f79ada0_d998_4026_9020_80d6de2692ca |    16476 |  13685 |         |            |        | {"address=192.168.1.245:25000,192.168.1.218:25000",hdfscfgpath=/MRS/8f79ada0-d998-4026-9020-80d6de2692ca,type=hdfs}
    (1 row)