Skip to main content

"createDatabase"

Abstract

createDatabase creates a new database.

The "createDatabase" action creates a database. A database contains tables.

Request examples

Arrays request example

{
  "api": "db",
  "authToken": "replaceWithValidAuthtoken",
  "action": "createDatabase",
  "params": {
    "databaseName": "test_db_min"
  }
}

Maximal request example

Note

To put the \ character in the "path" property, you must include two backslashes in a row, such as "c:\\temp". This is because in JSON the single backslash character is an escape character.

{
  "api": "db",
  "apiVersion": "1.0",
  "requestId": "1",
  "authToken": "replaceWithValidAuthtoken",
  "action": "createDatabase",
  "params": {
    "databaseName": "test_db_max",
    "path": "c:\\"
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string"
  },
  "debug": "max"
}

Response examples

Successful response example

{
  "authToken": "replaceWithValidAuthtoken",
  "requestId": "1",
  "debugInfo": {
    "request": {
      "authToken": "replaceWithValidAuthtoken",
      "api": "db",
      "action": "createDatabase",
      "params": {
        "databaseName": "test_db_max",
        "path": "c:\\"
      },
      "apiVersion": "1.0",
      "requestId": "1",
      "responseOptions": {
        "binaryFormat": "hex",
        "dataFormat": "objects",
        "numberFormat": "string"
      },
      "debug": "max"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 19,
  "errorMessage": "Can't create database"
}

Failure response example

{
  "authToken": "replaceWithValidAuthtoken",
  "requestId": "3",
  "debugInfo": {
    "request": {
      "authToken": "replaceWithValidAuthtoken",
      "api": "db",
      "action": "createDatabase",
      "params": {
        "databaseName": "test_db_min"
      },
      "requestId": "3",
      "debug": "max"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 4021,
  "errorMessage": "Can't create database"
}

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Properties summary

Table 1. "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

databaseName

defines the name of the database about to be created

Required - No default value

string

1 to 64 bytes

path

changes the path of the database

""

string

0 to 2,048 bytes



"path"

The "path" property is an optional string that specifies the path of the database folder on a disk.

Things to know:

  • Do not include the name of the database folder in the path because the name of the database and the extension .dbs is automatically added to the path, see Create a database in c:\temp\test_db_max.dbs.

  • When "path" is omitted or set to null, the FairCom server creates the database in the <FAIRCOM>/data folder.

  • When you include the \ character in the "path" property, you must include two backslashes in a row because in JSON the single backslash character is an escape character— for example, "c:\\temp".

  • You can use forward slashes in the path property (even on Microsoft Windows) because the FairCom server correctly interprets the forward slash as a backslash on Windows and as a forward slash on Linux, MacOS, and Unix.

Examples

Create a database in c:\temp\test_db_max.dbs

This code creates a database in the folder c:\temp\test_db_max.dbs

{
    "authToken": "replaceWithValidAuthToken",
    "action": "createDatabase",
    "params": {
        "databaseName": "test_db_max",
         "path": "c:\\temp"
    }
}
"path" omitted or set to null example

If the FairCom server is installed in the C:\FairCom\FairCom-Edge.windows.64bit.v4.5.1.170 folder, this code example creates a database in C:\FairCom\FairCom-Edge.windows.64bit.v4.5.1.170\data\test3.dbs.

{
    "authToken": "replaceWithValidAuthToken",
    "action": "createDatabase",
    "params": {
        "databaseName": "test3",
         "path": "c:\\temp"
    }
}
Forward slash example
{
    "authToken": "replaceWithValidAuthToken",
    "action": "createDatabase",
    "params": {
        "databaseName": "test4",
         "path": "c:/temp"
    }
}

"result"

Properties summary

Table 2. "result" properties summary

Property

Description

Type

Limits (inclusive)

data

specifies an array or object that the server returns, such as records returned by a query

Note

It is an empty array when there are no results available.

array

Its contents are determined by the action

dataFormat

specifies the format of the data in the "data" property

string

"autoDetect"
"arrays"
"objects"

fields

specifies an array of objects set by the server, where each object is the definition of a field in a table defining the details of each field returned by a query

array

fields
.autoValue

specifies when and how the server automatically sets the field value

string

"none"
"incrementOnInsert"
"timestampOnInser"
"timestampOnUpdate"
"timestampOnUpdateAndInsert"
"changeid"
fields
.defaultValue

specifies the default value of a field

string

0 to 65,500 bytes

fields
.length

specifies the length of a field's value in a record

integer

1 to 65500 

fields
.name

specifies the new name of the field

string

0 to 64 bytes

fields
.nullable

allows a field to contain a NULL value when true

Boolean

true
false
fields
.primaryKey

adds a field to the specified ordinal position of the table's primary key when > 0

integer

0 to 32

fields
.scale

specifies the number of places to the right of the decimal point

integer

0 to 32

fields
.type

specifies the type of field

string

"bit"
"tinyint"
"smallint"
"integer"
"bigint"
"real"
"double"
"number"
"money"
"date"
"time"
"timestamp"
"char"
"varchar"
"lvarchar"
"binary"
"varbinary"
"lvarbinary"
"json"


"dataFormat"

The "dataFormat" property is an optional, case-insensitive string enum that defines the format of the response in the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request and another occurs in a response. They all indicate how data is formatted.

  • "dataFormat" in the request inside "responseOptions" determines how the "data" property in the response is formatted.

    Possible values include:

    • "arrays"

      This is the default and causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

  • "dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.

    Possible values include:

    • "arrays"

      This causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

    • "autoDetect"

      This is the default and causes the server to automatically detect the format of the data in the "sourceData" property.

  • "dataFormat" in the response shows the client how the server formatted the "data" property.

    Possible values include:

    • "arrays"

      This is the default and causes the server to return results as an array of arrays, which is the most efficient.

    • "objects"

      This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

"fields"

The "fields" property is a required array of field-type objects. There is one object for each top-level field in the array. Each object identifies the actual data type of the field as stored in the database.

A field-type object is used when creating a table. It contains one object for each field definition returned in the data.

Full request example

"fields": 
[
    {
      "name": "name",
      "type": "varchar",
      "length": 50,
      "scale": null,
      "defaultValue": null,
      "nullable": false,
      "primaryKey":1
   }
]

Full response example

"fields":
[
  {
      "name": "id",
      "type": "bigint",
      "length": null,
      "scale": null,
      "autoValue": "none",
      "defaultValue": null,
      "nullable": false,
      "primaryKey": 1
  }
]

"autoValue"

This property controls when and how the server automatically sets the field value.

Specify only one of these values per field.

  • "none" indicates the server does not automatically set the field's value.

  • "incrementOnInsert" indicates the server automatically increments a field’s value each time the server inserts a new record. It applies to fields that are of the type of decimal or one of the integer types, such as "bigint". Only one field per table can have this attribute. The server returns an error when assigning this attribute to multiple fields. The JSON DB API automatically creates the "id" field as an "incrementOnInsert" field. If you apply this attribute to another field, it becomes the only automatically incremented field in the table. If you want that field to be the primary key, assign  "primaryKey": 1 to it.

  • "timestampOnInsert" indicates the server automatically sets a field’s value to the current date and time of an insert. It applies only to fields with a type of "timestamp".

  • "timestampOnUpdate" indicates the server automatically sets a field’s value to the current date and time of an update. It applies only to timestamp fields.

  • "timestampOnUpdateAndInsert" indicates the server automatically sets a field’s value to the current date and time of an insert and an update. It applies only to fields with a type of "timestamp".

  • "changeId" indicates the server uses the field for optimistic locking. The server automatically sets the field's value to the internal transaction number used during the last update of the record. This value changes each time the server updates the record. A table may only have one change tracking field. The field type must be "bigint".

    The JSON DB API automatically creates a "changeid" field with change-tracking functionality.

    Change tracking is optional in the CTDB and ISAM APIs. The application must create a 64-bit integer field and assign change-tracking functionality to it.