createDatabase

JSON DB "createDatabase" action creates a database

A database contains tables.

 

Request examples

Minimal

{
  "action": "createDatabase",
  "params": {
    "databaseName": "test_db_min"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

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

 

Response examples

Success

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {
    "dataFormat": "objects",
    "fields": [
      {
        "name": "databaseName",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "path",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "uid",
        "type": "bigint",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": [
      {
        "databaseName": "testdatabase",
        "path": ".\\testdatabase.dbs\\SQL_SYS",
        "uid": 1007
      }
    ]
  },
  "requestId": "00000010",
  "debugInfo": {
    "request": {
      "authToken": "replaceWithAuthTokenFromCreateSession",
      "api": "db",
      "action": "createDatabase",
      "params": {
        "databaseName": "testdatabase",
        "path": "."
      },
      "apiVersion": "1.0",
      "requestId": "00000010",
      "responseOptions": {
        "binaryFormat": "hex",
        "dataFormat": "objects",
        "numberFormat": "string"
      },
      "debug": "max"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Failure

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

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

databaseName

The "databaseName" property is an optional string from 1 to 64 bytes that specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. Your session's account must have the appropriate privileges to access the code package.

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

path

The "path" property is a string that identifies the path of the database folder.

  • Do not include the name of the database file in the path because the database filename and the extension .dbs are automatically added to the path, see Create the test_db_max.dbs database in the c:\temp\ folder.
  • 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" designates the c:\temp path.
  • You can use forward slashes in the path property (even on Microsoft Windows) because the FairCom server correctly interprets them as backslashes on Windows and as forward slashes on Linux, MacOS, and Unix.

 

Create the test_db_max.dbs database in the c:\temp\ folder

{
    "action": "createDatabase",
    "params": {
        "databaseName": "test_db_max",
         "path": "c:\\temp"
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

"path" omitted or set to null

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

{
    "action": "createDatabase",
    "params": {
        "databaseName": "test3"
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Forward slash

{
    "action": "createDatabase",
    "params": {
        "databaseName": "test4",
         "path": "c:/temp"
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 "" string 0 to 2,048 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

data

 The "data" property specifies an array or object that the server returns, such as records returned by a query. It is an empty array when no results are available. array Its contents are determined by the action

data

.databaseName

The "databaseName" property specifies the database that contains the tables. 

In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

 

  • If the "databaseName" request property is omitted or set to null, the server will use the default database name specified at login.
  • If no default database is specified during "createSession", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.
  • This property's value is case insensitive. 
"data": [
      {        "databaseName": "test_db_max",
  }
 string 1 to 64 bytes

data

.path

 The "path" property specifies the directory path to the specified database. string 0 to 2,048 bytes

data

.uid

 The "uid" property specifies the unique id of the database. integer No limit

dataFormat

The "dataFormat" property is a case-insensitive string enum that defines the format of 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".

 

"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.
 string "autoDetect"
"arrays"
"objects"

fields

 The "fields" property 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

"autoValue"

"primaryKey"
"name"
"type"
"length"
"scale"
"defaultValue"
"nullable"

fields

.autoValue

 The "autoValue" property specifies when and how the server automatically sets the field value. See  for more details. string "none"
"incrementOnInsert"
"timestampOnInser"
"timestampOnUpdate"
"timestampOnUpdateAndInsert"
"changeid"

fields

.defaultValue

 The "defaultValue" property identifies the default value of the field. string 0 to 65,500 bytes

fields

.length

 The "length" property specifies the length of a field's value in a record. integer 1 to 65500

fields

.name

 The "name" property specifies the new name of the field. string 0 to 64 bytes

fields

.nullable

 The "nullable" property allows a field to contain a NULL value when true. Boolean true
false

fields

.primaryKey

 The "primaryKey" property adds a field to the specified ordinal position of the table's primary key when > 0. integer 0 to 32

fields

.scale

 The "scale" property specifies the number of places to the right of the decimal point for "number" and "money" type fields. integer 0 to 32

fields

.type

 The "type" property specifies the type of field. See Data types for more details. string "bit"
"tinyint"
"smallint"
"integer"
"bigint"
"real"
"float"
"number"
"money"
"date"
"time"
"timestamp"
"char"
"varchar"
"lvarchar"
"binary"
"varbinary"
"lvarbinary"
"json"
 

Was this article helpful?

Give feedback about this article

Related Articles