Skip to main content
PostgreSQL is a powerful open-source object-relational database system that extends the SQL language with advanced features. It’s known for its reliability, data integrity, and support for complex queries, making it ideal for enterprise applications, data warehousing, and web services.

​
0. Required pre work

In order to connect Nekt to a database, you have to do some pre work to ensure access is granted in a secure way. So, make sure to check this guide before proceeding.

​
Configuring PostgreSQL as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Postgres option from the list of connectors. Click Next and you’ll be prompted to add your database access.

​
1. Add account access

Once you have done the pre work defined in section 0, you can inform your database accesses:
  • Host: The host address of your Postgres database.
  • Port: The port used for connecting to your Postgres database (default: 5432).
  • Database: The name of the database you want to extract data from.
  • User: The user name for accessing your Postgres database.
  • Password: The password used for accessing your Postgres database.
Additionally, the following advanced configurations are available:
  • Sanitize column names: (Default: false) Replace characters rejected by the destination warehouse (e.g., BigQuery) with underscores in column names. Enable this setting when a table has columns with special characters (like ‘Cliente-Código/Nome’), which would otherwise cause the whole sync to fail.
  • Invalid text characters: (Default: Stop the extraction) What to do when a text value contains a character that the source database’s own encoding does not define (common on WIN1252/LATIN1 databases, which PostgreSQL does not validate on write). Stop the extraction aborts the run; Replace the character and continue substitutes the offending character with a replacement symbol (’�’), keeps the rest of the value intact and lists the affected columns in the run log. Correcting the value at the source is what recovers the original character.
Click Next.

​
2. Select streams

The next step is letting us know which streams you want to bring. You can select entire groups of streams or only a subset of them.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: you can choose between INCREMENTAL, FULL TABLE and LOG BASED.
    • Incremental: every time the extraction happens, we’ll get only the new data, which is good if, for example, you want to keep every record ever fetched and save some extraction time.
    • Full table: every time the extraction happens, we’ll get the current state of the data, which is good if, for example, you don’t want to have deleted data in your catalog.
    • Log based: to support log based syncs, you have to do a little pre work on your database. Check the procedure here.
Click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization. You can inform things like what data it brings, to which team it belongs, etc. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Click Done to finalize the setup. Once completed, you’ll receive confirmation that your new source is set up!

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.
If you encounter any issues, reach out to us via Slack, and we’ll gladly assist you!

​
Streams and Fields

For PostgreSQL, the streams correspond to the tables and views in the schemas your database user is allowed to read, and the fields correspond to their columns. They are discovered dynamically when the source is created, so there is no fixed list of streams.

​
Implementation Notes

​
Database Compatibility

The PostgreSQL connector is designed to be highly compatible with standard PostgreSQL databases as well as Postgres-compatible virtual databases and SQL APIs (such as the Cube.dev SQL API). During the discovery phase, the connector gracefully tolerates missing system tables (such as pg_catalog.pg_opclass) that might not be fully implemented in some virtual databases. If primary key or index reflection fails due to missing system metadata, the connector will continue discovery without inferring primary keys, ensuring your tables and views are still available for syncing.

​
Character Encodings

PostgreSQL does not validate single-byte encodings (such as WIN1252 or LATIN1) on write, meaning invalid bytes can be stored in the database and only cause errors when read during extraction. If a run fails with a 'charmap' codec can't decode byte error, switch the Invalid text characters advanced setting to Replace the character and continue. The offending characters are substituted with a replacement symbol (’�’), the rest of each value is preserved, and the run log names the affected columns and how many values were changed in each. The original characters can only be recovered by correcting the values at the source.

​
SSH Tunnel Key Types

When connecting through an SSH tunnel, use a modern private key type such as Ed25519, ECDSA or RSA. DSA/DSS keys are no longer supported by the SSH library the connector uses and cannot be loaded for tunnel authentication.

​
Troubleshooting

Extraction runs plain SELECT statements. It takes no read locks and does not block writes on the source database.

​
Skills for agents

Download PostgreSQL skills file

PostgreSQL connector documentation as plain markdown, for use in AI agent contexts.