Retrieving Information About Databases

Use the get-db operation to retrieve the following database preferences:

• Name
• Type
• Webspace ID
• Database server ID
• Default database user ID

Request Packet Structure

A request XML packet retrieving database parameters includes the get-db operation node:

<packet>
<database>
   <get-db>
   ...
   </get-db>
</database>
</packet>

The get-db node is presented by type DatabaseGetDBInputType (database_input.xsd), and its graphical representation is as follows:

• The filter node is required. Specifies the filtering rule. For more information, refer to the Available Filters section. Data type: DatabaseFilterType (database_input.xsd).

Remarks

You can retrieve information on multiple databases using a single packet. Add as many get-db operations as the number of different filtering rules (you can either filter by ID, webspace-id, or by webspace-name).

<database>
   <get-db>
      <filter>
      ...
      </filter>
   </get-db>
</database>

Response Packet Structure

The get-db node of the output XML packet is presented by type DatabaseGetDBOutputType (database_output.xsd) and structured as follows:

• The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd).
• The status node is required. It specifies the execution status of the get-db operation. Data type: string. Allowed values: ok | error.
• The errcode node is optional. Is returns the error code if the get-db operation fails. Data type: integer.
• The errtext node is optional. It returns the error message if the get-db operation fails. Data type: string.
• The filter-id node is optional. It returns the filtering rule parameter. For more information, refer to the Available Filters section.
• The name node is required. It specifies the database name. Data type: string.
• The type node is required. It specifies the database type. MySQL and Microsoft SQL Server are available in Plesk for Windows. MySQL and PostgreSQL types are available in Plesk for Unix. Data type: string. Allowed values: mssql | mysql | postgresql.
• The webspace-id node is optional. It is required if the get-db operation succeeds. It specifies the ID of the webspace on which a database is added. Data type: integer.
• The db-server-id node is optional. It is required if the get-db operation succeeds. It specifies the ID of the database server on which a database will be created. This node is required only in Plesk for Linux. Data type: integer.
• The default-user-id node is optional. It is required if the get-db operation succeeds. It specifies the ID of the default database user. Data type: integer.

Samples

Retrieving database parameters

This packet retrieves information on a database with ID 5.

<packet>
<database>
   <get-db>
      <filter>
          <id>5</id>
      </filter>
   </get-db>
</database>
</packet>

Response:

<packet>
<database>
   <get-db>
      <result>
          <status>ok</status>
          <filter-id>5</filter-id>
          <id>5</id>
          
          <name>MyDatabase</name>
          <type>mysql</type>
          <webspace-id>77</webspace-id>
          <db-server-id>17</db-server-id>
          <default-user-id>10</default-user-id>
      </result>     
   </get-db>
</database>
</packet>

 Retrieving parameters of multiple databases

This packet retrieves information on all databases added to the MyDomain.com, My2Domain.com webspaces and to the webspace specified by ID 45.

<packet>
<database>
   <get-db>
      <filter>
          <webspace-name>MyDomain.com</webspace-name>
          <webspace-name>My2Domain.com</webspace-name>
      </filter>
   </get-db>
   <get-db>
      <filter>
          <webspace-id>45</webspace-id>
      </filter>
   </get-db>
</database>
</packet>

Response (when one database was found on webspace MyDomain.com, the webspace with ID 45 and webspace My2webspace.com were not found):

<packet>
<database>
   <get-db>
      <result>
          <status>ok</status>
          <filter-id>MyDomain.com</filter-id>
          <id>5</id>
          
          <name>MyDatabase</name>
          <type>mysql</type>
          <webspace-id>77</webspace-id>
          <db-server-id>17</db-server-id>
          <default-user-id>10</default-user-id>
      </result>     
   </get-db>
   <get-db>
      <result>
          <status>error</status>
          <errcode>1015</errcode>
          <errtext>Domain does not exist</errtext>
          <filter-id>My2Domain.com</filter-id>
      </result>     
      <result>
          <status>error</status>
          <errcode>1015</errcode>
          <errtext>Domain does not exist</errtext>
          <filter-id>45</filter-id>
      </result>     
   </get-db>
</database>
</packet>

Response (when two or more databases are found on the specified ):

<packet>
<database>
   <get-db>
      <result>
          <status>ok</status>
          <filter-id>MyDomain.com</filter-id>
          <id>5</id>
          
          <name>MyDatabase</name>
          <type>mysql</type>
          <webspace-id>77</webspace-id>
          <db-server-id>17</db-server-id>
          <default-user-id>10</default-user-id>
      </result>     
   </get-db>
   <get-db>
      <result>
          <status>ok</status>
          <filter-id>MyDomain.com</filter-id>
          <id>8</id>
          <name>My2base</name>
          <type>mysql</type>
          <webspace-id>77</webspace-id>
          <db-server-id>17</db-server-id>
          <default-user-id>10</default-user-id>
      </result>     
   </get-db>
</database>
</packet>