Support – Frequently Asked Questions

Q: Aqua Data Studio is crashing, not responding, or showing other signs of unstable behavior.
A: All unstable behavior is caused by 1 of 3 things: 1) outdated video drivers, 2) incorrect Java Virtual Machine or 3) an incompatible Oracle Client/JDBC mismatch with the use of the “Oracle – OCI” connection type. Such issues can be easily isolated and corrected by users.
Read More >>>

Q: Executing queries that have large result-sets cause Aqua Data Studio to hang or crash.
A: Aqua Data Studio is a Java application, and is limited to the size of memory allocated to the Java Virtual Machine (JVM) at startup. The default is 256MB. You may increase the size of memory allocated to the JVM to increase Aqua Data Studio’s memory capacity.
Read More >>>

Q: Aqua Data Studio gets disconnected after a certain period of time.
A: Aqua Data Studio does not timeout user connections. However, many DBAs configure the database servers to timeout inactive database connections, and sometimes firewalls are set to timeout socket connections.
Read More >>>

Q: Scripts with multiple statements return errors. Some database commands or symbols (such as “;”) do not work in Aqua Data Studio while they do work in the database vendor’s command line tool.
A: Most command line tools provided by vendors accept their own specific commands and symbols. These are processed on the client side—they are not accepted by the server. Before sending scripts to the server, these tools extract “client-side” commands, and send only “server-side” commands to the database. ADS cannot detect third-party client commands and symbols. It is designed only to work with the database “server-side” SQL commands specified for each database vendor.
Read More >>>

Q: How can I backup Aqua Data Studio settings and server connections, or move them from one computer to another?
A: Aqua Data Studio stores all application settings and configurations in the USER_HOME\.datastudio directory. A copy of this directory can be used for making backups or transferring data to another installation.
Read More >>>

Detailed Answers

Unstable Behavior and Crashes Using ADS

JRE-related Issues

Please make sure to run ADS with the bundled JRE. ADS requires the Oracle (formerly Sun) JRE. The OpenJDK JREs that come with some OS installations are not adequate. ADS 8.0.x was released with JRE 1.6.0_16, but it is always a good approach to upgrade to the latest JRE version available from Oracle.

The latest JRE for Linux, Solaris, and Windows can be found here:
http://www.oracle.com/technetwork/java/javase/downloads/index.html

Older JREs are available at:
http://java.sun.com/products/archive/

You can update your ADS installation by doing the following:

  1. Exit the ADS application.
  2. Rename <ADS_HOME>\jre to: jre_old
  3. Download the JRE archive file into your <ADS_HOME> folder.
  4. Unzip it into your <ADS_HOME> folder. This will create a folder named “jre” with the new JRE version.
  5. Run ADS and confirm the Java version in Help->About->System:[java.version]
NOTE: Windows 7 GUI Issues – ADS 8.0.x was released with Java 1.6.0_16. Java 1.6.0_16 has minor GUI issues with Windows 7. This has been fixed in Java 1.6.0_18 and above.

On Mac OS X, the full SDK—with the JRE included—is provided with every Mac OS X installation. The file is located in: /System/Library/Frameworks/JavaVM.framework/Versions/1.x/ and is updated from Apple’s Software Update whenever Apple prepares a new version or patch. This means that you DO NOT need to install Java on a Mac. Apple will do this for you as long as you keep your system software up to date.

OpenGL/JOGL related GUI Issues

Aqua Data Studio includes charting functionality that takes advantage of Java bindings for OpenGL. Many GUI issues are related to OpenGL driver implementation with the video driver.

Please make sure you have up-to-date video drivers for your video card. Information about your driver can be found here:

In Windows:
Start – > Settings – > Control Panel – > Display Properties – > Advanced – > Adapter
The latest driver version can be downloaded from the vendor’s website.

You may also try reducing hardware acceleration of the video adapter:

In Windows:
Start – > Settings – > Control Panel – > Display Properties – > Advanced – > Troubleshoot – > [Hardware acceleration]

If reducing hardware acceleration fixes the problem, then the issue is either with the video card, or the video drivers. Please refer to the following ADS online documentation page for instructions on fixing this problem:

http://www.aquaclusters.com/app/home/project/public/aquadatastudio/wikibook/Documentation13/page/136/Charts-and-OpenGL-or-JOGL-Configuration

If the problem persists, remove the JOGL libraries and then restart ADS. ADS will be unable to find the libraries and will disable chart functionality

“Oracle OCI” connections may cause crashes

If you are using an “Oracle OCI” connection, then you need to make sure to update the Oracle JDBC driver in <ADS_HOME>\lib\drivers to the versions that come with the Oracle Client installation.

Please refer to the following documentation for instructions on updating the JDBC drivers:

http://www.aquaclusters.com/app/home/project/public/aquadatastudio/wikibook/Documentation13/page/Oracle-JDBC-Drivers/Oracle-JDBC-Drivers

Memory Allocation in Aqua Data Studio

If Aqua Data Studio crashes, becomes unresponsive, or displays no output when querying for a large amount of data, it has likely run out of memory. The issue also appears when ADS exports large amounts of data to external applications. Such behavior is caused by Aqua Data Studio and JVM running out of memory.

When the JVM starts, it has a defined “Max Memory”. This memory allocation is defined by the “vmarg.2” variable in the <ADS_HOME>/datastudio.ini file). By default, Aqua Data Studio is limited to 256MB of memory (“vmarg.2=-Xmx256M”). As the application uses memory, the JVM will allocate additional memory from the OS as needed; this amount is called “Total Memory”. The amount of memory used by the application within the JVM is called “Used Memory”. “Used Memory” will grow and shrink as the application uses memory, but “Total Memory” will increase only up to the size of the “Max Memory”. The problem results from the fact that the “Total Memory” of the JVM is not released until you restart the JVM. There have been numerous requests to Sun to change this behavior.

