Skip to content
/
Provision an empty VDB.

Provision an empty VDB.

Request

Security
ApiKeyAuth
Bodyapplication/jsonrequired

The parameters to provision an empty VDB.

pre_refreshArray of objects, <= 100 items(Hook)

The commands to execute on the target environment before refreshing the VDB.

post_refreshArray of objects, <= 100 items(Hook)

The commands to execute on the target environment after refreshing the VDB.

pre_self_refreshArray of objects, <= 100 items(Hook)

The commands to execute on the target environment before refreshing the VDB with data from itself.

post_self_refreshArray of objects, <= 100 items(Hook)

The commands to execute on the target environment after refreshing the VDB with data from itself.

configure_cloneArray of objects, <= 100 items(Hook)

The commands to execute on the target environment when the VDB is created or refreshed.

pre_snapshotArray of objects, <= 100 items(Hook)

The commands to execute on the target environment before snapshotting a virtual source. These commands can quiesce any data prior to snapshotting.

post_snapshotArray of objects, <= 100 items(Hook)

The commands to execute on the target environment after snapshotting a virtual source.

pre_startArray of objects, <= 100 items(Hook)

The commands to execute on the target environment before starting a virtual source.

post_startArray of objects, <= 100 items(Hook)

The commands to execute on the target environment after starting a virtual source.

pre_stopArray of objects, <= 100 items(Hook)

The commands to execute on the target environment before stopping a virtual source.

post_stopArray of objects, <= 100 items(Hook)

The commands to execute on the target environment after stopping a virtual source.

target_group_idstring, [ 1 .. 256 ] characters

The ID of the group into which the VDB will be provisioned. This field must be explicitly set when marked as mandatory; otherwise, a group is selected randomly on the Engine.

Example:"group-123"
namestring, [ 1 .. 256 ] characters

The unique name of the provisioned VDB within a group. This field must be explicitly set when marked as mandatory; otherwise, a name will be randomly generated.

Example:"my-test-vdb"
database_namestring, [ 1 .. 256 ] characters

The name of the database on the target environment. Defaults to the value of the name property.

Example:"my-test-database"
cdb_idstring, [ 1 .. 256 ] characters

The ID of the container database (CDB) to provision an Oracle Multitenant database into. This corresponds to a CDB or VCDB API object. When this is not set, a new vCDB will be provisioned.

Example:"ORACLE_SINGLE_CONFIG-376"
cluster_node_idsArray of strings, non-empty

The cluster node ids, name or addresses for this provision operation (Oracle RAC Only).

Example:
[
  "ORACLE_CLUSTER_NODE-1"
]
cluster_node_instancesArray of objects, non-empty(ClusterNodeInstance)

The cluster node instances details for this provision operation(Oracle RAC Only).This property is mutually exclusive with cluster_node_ids.

Example:
[
  {
    "node_reference": "ORACLE_CLUSTER_NODE-1",
    "instance_number": 1,
    "instance_name": "cluster_instance1",
    "okv_client_id": "1-ORACLE_OKV_CLIENT-1"
  }
]
truncate_log_on_checkpointboolean

Whether to truncate log on checkpoint (ASE only).

Example:true
os_usernamestring, [ 1 .. 256 ] characters

The name of the privileged user to run the provision operation (Oracle Only).

Example:"os-user-x"
os_passwordstring, [ 1 .. 256 ] characters

The password of the privileged user to run the provision operation (Oracle Only).

Example:"os-user-secret-password"
environment_idstring, [ 1 .. 256 ] characters

The ID of the target environment where to provision the VDB. If repository_id unambigously identifies a repository, this is unnecessary and ignored. Otherwise, a compatible repository is randomly selected on the environment.

Example:"environment-123"
environment_user_idstring, [ 1 .. 256 ] characters

The environment user ID to use to connect to the target environment.

Example:"environment-user-123"
repository_idstring, [ 1 .. 256 ] charactersrequired

The ID of the target repository where to provision the VDB. A repository typically corresponds to a database installation (Oracle home, database instance, ...). Setting this attribute implicitly determines the environment where to provision the VDB.

Example:"Unstructured Files"
auto_select_repositoryboolean

Option to automatically select a compatible environment and repository. Mutually exclusive with repository_id.

Example:true
vdb_restartboolean

Indicates whether the Engine should automatically restart this virtual source when target host reboot is detected.

Example:true
template_idstring, [ 1 .. 256 ] characters

The ID of the target VDB Template (Oracle and MSSql Only).

Example:"template-123"
auxiliary_template_idstring, [ 1 .. 256 ] characters

The ID of the configuration template to apply to the auxiliary container database. This is only relevant when provisioning a Multitenant pluggable database into an existing CDB, i.e when the cdb_id property is set.(Oracle Only)

