Connection

Connection Object

Connection objects are used by SQL Yoga to connect to databases that have the same schema. The object properties tell SQL Yoga where the database is located, which credentials to use to connect, etc.

A Database object can have multiple connections. For example, you can define one connection that connects to a database used for testing and another that connects to the live database.

The default connection that SQL Query and SQL Record objects use can be changed at any time by setting the default connection property (see dbobject_set) of the Database object. Whenever you call a handler that takes a connection object as a parameter you can leave the parameter empty to use the default connection.

Configuration

If you are using SQL Yoga with Levure then you can configure connections using YAML.

If you are not using Levure, or you want to configure your connections using the API, then look at dbconn_createObject and dbconn_set

Connecting to a database

To connect to a database using a pre-configured connection object use dbconn_connect. If a connection fails then an error is thrown. This allows you to handle the error globally in your application by adding your own errorDialog handler to a script in the message path (e.g. a library).

For more information on handling errors refer to the Error Handling page.

Working with multiple Connection objects

You are not limited to how many connection objects you create. In order to make writing SQL Yoga code easier, all API calls in the library assume you are targeting the default Connection Object of the default Database object. The name of the default Connection object is a property of a Database object and can be retrieved by calling dbobject_get():

put dbobject_get("default connection")  

For example, you look at the sqlquery_createObject() function you will notice that the 2nd and 3rd parameters are optional: pConnection and pDBKey. If the 3rd parameter is empty then the Database object name returned by sqlyoga_getDefaultDatabase() will be used. If the 2nd parameter is empty then the default connection Database object property will be used.

If you want to work with more than one Connection Object you have two options.

Option 1: in the name of the Connection object to any API calls that accept the pConnection parameter.

put sqlquery_createObject("lessons", "my connection name") into theQueryA

Option 2: Change the name of the default Connection object by setting the default connection property for the Database Object using dbobject_set:

dbobject_set "default connection", "my connection name"