PostgreSQL connector#

The PostgreSQL connector allows querying and creating tables in an external PostgreSQL database. This can be used to join data between different systems like PostgreSQL and Hive, or between different PostgreSQL instances.

Requirements#

To connect to PostgreSQL, you need:

PostgreSQL 9.6 or higher.
Network access from the Trino coordinator and workers to PostgreSQL. Port 5432 is the default port.

Configuration#

The connector can query a database on a PostgreSQL server. Create a catalog properties file that specifies the PostgreSQL connector by setting the connector.name to postgresql.

For example, to access a database as the postgresql catalog, create the file etc/catalog/postgresql.properties. Replace the connection properties as appropriate for your setup:

connector.name=postgresql
connection-url=jdbc:postgresql://example.net:5432/database
connection-user=root
connection-password=secret

The connection-url defines the connection information and parameters to pass to the PostgreSQL JDBC driver. The parameters for the URL are available in the PostgreSQL JDBC driver documentation. Some parameters can have adverse effects on the connector behavior or not work with the connector.

The connection-user and connection-password are typically required and determine the user credentials for the connection, often a service user. You can use secrets to avoid actual values in the catalog properties files.

Multiple PostgreSQL databases or servers#

The PostgreSQL connector can only access a single database within a PostgreSQL server. Thus, if you have multiple PostgreSQL databases, or want to connect to multiple PostgreSQL servers, you must configure multiple instances of the PostgreSQL connector.

To add another catalog, simply add another properties file to etc/catalog with a different name, making sure it ends in .properties. For example, if you name the property file sales.properties, Trino creates a catalog named sales using the configured connector.

General configuration properties#

The following table describes general configuration properties for the connector:

Property name	Description	Default value
`case-insensitive-name-matching`	Match schema and table names case insensitively	False
`case-insensitive-name-matching.cache-ttl`		1 minute
`metadata.cache-ttl`	Duration for which metadata, including table and column statistics, is cached	0 (disabled caching)
`metadata.cache-missing`	Cache the fact that metadata, including table and column statistics, is not available	False
`metadata.cache-maximum-size`	Maximum number of objects stored in the metadata cache	10000
`write.batch-size`	Maximum number of statements in a batched execution. Do not change this setting from the default. Non-default values may negatively impact performance.	1000
`join-pushdown.enabled`	Enable join pushdown. Equivalent catalog session property is `join_pushdown_enabled`. Enabling this may negatively impact performance for some queries.	False

Non-transactional INSERT#

The connector supports adding rows using INSERT statements. By default, data insertion is performed by writing data to a temporary table. You can skip this step to improve performance and write directly to the target table. Set the insert.non-transactional-insert.enabled catalog property or the corresponding non_transactional_insert catalog session property to true.

Note that with this property enabled, data can be corrupted in rare cases where exceptions occur during the insert operation. With transactions disabled, no rollback can be performed.

Type mapping#

Decimal type handling#

DECIMAL types with precision larger than 38 can be mapped to a Trino DECIMAL by setting the decimal-mapping configuration property or the decimal_mapping session property to allow_overflow. The scale of the resulting type is controlled via the decimal-default-scale configuration property or the decimal-rounding-mode session property. The precision is always 38.

By default, values that require rounding or truncation to fit will cause a failure at runtime. This behavior is controlled via the decimal-rounding-mode configuration property or the decimal_rounding_mode session property, which can be set to UNNECESSARY (the default), UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, or HALF_EVEN (see RoundingMode).

Array type handling#

The PostgreSQL array implementation does not support fixed dimensions whereas Trino support only arrays with fixed dimensions. You can configure how the PostgreSQL connector handles arrays with the postgresql.array-mapping configuration property in your catalog file or the array_mapping session property. The following values are accepted for this property:

DISABLED (default): array columns are skipped.
AS_ARRAY: array columns are interpreted as Trino ARRAY type, for array columns with fixed dimensions.
AS_JSON: array columns are interpreted as Trino JSON type, with no constraint on dimensions.

General configuration properties#

The following properties can be used to configure how data types from the connected data source are mapped to Trino data types and how the metadata is cached in Trino.

Property name

Description

Default value

unsupported-type-handling

Configure how unsupported column data types are handled:

IGNORE, column is not accessible.
CONVERT_TO_VARCHAR, column is converted to unbounded VARCHAR.

The respective catalog session property is unsupported_type_handling.

IGNORE

jdbc-types-mapped-to-varchar

Allow forced mapping of comma separated lists of data types to convert to unbounded VARCHAR

Querying PostgreSQL#

The PostgreSQL connector provides a schema for every PostgreSQL schema. You can see the available PostgreSQL schemas by running SHOW SCHEMAS:

SHOW SCHEMAS FROM postgresql;

If you have a PostgreSQL schema named web, you can view the tables in this schema by running SHOW TABLES:

SHOW TABLES FROM postgresql.web;

You can see a list of the columns in the clicks table in the web database using either of the following:

DESCRIBE postgresql.web.clicks;
SHOW COLUMNS FROM postgresql.web.clicks;

Finally, you can access the clicks table in the web schema:

SELECT * FROM postgresql.web.clicks;

If you used a different name for your catalog properties file, use that catalog name instead of postgresql in the above examples.

SQL support#

The connector provides read access and write access to data and metadata in PostgreSQL. In addition to the globally available and read operation statements, the connector supports the following features:

SQL DELETE#

If a WHERE clause is specified, the DELETE operation only works if the predicate in the clause can be fully pushed down to the data source.

ALTER TABLE#

The connector does not support renaming tables across multiple schemas. For example, the following statement is supported:

ALTER TABLE catalog.schema_one.table_one RENAME TO catalog.schema_one.table_two

The following statement attempts to rename a table across schemas, and therefore is not supported:

ALTER TABLE catalog.schema_one.table_one RENAME TO catalog.schema_two.table_two

Pushdown#

The connector supports pushdown for a number of operations:

Aggregate pushdown for the following functions: