# Getting Started with the Oracle Database Plugin for Eclipse

Welcome to the first step towards supporting the Eclipse Data Tool Platform (DTP) by Oracle. This document provides a high-level tour through each of the Oracle Database Plugin features.

## Using the Database Explorer

The Database Explorer is the Datasource View provided by the DTP. You use it to create Database connections and to navigate the database.

### Creating a Connection to a Database

You can creat a connection to a database.

To create a connection to a database using the Data Source Explorer view:

1. To open the Database Development perspective, click Windows > Open Perspective > Other from the Main menu, and then select Database Development from the Open Perspective dialog. This perspective opens the Data Source Explorer (DSE) view.

2. Right click on the Databases node in DSE and select New to create a database connection.

3. Select Oracle Database Connection from the list and provide a name for the connection. Click Next to proceed to the next step.

4. Complete the rest of the dialog as follows:

   - Select either `Oracle Database 10g Driver Default` or `Oracle Database 11g Driver Default` from the drop-down list of drivers.

   - If the default settings are not appropriate for your configuration, change the following information on the Properties > General tab of the New Connection Profile dialog:

     - In the SID field, replace `xe` with the Service Name (or SID) of the Database Service.

     - In the Host field, replace server with the hostname or IP address of the Oracle Database server (possibly `localhost`).

     - In the Port number field, replace 1521 with the port number of the Oracle Database Listener service.

     - Provide the database user name and password for the connection.

       Note that the Connection URL field reflects your changes.

     - Select a use group in the Catalog field.

   - On the Properties > Optional tab, set the following optional properties, if required:

     - `autocommit=false`

       By default, autocommit is set to true, which results in immediate commit of the operations from SQL Editor. When set to false, you need to execute the explicit COMMIT to commit the changes. See Oracle Database SQL Reference for more information.

     - `sysdba=true`

       Use this property to login with SYSDBA account.

     - `sysoper=true`

       Use this property to login with SYSOPER account.

   - Click Test Connection to test the connectivity. If this fails, try restarting Eclipse with -clean command option.

   - Select Connect when the wizard completes checkbox to enable the database connection.

5. Select Finish to complete the wizard.

### Working with a Database Connection

The open database connection allows you to navigate through the database objects.

### Editing Data in a Table

With the enabled database connection, you can edit the table data in the Data Source Explorer (DSE). Note that, for comprehensive editing capabilities, it is recommended that you install Data Tools Platform SQL Development Tools Data Functions feature.

To install the Data Tools Platform SQL Development Tools Data Functions feature:

1. If your machine is located inside of a network, which requires a proxy to access outside resource such as the Internet, the configuration (download) may fail due to the fact that Eclipse IDE includes a Web browser to let you access the Internet from within the IDE. In this case, reconfigure your Eclipse IDE proxy settings using Window > Preferences > General > Network Connections.

2. Select Help > Software Updates from the main menu.

3. Open the Available Software tab on the Software Updates and Add-ons dialog.

4. Click Add Site to install the feature provided by OEPE from OEPE's update site. To do so, enter `http://www.oracle.com/technology/software/products/oepe/oepe_12g.html` in the Location field of the Add Site dialog, and then click OK.

5. Expand the Ganymede Update Site node, and then expand the Database Development node. Select Data Tools Platform SQL Development Tools Data Functions, and then click Install.

To edit a table data:

1. Navigate to the table you want to edit in the DSE, then right-click the table, and select Data > Edit. This opens the table data in the editor.

2. Make changes to the table data by right-clicking on a table cell and using the popup menu. When you have finished editing, click Save to save the changes to the database.

### Loading Data into a Table

You can load data from a text file into a table using the DSE.

To load data into a table:

1. In the DSE, navigate to the table into which you want to load data. Right-click the table, and select Data > Load from the drop-down menu This opens the Load Data dialog.

2. Complete fields on the dialog, and then click Finish. Validation is performed before the data is loaded.

### Extracting Data from a Table

To extract data from a table to a text file using the DSE.

To extract the data:

1. In the DSE, navigate to the table from which you want to extract data. Right-click the table and select Data > Extract from the drop-down menu. This opens the Extract Data dialog, as Figure 11 shows. Complete fields on the dialog, and then click Finish.

2. Complete fields on the dialog, and then click Finish.

### Generating DDL

You can use the Generate DDL option on most database objects to create or drop the object.

To generate DDL:

1. If necessary, create a project in order to save the generated DDL Script.

2. In the DSE, navigate to the object you want to create or drop, right-click the object, and select Generate DDL from the drop-down menu to create a DDL script.

The DDL is generated.

## SQL Tools

SQL Tools enable you to edit and run stored procedures and functions, as well as execute the so-called explain plans in either graphic or text mode.

### Using SQL Editor

The SQL Editor enables standard text-based editing of SQL statements, provides syntax color, and multiple statement support.

To use a SQL Editor:

1. In the DSE, navigate to the procedure or function you want to edit.

2. Right-click the procedure or function and select Edit from the drop-down menu. The procedure or function opens in the SQL Editor.

### Executing a Stored Procedure or Function

