> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costgraph.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a PostgreSQL instance

> Connects a PostgreSQL instance so CostGraph can split its bill across the databases on it and the roles that use them. CostGraph logs in with a read-only login that needs the pg_monitor role, and checks the connection before saving: the login is refused when it cannot sign in or read usage statistics. instance_id is the instance's resource ID on your cloud bill; its cost is split from that bill line, and an instance_id that matches several resources on the bill is refused. Every hour CostGraph reads each database's size and activity, each role's query time from pg_stat_statements when that extension is enabled in the database it logs in to, and key=value labels from COMMENT ON DATABASE and COMMENT ON ROLE, which become tags on the split cost. The split appears in cost queries and showback with layer=database. Warnings name what is unavailable, such as pg_stat_statements, or that the instance ID has no cost on the bill yet. They are also kept on the connection: the connection list shows them in warnings, refreshed by every hourly read, and a read that fails sets status error with the reason in last_sync_error. CostGraph Cloud can only reach public addresses and only connects with sslmode verify-full (the default there) or verify-ca, so the server's certificate is checked before the password is sent; a self-hosted installation can reach private addresses and defaults to require. ca_certificate is an optional PEM CA certificate for instances whose certificate is signed by a private CA. The password is never returned.



## OpenAPI

````yaml /api-reference/costgraph/openapi.json post /api/v1/integrations/postgres/connect
openapi: 3.0.0
info:
  description: Read and manage your CostGraph organization, spend, alerts, and settings.
  title: CostGraph API
  contact: {}
  version: '1.0'
servers:
  - url: https://api.costgraph.ai
security: []
tags:
  - name: ai
    x-group: AI
  - name: ai-serving
    x-group: AI serving
  - name: anomalies
    x-group: Anomalies
  - name: auth
    x-group: Auth
  - name: billing
    x-group: Billing
  - name: billing-export
    x-group: Billing export
  - name: budgets
    x-group: Budgets
  - name: ci
    x-group: CI
  - name: compute-recommendations
    x-group: Compute recommendations
  - name: config
    x-group: Config
  - name: context-graph
    x-group: Context graph
  - name: cost
    x-group: Cost
  - name: gpus
    x-group: GPUs
  - name: graphai
    x-group: Graph AI
  - name: integrations
    x-group: Integrations
  - name: invitations
    x-group: Invitations
  - name: kubernetes-clusters
    x-group: Kubernetes clusters
  - name: marketplace
    x-group: Marketplace
  - name: network
    x-group: Network
  - name: network-requests
    x-group: Network requests
  - name: notifications
    x-group: Notifications
  - name: oauth
    x-group: OAuth
  - name: oauth-clients
    x-group: OAuth clients
  - name: opencost
    x-group: OpenCost
  - name: organization
    x-group: Audit log
  - name: organizations
    x-group: Organizations
  - name: placement-alternatives
    x-group: Placement alternatives
  - name: reports
    x-group: Reports
  - name: sandboxes
    x-group: Sandboxes
  - name: settings
    x-group: Settings
  - name: sso
    x-group: Single sign-on
  - name: tenants
    x-group: Tenants
  - name: ticketing
    x-group: Ticketing
  - name: user
    x-group: Users
  - name: virtual-machines
    x-group: Virtual machines
  - name: virtual-tags
    x-group: Virtual tags
  - name: workflows
    x-group: Workflows
