TWiki> Persistency Web>Cool>CoolConnectionStrings (revision 1)EditAttachPDF

COOL Connection String Formats

To connect to a database, the user must pass to the COOL API the details for the connection, in the form of a connection string.

The COOL software understands two formats for a connection string:

  • <CORAL connection string>[(<CORAL role>)]/<COOL database name>
  • <engine>://<server>;schema=<schema>;dbname=<COOL database name>;[user=<user>;password=<password>]

The first format allows users to take advantage of CORAL advanced functionalities (replica lookup with automatic fallback, user authentication and authorization with different roles, lookup and authentication via the LFC replica service...). The CORAL-aware COOL connection string is the only supported format for production use.

The second format (old-style COOL connection string with explicit username and password) is provided only for backward compatibility and for quick tests. It has several well-known limitations which may lead to unexpected behaviour. The old-style COOL connection string with explicit username and password is NOT supported for production use.

CORAL-aware COOL connection string

The connection string <CORAL connection string>[(<CORAL role>)]/<COOL database name> is made of three parts. The first and the third are compulsory, while the second is optional.

CORAL connection string

The first part, <CORAL connection string>, is passed directly to CORAL. Both types of connection string supported by CORAL are allowed, those pointing explicitly to physical connections, as well as CORAL aliases resolved at runtime using the replica lookup functionality. For instance:

  • oracle://oraserver1/cooldataowner (connect to the Oracle server with TNS identifier oraserver1 to use the schema called cooldataowner)
  • mysql://myserver1/cooldatabase (connect to the MySQL server on host myserver1 to use the MySQL database cooldatabase)
  • sqlite_file:cooldata.db (connect to the SQLite file identified by relative path cooldata.db)
  • sqlite_file:/tmp/cooldata.db (connect to the SQLite file identified by absolute path /tmp/cooldata.db)
  • MyCoolDatabase (connect to one of the physical replicas corresponding to the logical alias MyCoolDatabase)

Logical aliases are resolved at runtime by CORAL to physical connection strings using one of the implementations of the lookup service interface. If the default XML lookup service is used, you must have a dblookup.xml file describing the MyCoolDatabase, for instance:

<?xml version="1.0" ?>
  <logicalservice name="MyCoolDatabase">
    <service name="mysql://myserver1/cooldatabase" accessMode="readonly" authentication="password" />
    <service name="oracle://oraserver1/cooldataowner" accessMode="update" authentication="password" />
In this case, assuming that you are connecting to COOL in read-only mode, CORAL will first try to connect to the MySQL replica on myserver1 (and may then retry to connect to the Oracle replica on server oraserver1 if the MySQL connection failed).

CORAL role

The second part must be surrounded by parenthesis and is again CORAL specific. It declares the role to use for the COOL connection. In CORAL, role is an abstraction of the concept of user. For the same physical connection string, several username/password pairs can be declared to the authentication service for different roles. By selecting a role, users are able to select under which username they want to connect to the database. If the default XML authentication service is used, you must have an authentication.xml file listing the username/password pairs with which you want to be authenticated on each physical connection, for instance:

<?xml version="1.0" ?>
  <connection name="oracle://ora_srv/cool_main">
    <parameter name="user" value="dafault_user" />
    <parameter name="password" value="PASSWORD" />
    <role name="writer">
      <parameter name="user" value="oracle_writer" />
      <parameter name="password" value="PASSWORD" />
    <role name="owner">
      <parameter name="user" value="cool_main" />
      <parameter name="password" value="PASSWORD" />
  <connection name="mysql://myserver1/cooldb">
    <parameter name="user" value="mysql_reader" />
    <parameter name="password" value="PASSWORD" />
    <role name="writer">
      <parameter name="user" value="mysql_writer" />
      <parameter name="password" value="PASSWORD" />

In this case, if you do not specify the role, you will use the user default_user when connecting to the Oracle database of the previous example, while mysql_reader will be used to connect to MySQL. If you specify the role to be writer with something like MyCOOL(writer), you will use oracle_writer and mysql_writer respectively for Oracle and MySQL.

COOL database name

The third part of the connection string must be separated from the first two parts by a "/" and can consist of up to 8 upper case alphabetic characters, numbers or "_" (underscore) (the equivalent regular expression is "[A-Z][A-Z0-9_]{0,7}"). Valid examples are COOLDB, MARCO123, TEST_N1, etc. This string will identify the COOL database instance inside an Oracle or MySQL schema or inside an SQLite file.

Putting all together, these are few examples of valid connection strings:

oracle://ora_srv/cool_main(owner)/TEST_1 mysql://myserver1/cooldb/COOLDB sqlite_file:mydir/MyDB.db/MARCO123 MyCOOL/COOLDB MyCOOL(writer)/TEST_1

Old-style COOL connection string with explicit username and password

Old style connection string ://;schema=;dbname=;[user=;password=] As already said, this connection string format is mainly for backward compatibility and can be replaced with an equivalent CORAL-aware connection string.

The old style connection string

engine://server;schema=schema;dbname=COOLDB is equivalent to the CORAL-aware one

engine://server/schema/COOLDB The only thing that is not available with the new format is the explicit specification of username and password. Note: to make the old-style connection string to work with username and password, both have to be specified otherwise they will be ignored.

For any questions please contact Main.MarcoClemencic

-- AndreaValassi - 28-Jun-2010

Edit | Attach | Watch | Print version | History: r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r1 - 2010-06-28 - AndreaValassi
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Persistency All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback