1. Oracle REST Data Services API
  2. Tasks
  3. Pluggable Database Lifecycle Management

Create a Pluggable Database

post

/database/pdbs/

Create a pluggable database from PDB$SEED or from an XML metadata file accessible to the database instance, hot clone PDB from another PDB or snapshot. The use of Oracle Transparent Data Encryption is only supported in topologies where the database and Oracle REST Data Services are on the same host. This service requires db.cdb.adminUser credentials to be set in the pool configuration. A client requires SQL Administrator role to invoke this service.

Request

There are no request parameters for this operation.

Supported Media Types
Request Body - application/json ()
Root Schema : schema
Type: object
Show Source
  • The administrator password for the new PDB. This property is required when creating pdb from PDB$SEED.
  • The administrator username for the new PDB. This property is required when creating pdb from PDB$SEED.
  • Indicate if 'AS CLONE' option should be used in the command to plug in a PDB. This property is optional when creating pdb from XML file.
  • NONE to disable Oracle Managed Files for the PDB, Specify either directory_path_name or diskgroup_name to enable Oracle Managed Files for the PDB. It is optional.
  • If defined, the response will contain a JSON object with the information of the script that was generated for execution. A database is not created when this property is set to true.
  • Relevant for create and plug operations. As defined in the Oracle Multitenant Database documentation. Values can be a filename convert pattern or NONE.
  • TDE password when applicable (optional). This property is optional when creating pdb from a source pdb or a snapshot.
  • The name of the new PDB.
  • Relevant for clone operations. Specifies that the source pluggable database data model definition is cloned but not the data. Defaults to false.
  • Grant one or more roles to the PDB_DBA role. This property is optional when creating pdb from PDB$SEED.
  • Relevant for create and plug operations. As defined in the Oracle Multitenant Database documentation. Values can be an even number of strings or NONE.
  • Creates a snapshot copy PDB from a storage-managed snapshot. Storage-managed snapshots are only supported on specific file systems. It must not be used with snapshotName, snapshotScn and snapshotTimestamp parameters.
  • The name of the PDB snapshot that the new PDB will clone from. Only one of snapshot_name, snapshot_scn and snapshot_timestame can be provided.
  • The id of the PDB snapshot that new PDB will clone from. Only one of snapshot_name, snapshot_scn and snapshot_timestame can be provided.
  • The time stamp of the PDB snapshot that new PDB will clone from. Only one of snapshot_name, snapshot_scn and snapshot_timestame can be provided.
  • Values can be a source filename convert pattern or NONE, This property is optional when creating pdb from XML file.
  • The name of the source PDB. This property is for clone pdb and clone pdb from snapshot.
  • Storage limits for the PDB. it can be UNLIMITED, MAXSIZE or MAX_AUDIT_SIZE, MAX_DIAG_SIZE etc.
  • Relevant for create and plug operations. True for temporary file reusage.
  • Allowed Values: [ "COPY", "NOCOPY", "MOVE" ]
    Indicate which copy option should be used in the command to plug in a PDB. This property is optional when creating pdb from XML file.
  • The path of the XML metadata file to use when plugging-in a PDB. This property is required when creating pdb from XML file.
Examples

Back to Top

Response

Supported Media Types

202 Response

The response indicates that the dbms scheduler job is created and the information on the scheduler job for creating a pdb.
Body ()
Root Schema : SchedulerJobsItem
Type: object
Represents a row in ALL_SCHEDULER_JOBS or DBA_SCHEDULER_JOBS views. See Oracle Database Reference documenation for more details.
Show Source
Nested Schema : LinkRelation
Type: object
Show Source
Back to Top

Examples

The following example shows how to create a new Pluggable Database by submitting a POST request on the REST resource using cURL. 

curl -i -X POST -u username:password 
-d @request_body.json 
-H "Content-Type:application/json" https://rest_server_url/ords/_/db-api/stable/database/pdbs/

Example of Request Body

