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

# PostgreSQL Integration for AI Agents & Workflows

> PostgreSQL database integration for executing SQL queries, managing tables, and performing CRUD operations. Uses the asyncpg driver.

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/df8MOr-hXotYLTh5/logos/postgresql.svg?fit=max&auto=format&n=df8MOr-hXotYLTh5&q=85&s=8e76538a0a61744d4f1ea09be55fd662" alt="PostgreSQL logo" width="72" height="72" data-path="logos/postgresql.svg" />

## Overview

Add **PostgreSQL** to any ModuleX agent or workflow. PostgreSQL database integration via the `asyncpg` driver. Provides raw SQL execution + CRUD + upsert + introspection.

<Info>
  **Categories**: Databases · Database · Data Management · Storage · **Auth**: PostgreSQL Database Credentials · **Actions**: 10
</Info>

## Authentication

### PostgreSQL Database Credentials

Authenticate using PostgreSQL connection credentials (host/port/user/password/database).

#### Required Credentials

| Field    | Description                                                                                                   | Required | Format                              |                    |            |
| -------- | ------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------- | ------------------ | ---------- |
| Host     | PostgreSQL server hostname or IP                                                                              | Yes      | `localhost or postgres.example.com` |                    |            |
| Port     | PostgreSQL server port (defaults to 5432 if omitted)                                                          | No       | `5432`                              |                    |            |
| Username | PostgreSQL username for authentication                                                                        | Yes      | `-`                                 |                    |            |
| Password | PostgreSQL password for authentication                                                                        | Yes      | `-`                                 |                    |            |
| Database | The database name to connect to                                                                               | Yes      | `-`                                 |                    |            |
| SSL Mode | SSL mode: 'disabled', 'verify' (default — full verify), or 'skip\_verification' (encrypted but no cert check) | No       | \`verify                            | skip\_verification | disabled\` |

## Available Actions

<AccordionGroup>
  <Accordion title="execute_raw_query — Execute a raw SQL statement (SELECT/INSERT/UPDATE/DELETE/DDL). Use $1, $2, ... placeholders for parameterized queries.">
    ### Parameters

    <ResponseField name="sql" type="string" required>
      The SQL to execute
    </ResponseField>

    <ResponseField name="values" type="array">
      Values for $1, $2, ... placeholders
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "row_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Row Count"
        },
        "data": {
          "anyOf": [
            {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Data"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        },
        "affected_rows": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Affected Rows"
        }
      },
      "required": [
        "success"
      ],
      "title": "ExecuteRawQueryOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_row — INSERT a new row, returning the inserted record">
    ### Parameters

    <ResponseField name="table" type="string" required>
      The table name
    </ResponseField>

    <ResponseField name="data" type="object" required>
      Column-value pairs to insert
    </ResponseField>

    <ResponseField name="schema_name" type="string">
      The schema name (default 'public') (Default: `public`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "table": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Table"
        },
        "schema_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Schema Name"
        },
        "inserted_row": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Inserted Row"
        },
        "columns": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Columns"
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateRowOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="delete_row — DELETE rows matching a WHERE condition (returns deleted rows)">
    ### Parameters

    <ResponseField name="table" type="string" required>
      The table name
    </ResponseField>

    <ResponseField name="condition" type="string" required>
      WHERE condition with '?' placeholders
    </ResponseField>

    <ResponseField name="values" type="array" required>
      Values matching the '?' placeholders in the condition
    </ResponseField>

    <ResponseField name="schema_name" type="string">
      The schema name (default 'public') (Default: `public`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "table": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Table"
        },
        "schema_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Schema Name"
        },
        "affected_rows": {
          "default": 0,
          "title": "Affected Rows",
          "type": "integer"
        },
        "deleted_rows": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Deleted Rows",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "DeleteRowOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="update_row — UPDATE rows matching a WHERE condition (returns updated rows)">
    ### Parameters

    <ResponseField name="table" type="string" required>
      The table name
    </ResponseField>

    <ResponseField name="data" type="object" required>
      Column-value pairs to update
    </ResponseField>

    <ResponseField name="condition" type="string" required>
      WHERE condition with '?' placeholders
    </ResponseField>

    <ResponseField name="condition_values" type="array" required>
      Values matching the '?' placeholders
    </ResponseField>

    <ResponseField name="schema_name" type="string">
      The schema name (default 'public') (Default: `public`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "table": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Table"
        },
        "schema_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Schema Name"
        },
        "affected_rows": {
          "default": 0,
          "title": "Affected Rows",
          "type": "integer"
        },
        "updated_columns": {
          "items": {
            "type": "string"
          },
          "title": "Updated Columns",
          "type": "array"
        },
        "updated_rows": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Updated Rows",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "UpdateRowOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="upsert_row — INSERT … ON CONFLICT (conflict_target) DO UPDATE …">
    ### Parameters

    <ResponseField name="table" type="string" required>
      The table name
    </ResponseField>

    <ResponseField name="data" type="object" required>
      Column-value pairs to insert/update
    </ResponseField>

    <ResponseField name="conflict_target" type="string" required>
      Column to use for conflict detection (usually PK)
    </ResponseField>

    <ResponseField name="schema_name" type="string">
      The schema name (default 'public') (Default: `public`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "table": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Table"
        },
        "schema_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Schema Name"
        },
        "upserted_row": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Upserted Row"
        },
        "conflict_target": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Conflict Target"
        }
      },
      "required": [
        "success"
      ],
      "title": "UpsertRowOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="find_row — SELECT * FROM table WHERE column <op> value">
    ### Parameters

    <ResponseField name="table" type="string" required>
      The table name
    </ResponseField>

    <ResponseField name="column" type="string" required>
      The column to filter by
    </ResponseField>

    <ResponseField name="operator" type="string">
      Comparison operator (=, >, >=, \<, !=, \<=, LIKE, ILIKE) (Default: `=`)
    </ResponseField>

    <ResponseField name="value" type="string">
      Value to compare against (typed dynamically)
    </ResponseField>

    <ResponseField name="schema_name" type="string">
      The schema name (default 'public') (Default: `public`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "table": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Table"
        },
        "schema_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Schema Name"
        },
        "row_count": {
          "default": 0,
          "title": "Row Count",
          "type": "integer"
        },
        "data": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Data",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "FindRowOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="execute_query_with_condition — SELECT * FROM table WHERE <condition>">
    ### Parameters

    <ResponseField name="table" type="string" required>
      The table name
    </ResponseField>

    <ResponseField name="condition" type="string" required>
      WHERE condition with '?' placeholders
    </ResponseField>

    <ResponseField name="values" type="array" required>
      Values matching the '?' placeholders in the condition
    </ResponseField>

    <ResponseField name="schema_name" type="string">
      The schema name (default 'public') (Default: `public`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "table": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Table"
        },
        "schema_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Schema Name"
        },
        "row_count": {
          "default": 0,
          "title": "Row Count",
          "type": "integer"
        },
        "data": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Data",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ExecuteQueryWithConditionOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_schemas — List all user-visible schemas (excludes pg_catalog etc.)">
    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "schemas": {
          "items": {
            "type": "string"
          },
          "title": "Schemas",
          "type": "array"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListSchemasOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_tables — List all tables and views in a schema">
    ### Parameters

    <ResponseField name="schema_name" type="string">
      The schema name (default 'public') (Default: `public`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "TableEntry": {
          "additionalProperties": false,
          "properties": {
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Name"
            },
            "type": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Type"
            }
          },
          "title": "TableEntry",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "schema_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Schema Name"
        },
        "tables": {
          "items": {
            "$ref": "#/$defs/TableEntry"
          },
          "title": "Tables",
          "type": "array"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListTablesOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="describe_table — Return column metadata + primary keys for a table">
    ### Parameters

    <ResponseField name="table" type="string" required>
      The table name
    </ResponseField>

    <ResponseField name="schema_name" type="string">
      The schema name (default 'public') (Default: `public`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "table": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Table"
        },
        "schema_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Schema Name"
        },
        "columns": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Columns",
          "type": "array"
        },
        "column_count": {
          "default": 0,
          "title": "Column Count",
          "type": "integer"
        },
        "primary_keys": {
          "items": {
            "type": "string"
          },
          "title": "Primary Keys",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "DescribeTableOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* 60s connection timeout.
* `find_row` operator allowlist: `=`, `>`, `>=`, `<`, `!=`, `<=`,
  `LIKE`, `ILIKE` (case-insensitive accepted as `like`/`ilike` too).
* `asyncpg` is imported lazily so the manifest can be inspected
  even without the driver installed.

## Related integrations

<CardGroup cols={3}>
  <Card title="MySQL" href="/integrations/tools/mysql" />

  <Card title="Snowflake" href="/integrations/tools/snowflake" />

  <Card title="Supabase" href="/integrations/tools/supabase" />
</CardGroup>

## Links

* [PostgreSQL](https://www.postgresql.org/)