Installing and Configuring Data Studio

This section describes how to install and configure Data Studio, and how to configure servers for debugging PL/SQL Functions.

Installation Preparations

On the Connections page of the GaussDB(DWS) console, download the Data Studio GUI client.

Installing Data Studio

You can run Data Studio after decompressing the installation package.

Perform the following steps to install Data Studio:

Decompress the required package (32-bit or 64-bit) to the Program Files or Program Files (x86) folder. If another folder is used, the administrator should control the user permission for accessing the folder.
The following files and folders are obtained after decompression:
Locate and double-click Data Studio.exe to start Data Studio client.

The UserData folder is created after the first user opens the instance using Data Studio. See Quick Start to rectify any error that occurs when Data Studio is started.

See Adding a Connection to create a database connection.

Configuring Data Studio

Configure Data Studio using Data Studio.ini file.

Restart Data Studio to view parameter changes. Invalid parameters added to the configuration file are ignored by Data Studio. All the following parameters are optional.

Table 1 Configuration parameters lists the configuration parameters of Data Studio.

**Table 1** Configuration parameters
Parameter	Description	Value Range	Default Value
-startup	Defines the JAR files required to load Data Studio. This information varies based on the version used.	N/A	plugins/org.eclipse.equinox.launcher_1.3.100.v20150511-1540.jar
--launcher.library	Specifies the library required for loading Data Studio. The library varies depending on the Data Studio version.	N/A	plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.1.300.v20150602-1417 or plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.300.v20150602-1417 depending on the installation package used
-clearPersistedState	Used to remove any cached content on the GUI and reload Data Studio.	N/A	N/A NOTE: You are advised to add this parameter.
-consoleLineCount	Specifies the maximum number of rows to be displayed in the Messages window.	1–5000	1000
-logfolder	Used to create a log folder. You can specify the path to save logs. If the default value . is used, the folder is created in the Data Studio\UserData\Username\logs directory. For details, see Setting the Location of the Created Log File.	N/A	-
-loginTimeout	Specifies the waiting time for creating a connection, in second. Within the period specified by this parameter, Data Studio continuously attempts to connect to the database. If the connection times out, the system displays a message indicating that the connection times out or the connection fails.	N/A	180
-data	Specifies the instance data location of a session.	N/A	@none
@user.home/MyAppWorkspace	Specifies the location where Eclipse workspace is created when Data Studio is being started. @user.home refers to C:/Users/Username. Eclipse log files are stored in @user.home/MyAppWorkspace/.metadata.	N/A	N/A
-detailLogging	Defines the criteria for logging error messages. True: All error messages are logged. False: Only error messages explicitly specified by Data Studio are logged. For details, see Fault Logging. This parameter is not added by default and can be configured manually if logging is required.	True/False	False
-logginglevel	Used to create a log file based on the specified value. If the value is out of range or empty, the default value WARN is used. For details, see Different Types of Log Levels. This parameter is not added by default and can be configured manually if logging is required.	FATAL, ERROR, WARN, INFO, DEBUG TRACE, ALL, and OFF	WARN
-focusOnFirstResult	Used for the auto-positioning of the Result tab. False: The auto-positioning to the last opened Result tab is enabled. True: The auto-positioning function is disabled.	True/False	False
NOTE: All the preceding parameters must be added in front of -vmargs. -startup and --launcher.library must be the first and second parameters, respectively.
-vmargs	Specifies the starting location of VM parameters. NOTE: -vmargs must locate at the end of the configuration file.	N/A	N/A
-vm	Specifies the file name, for example, javaw.exe, and the relative path to Java.	N/A	N/A
-Dosgi.requiredJavaVersion	Specifies the earliest Java version required for running Data Studio. Do not change the value of this parameter.	N/A	1.5 NOTE: The recommended Java version is 1.8.
-Xms	Specifies the initial heap size occupied by Data Studio. The value must be a multiple of 1024 and greater than 40 MB and less than or equal to the value of -Xmx. At the end of the value, add the letter k or K to indicate kilobytes, m or M to indicate megabytes, g or G to indicate gigabytes. Examples are as follows: -Xms40m -Xms120m For details, see Java documentation.	N/A	-Xms40m
-Xmx	Specifies the maximum heap size occupied by Data Studio. The value can be modified based on the available RAM space. At the end of the value, add the letter k or K to indicate kilobytes, m or M to indicate megabytes, g or G to indicate gigabytes. Examples are as follows: -Xmx1200m -Xmx1000m For details, see Java documentation.	N/A	-Xmx1200m
-OLTPVersionOldST	Used to configure the earlier OLTP versions. You can log in to gsql and run SELECT VERSION() to update the OLTPVersionOldST parameter in the .ini file using the obtained version number.	-	-
-OLTPVersionNewST	Used to configure the latest OLTP version. You can log in to gsql and run SELECT VERSION() to update the OLTPVersionNewST parameter in the .ini file using the obtained version number.	-	-
-testability	Used to enable the testability feature. When this function is enabled in the current version: You can press Ctrl+Space to copy the content of the latest Auto Suggest operation. When Include Analyze is selected, Execution Plan and Cost is displayed in tree and graphical view. This parameter is not available by default and needs to be added manually.	True/False	False
-Duser.language	Specifies the language settings of Data Studio. Add this parameter after the language settings are changed.	zh/en	N/A
-Duser.country	Specifies the country/region settings of Data Studio. Add this parameter after the language settings are changed.	CN/IN	N/A
-Dorg.osgi.framework.bundle.parent=ext	Specifies the class loader used for boot delegation.	boot/app/ext	boot
-Dosgi.framework.extensions=org.eclipse.fx.osgi	Specifies a list of framework extension names. The framework extension is a fragment of the system bundle (org.eclipse.osgi). You can use other classes provided by this framework.	N/A	N/A

