> 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/stage-2-productize/connect-to-engine/postgres.md).

# Postgres

PostgreSQL is useful for local development, smaller projects, and environments where you want direct control over the database infrastructure.

***

### Engine adapter type

For PostgreSQL, you configure a gateway with the following adapter type:

```yaml
type: postgres
```

### Before you start

Make sure you have:

* A PostgreSQL server instance (version 12 or higher) is recommended)
* A database user with the required permissions
* Network connectivity from Vulcan to the PostgreSQL server
* Database connection details:
  * host, port, database, username, password

### Required permissions

The PostgreSQL user should have these permissions:

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

### Required connection options

Use these fields in your PostgreSQL gateway configuration:

| Option     | Description                             |
| ---------- | --------------------------------------- |
| `type`     | Engine type. Must be `postgres`.        |
| `host`     | Hostname of the PostgreSQL server.      |
| `user`     | Username used to connect to PostgreSQL. |
| `password` | Password used to connect to PostgreSQL. |
| `port`     | PostgreSQL server port.                 |
| `database` | Database name to connect to.            |

***

### Optional connection options

Use these only if your environment requires them:

| Option             | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `sslmode`          | SSL mode for secure connections. Use `require` for production environments. |
| `connect_timeout`  | Number of seconds to wait before the connection times out.                  |
| `keepalives_idle`  | Number of seconds between keepalive packets.                                |
| `role`             | PostgreSQL role to use for authentication.                                  |
| `application_name` | Application name used for the connection.                                   |

### Example configuration

Add a PostgreSQL gateway to your Vulcan project configuration.

```yaml
gateways:
  postgres:
    type: postgres
    host: <postgres-host>
    port: 5432
    database: <database-name>
    user: <username>
    password: <password>
    sslmode: require
```

Use `sslmode: require` for secure production connections.

### Materialization behavior

Vulcan uses different materialization behavior depending on the model kind.

| Model kind                  | PostgreSQL behavior                                        |
| --------------------------- | ---------------------------------------------------------- |
| `FULL`                      | Drops the table, creates it again, and inserts all data.   |
| `INCREMENTAL_BY_TIME_RANGE` | Deletes rows in the time range, then inserts new data.     |
| `INCREMENTAL_BY_UNIQUE_KEY` | Merges records using a unique key.                         |
| `INCREMENTAL_BY_PARTITION`  | Deletes rows for the partition key, then inserts new data. |

For a quick start:

* Use `FULL` when you want to rebuild the output from scratch.
* Use incremental strategies when you want to update only changed records, time ranges, or partitions.

### Next steps

After configuring PostgreSQL, continue with:

```
Connect to Engine → Define models and logic → Validate and test locally
```

For more details, refer to \[Concepts]


---

# 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/stage-2-productize/connect-to-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.