paths:
  /api/v1/integrations/postgres/connect:
    post:
      tags:
        - integrations
      summary: Connect a PostgreSQL instance
      description: >-
        Connects a PostgreSQL instance so CostGraph can split its bill across
        the databases on it and the roles that use them. CostGraph logs in with
        a read-only login that needs the pg_monitor role, and checks the
        connection before saving: the login is refused when it cannot sign in or
        read usage statistics. instance_id is the instance's resource ID on your
        cloud bill; its cost is split from that bill line, and an instance_id
        that matches several resources on the bill is refused. Every hour
        CostGraph reads each database's size and activity, each role's query
        time from pg_stat_statements when that extension is enabled in the
        database it logs in to, and key=value labels from COMMENT ON DATABASE
        and COMMENT ON ROLE, which become tags on the split cost. The split
        appears in cost queries and showback with layer=database. Warnings name
        what is unavailable, such as pg_stat_statements, or that the instance ID
        has no cost on the bill yet. They are also kept on the connection: the
        connection list shows them in warnings, refreshed by every hourly read,
        and a read that fails sets status error with the reason in
        last_sync_error. CostGraph Cloud can only reach public addresses and
        only connects with sslmode verify-full (the default there) or verify-ca,
        so the server's certificate is checked before the password is sent; a
        self-hosted installation can reach private addresses and defaults to
        require. ca_certificate is an optional PEM CA certificate for instances
        whose certificate is signed by a private CA. The password is never
        returned.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/integrations.postgresConnectRequest'
        description: Connection settings
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/responses.SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: >-
                          #/components/schemas/integrations.postgresConnectionResponse
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/middleware.SubscriptionRequiredResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    integrations.postgresConnectRequest:
      type: object
      required:
        - host
        - instance_id
        - tenant_id
        - user
      properties:
        ca_certificate:
          type: string
        database:
          type: string
        host:
          type: string
        instance_id:
          type: string
        name:
          type: string
        password:
          type: string
        port:
          type: integer
        sslmode:
          type: string
          enum:
            - disable
            - allow
            - prefer
            - require
            - verify-ca
            - verify-full
        tenant_id:
          type: string
        user:
          type: string
    responses.SuccessResponse:
      type: object
      required:
        - message
        - status
      properties:
        data: {}
        message:
          type: string
          example: some message
        status:
          type: string
          example: success
    integrations.postgresConnectionResponse:
      type: object
      properties:
        connection:
          $ref: '#/components/schemas/integrations.connectionResponse'
        database:
          type: string
        host:
          type: string
        instance_id:
          type: string
        port:
          type: integer
        sslmode:
          type: string
        user:
          type: string
        warnings:
          type: array
          items:
            type: string
    responses.ErrorResponse:
      type: object
      required:
        - message
        - status
      properties:
        message:
          type: string
          example: some message
        status:
          type: string
          example: error
    middleware.SubscriptionRequiredResponse:
      type: object
      required:
        - code
        - message
        - status
      properties:
        code:
          type: string
          enum:
            - subscription_required
            - free_plan_limit
            - reporting_paused
        message:
          type: string
          example: some message
        status:
          type: string
          example: error
    integrations.connectionResponse:
      type: object
      properties:
        connection_id:
          type: string
        connection_modes:
          type: array
          items:
            type: string
            enum:
              - cost
              - metrics
              - workflows
        created_at:
          type: string
        display_name:
          type: string
        has_metrics_source:
          type: boolean
          nullable: true
        history:
          allOf:
            - $ref: '#/components/schemas/db.ConnectionHistory'
          nullable: true
        hosted:
          type: boolean
        id:
          type: string
        in_jobs:
          type: integer
        ingest_mode:
          type: string
          enum:
            - pull
            - push
            - telemetry
            - export
            - automation
            - ticketing
            - mcp
            - query
        last_sync_error:
          type: string
        last_synced_at:
          type: string
        needs_service_token:
          type: boolean
        provider:
          type: string
        provider_account_id:
          type: string
        recommendations_checked_at:
          type: string
        recommendations_status:
          type: string
        sandbox_provider:
          type: string
          nullable: true
        status:
          type: string
        tenant_id:
          type: string
        trialing_jobs:
          type: integer
        updated_at:
          type: string
        warnings:
          type: array
          items:
            type: string
    db.ConnectionHistory:
      type: object
      required:
        - days_remaining
        - window_days
      properties:
        days_remaining:
          type: integer
        loaded_through:
          type: string
          format: date
          nullable: true
        window_days:
          type: integer
  securitySchemes:
    BearerAuth:
      description: Enter "Bearer {token}"
      type: apiKey
      name: Authorization
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.