Example:"aux-template-123"
file_mapping_rulesstring, [ 1 .. 131072 ] characters

Target VDB file mapping rules (Oracle Only). Rules must be line separated (\n or \r) and each line must have the format "pattern:replacement". Lines are applied in order.

Example:"/datafile/dbdhcp3/oradata/dbdhcp3:/data\n/u03/app/ora11202/product/11.2.0/dbhome_1/dbs/dbv_R2V4.dbf:/data/dbv_R2V4.dbf"
oracle_instance_namestring, [ 1 .. 15 ] characters^[a-zA-Z0-9_]+$

Target VDB SID name (Oracle Only).

Example:"dbdhcp2"
unique_namestring, [ 1 .. 30 ] characters^[a-zA-Z0-9_\$#]+$

Target VDB db_unique_name (Oracle Only).

Example:"dbdhcp2"
vcdb_namestring, [ 1 .. 256 ] characters^[a-zA-Z0-9_]+$

When provisioning an Oracle Multitenant vCDB (when the cdb_id property is not set), the name of the provisioned vCDB (Oracle Multitenant Only).

Example:"VCCD_6QQ"
vcdb_database_namestring, [ 1 .. 8 ] characters

When provisioning an Oracle Multitenant vCDB (when the cdb_id property is not set), the database name of the provisioned vCDB. Defaults to the value of the vcdb_name property. (Oracle Multitenant Only).

Example:"VCCD_6QQ"
mount_pointstring, [ 1 .. 256 ] characters

Mount point for the VDB (Oracle, ASE, AppData).

Example:"/var/mnt"
open_reset_logsboolean

Whether to open the database after provision (Oracle Only).

Example:true
snapshot_policy_idstring, [ 1 .. 256 ] characters

The ID of the snapshot policy for the VDB.

Example:"snapshot-123"
retention_policy_idstring, [ 1 .. 256 ] characters

The ID of the retention policy for the VDB.

Example:"retention-policy-123"
recovery_modelstring

Recovery model of the source database (MSSql Only).

Enum:"FULL""SIMPLE""BULK_LOGGED"
Example:"FULL"
pre_scriptstring, [ 1 .. 1024 ] characters

PowerShell script or executable to run prior to provisioning (MSSql Only).

Example:"C:\\Program Files\\Delphix\\scripts\\myscript.ps1"
post_scriptstring, [ 1 .. 1024 ] characters

PowerShell script or executable to run after provisioning (MSSql Only).

Example:"C:\\Program Files\\Delphix\\scripts\\myscript.ps1"
cdc_on_provisionboolean

Option to enable change data capture (CDC) on both the provisioned VDB and subsequent snapshot-related operations (e.g. refresh, rewind) (MSSql Only).

Example:true
online_log_sizeinteger, >= 4

Online log size in MB (Oracle Only).

Example:4
online_log_groupsinteger, >= 2

Number of online log groups (Oracle Only).

Example:2
archive_logboolean

Option to create a VDB in archivelog mode (Oracle Only).

Example:true
new_dbidboolean

Option to generate a new DB ID for the created VDB (Oracle Only).

Example:true
maskedboolean

Indicates whether to mark this VDB as a masked VDB.

Example:true
listener_idsArray of strings

The listener IDs for this provision operation (Oracle Only).

Example:
[
  "listener-123",
  "listener-456"
]
custom_env_varsobject

Environment variable to be set when the engine creates a VDB. See the Engine documentation for the list of allowed/denied environment variables and rules about substitution.

Example:
{
  "MY_ENV_VAR1": "$ORACLE_HOME",
  "MY_ENV_VAR2": "$CRS_HOME/after"
}
custom_env_filesArray of strings

Environment files to be sourced when the Engine creates a VDB. This path can be followed by parameters. Paths and parameters are separated by spaces.

Example:
[
  "/export/home/env_file_1",
  "/export/home/env_file_2"
]
oracle_rac_custom_env_filesArray of objects(OracleRacCustomEnvFile)

Environment files to be sourced when the Engine creates an Oracle RAC VDB. This path can be followed by parameters. Paths and parameters are separated by spaces.

Example:
[
  {
    "node_id": "ORACLE_CLUSTER_NODE-1",
    "path_parameters": "/export/home/env_file_1"
  }
]
oracle_rac_custom_env_varsArray of objects(OracleRacCustomEnvVar)

Environment variable to be set when the engine creates an Oracle RAC VDB. See the Engine documentation for the list of allowed/denied environment variables and rules about substitution.

Example:
[
  {
    "node_id": "ORACLE_CLUSTER_NODE-1",
    "name": "MY_ENV_VAR1",
    "value": "$CRS_HOME/after"
  }
]
parentTdeKeystorePathstring, [ 1 .. 1024 ] characters

Path to a copy of the parent's Oracle transparent data encryption keystore on the target host. Required to provision from snapshots containing encrypted database files. (Oracle Multitenant Only)

Example:"/foo/bar/tde"
parent_tde_keystore_passwordstring, [ 1 .. 1024 ] characters

The password of the keystore specified in parentTdeKeystorePath. (Oracle Multitenant Only)

Example:"password"
parent_pdb_tde_keystore_pathstring, [ 1 .. 512 ] characters

Path to a copy of the parent PDB's Oracle transparent data encryption keystore on the target host. Required to provision from snapshots of PDB containing encrypted database files with isolated mode keystore. (Oracle Multitenant Only)

Example:"/work/MYCDB/0FE1C5BBC29D9B20E06379CB6E0A1EFC/tde"
parent_pdb_tde_keystore_passwordstring, [ 1 .. 128 ] characters

The password of the parent PDB keystore. (Oracle Multitenant Only)

Example:"password"
target_pdb_tde_keystore_passwordstring, [ 1 .. 128 ] characters

The password for the isolated mode TDE keystore of the target virtual PDB. (Oracle Multitenant Only)

Example:"password"
tde_exported_key_file_secretstring, [ 1 .. 1024 ] characters

Secret to be used while exporting and importing vPDB encryption keys if Transparent Data Encryption is enabled on the vPDB. (Oracle Multitenant Only)

Example:"secret"
tde_key_identifierstring, [ 1 .. 256 ] characters

ID of the key created by Delphix. (Oracle Multitenant Only)

Example:"tde-indentifier"
target_vcdb_tde_keystore_pathstring, [ 1 .. 1024 ] characters

Path to the keystore of the target vCDB. (Oracle Multitenant Only)

Example:"/foo/cdb/tde"
cdb_tde_keystore_passwordstring, [ 1 .. 1024 ] characters

The password for the Transparent Data Encryption keystore associated with the CDB. (Oracle Multitenant Only)

Example:"cdb-password"
vcdb_tde_key_identifierstring, [ 1 .. 256 ] characters

ID of the key created by Delphix. (Oracle Multitenant Only)

Example:"vcdb-identifier"
tde_keystore_config_typestring(OracleTdeKeystoreConfigTypeEnum)

Oracle TDE keystore configuration type.

Enum:"FILE""OKV""HSM""OKV|FILE""FILE|OKV""HSM|FILE""FILE|HSM""OCI_VAULT""UNSET"
okv_client_idstring, non-empty.*\S.*

The id of the OKV client used by the target new vCDB for TDE keystore access. If provided, it must include at least one non-whitespace character.

Example:"1-ORACLE_OKV_CLIENT-1"
appdata_source_paramsobject

The JSON payload conforming to the DraftV4 schema based on the type of application data being manipulated.

Example:
{
  "param": "value"
}
additional_mount_pointsArray of objects or null(AdditionalMountPoint)

Specifies additional locations on which to mount a subdirectory of an AppData container.

Example:
[
  {
    "shared_path": "/",
    "mount_path": "/work",
    "environment_id": "environment-123"
  }
]
appdata_config_paramsobject or null

The list of parameters specified by the source config schema in the toolkit

Example:
{
  "option": "value"
}
config_paramsobject or null

Database configuration parameter overrides.

Example:
{
  "processes": 150
}
privileged_os_userstring, <= 32 characters^$|^[a-zA-Z_][a-zA-Z0-9_\-]+[$]?$

This privileged unix username will be used to create the VDB. Leave this field blank if you do not want to use privilege elevation. The unix privileged username should begin with a letter or an underscore, followed by letters, digits, underscores, or dashes. They can end with a dollar sign (postgres only).

postgres_portinteger, [ 1 .. 65536 ]

Port number for Postgres target database (postgres only).

config_settings_stgArray of objects(ConfigSettingsStg)

Custom Database-Level config settings (postgres only).

vcdb_restartboolean

Indicates whether the Engine should automatically restart this vCDB when target host reboot is detected. If vdb_restart property value is not explicitly set and vcdb_restart is set as false - the vdb_restart property is defaulted to false.

Example:true
mssql_failover_drive_letterstring, = 1 characters

Base drive letter location for mount points. (MSSql Only).

tagsArray of objects, [ 1 .. 1000 ] items(Tag)

The tags to be created for VDB.

invoke_datapatchboolean

Whether to invoke datapatch during provisioning (Oracle Only).

Example:false
container_modeboolean

Whether the virtual database will be provisioned for a containerized environment, such as Linux containers.

Example:false
mssql_ag_backup_locationstring

Shared backup location to be used for VDB provision on AG Cluster.

Example:"shared_backup_location/location1"
mssql_ag_backup_basedboolean

Indicates whether to do fast operations for VDB on AG which will use a healthy secondary replica to recreate the AG or backup based operations which will use the primary replica to recreate the AG using backup and restore process.

Example:true
cache_prioritystring

When set to a value other than NORMAL (valid only for object storage engines) the engine will aggressively cache required data to ensure improved performance.

Enum:"NORMAL""HIGH"
Example:"HIGH"
mssql_incremental_export_backup_frequency_minutesinteger, >= 10

Frequency in minutes for incremental export backups for VDBs.

Example:30
engine_idstring, [ 1 .. 256 ] charactersrequired

The ID of the Engine onto which to provision.

Example:"engine-123"
pre_rollbackArray of objects, <= 100 items(Hook)deprecated

The commands to execute on the target environment before rewinding the VDB.

post_rollbackArray of objects, <= 100 items(Hook)deprecated

The commands to execute on the target environment after rewinding the VDB.

The above request example is intended for AppData empty vdb

curl -i -X POST \
  https://help-api.delphix.com/_mock/data-control-tower/continuous-data/2026.5.0.0/continuous-data-apis-dct-2026.5.0.0/vdbs/empty_vdb \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "engine_id": "1",
    "name": "vdb_to_be_created",
    "target_group_id": "Untitled",
    "repository_id": "1-APPDATA_REPOSITORY-292",
    "mount_point": "/home/oracle/tmp",
    "vdb_restart": true,
    "database_name": "database_name",
    "environment_user_id": "environment-user-123",
    "pre_refresh": [
      {
        "name": "pre_refresh_command",
        "command": "echo \"testing pre-refresh\"",
        "shell": "ps/bash"
      }
    ],
    "post_refresh": [
      {
        "name": "post_refresh_command",
        "command": "echo \"testing post_refresh\"",
        "shell": "ps/bash"
      }
    ],
    "pre_rollback": [
      {
        "name": "pre_rollback_command",
        "command": "echo \"testing pre_rollback\"",
        "shell": "ps/bash"
      }
    ],
    "post_rollback": [
      {
        "name": "post_rollback_command",
        "command": "echo \"testing post_rollback\"",
        "shell": "ps/bash"
      }
    ],
    "configure_clone": [
      {
        "name": "configure_clone_command",
        "command": "echo \"testing configure_clone\"",
        "shell": "ps/bash"
      }
    ],
    "pre_snapshot": [
      {
        "name": "pre_snapshot_command",
        "command": "echo \"testing pre_snapshot\"",
        "shell": "ps/bash"
      }
    ],
    "post_snapshot": [
      {
        "name": "post_snapshot_command",
        "command": "echo \"testing post_snapshot\"",
        "shell": "ps/bash"
      }
    ],
    "pre_start": [
      {
        "name": "pre_start_command",
        "command": "echo \"testing pre_start\"",
        "shell": "ps/bash"
      }
    ],
    "post_start": [
      {
        "name": "post_start_command",
        "command": "echo \"testing post_start\"",
        "shell": "ps/bash"
      }
    ],
    "pre_stop": [
      {
        "name": "pre_stop_command",
        "command": "echo \"testing pre_stop\"",
        "shell": "ps/bash"
      }
    ],
    "post_stop": [
      {
        "name": "post_stop_command",
        "command": "echo \"testing post_stop\"",
        "shell": "ps/bash"
      }
    ],
    "snapshot_policy_id": "test_snapshot_policy"
  }'

