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

# PostgreSQL

> Prepare a secure, read-only PostgreSQL connection for Platinur.

PostgreSQL is a native Platinur v1 source. Platinur discovers the tables visible to the configured
user and loads the tables you select into a dedicated `raw_` ClickHouse database.

## Before you connect

Prepare:

* a publicly reachable PostgreSQL hostname;
* port `5432`, unless your provider uses another TLS endpoint;
* the database name and optional source schema;
* a dedicated read-only username and password; and
* a server certificate trusted by the standard CA bundle and valid for the hostname.

Platinur does not expose SSH tunnel fields in v1. Private-only database hosts require a reviewed
network path before they can be used.

## Create a read-only user

Create a separate login rather than sharing an application administrator. Adjust the database,
schema, and role names for your installation:

```sql theme={null}
create role platinur_reader login password '<generate-a-strong-password>';
grant connect on database app_database to platinur_reader;
grant usage on schema public to platinur_reader;
grant select on all tables in schema public to platinur_reader;
alter default privileges in schema public
  grant select on tables to platinur_reader;
```

Run the default-privileges statement as the role that creates future tables. Grant access to only
the schemas Platinur should load.

## Network access

Allow inbound PostgreSQL TLS connections from the Platinur host address provided by support or
your workspace administrator. Use the provider's direct or pooled TLS hostname, not a private
address such as `localhost`, `10.x.x.x`, or an internal service name.

For managed providers, use the provider's connection-details page to copy the public **host**,
**port**, and **database**. Do not copy a URI containing a password into a ticket or chat; paste
the values into their separate Platinur fields instead.

## Connect in Platinur

1. Open **Integrations → New Source → PostgreSQL**.
2. Enter a source name and target schema suffix.
3. Enter the host, port, database, optional schema, username, and password.
4. Test the connection, then save it.
5. Open **Schema**, discover the database, and choose the tables to load.

The Platinur fields map directly to the values above: **Host**, **Port**, **Database**, optional
**Schema**, **Username** (`platinur_reader`), and **Password**. **Test Connection** must succeed
before you create the source; after it is saved, use **Schema** to discover tables and **Sync** to
run the first load.

The same verified TLS connection is used for testing, discovery, and every sync. A successful
test cannot fall back to plaintext during loading.

## Refresh behavior

Database tables support Override, Append, and Merge when the selected table has the required
cursor or primary-key contract. Start with Override unless you have confirmed the incremental
columns. You can run the source manually or configure a schedule.

## Troubleshooting

* **Host or port unreachable:** confirm the public hostname, firewall, allowlist, and port.
* **TLS or hostname failure:** use the provider hostname covered by its certificate; IP addresses
  commonly fail hostname verification.
* **Authentication failed:** verify the dedicated username and rotate the stored password.
* **No tables discovered:** grant `USAGE` on the schema and `SELECT` on the intended tables.
* **A table fails during sync:** check that the reader retained access and that the table was not
  renamed or removed after discovery.

## Rotate or revoke access

To rotate the password, set a new password for `platinur_reader`, replace the password on the
source's **Config** tab, and select **Test Connection** before the old password expires. To stop
access immediately, disable the source and revoke the role's `CONNECT`/`SELECT` grants or drop
the login; subsequent runs will fail safely without exposing the password.

## Official PostgreSQL references

* [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html)
* [GRANT](https://www.postgresql.org/docs/current/sql-grant.html)
* [Client authentication and TLS](https://www.postgresql.org/docs/current/client-authentication.html)