You can execute stored procedures and functions.

To execute a stored procedure or function:

1. In the DSE, navigate to the procedure or function you want to run.

2. Right-click the procedure or function and select Run from the drop-down menu.

3. If the procedure or function has any input parameters, the Configure Parameters dialog appears.

   Enter input values and click OK to run the procedure or function.

### Executing Explain Plans

You can use explain plans to optimize your code.

To execute the explain plan:

1. In the Navigator or DSE, navigate to the script containing the SQL statement for which you want to execute an explain plan.

2. Right-click on the script and select either Execute Text Explain Plan or Execute Graphic Explain Plan from the drop-down menu.

   For example, open the `views.sql` file that you created in the Generating DDL section. Highlight the SELECT statement block. Right-click and select Execute Graphic Explain Plan from the drop-down menu. This opens the execution plan in graphic mode in the Execution Plan view.

   Alternatively, if you select Execute Text Explain Plan from the drop-down menu, it will result in a text version of the execution plan.

## Granting and Revoking Privileges

To grant specific database privileges to a specific user:

1. In the DSE, navigate to the element (such as a table, for example) for which you want the user to have certain privileges.

2. Right-click the element and select Grant Privileges from the drop-down menu. This opens the Grant Privileges dialog.

3. Select one of the privileges from the list and click OK.

To revoke specific database privileges from a specific user:

1. In the DSE, navigate to the element (such as a table, for example) for which you want to revoke the user privileges.

2. Right-click the element and select Revoke Privileges from the drop-down menu. This opens the Revoke Privileges dialog.

3. Select one of the privileges from the list and click OK.

## Creating Tables

Using the tool, you can create new database tables by declaring new columns, defining primary, unique, and foreign keys, as well as adding checked constraints and indices.

To create a new database table, follow this procedure:

1. In the DSE, navigate to the Tables element.

2. Right-click the element and select New Table from the drop-down menu. This opens the Create Table dialog.

   Even though by default the table is created using the schema of the user who established the connection, you can change the database schema. If the user who established the connection does not have privileges to create a new table in another schema, the SQL Result view will display an error message after the wizard completes.

3. Using the Create Table dialog, specify the following:

   - The name for your table.

   - One or more table columns: to define a column, click Add, and then provide the column's name, select the type using the Type dialog, and specify whether or not the value can be `null`.

     You can reorder the table columns using the Move Up and Move Down buttons.

   - Click Next on the Create Table dialog to open the Create Table > Primary Key dialog. On this dialog, select Add primary key, and then define the name and select one or more columns that make up the primary key. If a column type is not suitable as a primary key column, a validation error will be displayed. Proceed by clicking Next.

   - On the next Create Table > Unique Constraints dialog, define unique constraints for the table by clicking Add. When defined, click Next to proceed.

     There are three types of validation for the unique constraints:

     - Each column must be suitable for unique constraints. For example, a column of type CLOB is not suitable as a column in unique constraints.

     - A unique constraint must not contain the same columns as the primary key.

     - A unique constraint must not contain the same columns as another unique constraint.

   - On the next Create Table > Foreign Keys dialog, define foreign keys for the table by clicking Add.

     Note: Foreign keys can reference the primary key of a table which resides in another schema. You can switch schemas by clicking Browse for the Referenced schema field. By clicking Browse for the Referenced table field you can switch to different tables in the referenced schema. When the referenced table is selected, the wizard will look up its primary key and fill the Referenced constraint field if the primary key exist. It will also try to match the columns in the referenced table with columns in the new table based on their types. Matched columns will show in the Associations table. If there are multiple columns that match a column in the referenced table, the wizard will choose the first one it finds, which you can change.

4. When finished, click Next.

5. Using the next Create Table > Check Constraints dialog, add checked constraints for the new table by clicking Add.

   Note: The Condition field is represented by a free-formatted text area. When using it, you have to ensure that the text for the checked constraints conforms to PL/SQL syntax. Otherwise, you will not be able to set the condition successfully.

6. When finished, click Next.

7. Use the next Create Table > Indices dialog to add create indices for the new table by clicking Add, and then click Next.

8. The next Create Table > DDL dialog shows summarizes the DDL used to create the new table. You can make changes to the DDL before it is executed. Note that if you do make changes to the DDL, and then go back to previous dialogs and decide to add a new column, then your changes to the DDL will be lost and a new DDL will be generated.

9. Click Finish to complete the wizard.

Upon completion, the table creation DDL is sent to the JDBC driver and executed there. If the execution is successful, a new table with all the specified constraints will be created. You can examine the result of new table creation from the SQL Result view that opens.

Note: The table creation DDL is not executed as a single SQL statement. For any constraint, an `ALTER TABLE` statement is executed. If any of the `ALTER TABLE` statements fails, you have the option on whether or not to continue to execute subsequent statements.

If the newly created table is not displayed in the Tables node in Data Source Explorer, you will need to refresh the view.

## Troubleshooting

Unable to sort folders

This issue results in an inability to sort the nodes on Data Source Explorer (DSE) in an order that is consistent with how it is displayed in Oracle SQL Developer.