You are not allowed to modify the following settings:
Dorg.osgi.framework.bundle.parent=ext

Dosgi.framework.extensions=org.eclipse.fx.osgi

If you receive the message SocketException: Bad Address: Connect:
Check whether the client is connected to the server using the IPv6 or IPv4 protocol. You can also establish the connection by configuring the following parameters in the .ini file:

-Djava.net.preferIPv4Stack=true

-Djava.net.preferIPv6Stack=false

Table 2 lists the supported communication scenarios.

The first row and first column indicate the types of nodes that attempt to communicate with each other. x indicates that the nodes can communicate with each other.

**Table 2** Communication scenarios
Node	V4 Only	V4/V6	V6 Only
V4 only	x	x	No communication possible
V4/V6	x	x	x
V6 only	No communication possible	x	x

Setting the Location of the Created Log File

Open the Data Studio.ini file.
Specify a log file path using the -logfolder parameter.
For example:

-logfolder=c:\test1

In this example, the Data Studio.log file is created in the c:\test1\Username\logs path.

If you do not have the permission for accessing the path specified in the Data Studio.ini file, Data Studio is closed and the following dialog box is displayed.

The Data Studio.log file will be created in the Data Studio\UserData\Username\logs path if:

The path of the Data Studio.ini file is not specified.
For example, the value of -logfolder= is empty.
The specified path does not exist.

For details about server logs, see the server manual.

You can use any text editor to open and view the Data Studio.log file.

Fault Logging

Configure the -detailLogging parameter to determine whether to log errors, exceptions, or stack running details of throwables.

For example, set -detailLogging to False.

If the value of -detailLogging is set to True, errors, exceptions, or stack running details of throwables will be logged.

If the value of -detailLogging is set to False, errors, exceptions, or stack running details of throwables will not be logged.

Log Message Description

The log message is described as follows:

When the size of the Data Studio.log file reaches 10,000 KB (the maximum value), the system automatically creates a file and saves it as Data Studio.log.1. Logs in Data Studio.log are stored in Data Studio.log.1. When the size of Data Studio.log reaches the maximum again, the system automatically creates a file and saves it as Data Studio.log.2. The latest logs are continuously written to Data Studio.log. This process continues till the size of Data Studio.log.5 reaches maximum, and the cycle restarts. Data Studio deletes the earliest log file Data Studio.log.1. For example, Data Studio.log.5 is renamed to Data Studio.log.4,, Data Studio.log.4 to Data Studio.log.3, and so on.

To enable performance logging in server logs, enable the parameter log_min_messages and set the parameter to debug1 in the configuration file data/postgresql.conf, that is, log_min_messages = debug1.

Different Types of Log Levels

Different types of log levels that are displayed in Data Studio.log are as follows:

TRACE: Provides more detailed information than the DEBUG level.
DEBUG: Indicates the granular information events and is useful for application debugging.
INFO: Displays the messages of application progresses.
WARN: Indicates a potentially hazardous situation.
ERROR: Indicates error events.
FATAL: Indicates an event that causes the application to stop.
ALL: Indicates that all the log levels are enabled.
OFF: Indicates that all the log levels are disabled.
- If you enter an invalid value of log level, the log level will be set to WARN.
- If you do not specify the log level, the log level will be set to WARN.

The logger outputs all messages equal to or greater than its log level.

The log levels of the Log4j framework are as follows.

**Table 3** Log levels
-	FATAL	ERROR	WARN	INFO	DEBUG	TRACE
OFF	x	x	x	x	x	x
FATAL	√	x	x	x	x	x
ERROR	√	√	x	x	x	x
WARN	√	√	√	x	x	x
INFO	√	√	√	√	x	x
DEBUG	√	√	√	√	√	x
TRACE	√	√	√	√	√	√
ALL	√	√	√	√	√	√
√- Creating a log file x - Not creating a log file