This section describes the installation and configuration steps to use Data Studio. It also explains the steps 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
Data Studio can be run after decompression of the package.
Follow the steps below to install Data Studio:
- Unzip the required package (32-bit or 64-bit) to the program files (x86) or program files folder respectively. If the user prefers to install in other folder, then the admin should control the folder access permissions to users.
You will see the following files and folders:
- Locate and double-click the Data Studio.exe to launch Data Studio.
The UserData folder is created after the first user launches Data Studio. Refer to Quick Start in case of any error while launching Data Studio.
See Adding a Connection to create a database connection.
Configuring Data Studio
Steps to configure Data Studio using Data Studio.ini file:
Restart Data Studio to view parameter changes. Invalid parameters added in the configuration file are ignored by Data Studio. All the following mentioned parameters are not mandatory.
List of configuration parameters used in Data Studio:
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 |
Removes any cached content on the GUI and reloads Data Studio. |
N/A |
N/A NOTE:
You are advised to add this parameter. |
-consoleLineCount |
Defines the maximum number of lines to be displayed in the Messages window. |
1-5000 |
1000 |
-logfolder |
Used to create the log folder. The user can specify the path to save logs. If the default value "." is used, then the folder is created in Data Studio\UserData\<user name>\logs. For details, see Setting the Location for Creating Log Files. |
N/A |
- |
-loginTimeout |
Defines the connection wait time in seconds. 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 |
Defines the instance data location for the session. |
N/A |
@none |
@user.home/MyAppWorkspace |
Eclipse workspace is created in this location while Data Studio is being launched. @user.home refers to C:/Users/<username> Eclipse log files are available in @user.home/MyAppWorkspace/.metadata |
N/A |
N/A |
-detailLogging |
Defines the criteria with reference to logging error messages. Set to True to log all error messages. Set to False to log only error messages explicitly specified by Data Studio. Refer to Controlling Exception and Error Logs for more information. This parameter is not added by default and it can be set manually if logging is required. |
True/False |
False |
-logginglevel |
Creates the log files based on the value specified. If the value provided is arbitrary or empty, log files will be created using WARN value. For details, see Different Types of Log Levels. This parameter is not added by default and it can be set manually if logging is required. |
FATAL, ERROR, WARN, INFO, DEBUG TRACE, ALL, and OFF |
WARN |
-focusOnFirstResult |
Defines auto focus behavior for Result window. Set to false to automatically set focus to the last opened Result window. Set to true to disable the automatic set focus. |
True/False |
False |
NOTE:
|
|||
-vmargs |
Specifies the start of virtual machine arguments. NOTE:
-vmargs must be the last parameter in the configuration file. |
N/A |
N/A |
-vm <file name (javaw.exe) with relative path to Java executable> |
Defines the relative path to Java executable |
N/A |
N/A |
-Dosgi.requiredJavaVersion |
Defines the minimum java version required to run Data Studio. This value must not be modified. |
N/A |
1.5 NOTE:
Note: Recommended Java version is 1.8.0_141 |
-Xms |
Defines the initial heap space that Data Studio consumes. This value must be in multiples of 1024 and greater than 40 MB and less than or equal to -Xmx size. Append the letter k or K to indicate kilobytes, m or M to indicate megabytes, g or G to indicate gigabytes. For example: -Xms40m -Xms120m Refer to Java documentation for more information. |
N/A |
-Xms40m |
-Xmx |
Defines the maximum heap space that Data Studio consumes. This value can be modified based on the available RAM space. Append the letter k or K to indicate kilobytes, m or M to indicate megabytes, g or G to indicate gigabytes. For example: -Xmx1200m -Xmx1000m Refer to Java documentation for more information. |
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 |
This parameter is used to enable testability features. For the current version after this function is enabled:
This parameter is available by default and needs to be added manually for testing. |
True/False |
False |
-Duser.language |
Defines the language settings for Data Studio. This parameter is added after the language setting is changed. |
zh/en |
N/A |
-Duser.country |
Specifies the country/region settings of Data Studio. This parameter is added after the language setting is changed. |
CN/IN |
N/A |
-Dorg.osgi.framework.bundle.parent=ext |
This parameter specifies which class loader is used for boot delegation. |
boot/app/ext |
boot |
-Dosgi.framework.extensions=org.eclipse.fx.osgi |
This parameter is used to specify a list of framework extension names. Framework extension bundles are fragments of the system bundle (org.eclipse.osgi). As a fragment, user can provide extra classes with the framework to use. |
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.
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 for Creating Log Files
- Open the Data Studio.ini file.
- Provide the path for the -logfolder parameter.
For example:
-logfolder=c:\test1
In this case, the Data Studio.log file is created in the c:\test1\<user name>\logs path.
If any of the users does not have access to the path mentioned in the Data Studio.ini file, then Data Studio closes with the below pop-up message.
The Data Studio.log file will be created in the Data Studio\UserData\<user name>\logs path if:
- The path is not provided in the Data Studio.ini file.
For example: -logfolder=.
- The path provided does not exist.
Refer to the server manual for detailed information.
You can use any text editor to open and view the Data Studio.log file.
Controlling Exception and Error Logs
The stack running details of exception, error or throw-able are controlled based on the program argument parameter. This parameter is configured in the Data Studio.ini file.
-detailLogging=false
If the flag value is true, then the stack trace details of exception, error or throw-able will be saved in the log file.
If the flag value is false, then no stack trace details will be saved in the log file.
Description of the Log Message
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 the Data Studio.log file reaches the maximum again, the system will automatically create a file and save it as Data Studio.log.2. Latest logs are always written in the Data Studio.log file. This process continues till Data Studio.log.5 reaches the maximum file size and the cycle restarts. The Data Studio deletes the old log file that is Data Studio.log.1. For example, the Data Studio.log.5 renames to Data Studio.log.4, the Data Studio.log.4 renames to Data Studio.log.3 and so on.
To enable performance logging in the server log file, the configuration parameter log_min_messages must be enabled and value must be set as debug1 in the configuration file data/postgresql.conf, that is, log_min_messages = debug1.
Different Types of Log Levels
The different types of log levels that are displayed in the Data Studio.log file are as follows:
- TRACE: The TRACE level provides more detailed information than the DEBUG level.
- DEBUG: The DEBUG level indicates the granular information events that are most useful for debugging an application.
- INFO: The INFO level indicates the information messages that highlight the progress of the application.
- WARN: The WARN level indicates potentially harmful situations.
- ERROR: The ERROR level indicates error events.
- FATAL: The FATAL level indicates event(s) which cause the application to abort.
- ALL: The ALL level turns on all the log levels.
- OFF: The OFF level turns off all the log levels. This is opposite to ALL level.
- If the user enters an invalid value to log level, then log level will be set to WARN.
- If the user does not provide any log level, then log level will be set to WARN.
The logger outputs all messages greater than or equal to its log level.
The order of the standard log4j levels is as follows:
- |
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 |
||||||