# Create

Launch stage: GA

`POST /api/2.0/postgres/catalogs`

Register a Postgres database in the Unity Catalog.

API scopes: postgres

## Query parameters

- `catalog_id` (string, optional)
  The ID in the Unity Catalog.
   It becomes the full resource name, for example "my_catalog" becomes "catalogs/my_catalog".

## Request body

- `catalog` (object, optional)
  - `name` (string, optional)
    Output only. The full resource path of the catalog.
    
     Format: "catalogs/{catalog_id}".
  - `uid` (string, optional)
    System-generated unique identifier for the catalog.
  - `spec` (object, optional)
    The desired state of the Catalog.
    - `postgres_database` (string, optional)
      The name of the Postgres database inside the specified Lakebase project and branch to be associated with the UC catalog.
       This database must already exist, unless create_database_if_missing is set to true on creation.
      
       A database can only be registered with one UC catalog at a time.
       To re-register a database with a different catalog, the existing catalog must be deleted first.
      
       A child branch inherits the fact of parent's registration. This means the same-named database
       in a child branch cannot be registered with a second catalog
       while the parent's registration exists. To allow registering the database of a child branch,
       drop and recreate the database on the child branch.
       This removes the fact of parent's registration from this branch only.
      
       Doing Point In Time Restore (PITR) prior to the moment before the Postgres DB was registered
       in the Catalog drops the fact of registration of the database. So the user should avoid doing so.
    - `create_database_if_missing` (boolean, optional)
      If set to true, the specified postgres_database is created on behalf of the calling user
       if it does not already exist. In this case, the calling user has a role created for
       them in Postgres if they do not already have one.
      
       Defaults to false, meaning that the request fails if the specified postgres_database does not already exist.
    - `branch` (string, optional)
      The resource path of the branch associated with the catalog.
      
       Format: projects/{project_id}/branches/{branch_id}.
  - `status` (object, optional)
    The observed state of the Catalog.
    - `postgres_database` (string, optional)
      The name of the Postgres database associated with the catalog.
    - `project` (string, optional)
      The resource path of the project associated with the catalog.
      
       Format: projects/{project_id}.
    - `branch` (string, optional)
      The resource path of the branch associated with the catalog.
      
       Format: projects/{project_id}/branches/{branch_id}.
  - `create_time` (string, optional)
    A timestamp indicating when the catalog was created.
  - `update_time` (string, optional)
    A timestamp indicating when the catalog was last updated.
  - `catalog_id` (string, optional)
    The part of the name, chosen by the user when the resource was created.

## Returns

- `name` (string, optional)
  The server-assigned name, which is only unique within the same service that
   originally returns it. If you use the default HTTP mapping, the
   `name` should be a resource name ending with `operations/{unique_id}`.
- `metadata` (object, optional)
  Service-specific metadata associated with the operation.  It typically
   contains progress information and common metadata such as create time.
   Some services might not provide such metadata.
- `done` (boolean, optional)
  If the value is `false`, it means the operation is still in progress.
   If `true`, the operation is completed, and either `error` or `response` is
   available.
- `error` (object, required)
  The error result of the operation in case of failure or cancellation.
  - `error_code` (string, optional)
    Possible values: `UNKNOWN`, `INTERNAL_ERROR`, `TEMPORARILY_UNAVAILABLE`, `IO_ERROR`, `BAD_REQUEST`, `SERVICE_UNDER_MAINTENANCE`, `WORKSPACE_TEMPORARILY_UNAVAILABLE`, `DEADLINE_EXCEEDED`, `CANCELLED`, `RESOURCE_EXHAUSTED`, `ABORTED`, `NOT_FOUND`, `ALREADY_EXISTS`, `UNAUTHENTICATED`, `UNAVAILABLE`, `INVALID_PARAMETER_VALUE`, `ENDPOINT_NOT_FOUND`, `MALFORMED_REQUEST`, `INVALID_STATE`, `PERMISSION_DENIED`, `FEATURE_DISABLED`, `CUSTOMER_UNAUTHORIZED`, `REQUEST_LIMIT_EXCEEDED`, `RESOURCE_CONFLICT`, `UNPARSEABLE_HTTP_ERROR`, `NOT_IMPLEMENTED`, `DATA_LOSS`, `INVALID_STATE_TRANSITION`, `COULD_NOT_ACQUIRE_LOCK`, `RESOURCE_ALREADY_EXISTS`, `RESOURCE_DOES_NOT_EXIST`, `QUOTA_EXCEEDED`, `MAX_BLOCK_SIZE_EXCEEDED`, `MAX_READ_SIZE_EXCEEDED`, `PARTIAL_DELETE`, `MAX_LIST_SIZE_EXCEEDED`, `DRY_RUN_FAILED`, `RESOURCE_LIMIT_EXCEEDED`, `DIRECTORY_NOT_EMPTY`, `DIRECTORY_PROTECTED`, `MAX_NOTEBOOK_SIZE_EXCEEDED`, `MAX_CHILD_NODE_SIZE_EXCEEDED`, `SEARCH_QUERY_TOO_LONG`, `SEARCH_QUERY_TOO_SHORT`, `MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST`, `PERMISSION_NOT_PROPAGATED`, `DEPLOYMENT_TIMEOUT`, `GIT_CONFLICT`, `GIT_UNKNOWN_REF`, `GIT_SENSITIVE_TOKEN_DETECTED`, `GIT_URL_NOT_ON_ALLOW_LIST`, `GIT_REMOTE_ERROR`, `PROJECTS_OPERATION_TIMEOUT`, `IPYNB_FILE_IN_REPO`, `INSECURE_PARTNER_RESPONSE`, `MALFORMED_PARTNER_RESPONSE`, `METASTORE_DOES_NOT_EXIST`, `DAC_DOES_NOT_EXIST`, `CATALOG_DOES_NOT_EXIST`, `SCHEMA_DOES_NOT_EXIST`, `TABLE_DOES_NOT_EXIST`, `SHARE_DOES_NOT_EXIST`, `RECIPIENT_DOES_NOT_EXIST`, `STORAGE_CREDENTIAL_DOES_NOT_EXIST`, `EXTERNAL_LOCATION_DOES_NOT_EXIST`, `PRINCIPAL_DOES_NOT_EXIST`, `PROVIDER_DOES_NOT_EXIST`, `METASTORE_ALREADY_EXISTS`, `DAC_ALREADY_EXISTS`, `CATALOG_ALREADY_EXISTS`, `SCHEMA_ALREADY_EXISTS`, `TABLE_ALREADY_EXISTS`, `SHARE_ALREADY_EXISTS`, `RECIPIENT_ALREADY_EXISTS`, `STORAGE_CREDENTIAL_ALREADY_EXISTS`, `EXTERNAL_LOCATION_ALREADY_EXISTS`, `PROVIDER_ALREADY_EXISTS`, `CATALOG_NOT_EMPTY`, `SCHEMA_NOT_EMPTY`, `METASTORE_NOT_EMPTY`, `PROVIDER_SHARE_NOT_ACCESSIBLE`
  - `message` (string, optional)
  - `stack_trace` (string, optional)
  - `details` (array of object, optional)
- `response` (object, required)
  The normal, successful response of the operation.

## Response

```json
{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "string",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}
```