> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/v1/productize/connect-engine/postgres.md).

# Postgres

PostgreSQL suits smaller products, prototypes, and local-first work where you want direct control over the database. It's the engine behind the `orders-analytics` example used throughout this guide. Use the `postgres` adapter to connect. For the full reference, see the [Postgres engine manual](https://v2.dataos.info/references/engine-guide/postgres) in References.

## Before you start

* A PostgreSQL server (version 12 or higher recommended).
* A database user with the required permissions.
* Network connectivity from Vulcan to the server, and the connection details: host, port, database, user, password.
* `connection.database` must already exist before `vulcan plan`: Postgres has no catalog tier, and Vulcan doesn't create the database itself.
* DataOS access: a `roles:id:data-dev`-equivalent role tag, `depot:rw:<postgres-depot-name>` (or `depot:r` for read-only), **Can Use** on Compute/Depots/Secrets, and a git-sync Secret.

## Permissions

| Permission                                       | Required for                     |
| ------------------------------------------------ | -------------------------------- |
| `CREATE` on the database                         | Creating schemas                 |
| `CREATE` on schemas                              | Creating tables and views        |
| `SELECT`, `INSERT`, `UPDATE`, `DELETE` on tables | Reading and writing model output |
| `USAGE` on schemas                               | Accessing schemas Vulcan uses    |

## Connection options

| Option                                                           | Required | Description                            |
| ---------------------------------------------------------------- | :------: | -------------------------------------- |
| `type`                                                           |    Yes   | Must be `postgres`                     |
| `host`                                                           |    Yes   | Server hostname                        |
| `port`                                                           |    Yes   | Server port                            |
| `database`                                                       |    Yes   | Database name                          |
| `user`                                                           |    Yes   | Connection username                    |
| `password`                                                       |    Yes   | Connection password                    |
| `sslmode`                                                        |    No    | SSL mode. Use `require` in production. |
| `connect_timeout`, `keepalives_idle`, `role`, `application_name` |    No    | Tune as your environment needs         |

### Authentication methods

* **Username and password** (required): set `user` and `password`.
* **SSL mode** (optional): set `sslmode: require` or stricter for secure connections in production.

## Example

```yaml
gateways:
  postgres:
    connection:
      type: postgres
      host: <postgres-host>
      port: 5432
      database: <database-name>
      user: <username>
      password: "{{ env_var('PG_PASSWORD') }}"
      sslmode: require
```

## Supported model kinds

`SEED`, `FULL`, `VIEW`, `INCREMENTAL_BY_TIME_RANGE`, `INCREMENTAL_BY_UNIQUE_KEY`, `INCREMENTAL_BY_PARTITION`, `INCREMENTAL_UNMANAGED`, `SCD_TYPE_2`, `SCD_TYPE_2_BY_TIME`, `SCD_TYPE_2_BY_COLUMN`, and `EMBEDDED`. For how each kind materializes, see the [Postgres engine manual](https://v2.dataos.info/references/engine-guide/postgres).

> Postgres folds unquoted identifiers to lowercase (the opposite of Snowflake and Spark's UPPERCASE convention). Author model names, columns, semantic references, and metric references in lowercase, or quote identifiers consistently everywhere.

Once `vulcan info` succeeds, continue to [Assets](/build/v1/productize/assets.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/build/v1/productize/connect-engine/postgres.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.