In the bottom right corner of Aqua Data Studio, you can see the “Used Memory” and “Total Memory” indicator. If it shows that the “Used Memory” size is nearing “Total Memory” size, you need to increase the amount of memory available to ADS (the “Max Memory” size).

Please refer to the following section of the ADS online documentation:

http://www.aquaclusters.com/app/home/project/public/aquadatastudio/wikibook/Documentation13/page/50/Launcher-Memory-Configuration

Tips for lowering memory consumption

If you will be working with large query results:

  1. Disable Text Results and Pivot Grid Results, and use only Grid Results. Text Results use three times more memory than Grid Results alone.
  2. Disable Charts in File -> Options -> General -> Chart -> [Support Chart]

32-bit vs. 64-bit versions of Aqua Data Studio

The 32-bit version of ADS can use up to 1 GB memory (maximum value for “vmarg.2=-Xmx1024M” )

The 64-bit version of ADS is not limited to 1GB (maximum value for “vmarg.2” can be more than 1024), but the 64-bit version uses twice as much memory for the same operations as the 32-bit version. If you will be using less than a 1GB, then you should use the 32-bit version of ADS.

Timeouts: ADS periodically gets disconnected from the server

Aqua Data Studio does not timeout user connections. However, many DBAs configure the database servers to timeout inactive database connections, and sometimes firewalls are set to timeout socket connections. Check with your DBA, as he will probably be able to assist you. If you are working as a database administrator yourself, note that some databases have default settings for timeout connections. For example, by default MySQL will timeout idle connections, but this behavior can be modified by changing the database Settings.

Client-specific Commands and Symbols in Aqua Data Studio

Q: Scripts with multiple statements return errors, while each statement can be executed individually without errors.

    Example:

  • select * from t1
  • select * from t2
  • select * from t3

This script returns errors.

A: Aqua Data Studio uses “go” or “/” symbols as line separators between statements. Here is a corrected example of the same script:

    • select * from t1
    • /
    • select * from t2
    • /
    • select * from t3
    • /

    or

    • select * from t1
    • go
    • select * from t2
    • go
    • select * from t3
    • go

Q: Some database commands do not work in Aqua Data Studio while they do work in command line tools, such as Oracle SQL*Plus, provided by database vendors.

A: Databases have server SQL commands, as well as commands that are part of the vendor’s command line tool. Server SQL commands are executed on the server, while command line commands are executed on the client by its native library. The command line tool recognizes the client-side commands and does not send them to the server. This means that, using the vendor’s command line tool, you can write scripts that execute both server SQL commands and client-side commands. Unfortunately, client-side commands are not typically specified by database vendors. ADS is therefore designed to send only server commands specific to each database vendor; if the script contains a client-side command, it will be sent to the server which will not recognize it and return an error.

    Example:

    DB2

“RUNSTATS” is a client-side command. If you execute RUNSTATS in ADS, it will be sent to the server for execution. However, because RUNSTATS is a client-side command, the DB2 server will not recognize it and return an error.

Oracle

The output formatting commands below are commands specific to SQL*Plus:

  • set lines 100
  • col name format a10
  • col path format a30

Aqua Data Studio does not require the use of these commands, since it pre-formats text results and provides Grid Results. If entered, these commands will be sent to the database and the server will return an error.

MySQL

The “delimiter” command is not a command understood by the MySQL server. It is a command understood only by the MySQL command line tool, and used to interpret the SQL script before sending it to the server. The following shows you how to execute the script using ADS:

MySQL command tool script

  • use ctom_dev;
  • drop procedure if exists init_ctom_db;
  • delimiter ||
  • create procedure init_ctom_db()
  • begin /* procedure */
  • …procedure body
  • end /* procedure */;
  • ||
  • call init_ctom_db();
  • flush tables;
  • drop procedure init_ctom_db;

ADS script

  • use ctom_dev
  • /
  • drop procedure if exists init_ctom_db
  • /
  • create procedure init_ctom_db()
  • begin /* procedure */
  • …procedure body
  • end /* procedure */;
  • /
  • call init_ctom_db()
  • /
  • flush tables
  • /
  • drop procedure init_ctom_db
  • /

Using Semicolons ” ; ” in Aqua Data Studio scripts

Q: Is there a way to run Oracle scripts that contain semicolons in Aqua Data Studio? A script with a semicolon returns an “invalid character” error.

A: ADS does not support “;” as the statement separator, although it can be enabled when not using Stored Procedures by selecting File-> Options-> Scripts-> <DATABASE VENDOR> -> [‘;’ Statement separator].

If you enable and try to use semicolons in scripts with procedural bodies, it will likely cause problems.

Using the “/” statement separator allows you to run scripts in ADS and SQL*Plus without modification.

Backing up and Transferring Aqua Data Studio Settings

For details and OS-specific information about creating backups, or transferring all or part of your Aqua Data Studio settings, please refer to the following section of the online documentation:

http://www.aquaclusters.com/app/home/project/public/aquadatastudio/wikibook/Documentation13/page/128/Configuration-Connection-files

Please note that upgrading or uninstalling Aqua Data Studio will not change your configuration files.

Please note that passwords are not copied to the configuration files, as they are encrypted during creation. Passwords must be reentered after the connections settings are moved to the second computer.