FarCry 6.1 presents a completely refactored database layer. The goal is to make the layer abstract enough that implementing a gateway CFC is enough to add support for a database to FarCry.
The following outlines the features required and a testing methodology.
Location
Gateways are added to the dbgateways package. They can be implemented in any plugin / project for testing, but must be in core in order to be used during installation.
We have plans to change the dbgateways package so that instead of the standard extension (e.g. components in the package replace the corresponding components in core), gateway components would be loaded as mixins. This approach would allow plugin writers to put their own custom SQL in a single place, where it can be easily ported to other database servers.
Component
The component should have the following attributes.
Attribute |
Notes |
|---|---|
dbType |
A list of key:label values for each of the database types this gateway supports. The labels are used to populate the database type selection list during installation. When initializing a datasource this attribute is used to identify load the appropriate gateway. |
usesDBOwner |
0/1/true/false. Used by installer to determine if the database owner input should be shown. |
Functions
Name |
Specificity |
Notes |
|---|---|---|
createData |
Base |
|
setData |
Base |
|
setArrayData |
Base |
|
getData |
Base |
|
deleteData |
Base |
|
isDeployed |
Base |
|
deploySchema |
DB gateway |
Because this function translates FarCry data types to database datatypes. |
dropSchema |
Base |
|
diffSchema |
Base |
|
introspectType |
DB gateway |
|
isFieldAltered |
Base, typically overridden |
|
setArrayTypenames |
Base |
Base updates via a join, so some gateways may need to override it |
combineResults |
Base |
Utility function |
init |
Base |
Is passed the datasource and database owner |
getValueFromDB |
DB gateway |
Performs any necessary translation between the database value and FarCry value. e.g. in some versions of FarCry post 2050 dates are null dates. This function identifies those dates and converts them to empty strings. Because of the spotty support for actual null date columns, this function usually needs to be reimplemented for each database. |
getValueForDB |
DB gateway |
Performs any necessary translation from FarCry to database values. Returns a struct containing cfsqltype, null, and value, as appropriate for a cfqueryparam tag. Also see getValueFromDB. |
addColumn |
DB gateway |
Because this function translates FarCry data types to database datatypes. |
dropColumn |
DB gateway |
|
repairColumn |
DB gateway |
|
addIndex |
Base |
|
dropIndex |
Base |
|
repairIndex |
Base |
This function simply calls dropIndex, then addIndex. |
introspectType |
DB gateway |
Has been implemented with two utility functions introspectTable and introspectIndexes. Most gateways will have the same structure with different SQL, but only introspectType is accessed outside the component. |
Specificity:
Base This functionality is implemented in the base gateway, and probably won't need to be overridden.
Base, typically overridden Base does provide a default implementation, but it will probably not be enough.
DB gateway New database gateways need to include an implementation of this function.
Testing
An exhaustive test suite (for mxUnit) has been added to core. By default this suite uses datasource defined for the application for testing, but you can override this by setting dsn, dbowner, and dbtype on application.stPlugins.testMXUnit.
The tests can be run using the testMXUnit plugin.