Skip to content

Data Access Service Reference

Data Access Application

General

A data access application is a collection of data access services organized into modules. It is developed and deployed as one unit against one data source.

Database Type

An application is specific to a database type, MySQL for example. The database type is specified when the application is created. It should match the database type of the data source associated with the application at both dev and run time.

Data Source

The data access application must be associated with a data source at both dev and run time. The data source must be created and deployed before the application can be deployed. The following shows a sample data source configuration file:

{
    "dbType": "mysql",
    "host": "myHost",
    "port": 3306,
    "database": "myDatabase",
    "username": "myUsername",
    "password": "myPassword",
    "ssl": true
}

Multiple applications may be associated with the same data source. In this case, the applications may use the same or different schemas.

Note: The password is to be provided encrypted.

File Structure

The following shows the source file structure of a DAS application in Service Builder. It is automatically created as the application, module, service, and test are created.

myApplication/
    src/
        application.json
        myModule/
            module.json
            myQueryService/
                service.json
                input.json
                output.json
                query.sql
                input-bindings.json
                output-bindings.json
                tests/
                    testMyQueryService.json
                    ...
            mySqlService/
                service.json
                input.json
                output.json
                sqls.sql
                query.sql
                input-bindings.json
                output-bindings.json
                tests/
                    testMySqlService.json
                    ...
            MyCrudObject/
                service.json
                object.json
                read/
                    input.json
                    query.sql
                    input-bindings.json
                    output-bindings.json
                write/
                    tables.json
                    my-root-table.columns.json
                    my-child-table.columns.json
                    ...
                tests/
                    testReadMyCrudObject.json
                    testCreateMyCrudObject.json
                    testUpdateMyCrudObject.json
                    testDeleteMyCrudObject.json
                    ...
    README.md

Application File

Each application includes an application file: application.json, as shown below:

{
    "name": "myApplication",
    "description": "application. Don't modify this file!",
    "dbType": "mysql",
    "dataSource": "mydb",
    "schema": "classicmodels"
}

The application file is automatically generated when the application is created. The user is expected to configure a data source, and optionally a database schema, for the application in this file. The dataSource is a name referring a data source deployed in the workspace or on the runtime instance.

The schema means a different thing for different database types. For MySQL database, a schema is a database to use. If configured, the application uses this schema. If not, the application uses the default database configured at the data source level. For PostgreSQL database, a schema is a logical container within the database. If configured, the application uses this schema within the database. If not, the application uses the default schema of the database configured at the data source level.

Module File

Each module includes a module file: module.json, as shown below

{
    "name": "myModule",
    "description": "module. Don't modify this file!"
}

This file is automatically generated when the module is created. The user is not expected to make change to this file.

Service File

Each service include a service file: service.json, along with files for the various components of the service. The content of the service file varies with the type of service. The service file is automatically generated when the service is created. The user is not expected to make change to this file, except when the user needs:

  • To enable dynamic query for a query service, by setting its dynamic property to true; or
  • To allow substitution variable for a SQL service, by setting its variableLength property to a number greater than zero.

Query Service File

{
    "name": "myQueryService",
    "type": "query",
    "description": "query service. Don't modify this file except the dynamic field!",
    "input": "./input.json",
    "output": "./output.json",
    "query": "./query.sql",
    "dynamic": false,
    "inputBindings": "./input-bindings.json",
    "outputBindings": "./output-bindings.json"
}

SQL Service File

{
    "name": "mySqlService",
    "type": "sql",
    "description": "sql service. Don't modify this file except the variableLength field!",
    "input": "./input.json",
    "output": "./output.json",
    "sqls": "./sqls.sql",
    "variableLength": 0,
    "query": "./query.sql",
    "inputBindings": "./input-bindings.json",
    "outputBindings": "./output-bindings.json"
}}

Repository Service File

{
    "name": "MyCrudObject",
    "type": "crud",
    "description": "crud/repository service. Don't modify this file!",
    "object": "./object.json",
    "read": {
        "input": "./read/input.json",
        "query": "./read/query.sql",
        "inputBinding": "./read/input-binding.json",
        "outputBinding": "./read/output-binding.json"
    },
    "write": {
        "tables": "./write/tables.json"
    }
}