> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/api-reference/software-delivery-agent-apis/database-devops/database-instance.md).

# Database Instance

This contains APIs for performing CRUD operations on Database Instance Entity

## Create a database instance

> Create a database instance

```json
{"openapi":"3.0.0","info":{"title":"Harness NextGen Software Delivery Platform API Reference","version":"1.0"},"tags":[{"description":"This contains APIs for performing CRUD operations on Database Instance Entity","name":"Database Instance"}],"paths":{"/v1/orgs/{org}/projects/{project}/dbschema/{dbschema}/instance":{"post":{"description":"Create a database instance","operationId":"V1CreateProjDbSchemaInstance","requestBody":{"$ref":"#/components/requestBodies/DBInstanceCreateRequest"},"responses":{"201":{"$ref":"#/components/responses/DBInstanceResponse"},"400":{"$ref":"#/components/responses/ErrorResponse"},"403":{"$ref":"#/components/responses/ErrorResponse"},"404":{"$ref":"#/components/responses/ErrorResponse"},"500":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Create a database instance","tags":["Database Instance"]}}},"components":{"requestBodies":{"DBInstanceCreateRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DBInstanceIn"}}},"required":true}},"schemas":{"DBInstanceIn":{"description":"Database Instance Request","properties":{"branch":{"description":"branch where the instance is stored\n","type":"string"},"commitSha":{"description":"Commit SHA to pin the changelog to a specific revision.\nMutually exclusive with branch and gitTag. Supports Harness expressions (e.g. <+trigger.commitSha>).\n","type":"string"},"connector":{"description":"DB Connector","minLength":1,"type":"string"},"context":{"description":"Liquibase context","type":"string"},"gitTag":{"description":"Git tag to pin the changelog to a specific tagged revision.\nMutually exclusive with branch and commitSha. Supports Harness expressions (e.g. <+trigger.tag>).\n","type":"string"},"identifier":{"description":"identifier of the database instance","pattern":"^[a-zA-Z_][0-9a-zA-Z_$]{0,127}$","type":"string"},"name":{"description":"name of the database instance","type":"string"},"substituteProperties":{"additionalProperties":{"type":"string"},"description":"Placeholder replacement in migration scripts.","type":"object"},"tags":{"additionalProperties":{"type":"string"},"description":"tags attached to the database instance","maxProperties":128,"type":"object"}},"required":["identifier","connector"],"title":"Database Instance Request","type":"object"},"DBInstanceOut":{"description":"Database Instance Response","properties":{"branch":{"description":"branch where the instance is stored","type":"string"},"commitSha":{"description":"commit SHA to pin the changelog to a specific revision","type":"string"},"connector":{"description":"DB Connector","type":"string"},"context":{"description":"Liquibase context","type":"string"},"created":{"description":"epoch seconds when the database instance was created","format":"int64","type":"integer"},"gitTag":{"description":"Git tag to pin the changelog to a specific tagged revision","type":"string"},"identifier":{"description":"identifier of the database instance","type":"string"},"lastAppliedTag":{"description":"Most recent tag applied to the database","type":"string"},"lastDeployedChangeSetTag":{"description":"Tag on last deployed changeSet","type":"string"},"name":{"description":"name of the database instance","type":"string"},"schemaId":{"type":"string"},"schemaIdentifier":{"type":"string"},"substituteProperties":{"additionalProperties":{"type":"string"},"description":"Placeholder replacement in migration scripts.","type":"object"},"tags":{"additionalProperties":{"type":"string"},"description":"tags attached to the database instance","type":"object"},"toOnboard":{"type":"boolean"},"updated":{"description":"epoch seconds when the database instance was last updated","format":"int64","type":"integer"}},"required":["identifier","name","created","connector","lastDeployedChangeSetTag"],"title":"Database Instance Response","type":"object"},"Error":{"description":"Error Response","properties":{"message":{"description":"error message detail","type":"string"}},"required":["message"],"title":"Error Response","type":"object"}},"responses":{"DBInstanceResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DBInstanceOut"}}},"description":"Response body for Database Instance"},"ErrorResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error Response body"}}}}
```

## Get a database instance

> Retrieves the specified database instance

