SQL Server connector#

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

Requirements#

The connector supports SQL Server 2016, SQL Server 2014, SQL Server 2012 and Azure SQL Database as connected data sources.

Configuration#

The connector can query a single database on an SQL server instance. Create a catalog properties file that specifies the SQL server connector by setting the connector.name to sqlserver.

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

connector.name=sqlserver
connection-url=jdbc:sqlserver://<host>:<port>;database=<database>
connection-user=root
connection-password=secret

The connection-url defines the connection information and parameters to pass to the SQL Server JDBC driver. The supported parameters for the URL are available in the SQL Server JDBC driver documentation.

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 SQL Server databases or servers#

The SQL Server connector can’t access more than one database using a single catalog.

If you have multiple databases, or want to access multiple instances of SQL Server, you need to configure one catalog for each instance.

To add another catalog:

  • Add another properties file to etc/catalog

  • Save it with a different name that ends in .properties

For example, if you name the property file sales.properties, Trino uses the configured connector to create a catalog named sales.

Querying SQL Server#

The SQL Server connector provides access to all schemas visible to the specified user in the configured database. For the following examples, assume the SQL Server catalog is sqlserver.

You can see the available schemas by running SHOW SCHEMAS:

SHOW SCHEMAS FROM sqlserver;

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

SHOW TABLES FROM sqlserver.web;

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

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

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

SELECT * FROM sqlserver.web.clicks;

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

Type mapping#

Trino supports the following SQL Server data types:

SQL Server Type

Trino Type

bigint

bigint

smallint

smallint

int

integer

float

double

char(n)

char(n)

varchar(n)

varchar(n)

date

date

datetime2(n)

timestamp(n)

Complete list of SQL Server data types.

JDBC type mapping and metadata cache#

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.

Configuration properties that manage JDBC type mapping and metadata cache#

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

case-insensitive-name-matching

Support case insensitive database and collection names

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

SQL support#

The following SQL statements are not yet supported:

Pushdown#

The connector supports pushdown for a number of operations:

Aggregate pushdown for the following functions:

Data compression#

You can specify the data compression policy for SQL Server tables with the data_compression table property. Valid policies are NONE, ROW or PAGE.

Example:

CREATE TABLE myschema.scientists (
  recordkey VARCHAR,
  name VARCHAR,
  age BIGINT,
  birthday DATE
)
WITH (
  data_compression = 'ROW'
);