trino Documentation

File: README.md Copy Chapter

Development Copy Chapter

See DEVELOPMENT for information about development and release process,
code style and guidelines for implementors of Trino plugins.

See CONTRIBUTING for contribution requirements.

Security Copy Chapter

See the project security policy for
information about reporting vulnerabilities.

Trino supports reproducible builds as of version 449.

Build requirements Copy Chapter

• Mac OS X or Linux
  • Note that some npm packages used to build the web UI are only available
    for x86 architectures, so if you're building on Apple Silicon, you need
    to have Rosetta 2 installed.
• Java 25.0.1+, 64-bit
• Docker
  • Turn SELinux or other systems disabling write access to the local checkout
    off, to allow containers to mount parts of the Trino source tree

Building Trino Copy Chapter

Trino is a standard Maven project. Simply run the following command from the
project root directory:

./mvnw clean install -DskipTests

On the first build, Maven downloads all the dependencies from the internet
and caches them in the local repository (~/.m2/repository), which can take a
while, depending on your connection speed. Subsequent builds are faster.

Trino has a comprehensive set of tests that take a considerable amount of time
to run, and are thus disabled by the above command. These tests are run by the
CI system when you submit a pull request. We recommend only running tests
locally for the areas of code that you change.

Running Trino in your IDE Copy Chapter

Overview Copy Section

After building Trino for the first time, you can load the project into your IDE
and run the server. We recommend using
IntelliJ IDEA. Because Trino is a standard
Maven project, you can easily import it into your IDE. In IntelliJ, choose
Open Project from the Quick Start box or choose Open
from the File menu and select the root pom.xml file.

After opening the project in IntelliJ, double-check that the Java SDK is
properly configured for the project:

• Open the File menu and select Project Structure
• In the SDKs section, ensure that JDK 25 is selected (create one if none exist)
• In the Project section, ensure the Project language level is set to 25

Running a testing server Copy Section

The simplest way to run Trino for development is to run the TpchQueryRunner
class. It will start a development version of the server that is configured with
the TPCH connector. You can then use the CLI to execute queries against this
server. Many other connectors have their own *QueryRunner class that you can
use when working on a specific connector. The VM option generally required here
is --add-modules jdk.incubator.vector, but various *QueryRunner classes
might require additional options (if necessary, check the air.test.jvm.additional-arguments
property in the pom.xml file of the module from which the runner comes).

Running tests from the IDE Copy Section

When running individual test classes directly from IntelliJ, you need to
configure the JUnit run configuration template. Go to Run/Debug Configurations >
Edit Configuration Templates > JUnit > VM options and set the value to
-ea --add-modules=jdk.incubator.vector. Some tests may rely on JVM options provided
by airbase (e.g. -XX:-OmitStackTraceInFastThrow), so check for that too.

Running the full server Copy Section

Trino comes with sample configuration that should work out-of-the-box for
development. Use the following options to create a run configuration:

• Main Class: io.trino.server.DevelopmentServer
• VM Options: -ea -Dconfig=etc/config.properties -Dlog.levels-file=etc/log.properties -Djdk.attach.allowAttachSelf=true --sun-misc-unsafe-memory-access=allow --add-modules jdk.incubator.vector
• Working directory: $MODULE_DIR$
• Use classpath of module: trino-server-dev

The working directory should be the trino-server-dev subdirectory. In
IntelliJ, using $MODULE_DIR$ accomplishes this automatically.

If VM options doesn't exist in the dialog, you need to select Modify options
and enable Add VM options.

To adjust which plugins are enabled for the development server, adjust the value of
plugin.bundles in config.properties. Each entry in this list must represent a plugin
specified by one of the following options:

• A path to a pom.xml or *.pom file describing a Maven project that produces a plugin.
• Maven coordinates, in the form <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>. The plugin will be loaded via Maven and therefore must be available in your local repository or a remote repository.
• A path to a plugin directory containing JAR files. See Deploying a custom plugin for more details.

If you want to use a plugin in a catalog, you must add a corresponding
<catalog_name>.properties file to testing/trino-server-dev/etc/catalog.

Running the CLI Copy Section

Start the CLI to connect to the server and run SQL queries:

client/trino-cli/target/trino-cli-*-executable.jar

Run a query to see the nodes in the cluster:

SELECT * FROM system.runtime.nodes;

Run a query against the TPCH connector:

SELECT * FROM tpch.tiny.region;

File: docs/README.md Copy Chapter

Trino documentation

The docs module contains the reference documentation for Trino.

• Writing and contributing
• Tools
• Fast doc build option
• Default build
• Viewing documentation
• Versioning
• Style check
• Contribution requirements
• Workflow
• Videos
• Docker container

Writing and contributing Copy Chapter

We welcome any contributions to the documentation. Contributions must follow
the same process as code contributions and
can be part of your code contributions or separate documentation improvements.

The documentation follows the Google developer documentation style guide for any
new documentation:

• Google developer documentation style guide
• Highlights
• Word list
• Style and tone
• Writing for a global audience
• Cross-references
• Present tense

The Google guidelines include more material than listed here, and are used as a
guide that enables easy decision-making about proposed doc changes. Changes to
existing documentation to follow these guidelines are underway.

As a specific style note, because different readers may perceive the phrases "a
SQL" or "an SQL" to be incorrect depending on how they pronounce SQL, aim to
avoid use of "a/an SQL" in Trino documentation. Try to reword, re-order, or
adjust writing so that it is not necessary. If there is absolutely no way around
it, default to using "a SQL."

Other useful resources:

• Style check
• Google Technical Writing Courses
• Myst guide

Tools Copy Chapter

Documentation source files can be found in Myst Markdown
(.md) format in src/main/sphinx and subdirectories. Refer to the Myst
guide and the existing documentation for more
information about how to write and format the documentation source.