```json
{"openapi":"3.0.0","info":{"title":"Harness NextGen Software Delivery Platform API Reference","version":"1.0"},"tags":[{"description":"This contains APIs for performing CRUD operations on Database Instance Entity","name":"Database Instance"}],"paths":{"/v1/orgs/{org}/projects/{project}/dbschema/{dbschema}/instance/{dbinstance}":{"get":{"description":"Retrieves the specified database instance","operationId":"V1GetProjDbSchemaInstance","responses":{"200":{"$ref":"#/components/responses/DBInstanceResponse"},"400":{"$ref":"#/components/responses/ErrorResponse"},"403":{"$ref":"#/components/responses/ErrorResponse"},"404":{"$ref":"#/components/responses/ErrorResponse"},"500":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Get a database instance","tags":["Database Instance"]}}},"components":{"responses":{"DBInstanceResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DBInstanceOut"}}},"description":"Response body for Database Instance"},"ErrorResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error Response body"}},"schemas":{"DBInstanceOut":{"description":"Database Instance Response","properties":{"branch":{"description":"branch where the instance is stored","type":"string"},"commitSha":{"description":"commit SHA to pin the changelog to a specific revision","type":"string"},"connector":{"description":"DB Connector","type":"string"},"context":{"description":"Liquibase context","type":"string"},"created":{"description":"epoch seconds when the database instance was created","format":"int64","type":"integer"},"gitTag":{"description":"Git tag to pin the changelog to a specific tagged revision","type":"string"},"identifier":{"description":"identifier of the database instance","type":"string"},"lastAppliedTag":{"description":"Most recent tag applied to the database","type":"string"},"lastDeployedChangeSetTag":{"description":"Tag on last deployed changeSet","type":"string"},"name":{"description":"name of the database instance","type":"string"},"schemaId":{"type":"string"},"schemaIdentifier":{"type":"string"},"substituteProperties":{"additionalProperties":{"type":"string"},"description":"Placeholder replacement in migration scripts.","type":"object"},"tags":{"additionalProperties":{"type":"string"},"description":"tags attached to the database instance","type":"object"},"toOnboard":{"type":"boolean"},"updated":{"description":"epoch seconds when the database instance was last updated","format":"int64","type":"integer"}},"required":["identifier","name","created","connector","lastDeployedChangeSetTag"],"title":"Database Instance Response","type":"object"},"Error":{"description":"Error Response","properties":{"message":{"description":"error message detail","type":"string"}},"required":["message"],"title":"Error Response","type":"object"}}}}
```

## Delete a database instance

> Delete a database instance

```json
{"openapi":"3.0.0","info":{"title":"Harness NextGen Software Delivery Platform API Reference","version":"1.0"},"tags":[{"description":"This contains APIs for performing CRUD operations on Database Instance Entity","name":"Database Instance"}],"paths":{"/v1/orgs/{org}/projects/{project}/dbschema/{dbschema}/instance/{dbinstance}":{"delete":{"description":"Delete a database instance","operationId":"V1DeleteProjDbSchemaInstance","responses":{"204":{"description":"The database instance was deleted successfully"},"400":{"$ref":"#/components/responses/ErrorResponse"},"403":{"$ref":"#/components/responses/ErrorResponse"},"404":{"$ref":"#/components/responses/ErrorResponse"},"500":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Delete a database instance","tags":["Database Instance"]}}},"components":{"responses":{"ErrorResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error Response body"}},"schemas":{"Error":{"description":"Error Response","properties":{"message":{"description":"error message detail","type":"string"}},"required":["message"],"title":"Error Response","type":"object"}}}}
```

## Resolve the value of a tag (by key) on an instance

> Resolves a single tag on the instance by key. Returns whether the tag is present\
> and its raw stored value (empty string for a bare, valueless key).

```json
{"openapi":"3.0.0","info":{"title":"Harness NextGen Software Delivery Platform API Reference","version":"1.0"},"tags":[{"description":"This contains APIs for performing CRUD operations on Database Instance Entity","name":"Database Instance"}],"paths":{"/v1/orgs/{org}/projects/{project}/dbschema/{dbschema}/instance/{dbinstance}/tag-value":{"get":{"description":"Resolves a single tag on the instance by key. Returns whether the tag is present\nand its raw stored value (empty string for a bare, valueless key).","operationId":"V1GetProjDbSchemaInstanceTagValue","parameters":[{"description":"Tag key to resolve.","in":"query","name":"key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DBInstanceTagValueResponse"},"400":{"$ref":"#/components/responses/ErrorResponse"},"403":{"$ref":"#/components/responses/ErrorResponse"},"404":{"$ref":"#/components/responses/ErrorResponse"},"500":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Resolve the value of a tag (by key) on an instance","tags":["Database Instance"]}}},"components":{"responses":{"DBInstanceTagValueResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DBInstanceTagValue"}}},"description":"Resolved tag presence and raw value for an instance"},"ErrorResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error Response body"}},"schemas":{"DBInstanceTagValue":{"description":"Resolved presence and raw value of a tag on an instance","properties":{"present":{"description":"Whether a tag with the requested key exists on the instance","type":"boolean"},"value":{"description":"Raw stored value of the tag; empty string for a bare, valueless key","type":"string"}},"required":["present","value"],"title":"DBInstanceTagValue","type":"object"},"Error":{"description":"Error Response","properties":{"message":{"description":"error message detail","type":"string"}},"required":["message"],"title":"Error Response","type":"object"}}}}
```

## List database instances

> Retrieves the specified database instances of the database schema

