Connections¶

Connections map logical entity names to database driver objects. A connection ID belongs in entity metadata; the connection manager maps that ID to a connection URI and the driver class that handles the URI scheme.

Connection manager and connection IDs¶

cDbConnectionManager is intended to be used as a singleton object in applications to manage database connections. During Construct_Object, it stores its object handle in the global ghoDbConnectionManager so Data Dictionaries can find it.

The manager stores two lists:

Connection IDs are normalized to uppercase when registered or discovered from child driver objects. For example, registering order_data stores ORDER_DATA; the driver object created for it is named oCon_ORDER_DATA.

Use Db\cDbConnectionManager.pkg
Use Db\cDbSqliteDriver.pkg

Object oConnectionManager is a cDbConnectionManager
    Send RegisterDriver "sqlite" (RefClass(cDbSqliteDriver))
    Send RegisterConnection "OrderEntry" "sqlite:OrderEntryFull.db?mode=rwc"
End_Object

Registering drivers¶

Register each driver class before a connection URI needs it.

Send RegisterDriver "sqlite" (RefClass(cDbSqliteDriver))

The first argument to RegisterDriver is the driver name. It must match the scheme in connection URIs. A URI such as sqlite:OrderEntryFull.db?mode=rwc uses the driver registered as sqlite.

When a connection is first materialized, DriverClassForConnectionURI parses the URI scheme and looks up the matching registered driver class. Registering the same driver name twice raises DFERR_PROGRAM.

Defining connection URIs¶

Register a logical connection ID with its URI.

Send RegisterConnection "OrderEntry" "sqlite:OrderEntryFull.db?mode=rwc"

RegisterConnection stores the connection ID and URI. It does not instantiate the driver object and does not connect immediately.

The URI scheme selects the driver class. These examples all use the driver registered as sqlite:

sqlite:OrderEntryFull.db?mode=ro
sqlite:OrderEntryFull.db?mode=rwc
sqlite:./data/OrderEntry.db?autocreate=true
sqlite:///C:\SQLiteDB\Stuff\OrderEntry.db?autocreate=true

Query parameters are passed as part of the connection URI. Common examples in connection URIs include mode=ro, mode=rwc, and autocreate=true.

Where this is heading: the URI-and-driver design is meant to grow. Additional back-end drivers, and reading connection settings from external sources such as configuration files or environment variables, are planned directions. Today, sqlite connections and driver objects registered in code are the supported path.

Static driver objects¶

You can define driver objects as children of the connection manager instead of registering connection URIs.

Object oConnectionManager is a cDbConnectionManager
    Object oOrderData is a cDbSqliteDriver
        Set psConnectionId to "OrderData"
        Set psConnectionUri to "sqlite:OrderEntryFull.db?mode=rwc"
    End_Object
End_Object

Child driver objects are discovered by ScanChildren during End_Construct_Object. Child driver objects must implement the adapter protocol from cDbFlexAdapter_mixin; that mixin defines psConnectionId, psConnectionUri, InitializeConnection, and IsAdapter.

If a child driver's psConnectionId is blank, the manager uses the object's label as the connection ID. For example, a child object named oByLabel is registered with the connection ID OBYLABEL.

Connecting entities to drivers¶

Entity-level { Connection="OrderEntry" } metadata is the logical connection ID used by the Data Dictionary adapter path.

{ Connection="OrderEntry" }
Entity Customer
    {
        PrimaryKey=On
        AutoIncrement=On
    }
    Integer Customer_Number
    String Name
End_Entity

cDD_Adapter.pkg reads Entity_Attribute C_DbTableAttribute_Connection. When a connection ID exists and ghoDbConnectionManager is available, it calls DriverByConnectionId with bConnect=True, stores the returned driver in phoAdapter, and uses that adapter for database messages.

If an entity has a connection ID but no global connection manager is available, the adapter raises DFERR_PROGRAM with No connection manager available to find connection '<id>'.

Auto-connect and lazy-connect behavior¶

DriverByConnectionId is the main entry point used by Data Dictionaries.

Get DriverByConnectionId of ghoDbConnectionManager "OrderEntry" True to hoAdapter

With bConnect=False, the manager returns or creates the driver object without calling InitializeConnection.

With bConnect=True, the manager calls InitializeConnection only if the connection is not already active. Repeated lookups reuse the active driver rather than initializing it again.

ConnectAll connects all registered connections that are not disabled and not active. pbAutoConnect defaults to False; when set True, End_Construct_Object calls ConnectAll.

See the cDbConnectionManager API reference for exact connection manager members.

Unknown connection IDs, unknown drivers, disabled connections, and invalid URIs with no scheme raise DFERR_PROGRAM.

Checklist¶

1. Create one cDbConnectionManager object for the application.
2. Register each driver name with RegisterDriver.
3. Register each logical connection ID with RegisterConnection, or define a child driver object with psConnectionId and psConnectionUri.
4. Use the same logical connection ID in entity { Connection="..." } metadata.
5. Let Data Dictionaries call DriverByConnectionId through the adapter path, or call it directly when application code needs the driver object.
6. Use ConnectAll or pbAutoConnect=True only when the application should open every registered connection during startup.