三、Trino406系列 之 客户端
文章目录
- 前言
- 客户端命令行
-
- 要求条件
- 客户端安装
- Running the CLI
- TLS/HTTPS
- JDBC驱动
-
- 需求条件
- 安装
- Registering and configuring the driver
- Connecting
- Connection parameters
- Parameter reference
前言
https://trino.io/docs/current/client/cli.html
客户端是向trino server提交sql查询语句和返回结果的，或以其他方式与Trino和连接的数据源交互。
一些客户端，例如命令行界面，可以直接提供用户界面。像JDBC驱动程序这样的客户端为其他工具提供了连接到Trino的机制。
可用客户端如下：
- Command line interface
- JDBC driver
此外，社区还为Python等平台提供了许多其他客户端，这些客户端可以反过来用于连接使用这些平台的应用程序。
Trino CLI提供了一个基于终端的交互式shell来运行查询。CLI是一个自动执行的JAR文件，这意味着它像普通的UNIX可执行文件一样工作。
客户端命令行
要求条件
CLI要求路径上有一个可用的Java虚拟机。它可以与Java版本8及更高版本一起使用。
CLI通过HTTP/HTTPS使用Trino客户端REST API与集群上的协调器通信。
客户端安装
下载trino-CLI-406-executable.jar（提供的下载路径），将其重命名为trino，使用chmod +x使其可执行，并运行它来显示CLI的版本:
./trino --version
使用命令行命令–help或-h查看所有选项。
Windows用户和无法执行上述步骤的用户，可以使用类似的java命令，带-jar选项运行命令行，并显示版本:
java -jar trino-cli-*-executable.jar --version
该语法可用于以下部分中的示例。此外，使用java命令允许您使用-D语法为java运行时添加配置选项。您可以使用它进行调试和故障排除，例如在指定其他Kerberos调试选项时。
Running the CLI
在交互模式下启动CLI的最小命令指定了Trino集群中协调器的URL:
./trino --server http://trino.example.com:8080
如果成功，您将得到执行命令的提示。使用help命令查看支持的命令列表。使用clear命令清除终端。需要停止并退出命令行，使用exit或quit命令。
trino> help
Supported commands:
QUIT
EXIT
CLEAR
EXPLAIN [ ( option [, ...] ) ] <query>
options: FORMAT { TEXT | GRAPHVIZ | JSON }
TYPE { LOGICAL | DISTRIBUTED | VALIDATE | IO }
DESCRIBE <table>
SHOW COLUMNS FROM <table>
SHOW FUNCTIONS
SHOW CATALOGS [LIKE <pattern>]
SHOW SCHEMAS [FROM <catalog>] [LIKE <pattern>]
SHOW TABLES [FROM <schema>] [LIKE <pattern>]
USE [<catalog>.]<schema>
现在可以运行SQL语句了。处理后，CLI将显示结果和统计信息。
trino> SELECT count(*) FROM tpch.tiny.nation;
_col0
-------
25
(1 row)
Query 20220324_213359_00007_w6hbk, FINISHED, 1 node
Splits: 13 total, 13 done (100.00%)
2.92 [25 rows, 0B] [8 rows/s, 0B/s]
作为启动CLI的一部分，您可以设置默认catalog和schema。这允许您直接查询表，而无需指定catalog和schema。
./trino --server http://trino.example.com:8080 --catalog tpch --schema tiny
trino:tiny> SHOW TABLES;
Table
----------
customer
lineitem
nation
orders
part
partsupp
region
supplier
(8 rows)
您还可以使用USE语句设置默认catalog和schema。
trino> USE tpch.tiny;
USE
trino:tiny>
在交互模式下，还有许多其他选项可以进一步配置CLI:
选项 描述
-- catalog：设置默认的catalog。用户可以使用USE切换catalog和schema
--client-info：添加任意文本作为关于客户端的额外信息。
--client-request-timeout：设置查询处理的持续时间，在此之后，客户端请求将被终止。默认为2m。
--client-tags：添加关于客户端和CLI用户的额外标记信息。多个标签之间用逗号分隔。这些标记可以用作资源组的输入。
--debug：在CLI使用疑难解答时，开启调试信息的显示。显示查询处理统计信息的更多信息。
--disable-auto-suggestion：禁用自动完成建议。
--disable-compression：禁止压缩查询结果。
--editing-mode：将CLI中的键绑定设置为与VI或EMACS编辑器兼容。默认为EMACS。
--http-proxy：配置HTTP代理连接到Trino的URL。
--network-logging：配置为CLI的网络日志记录提供的详细级别。默认为NONE，其他选项为BASIC, HEADERS或BODY。
--no-progress：不显示查询处理进度。
--password：提示输入密码。如果您的Trino server需要密码验证，请使用。您可以将TRINO_PASSWORD环境变量设置为password值，以避免提示。有关详细信息，请参见用户名和密码身份验证(https://trino.io/docs/current/client/cli.html#cli-username-password-auth)。
--schema：设置默认的schema。你可以使用USE命令切换catalog和schema
--server：Trino协调器的HTTP/HTTPS地址和端口。端口必须设置为Trino协调器正在侦听连接的端口。Trino服务器位置默认为http://localhost:8080。
--session：设置一个或多个会话属性。属性可以使用格式为session_property_name=value多次使用。
--socks-proxy：配置SOCKS代理的URL以连接到Trino。
--source：指定连接到Trino的应用程序或源的名称。默认为trino-cli。可以作为资源组的输入。
--timezone：使用时区名称设置会话的时区。默认为工作站上设置的时区。
--user：设置用户名和密码认证的用户名。默认为您的操作系统用户名。如果集群使用不同的用户名或身份验证机制，则可以覆盖默认用户名。
TLS/HTTPS
Trino通常提供HTTPS URL。这意味着CLI和Trino之间的所有网络流量都使用TLS。TLS配置很常见，因为它是任何身份验证的要求。
使用HTTPS URL连接到server:
./trino --server https://trino.example.com
建议TLS实现使用全局受信任的证书。在这种情况下，不需要其他选项，因为运行CLI的JVM可以识别这些证书。
使用下表中的选项进一步配置TLS和证书使用:
Trino JDBC驱动程序允许用户使用基于java的应用程序和运行在JVM中的其他非java应用程序访问Trino。桌面和服务器端应用程序(例如用于报告和数据库开发的应用程序)都使用JDBC驱动程序。
JDBC驱动
需求条件
Trino JDBC驱动有下面的需求：
- java version 8 及以上
- 所有的用户通过JDBC驱动连接Trino一定要授予查询表权限（All users that connect to Trino with the JDBC driver must be granted access to query tables in the system.jdbc schema.）
安装
下载trino-jdbc-406.jar并将其添加到Java应用程序的类路径中。
该驱动程序也可以从Maven Central获得:
<dependency>
<groupId>io.trinogroupId>
<artifactId>trino-jdbcartifactId>
<version>406version>
dependency>
我们建议使用最新版本的JDBC驱动程序。所有可用版本的列表可以在Maven中央存储库中找到。进入对应版本的目录，选择trino-jdbc-xxx.jar文件下载，其中xxx为版本号。
下载后，必须将JAR文件添加到用户将访问Trino的系统的类路径中的目录中。
在你已经下载了JDBC driver且将它添加到classpath，通常需要重启你的应用app为了识别新的driver驱动程序。然后，根据你的需要你可能需要手工注册和配置驱动。
CLI通过HTTP协议和Trino客户端REST API与Trino通信。
Registering and configuring the driver
驱动程序通常在被添加到类路径后由应用程序自动加载。如果您的应用程序没有，例如一些基于gui的SQL编辑器，请阅读本节。在UI中或命令行上注册JDBC驱动程序的步骤取决于您正在使用的特定应用程序。请查看您的申请文件。
注册后，还必须按照以下部分中的描述配置连接信息。
Connecting
当你的驱动下载，注册和配置之后，你的应用就可以连接Trino了。支持以下JDBC URL格式:
jdbc:trino://host:port
jdbc:trino://host:port/catalog
jdbc:trino://host:port/catalog/schema
下面是一个用于创建连接的JDBC URL示例:
jdbc:trino://example.net:8080/hive/sales
这个示例JDBC URL定位在example.net的8080端口上运行的Trino实例，其中定义了hive catalog和schema sales。
注意：通常，JDBC驱动程序类名由您的客户机自动配置。如果不是，在需要驱动程序类名的地方使用io.trino.jdbc.TrinoDriver。
Connection parameters
驱动程序支持各种参数，这些参数可以设置为URL参数，也可以设置为传递给DriverManager的属性。下面两个例子是等价的:
// properties
String url = "jdbc:trino://example.net:8080/hive/sales";
Properties properties = new Properties();
properties.setProperty("user", "test");
properties.setProperty("password", "secret");
properties.setProperty("SSL", "true");
Connection connection = DriverManager.getConnection(url, properties);
// URL parameters
String url = "jdbc:trino://example.net:8443/hive/sales?user=test&password=secret&SSL=true";
Connection connection = DriverManager.getConnection(url);
这些方法可能是混用的；一些参数可能被指定在URL中，而另一边其它的参数可能被指定在属性里面。但是，使用这两种方法不能指定相同的参数。
Parameter reference
名称 描述
user：用于身份验证和授权的用户名。
password：用于LDAP身份验证的密码。
sessionUser：会话用户名覆盖，用于模拟。
socksProxy：SOCKS代理主机和端口。例如:localhost: 1080
httpProxy：HTTP代理主机和端口. 例如: localhost:8888
clientInfo：关于客户端的额外信息。
clientTags：用于选择资源组的客户端标记。例子:abc, xyz
traceToken：用于跨系统关联请求的跟踪令牌。
source：Trino查询的源名称。这个参数应该优先使用ApplicationName。因此，它优先于ApplicationName和/或applicationNamePrefix。
applicationNamePrefix：附加到任何指定的ApplicationName客户端信息属性的前缀，该属性用于在未设置源参数时为Trino查询设置源名称。如果既没有设置此属性，也没有设置ApplicationName或source，则查询的源名称为trino-jdbc。
accessToken：用于基于令牌的身份验证的JWT访问令牌。
SSL：设置为true指定使用TLS/HTTPS进行连接。
SSLVerification：TLS验证方法。有三种模式:FULL(默认)、CA和NONE。对于FULL，执行正常的TLS验证。对于CA，只验证CA，不允许主机名不匹配。对于NONE，没有验证。
SSLKeyStorePath：仅当连接到已启用证书身份验证的Trino集群时使用。指定PEM或JKS文件的路径，该文件必须包含受所连接的Trino集群信任的证书。
SSLKeyStorePassword：KeyStore的密码(如果有的话)。
SSLKeyStoreType：KeyStore的类型。默认类型由Java密钥库提供。如果不存在，则键入安全属性或JKS。
SSLTrustStorePath：要使用的Java TrustStore文件的位置。验证HTTPS服务器证书。
SSLTrustStorePassword：TrustStore的密码。
SSLTrustStoreType：TrustStore的类型。默认类型由Java密钥库提供。如果不存在，则键入安全属性或JKS。
SSLUseSystemTrustStore：如果设置为true，则根据操作系统自动使用系统TrustStore。支持的操作系统为Windows和macOS。对于Windows，选择Windows- root信任库。对于macOS系统，选择KeychainStore TrustStore。对于其他操作系统，将加载默认的Java TrustStore。可以使用SSLTrustStoreType重写TrustStore规范。
KerberosRemoteServiceName：Trino协调器Kerberos服务名称。Kerberos认证时需要配置。
KerberosPrincipal：向Trino协调器进行身份验证时使用的主体。
KerberosUseCanonicalHostname：使用Kerberos服务主体的Trino协调器的规范主机名，首先将主机名解析为一个IP地址，然后对该IP地址执行反向DNS查找。这是默认启用的。
KerberosServicePrincipalPattern：Trino协调器Kerberos服务主体模式。默认为 S E R V I C E @ {SERVICE}@ SERVICE@{HOST}。 S E R V I C E 替换为 K e r b e r o s R e m o t e S e r v i c e N a m e 的值， {SERVICE}替换为KerberosRemoteServiceName的值， SERVICE替换为KerberosRemoteServiceName的值，{HOST}替换为协调器的主机名(如果启用了规范化)。
KerberosConfigPath：Kerberos配置文件。
KerberosKeytabPath：Kerberos的Keytab文件路径。
KerberosCredentialCachePath：Kerberos凭据缓存。
KerberosDelegation：设置为true则使用来自现有Kerberos上下文的令牌。这允许客户机在不传递Keytab或凭据缓存的情况下使用Kerberos身份验证。默认为false。
extraCredentials：用于连接到外部服务的额外凭据，作为键-值对列表指定。例如，foo:bar;abc:xyz用xyz创建名为abc的凭据，用bar创建名为foo的凭据。
roles：要用于catalogs授权角色，作为catalogs角色的键-值对列表指定。例如，catalog1:roleA;catalog2:roleB为catalog1设置roleA，为catalog2设置roleB。
sessionProperties：要为system和catalogs设置的会话属性，作为键-值对列表指定。例如abc:xyz;示例。Foo:bar将系统属性ABC设置为值xyz，将目录示例的Foo属性设置为值bar。
externalAuthentication：如果您想通过OAuth 2.0身份验证使用外部身份验证，则设置为true。使用本地web浏览器使用为Trino协调器配置的标识提供程序(IdP)进行身份验证。
externalAuthenticationTokenCache：允许在同一经过身份验证的用户的不同连接之间共享外部身份验证令牌，直到缓存失效为止，例如当客户机重新启动或类加载器重新加载JDBC驱动程序时。默认情况下是禁用的，值为NONE。若要启用，请将该值设置为MEMORY。如果不同用户以共享模式使用JDBC驱动程序，则存储第一个注册令牌并对所有用户进行身份验证。
disableCompression：是否启动压缩标识。
assumeLiteralUnderscoreInMetadataCallsForNonConformingClients：启用后，传递给DatabaseMetaData方法的名称schema将被视为下划线。对于在将schema或表名作为schema或表名schema传递给DatabaseMetaData方法时不转义schema或表名的应用程序，可以使用此方法作为解决方案。