```json
{"openapi":"3.0.0","info":{"title":"Harness NextGen Software Delivery Platform API Reference","version":"1.0"},"tags":[{"description":"This contains APIs for performing CRUD operations on Database Instance Entity","name":"Database Instance"}],"paths":{"/v1/orgs/{org}/projects/{project}/dbschema/{dbschema}/instancelist":{"post":{"description":"Retrieves the specified database instances of the database schema","operationId":"V1ListProjDbSchemaInstance","parameters":[{"$ref":"#/components/parameters/PageIndex"},{"$ref":"#/components/parameters/InstanceListLimit"},{"$ref":"#/components/parameters/SearchTerm"},{"$ref":"#/components/parameters/Sort"},{"$ref":"#/components/parameters/Order"}],"requestBody":{"$ref":"#/components/requestBodies/DBInstanceFilterRequest"},"responses":{"200":{"$ref":"#/components/responses/DBInstanceListResponse"},"400":{"$ref":"#/components/responses/ErrorResponse"},"403":{"$ref":"#/components/responses/ErrorResponse"},"404":{"$ref":"#/components/responses/ErrorResponse"},"500":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"List database instances","tags":["Database Instance"]}}},"components":{"parameters":{"PageIndex":{"description":"Pagination page number strategy: Specify the page number within the paginated collection related to the number of items on each page.","in":"query","name":"page","schema":{"default":0,"format":"int64","type":"integer"}},"InstanceListLimit":{"description":"Pagination: Number of items to return. Allows a larger page size than the standard limit for bulk instance listing.","in":"query","name":"limit","schema":{"default":10,"maximum":1000,"type":"integer"}},"SearchTerm":{"allowEmptyValue":true,"description":"This would be used to filter resources having attributes matching the search term.","in":"query","name":"search_term","schema":{"type":"string"}},"Sort":{"description":"Parameter on the basis of which sorting is done.","in":"query","name":"sort","schema":{"default":"created","enum":["name","updated","created"],"type":"string"}},"Order":{"description":"Order on the basis of which sorting is done.","in":"query","name":"order","schema":{"default":"DESC","enum":["ASC","DESC"],"type":"string"}}},"requestBodies":{"DBInstanceFilterRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DBInstanceFilterIn"}}}}},"schemas":{"DBInstanceFilterIn":{"description":"DB Instance Filter Request","properties":{"filterType":{"default":"Equals","description":"filter criteria type. Example: Equals, NotEquals","enum":["Equals","NotEquals"],"type":"string"},"instanceTags":{"description":"an array on db instance key value pairs used against the filter","items":{"$ref":"#/components/schemas/NGTag"},"type":"array"}},"title":"DBInstanceFilterIn","type":"object"},"NGTag":{"description":"ng tag with key and value ","properties":{"key":{"type":"string"},"value":{"nullable":true,"type":"string"}},"required":["key"],"title":"NGTag","type":"object"},"DBInstanceOut":{"description":"Database Instance Response","properties":{"branch":{"description":"branch where the instance is stored","type":"string"},"commitSha":{"description":"commit SHA to pin the changelog to a specific revision","type":"string"},"connector":{"description":"DB Connector","type":"string"},"context":{"description":"Liquibase context","type":"string"},"created":{"description":"epoch seconds when the database instance was created","format":"int64","type":"integer"},"gitTag":{"description":"Git tag to pin the changelog to a specific tagged revision","type":"string"},"identifier":{"description":"identifier of the database instance","type":"string"},"lastAppliedTag":{"description":"Most recent tag applied to the database","type":"string"},"lastDeployedChangeSetTag":{"description":"Tag on last deployed changeSet","type":"string"},"name":{"description":"name of the database instance","type":"string"},"schemaId":{"type":"string"},"schemaIdentifier":{"type":"string"},"substituteProperties":{"additionalProperties":{"type":"string"},"description":"Placeholder replacement in migration scripts.","type":"object"},"tags":{"additionalProperties":{"type":"string"},"description":"tags attached to the database instance","type":"object"},"toOnboard":{"type":"boolean"},"updated":{"description":"epoch seconds when the database instance was last updated","format":"int64","type":"integer"}},"required":["identifier","name","created","connector","lastDeployedChangeSetTag"],"title":"Database Instance Response","type":"object"},"Error":{"description":"Error Response","properties":{"message":{"description":"error message detail","type":"string"}},"required":["message"],"title":"Error Response","type":"object"}},"responses":{"DBInstanceListResponse":{"content":{"application/json":{"schema":{"description":"Response body for List Schema","items":{"$ref":"#/components/schemas/DBInstanceOut"},"type":"array"}}},"description":"Response body for List Database Schema","headers":{"X-Page-Number":{"description":"Page number in Paginated response.","schema":{"type":"integer"}},"X-Page-Size":{"description":"Maximum page size in Paginated response.","schema":{"type":"integer"}},"X-Total-Elements":{"description":"Total number of elements returned in Paginated response.","schema":{"type":"integer"}}}},"ErrorResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error Response body"}}}}
```
