====== Database Connections ======

The page gives an overview about the Java Database Connection within Orbit. \\
All documentation about databases in Orbit : [[211:technology:core:databases|]].

===== What is a Database Connection =====

Database connections are used for accessing external tables. It is the link between an application and a database. \\ \\
This connection provides Orbit the information to connect to a given database. These connections are used to point file-based datasets to a database or join external tables to an existing dataset using one ore more key attributes.
\\ \\
In Orbit GIS each Database Connection has an individual name. This connection name is registered with the resource you use it for:
  * joining a database table to a dataset, read: [[211:desktop:dataset:contents:join|]]
  * accessing spatial databases, read: [[211:technology:core:spatial_databases|]]

==== JDBC - Java DataBase Connection ====

To make a Connection from a Java application to a database, a database driver is required. Many databases provide a Java class to access their database using the SQL language. These are JDBC drivers. 

Depending on the Driver, a URL will provide the information the driver needs to establish the connection and allow the application to execute SQL-commands on the database.

===== Define Connection =====

  * For Orbit GIS Standalone or Orbit Client: [[211:desktop:preferences:database|Main Toolbar > Preferences > Database]]
  * For the Orbit EOS Server [[211:server:console:resources:database|EOS Console > Resources > Database Connection]]

|< 100% 18% 82% >|
^ Connection configuration ^^
| Name | The user name of the JDBC Data Source. This is what you will use in Orbit GIS, and it must be unique. |
| Description | An optional description of the Data Source. |
| Username | The name of the user to access the database with. |
| Password | The password for that user. |
| **Driver** | The JDBC Driver to be used. |
| **URL** | The connection string that will allow the application to connect to the database and execute commands. \\ The format of this URL is driver dependant, and you probably need to consult the driver documentation to get the right syntax. |
| Test Connection | Complete the connection configuration and click the Test Connection button. The result should be "OK". \\ If not, check the connection parameters. In most cases, the URL syntax is not properly constructed. \\ If you're not familiar to this issue, consult your IT-manager or java.oracle.com. |

|< 100% 18% 82% >|
^ Database Driver ^ standard URL syntax ^
| MS Access (v6) | jdbc:odbc:Driver={Microsoft Access Driver (*.mdb)};DBQ=<database> |
| MS Access (v12) | jdbc:odbc:Driver={Microsoft Access Driver (*.mdb, *.accdb)};DBQ=<database> |
| MySQL | <nowiki>jdbc:mysql://<hostname>/<database></nowiki> |
| Oracle - Old Syntax| jdbc:oracle:thin:@<hostname>:<port> (default 1521):<sid> \\ jdbc:oracle:thin:<user>/<password>@<hostname>:<port> (default 1521):<sid> |
| Oracle - New Syntax | <nowiki>jdbc:oracle:thin:@//<hostname>:<port (default 1521)>/<sid or service></nowiki> \\ <nowiki>jdbc:oracle:thin:<user>/<password>@//<hostname>:<port (default 1521)>/<sid or service></nowiki>|
| PostgreSQL | <nowiki>jdbc:postgresql://<hostname>/postgres</nowiki> |
| SQL Server | <nowiki>jdbc:sqlserver://<hostname:<port> (default 1433);databaseName=<SOMEDB>;</nowiki> |

**Remark**
  * Use of "User" and "Password" in the respective connection configuration fields are required. It is not necessary to do this in the URL syntax.
  * Use of Microsoft Access Driver, requires some special attention : [[211:technology:core:database_driver|]]