Note:

The URL structure https://rest_server_url/resource-path, used in the preceding command has the following components:
  • rest_server_url is the REST server where Oracle Rest Data Server is running
  • The remainder of the URL includes the ORDS context root, the version of ORDS Database API to use, and the path for this operation. The PDB Lifecycle Management service requires db.cdb.adminUser credentials to be set in the pool configuration and in this example, the default pool is configured for the container database.

The following is an example request body to create a pluggable database called pdb_sample in this example, from PDB$SEED with unlimited storage. In this example, file_name_convert parameter is also provided that results in a FILE_NAME_CONVERT clause included in the CREATE PLUGGABLE DATABASE statement executed in the container database: 

{
  "new_pdb_name": "pdb_sample",
  "admin_user": "pdbadmin",
  "admin_password": "W3lc0m31",
  "file_name_convert": "('/disk1/oracle/dbs/pdbseed/','/disk1/oracle/dbs/pdb_sample/')",
  "storage": "UNLIMITED",
  "temp_file_reuse": true
}

The following is an example request body to get the generated script for creating a pluggable database from PDB$SEED with custom storage settings. Note that the script is not executed in the database. In this example, file_name_convert parameter has a NONE value that results in a FILE_NAME_CONVERT=NONE clause included in the CREATE PLUGGABLE DATABASE statement generated. 


{
  "new_pdb_name": "pdb_sample",
  "admin_user": "pdbadmin",
  "admin_password": "W3lc0m31",
  "file_name_convert": "NONE",
  "temp_file_reuse": true,
  "storage": "(MAXSIZE 2G MAX_SHARED_TEMP_SIZE 800M)",
  "dryrun": true
}

The following is an example request body to create a new pluggable database by cloning the pluggable database specified by the source_pdb_name parameter in the Json payload. In this example, file_name_convert parameter is also provided that results in a FILE_NAME_CONVERT clause included in the CREATE PLUGGABLE DATABASE statement executed in the container database: 


{
  "new_pdb_name": "pdb_new", 
  "source_pdb_name": "devpdb1",
  "file_name_convert": "('/disk1/oracle/dbs/devpdb1/','/disk1/oracle/dbs/pdb_new/')",
  "storage": "UNLIMITED" 
}

The following is an example request body to plugin a pluggable database called sales_pdb into the container database. In this example request body the pluggable database definition is specified in the sales_pdb.xml file:

{
  "new_pdb_name": "sales_pdb",
  "xml_file_name": "/disk1/oracle/dbs/sales_pdb.xml",
  "source_file_name_convert": "NONE",
  "file_name_convert": "NONE",
  "storage": "UNLIMITED",
  "xml_file_action": "NOCOPY",
  "temp_file_reuse": true,
  "dryrun":true
}

Example of Response Body when dryrun is true

The following example shows the response body with 200 returned in JSON format:

{"response":" BEGIN
DBMS_SCHEDULER.CREATE_JOB (
         job_name             => 'DBAPI_N6765OAGAO8NCPU120240326210214',
         job_type             => 'PLSQL_BLOCK',
         comments             => 'ORDS_PDB_Lifecycle_API',
         job_action           =>  'BEGIN
EXECUTE IMMEDIATE ''CREATE PLUGGABLE DATABASE sales_pdb
USING ''''/disk1/oracle/dbs/sales_pdb.xml'''' 
 NOCOPY 
 FILE_NAME_CONVERT = NONE 
 TEMPFILE REUSE
STORAGE UNLIMITED'';
EXECUTE IMMEDIATE ''ALTER PLUGGABLE DATABASE sales_pdb OPEN READ WRITE''; 
END;',
         start_date           => null,
         enabled              => TRUE);
  DBMS_SCHEDULER.SET_ATTRIBUTE (
        name           =>   'DBAPI_N6765OAGAO8NCPU120240326210214',
        attribute      =>   'job_priority',
        value          =>   1);
END;"}
Back to Top