The engine used to create the documentation in HTML format is the Python-based
Sphinx.

The fast doc build option requires only a local
installation of Docker Desktop on
Mac or Docker Engine on
Linux. No other tools are required.

The default formal build of the docs is performed with Apache Maven, which requires an
installation of a Java Development Kit.

Fast doc build option Copy Chapter

For fast local build times when writing documentation, you can run the Sphinx
build directly. The build runs inside a Docker container and thus does not
require having anything installed locally other than Docker. You can run the
Sphinx build on a fresh clone of the project, with no prerequisite commands. For
example:

docs/build

Sphinx attempts to perform an incremental build, but this does not work
in all cases, such as after editing the CSS. You can force a full rebuild
by removing the target/html directory:

rm -rf docs/target/html

Default build Copy Chapter

The default build uses Apache Maven and Java as does the rest of the
Trino build. You only need to have built the current Trino version from the root.
That is, before building the docs the first time, run the following command:

./mvnw clean install -DskipTests

Subsequently, you can build the doc site using the Maven wrapper script:

./mvnw -pl docs clean install

If you have Maven installed and available on the path, you can use the mvn command
directly.

This also performs other checks, and is the authoritative way to build the
docs. However, using Maven is also somewhat slower than using Sphinx directly.

Viewing documentation Copy Chapter

However you build the docs, the generated HTML files can be found in the folder
docs/target/html/.

You can open the file docs/target/html/index.html in a web browser on
macOS with

open docs/target/html/index.html

or on Linux with

xdg-open docs/target/html/index.html

Or you can directly call your browser of choice with the same filename. For example, on Ubuntu
with Chromium:

chromium-browser docs/target/html/index.html

Alternatively, you can start a web server with that folder as root, such as with
the following Python command. You can then open
http://localhost:4000 in a web browser.

cd docs/target/html/
python3 -m http.server 4000

In order to see any changes from the source files in the HTML output, simply
re-run the build command and refresh the browser.

Versioning Copy Chapter

The version displayed in the resulting HTML is read by default from the top-level Maven
pom.xml file's version field.

To deploy a specific documentation set (such as a SNAPSHOT version) as the release
version you must override the pom version with the TRINO_VERSION
environment variable.

TRINO_VERSION=355 docs/build

If you work on the docs across multiple builds, you can export the
variable and use it with Sphinx.

export TRINO_VERSION=354
docs/build

This is especially useful when deploying doc patches for a release where the
Maven pom has already moved to the next SNAPSHOT version.

Style check Copy Chapter

The project contains a configuration for Vale and the
Google developer documentation style. Vale is a command-line tool to check for
editorial style issues of a document or a set of documents.

Install Vale with Homebrew on macOS or follow the instructions on the website.

brew install vale

The docs folder contains the necessary configuration to use vale for any
document in the repository:

• .vale directory with Google style setup
• .vale/config/vocabularies/Base/accept.txt file for additional approved
  words and spelling
• .vale.ini configuration file configured for Markdown and reStructuredText
  files

With this setup you can validate an individual file from the repository root by
specifying the path:

vale docs/src/main/sphinx/overview/use-cases.md

You can also use directory paths and all files within.

Treat all output from Vale as another aid for improving the docs. Fixing any
issues is not required, but it can help you learn more about the Google style
guide that we try to follow.

Contribution requirements Copy Chapter

Contributing corrections or new explanations to the Trino documentation
requires only a willingness to help and submission of your Contributor
License Agreement (CLA).

Workflow Copy Chapter

The procedure to add a documentation contribution is the same as for a code
contribution.

• In the Trino project's GitHub Issues
  list, identify documentation issues
  by filtering on the docs
  label.

• If you want to help Trino documentation, but don't know where to start, look
  in the Issues list for both the docs and good first issue
  labels.

• If the doc fix you have in mind does not yet have an issue, add one (which
  requires a signed CLA). Add the docs label to your new issue.

• You can discuss proposed doc changes in the #docs channel of the Trino
  Slack.

• For a larger contribution, create a GitHub pull request as described
  in GitHub
  documentation.
  In brief, this means:

  • Create a fork of the
    trinodb/trino repository.

  • Create a working branch in your fork.

  • Make your edits in your working branch and push them to your fork.

  • In a browser, open your fork in GitHub, which offers to submit a pull
    request for you.

Videos Copy Chapter

1. See Contributing to the Trino
   documentation for a
   five-minute video introduction. Note that this video uses the old RST source
   format.

2. You might select a GitHub doc issue to work on that requires you to verify
   how Trino handles a situation, such as adding
   documentation for SQL
   functions.

   In this case, the five-minute video Learning Trino SQL with
   Docker gives you a starting
   point for setting up a test system on your laptop.

Docker container Copy Chapter

The build of the docs uses a Docker container that includes Sphinx and the
required libraries. The container is referenced in the SPHINX_IMAGE variable
in the build script.

The specific details for the container are available in Dockerfile, and
requirements.in. The file requirements.txt must be updated after any changes
to requirements.in.

The container must be published to the GitHub container registry at ghcr.io with
the necessary access credentials and the following command, after modification
of the version tag xxx to the new desired value as used in the build script:

docker buildx build docs --platform=linux/arm64,linux/amd64 --tag ghcr.io/trinodb/build/sphinx:xxx --provenance=false --push

Note that the version must be updated and the command automatically also
publishes the container with support for arm64 and amd64 processors. This is
necessary so the build performs well on both hardware platforms.

After the container is published, you can update the build script and merge
the related pull request.

Example PRs:

• https://github.com/trinodb/trino/pull/17778
• https://github.com/trinodb/trino/pull/13225