Responses

Empty VDB provisioning initiated.

Bodyapplication/json
jobobject(Job)

An asynchronous task.

vdb_idstring

The ID of the provisioned vdb.

Response
{
  "job": {
    "id": "job-123",
    "status": "RUNNING",
    "is_waiting_for_telemetry": true,
    "type": "DB_REFRESH",
    "localized_type": "DB Refresh",
    "error_details": "Unable to connect to the engine.",
    "warning_message": "Failed to remove local MaskingJob, engineId: 3 localMaskingJobId: 7.",
    "target_id": "vdb-123",
    "target_name": "vdb",
    "work_source_id": "string",
    "work_source_name": "string",
    "work_source_type": "DIRECT",
    "start_time": "2022-01-02T05:11:24.148Z",
    "update_time": "2022-01-02T06:11:24.148Z",
    "trace_id": "string",
    "engine_ids": [ … ],
    "tags": [ … ],
    "engines": [ … ],
    "account_id": 1,
    "account_name": "User 1",
    "compliance_node_id": "string",
    "compliance_node_name": "string",
    "percent_complete": 50,
    "virtualization_tasks": [ … ],
    "tasks": [ … ],
    "execution_id": "string",
    "result_type": "string",
    "result": {},
    "parent_job_id": "string"
  },
  "vdb_id": "string"
}