Help Center> GaussDB(DWS)> Tool Guide> Data Studio - Integrated Database Development Tool> Installing and Configuring Data Studio
Updated on 2023-04-03 GMT+08:00
View PDF

Installing and Configuring Data Studio

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:

  1. 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:

  2. 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:

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

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:
  • All the above parameters must be added before -vmargs.
  • -startup and --launcher.library must be added as first and second parameter respectively.

-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:

  • The user can copy content of last triggered auto-suggest operation using the Ctrl+Space shortcut key.
  • When Include Analyze is selected, Execution Plan and Cost is displayed in tree and graphical view.

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.

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 for Creating Log Files

  1. Open the Data Studio.ini file.
  2. 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:

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