Database Explorer Quickstart Last Revision: Outline 1. Preface 2. Requirements 3. Introduction 4. Creating a Database Connection 1. Configuring a JDBC Driver 2. Creating a Connection Profile 3. Opening a Database Connection 5. Working with a Database 1. Browsing a Database 2. SQL Editing and Snippet Execution 3. Editing table data 4. Using SQL Generation Utilities 5. Viewing Database Connection and Table Details 6. Advanced Features 1. Schema Filtering 7. Summary 8. User Feedback 9. References 1. Preface This document was written using Sun JDK 1.4.2, Eclipse 3.1, MyEclipse 4.0 and Oracle 9.2.x. All screenshots are based upon the default user interface settings for Eclipse, MyEclipse Enterprise Workbench, and Windows XP. If you experience difficulty with the instruction of this document, please see the User Feedback section for how to provide feedback to the MyEclipse documentation team. 2. Requirements Below is a list of requirements for this Quickstart: 1. Java 2 SDK, Standard Edition 1.4 or later installed (see Resources for a download link) 2. Eclipse 3.1 SDK (see Resources for a download link) 3. MyEclipse 4.0 (see Resources for a download link) 4. A database server that is supported by the MyEclipse Database Explorer such as: Axion Hypersonic DB InstantDB Interclient Firebird ODBC Bridge jtds Mckoi Microsoft SQL Server Mimer SQL MySQL Oracle Pointbase PostgresQL SAPDB Sunopsis XML Sybase ThinkSQL 3. Introduction Development of Java enterprise applications typically involves working with relational databases. To support this dimension of development, MyEclipse Enterprise Workbench provides the Database Explorer, a suite of database application development tools. The Database Explorer (DE) consists of the following features: Support for 25 preconfigured JDBC driver templates Create multiple database connections, to one or multiple databases Several database views: Hierarchical database structure browser view, e.g., tables, columns, sequences Table data editor Detailed table properties viewer Database snippet processing result history Database connection properties viewer SQL editor with code completion SQL code generation utilities SQL snippet evaluation Database Explorer Perspective: A customizable organization of DE tools and views (see Figure 1)
Figure 1. MyEclipse Database Explorer Perspective This Quickstart will demonstrate how to perform the following Database Explorer tasks: 1. Configuring a JDBC database driver 2. Creating a database profile and connection 3. Browsing a database and familiarization with the detailed DE database viewers 4. Editing SQL document 5. Executing SQL snippets 4. Creating a Database Connection This section demonstrates the process for configuring and connecting the Database Explorer to a Oracle database server. The process is similar for all other JDBC drivers. To learn about JDBC visit this link. Connecting the Database Explorer to a database is a 3 step process: 1. Configure the Database Explorer JDBC driver for your database 2. Create a database connection profile 3. Open a database connection Steps 1 and 2 are one-time configuration tasks for each database that you wish to use. Step-3 must be performed when MyEclipse is started or after any other event that results in the database connection being dropped, such as a database server restart. 4.1 Configuring a JDBC Driver The first task is to configure the Database Explorer JDBC driver for your database. This is accomplished using the Driver Manager, shown in Figure 2. The Driver Manager provides a number of JDBC driver configuration templates that may be customized directly or copied and then customized. Note : A JDBC driver template requires you to provide the database-specific JDBC driver implementation. A JDBC driver should be available for download from your database vendor in the form of a ZIP or JAR archive. 1. Open the Database Driver Manager. From the MyEclipse menubar select Window > Preferences > MyEclipse > Database Explorer > Drivers
Figure 2. Driver Configuration Manager Figure 2 depicts the default JDBC driver templates provided by MyEclipse and their configuration status. The icon next to a driver indicates that it has been successfully loaded by the Database Explorer; otherwise the JDBC driver could not be located and loaded. In such cases the driver template is not available for connecting to a database. Note: The default driver definitions assume that the JDBC driver classes are on the current Eclipse Java classpath. Typically this is not the case and you will need to modify the driver definition to reference the JAR file or the classes directory that contains the driver classes for you database. The Add action enables you to create a new JDBC driver template. The Copy action will create a new template from the currently selected template. The Edit action will modify the existing template. We will configure the Oracle Thin Driver template using the Edit action. 2. Select the Oracle Thin Driver template followed by the Edit action This will open the Oracle Thin Driver properties as shown in Figure 3. Figure 3. Oracle Thin Driver Dialog Table 1. Database driver dialog field definitions Field Description
Name A descriptive name for the driver template. This name will appear in the Driver Manager's list of driver templates. Example URL An example database connection string or pattern. Please consult the connection string syntax found in the documentation of your JDBC driver driver. Java Classpath The directories and JARs on the Java classpath of the MyEclipse/Eclipse process. The Driver Manager searches this path when attempting to load the JDBC driver class and its supporting classes. Driver Library User managed directory and JAR additions to the Driver Manager's classpath. If the database driver is not available on the the Java Classpath (see above) it should be added here. Driver Class Name The fully qualified Java classname of the JDBC driver class. This class must be accessible on the combined classpath locations of the Java Classpath + Driver Libraries fields. The next step is to add the location of Oracle Thin Driver JAR file using the Driver Libraries management features. 3. Select the Driver Libraries tab followed by the New button (see Figure 4) The New button action will open a file browser that you may use to navigate to and select a local JAR or directory containing the database driver (see Figure 5). Figure 4. Adding new Extra Class Path entry 4. Browse to location of the JDBC driver JAR file or classes directory and select it. 5. Select Open to accept the new classpath entry and return to the Driver Template Note: Prior to starting this example the Oracle JDBC connector was downloaded to the C:\dev\files directory.
Figure 5. Selecting Oracle JDBC driver JAR file Inspect the value of the Driver Class Name.Theojdbc.jar file contains 3 possible driver classes which may be selected from the Driver Class Name drop-down list. 6. In the Driver Class Name field select or enter oracle.jdbc.driver.oracledriver Figure 6. List JDBC driver classes found in selected JAR 7. Select OK to accept the template changes and close the dialog. In Figure 7, notice that the Oracle Thin Driver template shown in the Drivers list is now enabled,. This is because of the specified template's driver class, com.mysql.jdbc.driver, is now accessible on the template's classpath.
Figure 7. Driver list with enabled Oracle Thin Driver The Oracle Thin Driver template is now configured. 4.2 Creating a Connection Profile Once you have configured a driver to use, you need to create a Connection Profile for making connections to your database. A connection profile defines the basic connection string details required to connect to your database. Connection profiles and their resulting connections are managed in the Database Browser. To access the Database Browser open the Database Explorer Perspective select Window > Open Perspective > Other > MyEclipse Database Explorer followed by OK (see Figure 8). Figure 8. Opening MyEclipse Database Explorer Perspective Figure 9 shows the Database Explorer perspective with some of the main database tools highlighted. The first time you open the perspective the Database Browser view shown on the left of the view will be empty.
Figure 9. Database Explorer Perspective You will need to create a new connection profile for each separate connection to a database. Create a new connection profile using these steps. 1. From the Database Browser view select the New Connection Profile icon. This will open a New Connection Profile dialog. Figure 10. Launching New Connection Profile Wizard Figure 11. Completed New Connection Profile 2. Enter Oracle for the Profile Name 3. Select the Oracle Thin Driver from the drop-down in the Driver field. Note: This driver must be enabled in the Driver configuration page. 4. Modify the URL to correct connection string. For our local Oracle server we are using: jdbc:oracle:thin:@localhost:1521:dbtest 5. Fill out User Name and Password fields with appropriate values for your server. 6. Now click Finish to create the connection profile shown in Figure X. Table 2. New Connection Profile wizard field definitions Field Required Description Profile Name Yes A descriptive name that will appear Database Browser view.
Driver Yes A JDBC driver template selected from the Drivers List. Select the driver for this profile from the Driver drop-down or click on the New button to create a new driver definition. URL Yes The database connection string. Each database has its own URL structure, e.g., jdbc:oracle:thin:// User Name No The login name when creating a connection to the database. Password No The password when creating a connection to the database. Open on Eclipse Startup No Selecting this option will instruct the Database Explorer to automatically create this connection during the Eclipse startup process. Prompt For Password No Selecting this option instructs the Database Explorer to present password dialog the connection process. Enable this option if you do not wish the Database Explorer to store the password locally. The new connection profile will now show in the DB Browser view. Figure 12. Database Browser with new Oracle connection profile 4.3 Opening a Database Connection 1. Double-Clicking on a profile (or right-clicking and selecting "Open connection...") in the Database Browser view (see Figure 13). Figure 13. Opening a database connection If the connection profile is configured with the "Prompt for Password" option enabled then the Open Database Connection Wizard will appear (see Figure 14).
Figure 14. Database Connection Wizard 2. Either accept the default password provided when the connection profile was created or enter a new password. 3. Enable the Autocommit mode if you need changes to the database to be committed immediately. The default autocommit mode can be set on the MyEclipse Database Explorer Preferences. 4. Select OK to initiate the database connection process. At this point a new database connection will be opened and displayed in the Database Browser. Figure 15. New database connection in Database Explorer Note: Connections will not be closed if you close the Database Browser view or switch to a different perspective. 5. Working with Databases This section will introduce you to the Database Explorer tools that enable database browsing and SQL development. These tools include: 1. Database Browser for exploring database structure 2. SQL Editor 3. SQL Editor - snippet execution 4. Table Data Editor 5. SQL and DDL Generation 6. SQL Execution History 7. Table Information Report 8. Database Connection Information Report 5.1 Browsing a Database With the database connection established, expand the connection node in the Database Browser to view the database structure as shown in Figure 16.
Figure 16. Browsing database structure Expand the database structure to reveal table metadata such as tables, views, sequences as shown in Figure 17. Figure 17. Browsing Table Information
5.2 SQL Editing and Snippet Execution The Database Explorer tool set includes a smart SQL Editor. The SQL Editor may be associated with an open database connection that enables it to perform code completion of SQL statements and to execute SQL snippets. Please pay close attention to the Instructions in step-4 for enabling code completion. The following task will introduce basic SQL editing and snippet execution tasks. 1. Open a new SQL Editor by selecting File > New > SQL Editor from the MyEclipse menubar as shown in Figure 18. Figure 18. Opening new SQL Editor 2. Enter the location for the new SQL file. Figure 19. Location of SQL Editor file 3. Select the database connection and schema to which this editor will be associated (see Figure 20). Note: This step is required in order for code completion and snippet execution to function correctly. Figure 20. Associating SQL Editor database connection and schema 4. Now you can type in SQL statement taking advantage of code assist (ctrl+space) in each section of your SQL as demonstrated in the sequence of Figures 21a - 21d. Special Notice regarding SQL code completion The SQL code completion features requires the metadata of an editor's associated database be preloaded. By default, SQL code completion is disabled to avoid severe performance problems that may result from reading the metadata of very large database or retrieving this information over very low bandwidth database connections.
1. To enable the SQL code completion feature, open the Database Explorer preference, from the MyEclipse menubar select Window > Preferences > MyEclipse > Database Explorer 2. Enable the Load all database metadata when connection established option To optimize metadata retrieval consider using a schema filter. Select this link to learn more. Figure 21a. Standard SQL syntax code assistance Figure 21b. Code assist for schema names Figure 21c. Code assist for table names
Figure 21d. Completed SQL statement 5. A useful SQL Editor feature is to synchronize the Database Browser view with the context of the SQL Editor. In the SQL Editor, select a table name with the Ctrl key pressed. This will position the Database Browser to the selected table. Figure 22. Activating Database Browser synchronization from for echo_message table 6. Execute the SQL statement by pressing the icon. The action will execute the selected snippet. In the case no statements are selected, as in this example, the entire SQL Editor text will be executed. The query results are presented in the SQL Results view as shown in Figure 22. Figure 22. Results from mytest.sql snippet execution 5.3 Editing Table Data The Database Explorer provides an early access version of a table data editor, which will be enhanced in subsequent releases. To use this feature, begin by opening the Table Data Editor. 1. From the Database Browser select a table, open the context-menu (right-click menu), and select Edit Table Data (see Figure 23).
Figure 23. Launching Table Data Editor on echo_message table 2. In the Table Data Editor (see Figure 24), select the cell you wish edit 3. Enter the new value and select Apply to accept changes. In the example below the msg column value in row 2 has been revise from ABC to ABC-revised. Figure 24. Table Data Editor 5.4 Using SQL Generation Utilities The Database Explorer provides two SQL generation utilities, a table creation script generator and an example SQL query generator. To generate a Data Definition Language (DDL) script for an existing table do the following: 1. Select the table in the Database Browser 2. From the context-menu (right-click menu) select Create Table Script (see Figure 25)
Figure 25. Activating "Create Table Script" feature This feature will generate a DDL script for recreating the selected table and display it in a new SQL Editor (see Figure 26) Figure 26. Newly created Table Script DDL To generate an example SELECT statement for a table do the following: 1. Select the table in the Database Browser 2. From the context-menu (right-click menu) select Generate Select in SQL Editor (see Figure 27) Figure 27. Generate SQL Select statement from table This feature will generate a SELECT * statement and display it in a new SQL Editor (see Figure 28)
Figure 28. New created SELECT statement in SQL Editor 5.5 Viewing Database and Table Details This section provides a brief description of the features for viewing database and table detail. SQL History The SQL History view presents a list of all recent SQL statements executed on the database connection selected in the Database Browser. This view provides useful menu actions such as reopening the SQL statement in a new editor as shown in Figure 29. Figure 29. SQL History List Database Connection Info The Database Connection Information view presents detailed information about the database connection selected in the Database Browser. As you select different database connections the information is updated accordingly. Figure 30. Database Connection Information Table Information The Table Information view presents detailed metadata information for the selected database table in the Database Browser (see Figure 31). in read-only mode. The metadata information is presented
Figure 31. Table Information view 6. Advanced Features There are advanced features, such as performance optimizations, that Database Explorer users who work with large databases should know about. In this section we introduce schema filtering to enable users to determine how much metadata to fetch when a database connection is opened. 6.1 Schema Filtering When opening a database connection in the Database Browser, the default behavior is to fetch information about each database schema. The Database Explorer allows you to optionally filter the schemas managed by a database connection. The primary reasons for applying a schema filter are optimization related, such as: Increase connection performance when opening a database connection Limit the amount of information presented by the Database Browser Increase metadata retrieval performance for SQL code completion support Schema filters are created as part of a connection profile's definition and are therefore managed using the Connection Profile Wizard. To create a schema filter do the following: 1. In the Database Browser, select the connection profile upon which a schema filter will be created. 2. From the connection profile's context-menu, or the Database Browser's view menu, select the Edit icon. 3. In the Connection Profile Wizard select Next to continue to the Schema Details of the wizard (see Figure 32). By default, the Display all schemas option is selected. 4. Select the Display the selected schemas option. Initially the schema list will be empty. 5. Select Add to view the entire list of schemas available from the database connection. Note: The Add action will attempt to connect to the database and retrieve a list of all schemas. Figure 32. Schema Details page of the Connection Profile Wizard 6. Select the schemas that the connection should manage from the full list of the database's schemas (see Figure 33). 7. Select OK to accept your schema selections and return to the Connection Profile Wizard
Figure 33. Selecting schemas to manage Figure 34 shows that the"selected schema list" has been updated with the newly selected schemas. 8. Select Finish to complete the filter specification. Figure 34. Completed Connection Profile Wizard with schema filtering 9. Close and reopen all connections for this profile for the schema filtering to take effect. Figure 35 depicts a database connection for the MySQL Test database with filter enabled. Figure 35. Database connection with specified schemas 7. Summary This concludes your quickstart into using the MyEclipse Database Explorer features. Additional Quickstart documents are available that introduce working with Hibernate along with the Database Explorer, as well as working Web Projects, editing HTML, application server configuration, and enterprise application projectst. For more information visit the MyEclipse Quickstart library.
8. User Feedback If you have comments or suggestions regarding this document please submit them to the MyEclipse Documentation Forum. 9. References Download Java 2 SDK, Standard Edition 1.4 from Sun Microsystems. Download Eclipse 3.1 SDK or greater from the Eclipse Foundation Download the MyEclipse 4.0 30 day trial edition; portal registration is required. To learn more about JDBC visit this link from Sun Microsystems. Visit themyeclipse Quickstart Library for more MyEclipse tutorials. Copyright 2004-2005 by Genuitec L.L.C