The complete public API of @lakeql/adapter-trino, generated from the package's TypeScript source.
Register the adapter with trinoAdapterDefinition in your config. The rest of the surface is the connection config (TrinoConnectionConfig, TrinoAuth), the write strategies and their configs, the SQL dialect, the response normalizer, and the type mapper that the runtime wires together.
Trino adapter factory implementing the neutral AdapterFactory contract.
The factory is stateless: it retains no mutable per-data-source state between calls to createDataSource(), createReadStrategy(), and createWriteStrategy(). All construction methods are synchronous and do not perform network requests, metadata discovery, hidden global registration, or environment lookup.
Definition
AdapterFactoryTyped-config registration value compatible with AdapterDefinition<"trino", TrinoConnectionConfig, unknown, TrinoWriteConfig> from @lakeql/config through structural typing.
The adapter package does NOT import or depend on @lakeql/config. This definition is consumed by defineConfig() to provide compile-time connection-shape inference and per-adapter writeConfig narrowing (TrinoWriteConfig) for Trino data sources.
Intentionally omits registrationOptions and mergeDataSourceConfig because Trino receives a complete explicit connection payload.
Definition
{
/** Literal adapter name for typed narrowing. */
adapterName: ADAPTER_NAME,
/** The exact adapter factory instance. */
factory: trinoAdapterFactory,
/** The shared assertion-style config validator. */
validateDataSourceConfig: validateTrinoConfig,
/**
* Pins the adapter's `writeConfig` type to {@link TrinoWriteConfig} at the
* `defineConfig()` call site. Carries the compile-time type only; runtime
* validation happens in {@link trinoAdapterFactory.createWriteStrategy}.
*/
validateWriteConfig: validateTrinoWriteConfig,
} as constAdapter name literal for the Trino adapter. Used across all modules.
Definition
"trino" as constAssertion-style validator for TrinoConnectionConfig.
Validates the shape and constraints of a Trino connection configuration payload. Throws a plain Error synchronously when the input is invalid. Error messages identify the offending field by name but never include passwords, bearer tokens, authorization headers, or serialized configuration objects.
The same implementation is used at both the defineConfig() boundary (via trinoAdapterDefinition.validateDataSourceConfig) and the trinoAdapterFactory.createDataSource() boundary, ensuring a single set of validation rules.
Parameters
| Name | Type |
|---|---|
| configRequired | unknown |
The unknown value to validate. | |
Returns
asserts config is TrinoConnectionConfigValidates the Trino adapter writeConfig and narrows it by strategy.
An absent strategy is treated as "storage". The "storage" branch is validated by the storage strategy factory, so only its discriminator is checked here. The "insert" branch is validated fully, rejecting surplus fields and malformed options.
Parameters
| Name | Type |
|---|---|
| writeConfigRequired | unknown |
The adapter-owned write configuration to validate. | |
Returns
asserts writeConfig is TrinoWriteConfigConfiguration for connecting to a Trino coordinator.
Fields mirror TrinoClientProps from @lakeql/trino-client. The outer runtime definition owns adapter selection through its adapter field; this type intentionally does not include an inner adapter discriminator.
Properties
| Name | Type |
|---|---|
| hostRequired | string |
Trino coordinator hostname including protocol (e.g. "https://trino.example.com"). | |
| portRequired | number |
Port the Trino coordinator listens on. | |
| catalogRequired | string |
Default catalog for all queries. | |
| schema? | string |
Optional default schema. | |
| source? | string |
Source identifier for Trino’s X-Trino-Source header. | |
| authRequired | TrinoAuth |
Authentication credentials. | |
| retry? | RetryConfig |
Retry configuration forwarded unchanged to the Trino client. | |
| timeout? | number |
Default query timeout in milliseconds. | |
Authentication credentials for a Trino connection — either basic (username/password) or bearer (token).
Basic authentication using username and password.
Properties
| Name | Type |
|---|---|
| typeRequired | "basic" |
| usernameRequired | string |
The authentication username. | |
| passwordRequired | string |
The authentication password. | |
Bearer token authentication (e.g. OAuth2 or JWT).
Properties
| Name | Type |
|---|---|
| typeRequired | "bearer" |
| tokenRequired | string |
The bearer token value. | |
The Trino adapter’s write configuration, a discriminated union on strategy. Selects between the storage (default) and INSERT strategies.
Definition
TrinoStorageWriteConfig | TrinoInsertWriteConfigStorage (external-location + DDL) write strategy configuration.
This is the existing Hive/upload strategy, selected by default. The runtime injects dataSource; the config carries files, serializer, and optional prefix/shadow-table settings (validated by the storage strategy factory itself, not here).
Properties
| Name | Type |
|---|---|
| strategy? | "storage" |
Discriminator; defaults to "storage" when omitted. | |
INSERT write strategy configuration. Writes via INSERT INTO with no object storage.
Properties
| Name | Type |
|---|---|
| strategyRequired | "insert" |
Discriminator selecting the INSERT strategy. | |
| batchSize? | number |
Maximum number of rows per INSERT ... VALUES batch. 1000 | |
| autoCreateTable? | boolean |
When true, issue CREATE TABLE IF NOT EXISTS before appending, and use a pending-table swap for full_load. false | |
| tableProperties? | Record<string, string> |
Optional table properties applied on table creation. | |
Parameters
| Name | Type |
|---|---|
| errorRequired | unknown |
| dataSourceRequired | string |
Returns
DataSourceErrorTrino query dialect implementing the neutral QueryDialect contract.
Uses Kysely’s Postgres adapter/compiler since Trino’s SQL dialect is Postgres-compatible for query compilation purposes. The dialect provides Trino-specific SQL fragments for timestamp conversion, pagination, and identifier quoting.
Definition
QueryDialectTrino response normalizer implementing the neutral ResponseNormalizer contract. Accepts only true as the record sentinel.
Definition
ResponseNormalizerShared TypeMapper for Trino SQL types.
Definition
createTypeMapper({
toPrimitive: TRINO_TO_PRIMITIVE,
toEngine: PRIMITIVE_TO_TRINO,
})Creates a HiveTableManager that executes DDL via a DataSource instance. Implements the full TableManager interface with Hive-specific DDL (external tables with PARQUET format and storage locations).
URI scheme is automatically resolved from the files-sdk adapter:
- S3-compatible providers (s3, minio, r2, wasabi, etc.) → s3a://
- GCS → gs://
- Azure → abfss://
- Unknown providers → s3a:// (default)
The bucket is derived from files.adapter.bucket. If the adapter does not expose a bucket property, externalLocationPrefix must be provided.
Table recreation uses a shadow-table pattern for safe DDL replacement:
- Drop pre-existing shadow table (if not retaining)
- Create a shadow table to validate DDL
- Drop the original table
- Create the real table with the validated DDL
- Clean up the shadow table (unless keepShadowTables is true)
Parameters
| Name | Type |
|---|---|
| configRequired | HiveTableManagerConfig |
Returns
TableManagerConfiguration for the Hive Table Manager.
Properties
| Name | Type |
|---|---|
| dataSourceRequired | DataSource |
The DataSource instance to use for DDL operations. | |
| filesRequired | Files |
The files-sdk instance for deriving external location URIs. | |
| externalLocationPrefix? | string |
Override for Hive external_location prefix. Auto-derived from files.adapter.name + files.adapter.bucket for known providers. Recommended to set explicitly for production/Azure/custom Hadoop connectors. When provided, used verbatim as the prefix for buildExternalLocation. | |
| keepShadowTables? | boolean |
When true, shadow tables are not dropped after successful recreation. Default: false. | |
Creates a Trino-specific DataSourceWriteStrategy that performs the Upload+DDL pattern via the storage write pipeline.
The strategy internally constructs StorageOperations from the provided Files instance and a HiveTableManager from the DataSource + Files. Write calls are delegated to executeWritePipeline with pre-resolved dependencies.
Parameters
| Name | Type |
|---|---|
| configRequired | TrinoWriteStrategyConfig |
Returns
DataSourceWriteStrategyConfiguration for the Trino write strategy factory.
Properties
| Name | Type |
|---|---|
| filesRequired | Files |
The files-sdk instance for object storage operations. | |
| dataSourceRequired | DataSource |
The DataSource instance for DDL operations. | |
| serializerRequired | Serializer |
Serializer for data format conversion (e.g. parquetSerializer()). | |
| externalLocationPrefix? | string |
Override for Hive external_location prefix. Auto-derived from files.adapter.name + files.adapter.bucket for known providers. Recommended to set explicitly for production/Azure/custom Hadoop connectors. | |
| keepShadowTables? | boolean |
When true, shadow tables are retained after successful DDL. Default: false. | |
Creates a Trino DataSourceWriteStrategy that writes via INSERT INTO.
Capability requirements are checked eagerly: autoCreateTable and the full_load/full_load_append swap require the data source to report DDL support.
Parameters
| Name | Type |
|---|---|
| argsRequired | TrinoInsertWriteStrategyConfig |
Data source, its name, and INSERT options. | |
Returns
DataSourceWriteStrategyA write strategy backed by batched INSERT statements.
Default number of rows per INSERT ... VALUES batch.
Definition
1000Resolved configuration for createTrinoInsertWriteStrategy.
Properties
| Name | Type | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| dataSourceRequired | DataSource | ||||||||
Data source used to execute INSERT/DDL statements. | |||||||||
| dataSourceNameRequired | string | ||||||||
Configured runtime name of the data source (for error context). | |||||||||
| configRequired | Object | ||||||||
Adapter-owned INSERT write options. | |||||||||
| |||||||||